插件为可选项且默认关闭。未选择或未启用时，不会发现服务、订阅事件、创建任务、轮询 状态、读取规划几何或增加 Tick 回调。

安装

先安装 FastSim Core 0.1.0a26 或兼容的后续 0.1.x 版本：

bash
python -m pip install ./packages/fastsim-plugin-visualizer

需要浏览器工作台时安装 Web 与 GPU 指标依赖：

bash
python -m pip install './packages/fastsim-plugin-visualizer[workstation]'

Run 配置

yaml
plugins:
  visualizer:
    use: plugin://fastsim/visualizer
    config:
      enabled: true
      native:
        enabled: true
        planning_geometry: true
        geometry_update_hz: 2
        max_geometry_items: 2000
        geometry_color_rgba: [0.12, 0.72, 1.0, 0.35]
      telemetry:
        enabled: true
        sample_hz: 10
        history_seconds: 600
        max_series: 256
      web:
        enabled: true
        host: 127.0.0.1
        port: 8030
        update_hz: 10
        cameras:
          overview: sensors.overview.rgb
          wrist: sensors.wrist.rgb
        camera_mode: explicit
        jpeg_quality: 88

启动 Run 后访问 http://127.0.0.1:8030。相机通道显式声明，因此运行时只生产本次 应用真正需要的画面。

需要在没有桌面窗口时截图调试，应将 runtime.launch_profile 设为 headless，并在 场景中声明至少一个相机；原生调试图元会进入该相机的 RGB 画面。不要用 headless-physics 截图，它有意不启动相机和渲染器。若将 native.enabled 设为 false，Visualizer 仍可在该档位采集不依赖渲染的遥测信息。

工作台能力

  • 按机器人、铰接体、刚体、Link 和 Joint 展示场景层级；
  • 检查实体、Link 和 Joint 当前属性；
  • 同时查看一个或多个场景相机，保持画面宽高比且不裁切；
  • 查看带单位和点位检查的关节命令/实际状态曲线；
  • 查看自定义指标曲线和 Mission/Task 事件；
  • 查看 FPS、实时率、CPU、内存和可用时的 GPU 显存历史；
  • 管理可视化图层显隐、图元数量、预算省略量和清除操作；
  • 执行 Prepare、Start、Pause、单步、Resume、Reset 和 Stop；
  • 生成有界快照，供浏览器、Agent 或验收工具使用。

发布调试信息

插件从 FastSim 获得范围化的 visualization 服务。公共服务支持点、线段、坐标系、 路径、标签、包围盒、指标和事件。每个图元都属于一个图层，可设置稳定 Key 和有限生命 周期；重复使用同一个 Key 会更新原图元，不会不断堆积副本。

python
visualization = context.services.require("visualization")

await visualization.frame(
    layer="mission.grasps",
    key="selected",
    xyz_m=(0.54, 0.12, 0.83),
    quat_xyzw=(0.0, 0.0, 0.0, 1.0),
    axis_length_m=0.10,
    lifetime_s=2.0,
)

await visualization.path(
    layer="mission.plan",
    key="arm-path",
    points_xyz_m=planned_positions,
    color_rgba=(0.15, 0.85, 1.0, 1.0),
)

await visualization.metric(
    series="planner.minimum_clearance_m",
    value=minimum_clearance,
    unit="m",
)

await visualization.event(
    category="mission.action",
    name="pick.completed",
    fields={"entity": "objects.cup"},
)

具体签名由 FastSim Core 发布。插件契约不会暴露仿真器句柄、Stage Path 或渲染器对象。

几何与性能策略

规划几何与原生图元分别启用。开启后，Visualizer 使用公共批量规划场景服务，并严格 执行 max_geometry_items；超过预算的部分会明确报告为省略项，不会无限增加浏览器或 渲染器负担。遥测历史长度与曲线数量同样有界。

真实 Isaac Lab 对照测试中，完整启用 Visualizer 的吞吐下降为 3.30%；关闭插件时 与基线的 0.88% 差异属于运行波动。验收报告及全部图片、视频统一保存在受跟踪的 集成证据包中，不随 Python 包发布。

Demo

完整可见模式案例位于 FastSim Core 的 demo/official_plugins/visualizer，包含 Run 配置、公共 API 发布代码、Interactive Debug、MCP 工作流、几何预算和性能档位。