Skip to content

slamlab_core

The slamlab_core section configures the SLAM pipeline: point cloud preprocessing, ICP registration against local and prior maps, trajectory estimation, and output artifacts.

The following parameters apply to the original incoming point clouds.

ParameterTypeDefaultDescription
dirpathstring""Directory for the original (raw, non-deskewed) sensor-frame clouds; wiped and recreated on every run (required if save_clouds or loop_closure_detection is enabled)
ParameterTypeDefaultDescription
enabledboolfalseFilter points by distance from sensor origin
min_distancefloat0.0Minimum distance in meters
max_distancefloat.infMaximum distance in meters
ParameterTypeDefaultDescription
enabledboolfalseFilter points by intensity
min_intensityint320Minimum intensity
max_intensityint322147483647Maximum intensity
ParameterTypeDefaultDescription
enabledboolfalseFiltering of rows and columns of an organized point cloud
row_intervaluint321Sample every Nth row
col_intervaluint321Sample every Nth column

For unorganized point clouds, the cloud is interpreted as N x 1 (N rows, 1 column). In that case, row_interval performs index-based subsampling (for example, row_interval=2 keeps every second point), while col_interval is ignored.

ParameterTypeDefaultDescription
enabledboolfalseVoxel-based downsampling - keeps one point per voxel
voxel_sizefloat0.1Voxel grid size in meters
methodstringfirstWhich point to keep per voxel: first (lowest-index point; depends on input point order), centroid (voxel mean position, order-independent), or centroid_nn (the real point nearest the centroid)
ParameterTypeDefaultDescription
enabledboolfalseEstimate surface normals for organized point clouds using a local neighborhood
kernel_widthuint323Kernel width (must be odd, ≥ 3)
kernel_heightuint323Kernel height (must be odd, ≥ 3)
max_roughnessfloat0.2Max roughness to accept a normal
ParameterTypeDefaultDescription
voxel_sizefloat1.0Voxel size for plane extraction in meters
min_planarityfloat0.0Minimum planarity (0 = line-like, 1 = plane)
max_roughnessfloat0.1Maximum roughness to accept as plane

ParameterTypeDefaultDescription
cloud_to_local_mapbooltrueMatch incoming point clouds against local map
cloud_to_prior_mapboolfalseAlso match against a given prior map

At least one must be true (unless IMU measurements are provided).


ParameterTypeDefaultDescription
map_growsbooltrueMap grows over time; if false, map resets each iteration
map_radiusfloat20.0Radius around current pose to keep point clouds (meters, 0 = no limit)
min_distance_between_cloud_originsfloat1.0Min distance before adding a new point cloud to the map (meters)
ParameterTypeDefaultDescription
min_planarityfloat0.25Minimum planarity for plane detection
max_roughnessfloat0.15Maximum roughness
min_num_points_per_planeuint321Minimum points per plane

ParameterTypeDefaultDescription
filepathstring""Path to external voxel PCA map file (.voxelpca)
min_distance_between_cloud_originsfloat5.0Only re-match after moving this distance (meters)

Only used when matching.cloud_to_prior_map is true. If enabled, filepath must not be empty.


ParameterTypeDefaultDescription
max_iterationsuint325Max ICP iterations per point cloud
loss_functionstring"trivial_loss"Robust loss function (see below)
solverstring"ceres"Per-iteration point-to-plane solver (see below).
max_point_to_plane_distancefloat0.4Reject plane correspondences exceeding this distance (meters)
max_angle_between_normalsfloat45.0Reject pairs with normals differing more than this (degrees)
correspondences_max_weightfloat1000.0Maximum weight per correspondence
sigma_mad_limitfloat.infSigma-MAD outlier rejector on per-correspondence point-to-plane distances. Drops correspondences whose distance is farther from the median than sigma_mad_limit * 1.4826 * MAD. .inf disables; 4.0 is a typical robust setting.
sigma_mad_skip_iterationsuint323Initial ICP iterations to skip before sigma-MAD kicks in (a still-misaligned pose makes the median unreliable).
cache_mov_voxel_pcaboolfalseHow the moving cloud’s VoxelPCA is updated during ICP. false rebuilds it from scratch each iteration. true builds it once and reuses it (mapping centroids via the current pose), which is faster but freezes the voxel grouping at the initial pose — biased if the initial misalignment exceeds ~half a voxel.

loss_function options: trivial_loss, huber_loss, soft_l_one_loss, cauchy_loss, arctan_loss, tukey_loss

solver options:

  • ceres — point-to-plane minimization via a Ceres problem (autodiff + Levenberg-Marquardt). The reference implementation.
  • irls — hand-rolled robustified Gauss-Newton on the 6×6 normal equations. The selected loss_function is applied as an IRLS weight using the same Ceres loss derivative, so the converged transform and covariance match ceres for every loss, while the per-iteration solve is roughly an order of magnitude faster. Recommended.

