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.
| Parameter | Type | Default | Description |
|---|
dirpath | string | "" | 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) |
| Parameter | Type | Default | Description |
|---|
enabled | bool | false | Filter points by distance from sensor origin |
min_distance | float | 0.0 | Minimum distance in meters |
max_distance | float | .inf | Maximum distance in meters |
| Parameter | Type | Default | Description |
|---|
enabled | bool | false | Filter points by intensity |
min_intensity | int32 | 0 | Minimum intensity |
max_intensity | int32 | 2147483647 | Maximum intensity |
| Parameter | Type | Default | Description |
|---|
enabled | bool | false | Filtering of rows and columns of an organized point cloud |
row_interval | uint32 | 1 | Sample every Nth row |
col_interval | uint32 | 1 | Sample 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.
| Parameter | Type | Default | Description |
|---|
enabled | bool | false | Voxel-based downsampling - keeps one point per voxel |
voxel_size | float | 0.1 | Voxel grid size in meters |
method | string | first | Which 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) |
| Parameter | Type | Default | Description |
|---|
enabled | bool | false | Estimate surface normals for organized point clouds using a local neighborhood |
kernel_width | uint32 | 3 | Kernel width (must be odd, ≥ 3) |
kernel_height | uint32 | 3 | Kernel height (must be odd, ≥ 3) |
max_roughness | float | 0.2 | Max roughness to accept a normal |
| Parameter | Type | Default | Description |
|---|
voxel_size | float | 1.0 | Voxel size for plane extraction in meters |
min_planarity | float | 0.0 | Minimum planarity (0 = line-like, 1 = plane) |
max_roughness | float | 0.1 | Maximum roughness to accept as plane |
| Parameter | Type | Default | Description |
|---|
cloud_to_local_map | bool | true | Match incoming point clouds against local map |
cloud_to_prior_map | bool | false | Also match against a given prior map |
At least one must be true (unless IMU measurements are provided).
| Parameter | Type | Default | Description |
|---|
map_grows | bool | true | Map grows over time; if false, map resets each iteration |
map_radius | float | 20.0 | Radius around current pose to keep point clouds (meters, 0 = no limit) |
min_distance_between_cloud_origins | float | 1.0 | Min distance before adding a new point cloud to the map (meters) |
| Parameter | Type | Default | Description |
|---|
min_planarity | float | 0.25 | Minimum planarity for plane detection |
max_roughness | float | 0.15 | Maximum roughness |
min_num_points_per_plane | uint32 | 1 | Minimum points per plane |
| Parameter | Type | Default | Description |
|---|
filepath | string | "" | Path to external voxel PCA map file (.voxelpca) |
min_distance_between_cloud_origins | float | 5.0 | Only re-match after moving this distance (meters) |
Only used when matching.cloud_to_prior_map is true. If enabled, filepath must not be empty.
| Parameter | Type | Default | Description |
|---|
max_iterations | uint32 | 5 | Max ICP iterations per point cloud |
loss_function | string | "trivial_loss" | Robust loss function (see below) |
solver | string | "ceres" | Per-iteration point-to-plane solver (see below). |
max_point_to_plane_distance | float | 0.4 | Reject plane correspondences exceeding this distance (meters) |
max_angle_between_normals | float | 45.0 | Reject pairs with normals differing more than this (degrees) |
correspondences_max_weight | float | 1000.0 | Maximum weight per correspondence |
sigma_mad_limit | float | .inf | Sigma-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_iterations | uint32 | 3 | Initial ICP iterations to skip before sigma-MAD kicks in (a still-misaligned pose makes the median unreliable). |
cache_mov_voxel_pca | bool | false | How 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.
| Parameter | Type | Default | Description |
|---|
enabled | bool | false | Enable loop closure detection |
method | string | "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_clouds | bool | true | Apply 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_origins | float | 1.0 | Min distance between key point cloud origins (meters) |
num_merged_key_clouds | uint32 | 1 | Number 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_stop | bool | false | When 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_sec | float | 1.0 | Pause 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.
| Parameter | Type | Default | Description |
|---|
max_distance | float | 15.0 | Max distance between origins to consider as loop (meters) |
min_time_difference | float | 20.0 | Min time between key point clouds for loop closure (seconds) |
| Parameter | Type | Default | Description |
|---|
min_num_rotation_inliers | uint32 | 50 | A 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_inliers | uint32 | 50 | Same as above but for translation inliers. |
Only used with method: kiss_matcher_plus_icp.
| Parameter | Type | Default | Description |
|---|
num_correspondences_acceptance_threshold | uint32 | 100 | The 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. |
| Parameter | Type | Default | Description |
|---|
clamp_pose_covariance_eigenvalues_to | float | 1.0e-6 | Floor 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. |
factorization | string | cholesky | Factorization 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. |
| Parameter | Type | Default | Description |
|---|
enabled | bool | false | Use fixed-lag smoother instead of full batch optimization |
lag | float | 60.0 | Optimization window size in seconds |
Cannot be enabled simultaneously with loop_closure_detection.
| Parameter | Type | Default | Description |
|---|
accelerometer_sigma | float | 1.0 | Accelerometer noise std dev (m/s²) |
gyroscope_sigma | float | 1.0 | Gyroscope noise std dev (rad/s) |
integration_sigma | float | 1.0 | Integration error std dev (must be > 0) |
accelerometer_bias_sigma | float | 1.0 | Accelerometer bias random walk (m/s³) |
gyroscope_bias_sigma | float | 1.0 | Gyroscope bias random walk (rad/s²) |
average_delta_t | float | 0.0 | Expected IMU interval in seconds (0 = auto-detect) |
acceleration_unit_is_g | bool | false | If true, accelerometer data is in g units |
add_imu_factors_after_sec | float | 0.0 | Seconds 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). |
| Parameter | Type | Default | Description |
|---|
previous_cloud_idx_offset | uint32 | 20 | How many point clouds back to search for measurements |
interpolation_max_time_diff_sec | float | 0.5 | Max time difference for interpolation (seconds) |
min_elapsed_time_since_last_added_measurement_sec | float | 0.5 | Time gate between measurements (seconds) |
min_distance_to_last_added_measurement | float | 5.0 | Distance gate between measurements (meters) |
Array of sensor-to-base transforms:
| Parameter | Type | Default | Description |
|---|
frame | string | "lidar" | Sensor frame name |
base_T_frame.translation | float[3] | [0, 0, 0] | Translation x, y, z (meters) |
base_T_frame.rotation | float[4] | [0, 0, 0, 1] | Quaternion qx, qy, qz, qw |
| Parameter | Type | Default | Description |
|---|
translation | float[3] | [0, 0, 0] | Starting position x, y, z (meters) |
rotation | float[4] | [0, 0, 0, 1] | Starting orientation qx, qy, qz, qw |
| Parameter | Type | Default | Description |
|---|
enabled | bool | true | Save trajectory and optional point cloud artifacts |
dirpath | string | "" | Output directory (required if enabled) |
save_densified_trajectory | bool | true | Densify 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_covariances | bool | false | Estimate 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 |
| Parameter | Type | Default | Description |
|---|
enabled | bool | false | Save individual registered point clouds to disk, as LAZ files (see point cloud file formats) |
generate_prior_map | bool | false | Generate 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}
| Parameter | Type | Default | Description |
|---|
raw_distance | bool | false | Write a per-point raw_distance attribute: the range of the point from the sensor origin in meters |
| Parameter | Type | Default | Description |
|---|
enabled | bool | false | Split saved point clouds into spatial tiles |
tile_size | int[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.enabled | bool | false | Apply voxel filter to tiles |
voxel_filter.voxel_size | float | 0.1 | Voxel size for tile downsampling (meters) |
voxel_filter.method | string | first | Point kept per voxel: first, centroid, or centroid_nn (see clouds.voxel_filter.method) |
| Parameter | Type | Default | Description |
|---|
enabled | bool | false | Save intermediate processing stages |
dirpath | string | "" | Debug output directory (required if enabled) |
| Parameter | Type | Default | Description |
|---|
enabled | bool | true | Send 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) |