Skip to content

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.

ParameterTypeDefaultDescription
images_dirpathpath""Directory containing image files for display
config_filepathpath""Path to a separate Polyscope config YAML file (alternative to inline polyscope key)
mesh_base_frame_filepathpath""Mesh file to display in the base (sensor) frame
mesh_map_frame_filepathpath""Mesh file to display in the map frame
slam_hoststring"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_factorint4Supersampling 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_indexint-1EGL 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_recordingobject—MP4 recording of the run (see below)
polyscopeobject—Inline Polyscope viewer configuration (see below)

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.

ParameterTypeDefaultDescription
enabledboolfalseEnable video recording
headlessboolfalseRender 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.
fpsfloat30.0Playback frame rate of the encoded file. Range: [1, 240].
widthint1920Encoded 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].
heightint1080Encoded video height in pixels. Range: [16, 7680].
capture_only_each_nth_frameint1Record 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_secondsfloat5.0Freeze 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_dirpathpath""Directory for recordings. Empty means the current working directory.
font_ttf_filepathpath""TrueType font for all widget text. Empty selects the font bundled with the visualization.
widgetslist[]Info overlays drawn onto the recorded frames (see below). Empty means no overlays.

Each list entry is one info overlay. Overlays appear only in the recorded video, never in the interactive window.

ParameterTypeDefaultDescription
enabledbooltrueDraw this overlay
contentstring""Text with \n line breaks and placeholders (see below). Text wrapped in **double asterisks** renders in the slamlab highlight color.
positionstring"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
widthfloat0.25Overlay width as a fraction of the frame width. Range: [0, 1].
font.sizefloat0.02Text height as a fraction of the frame height. Range: [0, 1].
font.alignmentstring"left"left, center, or right
background_opacityfloat0.5Opacity of the dark backing panel. Range: [0, 1].
image_opacityfloat1.0Opacity scale of inline images. Range: [0, 1].

Text placeholders, replaced wherever they occur in a line:

PlaceholderValue
$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:

MarkerImage
$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.0

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.

ParameterTypeDefaultDescription
scene_length_scalefloat20.0Polyscope scene scale factor. Range: [2, 200].
polyscope_menuboolfalseShow the native Polyscope menu

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.

ParameterTypeDefaultDescription
enabledbooltrueEnable eye-dome lighting
strengthfloat100.0Exponential falloff of the shading with the relative depth difference. Range: [0, ∞).
radiusfloat3.0Neighbor sampling distance in screen pixels. Range: [0.5, 10].
ParameterTypeDefaultDescription
refframestring"map"Camera reference frame: map or base
camera_follow_modestring"Free"Free, Follow position, Follow pose, Follow orbit, Top view, or Follow chase
camera_stylestring"Turntable"Turntable, Free, Planar, None, or FirstPerson
projectionstring"perspective"perspective or orthographic
field_of_viewfloat45.0Field of view in degrees. Range: [5, 160].
chase_distancefloat15.0Follow chase: distance of the camera from the base in meters. Adjusted at runtime with the mouse wheel.
chase_azimuthfloat0.0Follow 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_elevationfloat25.0Follow chase: angle of the camera above the horizontal map plane in degrees. Range: [-90, 90].
chase_smoothing_secfloat1.0Follow chase: time constant in seconds of the low-pass filter applied to the camera motion, in trajectory time. 0 disables smoothing.

Initial camera pose in the reference frame.

ParameterTypeDefaultDescription
translationfloat[3][0, 0, 30]Camera position [x, y, z]
rotationfloat[4][0, 0, 0, 1]Camera orientation as quaternion [x, y, z, w]

A map of named curve network entities. Each entry configures how a curve network is rendered.

ParameterTypeDefaultDescription
enabledbooltrueShow/hide the curve network
radiusfloat0.003Tube radius. Range: [0, 0.1].
colorfloat[3][1, 1, 1]RGB color
materialstring"clay"clay, wax, candy, flat, mud, ceramic, jade, or normal

Each curve network can have color_quantities, scalar_quantities, vector_quantities, and covariance_quantities arrays (see Quantities).

Default curve networks: Frames, Loop closures, Trajectory

A map of named point cloud entities.

ParameterTypeDefaultDescription
enabledbooltrueShow/hide the point cloud
colorfloat[3][1, 1, 1]RGB color
point_radiusfloat0.003Point size. Range: [0, 0.1].
point_render_modestring"quad"quad, sphere, or voxel
materialstring"clay"Same material options as curve networks
edge_enabledboolfalseDraw point edges
edge_colorfloat[3][0, 0, 0]Edge RGB color
edge_widthfloat0.2Edge width. Range: [0, 3].

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

A map of named surface mesh entities.

ParameterTypeDefaultDescription
enabledbooltrueShow/hide the mesh
colorfloat[3][1, 1, 1]RGB color
edge_colorfloat[3][0, 0, 0]Wireframe edge color
edge_widthfloat1.0Wireframe edge width. Range: [0, 2].
shade_stylestring"smooth"smooth, flat, or tri flat
materialstring"clay"Same material options

Each surface mesh can have color_quantities arrays (see Quantities).

Quantities attach data visualizations to curve networks, point clouds, or surface meshes.

ParameterTypeDefaultDescription
namestring—Quantity name (must match the registered Polyscope quantity)
enabledboolfalseEnable this color quantity
ParameterTypeDefaultDescription
namestring—Quantity name
enabledboolfalseEnable this scalar quantity
color_mapstring"rainbow"viridis, coolwarm, blues, reds, ping-green, phase, spectral, rainbow, jet, turbo, or signal
map_range_modestring"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_rangefloat[2][0.10, 0.90]Quantile fractions (quantile mode) or explicit min/max limits (absolute mode)
ParameterTypeDefaultDescription
namestring—Quantity name
enabledboolfalseEnable this vector quantity
vector_radiusfloat0.003Arrow shaft radius. Range: [0, 0.1].
vector_length_scalefloat0.05Arrow length scaling. Range: [0, 0.1].
vector_colorfloat[3][1, 1, 1]Arrow RGB color
ParameterTypeDefaultDescription
namestring—Quantity name
enabledboolfalseEnable this covariance quantity
show_position_ellipsoidsbooltrueShow translational covariance ellipsoids
show_rotation_ellipsoidsboolfalseShow rotational covariance ellipsoids
show_only_lastboolfalseOnly show the most recent ellipsoid
show_every_nthint1Show every Nth ellipsoid. Must be ≥ 1.
position_scalefloat1.0Scale factor for position ellipsoids. Range: [0, 100].
rotation_scalefloat1.0Scale factor for rotation ellipsoids. Range: [0, 100].
position_ellipsoid_colorfloat[3][1, 0.5, 0]Position ellipsoid RGB color
rotation_ellipsoid_colorfloat[3][0, 0.5, 1]Rotation ellipsoid RGB color
transparencyfloat0.6Ellipsoid transparency. Range: [0, 1].