Both solvers honour loss_function and loss_function_scale; the choice only changes how the minimization is carried out, not the result.


ParameterTypeDefaultDescription
enabledboolfalseEnable loop closure detection
methodstring"kiss_matcher_plus_icp"Method used to estimate the relative pose between the key point clouds of a candidate pair. icp_only runs a single step, the ICP refinement, starting from the relative pose of the current trajectory, which requires the drift to be small enough for ICP to converge. kiss_matcher_plus_icp runs two steps: KISS-Matcher first estimates a rough transform from the point clouds themselves, independent of the trajectory, and ICP then refines it.
filter_key_cloudsbooltrueApply the clouds filters (distance/intensity/stride/voxel) to key point clouds when they are loaded for a loop closure attempt
min_distance_between_key_cloud_originsfloat1.0Min distance between key point cloud origins (meters)
num_merged_key_cloudsuint321Number of consecutive key point clouds merged around each endpoint of a candidate pair before registration. Must be odd. 1 merges nothing and registers the two key point clouds directly. See below.
drain_pending_attempts_on_stopboolfalseWhen the offline pipeline finishes, synchronously evaluate any key-cloud pair candidates the background thread did not get to. Useful for sequences that genuinely close their loop very close to the last frame (e.g. kitti seq 09), where the asynchronous detector would otherwise be torn down before the pair is tried. Leave false for open trajectories and sequences whose live ICP has drifted, since draining can find spurious matches and corrupt the smoother.
sleep_between_attempts_secfloat1.0Pause of the background thread before each loop closure attempt (seconds). A shorter pause gives more attempts per second of sensor data, which helps on short sequences. The number of loop closures that are available before each pose graph update then depends more on the machine load, so results can vary from run to run.

Key point clouds are stored as raw (non-deskewed) sensor-frame clouds in the clouds.dirpath store; when a loop closure attempt loads them, they are optionally filtered and always deskewed with the current trajectory (densified with IMU measurements when available).

With num_merged_key_clouds > 1, each endpoint of a candidate pair is registered as a small submap instead of a single scan. For num_merged_key_clouds: 5, each endpoint is merged with its two preceding and two following key point clouds — not the neighbouring cloud indices, since consecutive key point clouds are min_distance_between_key_cloud_origins apart and many clouds lie in between. Each window is merged into the frame of its center, the two merged clouds are registered, and the resulting relative pose is attributed to the two center key point clouds. Every member is loaded, filtered and deskewed with the current trajectory, so the merge reflects the latest state estimate.

The window spans roughly num_merged_key_clouds * min_distance_between_key_cloud_origins meters — tune the two together. A key point cloud only becomes a pair endpoint once it has its (num_merged_key_clouds - 1) / 2 newer neighbours, which delays detection by that many key point clouds; drain_pending_attempts_on_stop relaxes this at the end of the sequence and uses whatever neighbours are available. At the start of the sequence the window is clipped instead of delayed, since no older neighbours will ever follow.

Merged clouds cover more of the scene, so the kiss_matcher inlier thresholds and the ICP correspondence count become easier to reach: raise them when raising num_merged_key_clouds.

ICP orients normals towards a single view point per endpoint, the origin of the center key point cloud. Members scanned from other origins can therefore get an inverted normal, which costs valid correspondences during registration. The effect grows with the span of the window, so keep num_merged_key_clouds * min_distance_between_key_cloud_origins small relative to the sensor range.

ParameterTypeDefaultDescription
max_distancefloat15.0Max distance between origins to consider as loop (meters)
min_time_differencefloat20.0Min time between key point clouds for loop closure (seconds)
ParameterTypeDefaultDescription
min_num_rotation_inliersuint3250A candidate pair must produce at least this many feature correspondences agreeing on the KISS-Matcher–estimated rotation, otherwise the rough alignment is rejected before ICP. Lower to admit looser loop closures (e.g. geometrically sparse scenes) at the cost of more false positives reaching the ICP step.
min_num_translation_inliersuint3250Same as above but for translation inliers.

Only used with method: kiss_matcher_plus_icp.

ParameterTypeDefaultDescription
num_correspondences_acceptance_thresholduint32100The refining ICP must end with at least this many correspondences, otherwise the pair is rejected and no loop closure factor is added. Raise to reject weakly overlapping pairs, lower to admit loop closures in sparse scenes at the cost of more false positives. Scale it with num_merged_key_clouds, which enlarges the registered clouds.

