The viewer’s workspaces¶
lagrange_viewer (or lagrange viewer, or the viewer that lagrange starts beside the
simulator) groups its panels into workspaces, one tab each along the top. This page lists what
each workspace offers beyond the 3D view, with the keys and flags that reach it. The viewer
talks to the simulator only through its protocol: everything below comes from the server it is
connected to, or from the viewer itself where a section says so. The screens’ design is
docs/design/ui/ (one folder per workspace).
Workspace |
Key |
|
|---|---|---|
Scene |
Ctrl+1 |
|
Domains |
Ctrl+2 |
|
Electrical |
Ctrl+3 |
|
Signals |
Ctrl+4 |
|
Sensors |
Ctrl+5 |
|
Environment |
Ctrl+6 |
|
Replay |
Ctrl+7 |
|
ROS 2 |
Ctrl+8 |
|
World |
Ctrl+9 |
|
Performance |
Ctrl+0 |
|
Builder |
Ctrl+B |
|
The command palette¶
Ctrl K (or the menu’s Command palette, or the Ctrl K hint at the right of the menu bar)
opens one search over the viewer’s commands, the scene’s prims, the signals and the ROS 2
topics, best match first. Type a few letters of any of them in any order (the match is fuzzy);
Enter runs the chosen line: a command runs, a prim is selected and shown where it is
inspected (the Scene workspace), a signal is added to the scope in Signals, a topic opens the
ROS 2 workspace. Esc or a click outside closes it.
Domains¶
Beside the domain table, the schedule, the profile and the wiring, each group has secondary tabs:
Modules (beside Domains): every module the server runs, as it measures them: its step, rate, CPU per step, and what one millisecond of simulation costs. Substitutes cost nothing and say so.
Coupling (beside Schedule): every writer → reader pair of the wiring, what passes between them and at which rates, whether the pair is solved together or read through a hold (the 100 µs electrical reads the 100 ms thermal 1000 times per value).
Diff (beside Profile): the line diff of the applied profile and the one being edited.
Schema (beside Profile): the keys of
profiles/schema.json, with their types and descriptions, by domain.
The Profile panel’s YAML is the profile being edited: typing in it changes the domain rows,
and switching a row changes the text; the server validates the draft as it does any edit, and
Apply rebuilds the run with it. Every domain the run has is in the table with its module and
switch, its cost is the server’s measured CPU per simulated second, and a domain switched off
shows its substitute in the preview. The substitute picker offers the selected domain’s
substitutes (the first domain’s before any click). Headless, --set-domain <d>=on|off
(repeatable) and --apply-profile do the same as the switches and Apply.
Sensors¶
Besides lidar, IMU and camera views, the Radar view draws a radar’s detections as a fan and
over range and azimuth. In the 3D view, Overlays → Radar detections (--overlays radar)
draws each detection as a box sized by its radar cross-section (−20 to +20 dBsm), coloured by
radial velocity (blue closing, orange moving away) with a Doppler tick along the line of sight,
and the radar’s field of view as a faint wedge. It works for a RadarAPI_1 radar and an
imaging_radar; the sedan’s front_radar is the sample (Tutorial: a car in a city
block).
Environment and World¶
A weather preset sends its whole weather at once and the run is rebuilt once for it. Wind with
the aerodynamics domain off is said to push nothing. The World workspace lists everything
that moves on its own: other robots (spawned or --add-robot), traffic vehicles and pedestrians,
scenario entities and people, with their speeds.
Replay¶
With a recording open (lagrange_server --replay run.mcap, or File → Open recording), the
Replay workspace compares it with a second Lagrange recording: a real robot’s log converted into
one, or another simulated run (another engine, profile or parameter).
lagrange_viewer --workspace replay --compare other.mcap [--suite suite.yaml]
Compare: pick the second recording and press Compare.
Sim vs real: each signal of both runs plotted together, aligned by the lag (up to ±0.5 s) that matches them best, resampled to 100 Hz by default, with its error.
Validation: a pass or fail per signal, the normalised RMS error over the second run’s range against a limit, by driving phase (stopped, accelerate, cruise, brake). Export report writes JSON to
<config>/validation/.History, and the Source strip (what wrote the recording).
Without a suite every scalar signal both recordings share is compared with a 5 % limit. A suite file names signals, components, limits and the method:
suite: amr_drive
method: {alignment: cross-correlation, resample_hz: 100, max_lag_s: 0.5, window: [0, 10]}
signals:
- {sim: motor/left_drive_motor/current_q, real: motor/left_drive_motor/current_q, limit: 0.05}
- {sim: body/base_link/twist, component: 0, limit: 0.05}
The limit is a fraction of the real signal’s range (NRMSE). When the real signal is constant in
the window the NRMSE says nothing, so the row reads const ref and is judged by its RMSE in the
signal’s unit: against abs_limit when the entry gives one, else against the limit times the
larger of the constant’s size and the range of the sim signal.
Both files are read on the viewer’s machine, so a replay served from another machine cannot be
compared yet, and Re-simulate from here… is shown but disabled (both need protocol additions;
docs/design/viewer.md, “Replay comparison”).
ROS 2¶
The viewer does not join the ROS domain; the workspace shows the graph the server reports.
Topics and Node graph, as before; hidden topics (an action’s) stay out, as
ros2 topic listleaves them out.Actions: the graph’s actions, found from their hidden
<name>/_action/...topics, with the nodes that serve and use them; one nobody serves any more is marked.Services and Params: the server’s graph report does not carry them yet, so each tab says so and gives the command to run from a terminal in the same ROS domain.
TF tree: odom over the robot’s base, the bodies by the scene’s hierarchy, sensors on their bodies and cameras’ optical frames, each with who publishes it (
/tfor/tf_static) and how it moves; frames that nobody publishes (norobot_state_publisher) or that went stale are warned about. A paused run has no stale frames.
Performance¶
Six cards at the top: real-time factor (against the target), CPU per 1 ms of sim, viewer frame (ms and fps), protocol (deltas per second, kB/s, dropped), determinism and GPU per sensor frame (the modules the server runs on the GPU). The server sends no determinism check, so that card says not reported rather than guess. New tabs (the simulation’s own threads and GPU passes are not in what the server reports, so these measure the viewer):
Threads: the viewer’s threads from
/proc, once a second, and its UI thread’s frame by phase (panels, recording, waiting for the GPU, presenting).GPU passes: the viewer’s own passes, timed with Vulkan timestamp queries (when the device supports them).
Memory: the server’s resident and GPU memory as it reports them, the viewer’s resident memory with its peak, and the video memory the viewer holds against its budget (
VK_EXT_memory_budget).