slamlab_visualization
The slamlab_visualization section configures the slamlab-visualization executable: startup behavior, media inputs, mesh overlays, and the Polyscope 3D viewer.
All paths support the $CONFIG_DIRPATH$ token, which is replaced with the parent directory of the config file. The $STAMP$ token is replaced with a YYYY_MM_DD-HH_MM_SS timestamp.
| Parameter | Type | Default | Description |
|---|---|---|---|
images_dirpath | path | "" | Directory containing image files for display |
config_filepath | path | "" | Path to a separate Polyscope config YAML file (alternative to inline polyscope key) |
mesh_base_frame_filepath | path | "" | Mesh file to display in the base (sensor) frame |
mesh_map_frame_filepath | path | "" | Mesh file to display in the map frame |
slam_host | string | "127.0.0.1" | Host the viewer connects to for the SLAM data stream (the SLAM machine’s IP/hostname). Use "127.0.0.1" for a local SLAM process. Can be overridden at runtime with the SLAMLAB_VIZ_SLAM_HOST environment variable |
supersampling_factor | int | 4 | Supersampling anti-aliasing factor: the scene is rendered at this multiple of the output resolution then downsampled, trading GPU memory and fill rate for smoother edges. Each step squares the framebuffer footprint (4 → 16× the pixels). A factor whose framebuffer exceeds available GPU memory makes the headless allocation fail and the frame render all-black, so GPUs with little VRAM require a smaller value (e.g. 2). Range: [1, 4]. |
egl_device_index | int | -1 | EGL device index for headless rendering. -1 auto-selects (heuristic order); set explicitly to pin a specific GPU when auto-selection picks a device that initializes but renders nothing (all-black) or a software rasterizer. Ignored unless video_recording.headless is set. |
video_recording | object | — | MP4 recording of the run (see below) |
polyscope | object | — | Inline Polyscope viewer configuration (see below) |
video_recording
Section titled “video_recording”Records one video frame per SLAM update (a flipbook of SLAM steps) to an H.264 MP4. fps is the playback rate of the encoded file, not a wall-clock capture rate, so the video length is num_updates / fps. Each run writes a new file named slamlab-visualization-yyyy-mm-dd-hh-mm-ss.mp4, finalized when the run completes. Requires ffmpeg on PATH.
While recording, offline replay automatically throttles SLAM to the render/encode rate (one frame in flight, acknowledged over the frame-data socket) so every cloud is captured. The real-time ROS node is never throttled: if it outpaces rendering, dropped clouds are filled by duplicating the latest frame to keep the video length proportional to cloud progress.
| Parameter | Type | Default | Description |
|---|---|---|---|
enabled | bool | false | Enable video recording |
headless | bool | false | Render off-screen with the EGL backend instead of opening an interactive window. On multi-GPU or low-VRAM hosts that produce black frames, see egl_device_index and supersampling_factor above. |
fps | float | 30.0 | Playback frame rate of the encoded file. Range: [1, 240]. |
width | int | 1920 | Encoded video width in pixels. The rendered frame is fitted into it (letterboxed if aspect ratios differ); odd values are rounded down to even. Range: [16, 7680]. |
height | int | 1080 | Encoded video height in pixels. Range: [16, 7680]. |
capture_only_each_nth_frame | int | 1 | Record only every Nth cloud (clouds 0, N, 2N, …), each as one video frame played at fps. The recording is a flipbook of every Nth cloud — higher values cut screenshot/encode cost and shorten the video proportionally. Range: [1, ∞). |
hold_last_frame_seconds | float | 5.0 | Freeze on the last rendered frame for this many seconds at the end of each recorded file by duplicating it (round(seconds * fps) extra frames). 0 disables the hold. Range: [0, 60]. |
output_dirpath | path | "" | Directory for recordings. Empty means the current working directory. |
font_ttf_filepath | path | "" | TrueType font for all widget text. Empty selects the font bundled with the visualization. |
widgets | list | [] | Info overlays drawn onto the recorded frames (see below). Empty means no overlays. |
video_recording.widgets
Section titled “video_recording.widgets”Each list entry is one info overlay. Overlays appear only in the recorded video, never in the interactive window.
| Parameter | Type | Default | Description |
|---|---|---|---|
enabled | bool | true | Draw this overlay |
content | string | "" | Text with \n line breaks and placeholders (see below). Text wrapped in **double asterisks** renders in the slamlab highlight color. |
position | string | "top_left" | Anchor in a 3x3 grid: top_left, top_center, top_right, center_left, center, center_right, bottom_left, bottom_center, or bottom_right |
width | float | 0.25 | Overlay width as a fraction of the frame width. Range: [0, 1]. |
font.size | float | 0.02 | Text height as a fraction of the frame height. Range: [0, 1]. |
font.alignment | string | "left" | left, center, or right |
background_opacity | float | 0.5 | Opacity of the dark backing panel. Range: [0, 1]. |
image_opacity | float | 1.0 | Opacity scale of inline images. Range: [0, 1]. |
Text placeholders, replaced wherever they occur in a line:
| Placeholder | Value |
|---|---|
$CLOUD_INDEX$ | Index of the captured cloud |
$ELAPSED_TIME$ | Seconds since the start of the recording |
$STAMP$ | Timestamp of the trajectory pose in seconds |
$LENGTH$ | Trajectory length in meters |
$NUM_LOOP_CLOSURES$ | Number of accepted loop closures |
$TRAJECTORY_X$, $TRAJECTORY_Y$, $TRAJECTORY_Z$ | Pose position in meters |
$TRAJECTORY_ANGLE_X$, $TRAJECTORY_ANGLE_Y$, $TRAJECTORY_ANGLE_Z$ | Pose orientation in degrees |
Image markers, each on a line of its own, render at the full overlay width:
| Marker | Image |
|---|---|
$IMAGE$ | Current camera image |
$IMAGE:path$ | Static image at path (supports $CONFIG_DIRPATH$; a relative path is relative to the working directory) |
Example:
widgets: - enabled: true content: "**SLAMLab**\nCloud $CLOUD_INDEX$\nLength: $LENGTH$ m" position: bottom_right width: 0.2 font: size: 0.025 alignment: right background_opacity: 0.5 image_opacity: 1.0polyscope
Section titled “polyscope”The Polyscope configuration can be provided inline under the polyscope key or in a separate YAML file referenced by config_filepath. When using a separate file, the Polyscope keys are the root of that file (no wrapping polyscope: key).
Missing visualization entities (curve networks, point clouds, surface meshes) are filled from built-in defaults.
General
Section titled “General”| Parameter | Type | Default | Description |
|---|---|---|---|
scene_length_scale | float | 20.0 | Polyscope scene scale factor. Range: [2, 200]. |
polyscope_menu | bool | false | Show the native Polyscope menu |
eye_dome_lighting
Section titled “eye_dome_lighting”Eye-dome lighting (EDL): screen-space shading that darkens points occluded by closer neighbors, which makes the 3D structure of point clouds easier to read.
| Parameter | Type | Default | Description |
|---|---|---|---|
enabled | bool | true | Enable eye-dome lighting |
strength | float | 100.0 | Exponential falloff of the shading with the relative depth difference. Range: [0, ∞). |
radius | float | 3.0 | Neighbor sampling distance in screen pixels. Range: [0.5, 10]. |
camera
Section titled “camera”| Parameter | Type | Default | Description |
|---|---|---|---|
refframe | string | "map" | Camera reference frame: map or base |
camera_follow_mode | string | "Free" | Free, Follow position, Follow pose, Follow orbit, Top view, or Follow chase |
camera_style | string | "Turntable" | Turntable, Free, Planar, None, or FirstPerson |
projection | string | "perspective" | perspective or orthographic |
field_of_view | float | 45.0 | Field of view in degrees. Range: [5, 160]. |
chase_distance | float | 15.0 | Follow chase: distance of the camera from the base in meters. Adjusted at runtime with the mouse wheel. |
chase_azimuth | float | 0.0 | Follow chase: angle of the camera about the vertical in degrees. 0 = directly behind the direction of travel, positive = counter-clockwise seen from above (90 = view from the vehicle’s right side). Range: [-180, 180]. |
chase_elevation | float | 25.0 | Follow chase: angle of the camera above the horizontal map plane in degrees. Range: [-90, 90]. |
chase_smoothing_sec | float | 1.0 | Follow chase: time constant in seconds of the low-pass filter applied to the camera motion, in trajectory time. 0 disables smoothing. |
camera.refframe_T_camera
Section titled “camera.refframe_T_camera”Initial camera pose in the reference frame.
| Parameter | Type | Default | Description |
|---|---|---|---|
translation | float[3] | [0, 0, 30] | Camera position [x, y, z] |
rotation | float[4] | [0, 0, 0, 1] | Camera orientation as quaternion [x, y, z, w] |
curve_network
Section titled “curve_network”A map of named curve network entities. Each entry configures how a curve network is rendered.
| Parameter | Type | Default | Description |
|---|---|---|---|
enabled | bool | true | Show/hide the curve network |
radius | float | 0.003 | Tube radius. Range: [0, 0.1]. |
color | float[3] | [1, 1, 1] | RGB color |
material | string | "clay" | clay, wax, candy, flat, mud, ceramic, jade, or normal |
Quantity arrays
Section titled “Quantity arrays”Each curve network can have color_quantities, scalar_quantities, vector_quantities, and covariance_quantities arrays (see Quantities).
Default curve networks: Frames, Loop closures, Trajectory
point_cloud_network
Section titled “point_cloud_network”A map of named point cloud entities.
| Parameter | Type | Default | Description |
|---|---|---|---|
enabled | bool | true | Show/hide the point cloud |
color | float[3] | [1, 1, 1] | RGB color |
point_radius | float | 0.003 | Point size. Range: [0, 0.1]. |
point_render_mode | string | "quad" | quad, sphere, or voxel |
material | string | "clay" | Same material options as curve networks |
edge_enabled | bool | false | Draw point edges |
edge_color | float[3] | [0, 0, 0] | Edge RGB color |
edge_width | float | 0.2 | Edge width. Range: [0, 3]. |
Quantity arrays
Section titled “Quantity arrays”Each point cloud can have color_quantities, scalar_quantities, and vector_quantities arrays (see Quantities).
Default point clouds: Absolute position measurements, Correspondences, Global map, Key clouds, Local map voxel PCA, Prior map voxel PCA, Processed cloud
surface_mesh_network
Section titled “surface_mesh_network”A map of named surface mesh entities.
| Parameter | Type | Default | Description |
|---|---|---|---|
enabled | bool | true | Show/hide the mesh |
color | float[3] | [1, 1, 1] | RGB color |
edge_color | float[3] | [0, 0, 0] | Wireframe edge color |
edge_width | float | 1.0 | Wireframe edge width. Range: [0, 2]. |
shade_style | string | "smooth" | smooth, flat, or tri flat |
material | string | "clay" | Same material options |
Quantity arrays
Section titled “Quantity arrays”Each surface mesh can have color_quantities arrays (see Quantities).
Quantities
Section titled “Quantities”Quantities attach data visualizations to curve networks, point clouds, or surface meshes.
color_quantities
Section titled “color_quantities”| Parameter | Type | Default | Description |
|---|---|---|---|
name | string | — | Quantity name (must match the registered Polyscope quantity) |
enabled | bool | false | Enable this color quantity |
scalar_quantities
Section titled “scalar_quantities”| Parameter | Type | Default | Description |
|---|---|---|---|
name | string | — | Quantity name |
enabled | bool | false | Enable this scalar quantity |
color_map | string | "rainbow" | viridis, coolwarm, blues, reds, ping-green, phase, spectral, rainbow, jet, turbo, or signal |
map_range_mode | string | "quantile" | quantile: map_range holds low/high quantile fractions in [0, 1] and the colormap range adapts to the data quantiles. absolute: map_range holds explicit colormap limits |
map_range | float[2] | [0.10, 0.90] | Quantile fractions (quantile mode) or explicit min/max limits (absolute mode) |
vector_quantities
Section titled “vector_quantities”| Parameter | Type | Default | Description |
|---|---|---|---|
name | string | — | Quantity name |
enabled | bool | false | Enable this vector quantity |
vector_radius | float | 0.003 | Arrow shaft radius. Range: [0, 0.1]. |
vector_length_scale | float | 0.05 | Arrow length scaling. Range: [0, 0.1]. |
vector_color | float[3] | [1, 1, 1] | Arrow RGB color |
covariance_quantities
Section titled “covariance_quantities”| Parameter | Type | Default | Description |
|---|---|---|---|
name | string | — | Quantity name |
enabled | bool | false | Enable this covariance quantity |
show_position_ellipsoids | bool | true | Show translational covariance ellipsoids |
show_rotation_ellipsoids | bool | false | Show rotational covariance ellipsoids |
show_only_last | bool | false | Only show the most recent ellipsoid |
show_every_nth | int | 1 | Show every Nth ellipsoid. Must be ≥ 1. |
position_scale | float | 1.0 | Scale factor for position ellipsoids. Range: [0, 100]. |
rotation_scale | float | 1.0 | Scale factor for rotation ellipsoids. Range: [0, 100]. |
position_ellipsoid_color | float[3] | [1, 0.5, 0] | Position ellipsoid RGB color |
rotation_ellipsoid_color | float[3] | [0, 0.5, 1] | Rotation ellipsoid RGB color |
transparency | float | 0.6 | Ellipsoid transparency. Range: [0, 1]. |