ParameterTypeDefaultDescription
clamp_pose_covariance_eigenvalues_tofloat1.0e-6Floor for the eigenvalues of every 6×6 pose covariance before it becomes a GTSAM noise model — ICP against the local map, ICP against the prior map, loop closures, and the initial_base_pose prior alike (a sigma tighter than the floor is widened to it). Guards the smoother against numerical issues when a measurement claims a near-zero uncertainty. The value is a variance, so the default 1e-6 corresponds to a std-dev of 1 mm (translation) / ~1 mrad (rotation). Set to 0 to accept the covariances as they are — appropriate for well-conditioned poses where the floor would artificially inflate them.
factorizationstringcholeskyFactorization of the linearized problem in the smoother: cholesky or qr. Both give practically identical trajectories. cholesky is faster and needs less memory; qr is numerically more robust, but needs about 60 % more memory for the trajectory estimation.
ParameterTypeDefaultDescription
enabledboolfalseUse fixed-lag smoother instead of full batch optimization
lagfloat60.0Optimization window size in seconds

Cannot be enabled simultaneously with loop_closure_detection.

ParameterTypeDefaultDescription
accelerometer_sigmafloat1.0Accelerometer noise std dev (m/s²)
gyroscope_sigmafloat1.0Gyroscope noise std dev (rad/s)
integration_sigmafloat1.0Integration error std dev (must be > 0)
accelerometer_bias_sigmafloat1.0Accelerometer bias random walk (m/s³)
gyroscope_bias_sigmafloat1.0Gyroscope bias random walk (rad/s²)
average_delta_tfloat0.0Expected IMU interval in seconds (0 = auto-detect)
acceleration_unit_is_gboolfalseIf true, accelerometer data is in g units
add_imu_factors_after_secfloat0.0Seconds to wait before IMU measurements are added as factors to the GTSAM trajectory graph. 0 integrates from the first cloud onwards; a non-zero value lets the IMU bias / orientation warm up before being trusted (useful when the platform is stationary at start-up).
ParameterTypeDefaultDescription
previous_cloud_idx_offsetuint3220How many point clouds back to search for measurements
interpolation_max_time_diff_secfloat0.5Max time difference for interpolation (seconds)
min_elapsed_time_since_last_added_measurement_secfloat0.5Time gate between measurements (seconds)
min_distance_to_last_added_measurementfloat5.0Distance gate between measurements (meters)

Array of sensor-to-base transforms:

ParameterTypeDefaultDescription
framestring"lidar"Sensor frame name
base_T_frame.translationfloat[3][0, 0, 0]Translation x, y, z (meters)
base_T_frame.rotationfloat[4][0, 0, 0, 1]Quaternion qx, qy, qz, qw
ParameterTypeDefaultDescription
translationfloat[3][0, 0, 0]Starting position x, y, z (meters)
rotationfloat[4][0, 0, 0, 1]Starting orientation qx, qy, qz, qw

ParameterTypeDefaultDescription
enabledbooltrueSave trajectory and optional point cloud artifacts
dirpathstring""Output directory (required if enabled)
save_densified_trajectorybooltrueDensify the final trajectory to IMU rate using all received IMU measurements before writing the trajectory files (without IMU measurements, the estimated states are written)
estimate_pose_covariancesboolfalseEstimate the final marginal covariance of all poses and write it to trajectory_complete.csv and trajectory.geojson. Without it, no covariances are written. With the fixed-lag smoother, only poses in the last window get a covariance (zero otherwise); densified poses between estimated states have a zero covariance. The 6x6 covariance is ordered [rx, ry, rz, tx, ty, tz] (rotation first, in the local pose frame), i.e. cov_00 is the roll variance
ParameterTypeDefaultDescription
enabledboolfalseSave individual registered point clouds to disk, as LAZ files (see point cloud file formats)
generate_prior_mapboolfalseGenerate a prior map from saved point clouds

When enabled, the following filters can be applied independently to saved point clouds (same structure as clouds filters above):

  • distance_filter — {enabled, min_distance, max_distance}
  • intensity_filter — {enabled, min_intensity, max_intensity}
  • stride_filter — {enabled, row_interval, col_interval}
  • normal_estimation — {enabled, kernel_width, kernel_height}
ParameterTypeDefaultDescription
raw_distanceboolfalseWrite a per-point raw_distance attribute: the range of the point from the sensor origin in meters
ParameterTypeDefaultDescription
enabledboolfalseSplit saved point clouds into spatial tiles
tile_sizeint[3][50, 50, 50]Tile size in x, y, z (meters). Use 0 for an axis to disable tiling along it (e.g. [40, 0, 40] tiles only in the horizontal plane).
voxel_filter.enabledboolfalseApply voxel filter to tiles
voxel_filter.voxel_sizefloat0.1Voxel size for tile downsampling (meters)
voxel_filter.methodstringfirstPoint kept per voxel: first, centroid, or centroid_nn (see clouds.voxel_filter.method)

ParameterTypeDefaultDescription
enabledboolfalseSave intermediate processing stages
dirpathstring""Debug output directory (required if enabled)

ParameterTypeDefaultDescription
enabledbooltrueSend real-time data to slamlab-visualization. The SLAM process binds the connection ports on all interfaces; the visualization connects out to it (see slamlab_visualization.slam_host)