GPU-accelerated ROS2 visualization, debugging, and analysis.
Replaces rqt with a single Vulkan-powered tool — topic
monitor, live plotter, bag player/recorder, TF tree, node graph,
parameter editor, service caller, and more.
Goal: go from a live ROS graph to a scrolling GPU plot without installing
rqt, PlotJuggler, and RViz separately. Build once, then use
either --topics or a checked-in session preset.
spectra-ros
Default layout opens Topic Monitor (left), Plot Area (center), Topic Echo (bottom), and Topic Statistics (right). Select a topic in the monitor — the stats panel shows a hint until you pick a field to plot.
sessions/presets/. Load at startup with
--session — no manual dock setup required.
SPECTRA_USE_ROS2=OFF
(the default), no ROS2 headers are included and no ROS2 dependencies
are required. All adapter code is fully gated behind the CMake option.
Each workflow has a session preset, launch file, and QA scenario. See also how Spectra compares to rqt, PlotJuggler, RViz, and Foxglove.
Four IMU axes on a 2×2 grid — acceleration and angular rate.
Transport bar, bag info, plots, and echo on one timeline.
Commanded vs measured velocity for integrator bringup.
cmd_vel, odom, diagnostics — nav stack at a glance.
The adapter is a self-contained CMake library target
(spectra_ros2_adapter) that sits entirely under
src/adapters/ros2/. It does not modify the Spectra
core library.
Background executor introspects DDS messages; SPSC ring buffers decouple the Vulkan render thread.
Ros2Bridge — node lifecycleTopicDiscovery — periodic graph queryGenericSubscriber — type-erased subscriptionMessageIntrospector — runtime field extractionRosPlotManager — polls ring buffersLineSeries each frameScrollController — auto-scroll windowrosidl_typesupport_introspection_cpp to
walk any message type's field tree without code generation.
Field paths like pose.position.x are resolved at
subscribe time and extracted per-message via offset arithmetic.
All panels are dockable and resizable within the
spectra-ros layout. The default layout places the
topic monitor on the left, the plot area in the center, the
inspector on the right, and the log/bag controls at the bottom.
Phase B
Phase C
LineSeries bridge per subscribed pathPhase D
.db3 / .mcap bagsPhase F
Phase F
/tf + /tf_staticPhase F
DescribeParametersPhase F
Phase E
Phase C
sqrt($imu.accel.x^2 + ...)+ − * / ^ sqrt abs sin cos atan2 log exp
Subscribing a field creates a LineSeries in the active
axes. The render thread polls the ring buffer each frame and appends
new samples at zero-copy cost.
In the Topic Echo panel, expand a message type to see its numeric fields. Drag any numeric leaf onto a plot axes or the empty background to create a new series. Right-click for placement options.
Alternatively, use the CLI:
The X axis tracks [now − window, now] automatically.
Configurable range: 1 s – 3 600 s (default 30 s).
Add subplots from the toolbar (+ button) or by dragging fields to an empty area below existing plots. Each row/column is configurable via the layout dropdown.
AxisLinkManager
Any scalar-typed field in a ROS2 message can be plotted using
dot-separated paths. Arrays index with [N].
Create computed data streams by combining raw topic fields with
math expressions. Expressions are evaluated per-sample on the
render thread using the built-in ExpressionEngine.
Variables reference topic fields with the $topic.field.path
syntax. Multiple topics can be mixed in one expression — values
are interpolated to a common timeline.
| Category | Operators / Functions |
|---|---|
| Arithmetic | + − * / ^ |
| Comparison | < > <= >= == != |
| Math | sqrt abs sin cos atan2 log exp |
| Constants | pi e |
Parse errors are shown inline in the expression editor with the offending token highlighted. Presets can be saved and loaded by name.
Rosbag2 features are gated behind -DSPECTRA_ROS2_BAG=ON.
Both .db3 (SQLite) and .mcap formats are
supported.
./spectra-ros --bag /path/to/file.db3.db3 / .mcap file onto the windowThe Bag Info panel shows metadata (duration, topic count, message count, start/end timestamps) and a topic table. Click any topic to plot it immediately.
The scrub bar reuses Spectra's TimelineEditor with per-topic activity bands showing when each topic has messages.
Record live topics to a new bag file from within Spectra. The recorder panel lets you select topics, output path, format, and auto-split thresholds.
.db3 or .mcapspectra-ros-analyze)Export numeric bag fields to CSV without the GUI — for CI thresholds and post-run reports. See docs/ci/bag-analysis.md.
./build/spectra-ros-analyze \
--bag tests/data/ros_bags/imu_snippet \
--fields /imu/data.linear_acceleration.z \
--csv /tmp/imu_z.csv
Bag messages are fed through the same
RosPlotManager pipeline as live subscriptions.
You can run a bag alongside live topics simultaneously — the
plot series auto-color by source.
The node graph panel queries the ROS2 graph and renders the full publish/subscribe topology with a force-directed layout.
Subscribes to /tf and /tf_static and
maintains a live frame tree with age tracking.
world / mapDiscover and edit ROS2 node parameters at runtime. Supports all parameter types with range-aware widgets and YAML preset files.
Live-edit mode: sends SetParameters immediately on change. Apply mode: stages all edits, then sends in one batch via the Apply button.
ros2 param loadList, introspect, and call any ROS2 service from a generated UI form — no code required.
timestamp_sec, timestamp_nsec, wall_clock, field values, \t) and decimal precision| Option | Default | Description |
|---|---|---|
SPECTRA_USE_ROS2 |
OFF |
Enable the ROS2 adapter. Requires ROS2 workspace sourced. |
SPECTRA_ROS2_BAG |
OFF |
Enable rosbag2 reader/writer/player. Requires rosbag2 packages. |
SPECTRA_USE_ROS2 + SPECTRA_USE_FFMPEG |
— | Enables MP4 video export from the recording panel. |
cmake. Without the sourced environment,
find_package(rclcpp) will fail and the adapter will
not be built.
All options can be combined. --topics and
--bag can be used together.
| Flag | Example | Description |
|---|---|---|
--topics / -t |
--topics /cmd_vel:linear.x /imu/data:angular_velocity.z |
Subscribe and plot topic or topic:field_path at startup |
--bag / -b |
--bag /path/to/recording.db3 |
Open a rosbag immediately on launch |
--session / -s |
--session sessions/presets/tuning.spectra-ros-session |
Load a .spectra-ros-session preset (plots, panels, layout) |
--layout / -l |
--layout plot-only |
default, plot-only, monitor, rviz, rviz-plot |
--window-s / -w |
--window-s 60 |
Auto-scroll time window in seconds (default 30) |
--node-name / -n |
--node-name spectra_debug |
Override the ROS2 node name (default: spectra_ros) |
--rows / --cols |
--rows 2 --cols 2 |
Initial subplot grid dimensions |
spectra-ros uses a single ImGui dockspace with layout presets
(Default, Monitor, RViz,
RVizPlot, BagReview). Panel layout persists in
.spectra-ros-session files under imgui_layout.
nav_msgs/OccupancyGrid).
Run visual QA: spectra_ros_qa_agent --design-review --output-dir /tmp/ros_qa
| Shortcut | Action |
|---|---|
| Space | Play / Pause bag playback |
| Home | Resume auto-scroll (if paused by zoom/pan) |
| Ctrl+C | Copy selected plot range as TSV to clipboard |
| Ctrl+Shift+S | Save screenshot as timestamped PNG |
| Ctrl+Z | Undo last parameter change (Parameter Editor) |
| Ctrl+K | Open command palette |
| Ctrl+R | Refresh topic list / service list |
| Ctrl+L | Toggle legend visibility |
| Ctrl+G | Toggle grid on active axes |
| Ctrl+Shift+A | Auto-fit all axes |
| F | Auto-fit active axes |
Three example launch files are provided under
examples/ros2_launch/.
imu_monitor.launch.py
Subscribes to /imu/data (linear acceleration + angular
velocity) in a 2-row subplot layout with shared X axis and
auto-scrolling 10 s window.
nav_dashboard.launch.pyNavigation stack dashboard — velocity commands, odometry, and costmap diagnostics plotted in a 3-panel layout with the node graph and TF tree visible.
bag_replay.launch.py
Opens a specified rosbag, starts the bag player at 1× speed,
and plots all Float64 topics automatically.
Accepts the bag path as a launch argument.