The plugin is optional and disabled by default. An unselected or disabled Visualizer does not discover services, subscribe to events, create tasks, poll state, capture geometry, or add a tick callback.

Installation

Install FastSim Core 0.1.0a26 or a compatible later 0.1.x build first:

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

Install the browser workstation dependencies when Web access is required:

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

Run configuration

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

Start the Run and open http://127.0.0.1:8030. Camera channels are explicit so the runtime only produces frames that the selected application needs.

For debug screenshots without a desktop window, set runtime.launch_profile to headless and declare at least one scene camera. Native overlays are included in that camera's RGB output. Do not use headless-physics for screenshots: it intentionally starts neither cameras nor a renderer. The plugin can still collect non-rendered telemetry there when native.enabled is false.

What the workstation exposes

  • scene hierarchy for robots, articulations, rigid objects, links, and joints;
  • current entity, link, and joint properties;
  • one or several selected scene cameras without cropping their aspect ratio;
  • joint command and measured-state curves with units and point inspection;
  • custom metric curves and mission/task events;
  • FPS, real-time factor, CPU, memory, and available GPU-memory history;
  • visualization layers with visibility, item counts, omission budgets, and clear;
  • prepare, start, pause, single-step, resume, reset, and stop controls;
  • bounded snapshots suitable for a browser, an Agent, or an acceptance artifact.

Publish debug information

Plugins receive the scoped visualization service from FastSim. The public service supports points, line lists, coordinate frames, paths, labels, and boxes, as well as metrics and events. Every drawable belongs to a layer and can have a stable key and a finite lifetime. Reusing a key updates the drawable instead of accumulating copies.

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"},
)

The exact service signatures are published by FastSim Core. Simulator-native handles, stage paths, and renderer objects are intentionally absent from the plugin contract.

Geometry and performance policy

Planning geometry is disabled independently from native overlays. When enabled, the Visualizer uses the public batch planning-scene service and enforces max_geometry_items; excess items are reported as omitted instead of growing browser or renderer work without bound. Telemetry history and series count are bounded for the same reason.

The validated Isaac Lab comparison measured a 3.30% throughput reduction with the complete Visualizer enabled and a 0.88% run-to-run variation with it disabled. The acceptance report and all images/videos are maintained outside this package in the tracked integration evidence bundle.

Demo

The complete visible-mode example is in FastSim Core at demo/official_plugins/visualizer. It includes the Run configuration, public-API publisher, interactive-debug workflow, MCP workflow, geometry-budget case, and performance profiles.