trajectory_builder_2d.lua¶

Overview¶

Configuration for 2D local SLAM (LocalTrajectoryBuilder2D). Controls range data processing, scan matching, submap creation, and pose extrapolation.

Configuration¶

TRAJECTORY_BUILDER_2D = {
  use_imu_data = true,
  min_range = 0.,
  max_range = 30.,
  min_z = -0.8,
  max_z = 2.,
  missing_data_ray_length = 5.,
  num_accumulated_range_data = 1,
  voxel_filter_size = 0.025,

  adaptive_voxel_filter = {
    max_length = 0.5,
    min_num_points = 200,
    max_range = 50.,
  },

  loop_closure_adaptive_voxel_filter = {
    max_length = 0.9,
    min_num_points = 100,
    max_range = 50.,
  },

  use_online_correlative_scan_matching = false,
  real_time_correlative_scan_matcher = {
    linear_search_window = 0.1,
    angular_search_window = math.rad(20.),
    translation_delta_cost_weight = 1e-1,
    rotation_delta_cost_weight = 1e-1,
  },

  ceres_scan_matcher = {
    occupied_space_weight = 1.,
    translation_weight = 10.,
    rotation_weight = 40.,
    ceres_solver_options = {
      use_nonmonotonic_steps = false,
      max_num_iterations = 20,
      num_threads = 1,
    },
  },

  motion_filter = {
    max_time_seconds = 5.,
    max_distance_meters = 0.2,
    max_angle_radians = math.rad(1.),
  },

  imu_gravity_time_constant = 10.,
  pose_extrapolator = {
    use_imu_based = false,
    constant_velocity = {
      imu_gravity_time_constant = 10.,
      pose_queue_duration = 0.001,
    },
    imu_based = {
      pose_queue_duration = 5.,
      gravity_constant = 9.806,
      pose_translation_weight = 1.,
      pose_rotation_weight = 1.,
      imu_acceleration_weight = 1.,
      imu_rotation_weight = 1.,
      odometry_translation_weight = 1.,
      odometry_rotation_weight = 1.,
      solver_options = {
        use_nonmonotonic_steps = false;
        max_num_iterations = 10;
        num_threads = 1;
      },
    },
  },

  submaps = {
    num_range_data = 90,
    grid_options_2d = {
      grid_type = "PROBABILITY_GRID",
      resolution = 0.05,
    },
    range_data_inserter = {
      range_data_inserter_type = "PROBABILITY_GRID_INSERTER_2D",
      probability_grid_range_data_inserter = {
        insert_free_space = true,
        hit_probability = 0.55,
        miss_probability = 0.49,
      },
      tsdf_range_data_inserter = {
        truncation_distance = 0.3,
        maximum_weight = 10.,
        update_free_space = false,
        normal_estimation_options = {
          num_normal_samples = 4,
          sample_radius = 0.5,
        },
        project_sdf_distance_to_scan_normal = true,
        update_weight_range_exponent = 0,
        update_weight_angle_scan_normal_to_ray_kernel_bandwidth = 0.5,
        update_weight_distance_cell_to_hit_kernel_bandwidth = 0.5,
      },
    },
  },
}

Parameter Reference¶

Range Data Filtering¶

Parameter	Type	Description
`use_imu_data`	bool	Fuse IMU for pose extrapolation
`min_range`	float	Ignore returns closer than this (m)
`max_range`	float	Max sensor range (m)
`min_z` / `max_z`	float	Crop point cloud by height (m)
`missing_data_ray_length`	float	Length of miss rays for free space (m)
`num_accumulated_range_data`	int	Scans to accumulate before matching
`voxel_filter_size`	float	Voxel filter resolution (m)

Adaptive Voxel Filter¶

Downsamples point clouds to target point count:

Parameter	Description
`max_length`	Max voxel size (m)
`min_num_points`	Target minimum points
`max_range`	Only affects points within this range

Two instances: adaptive_voxel_filter (local SLAM) and loop_closure_adaptive_voxel_filter (loop closure).

Scan Matching¶

Real-Time Correlative Scan Matcher¶

Coarse search for initial alignment:

Parameter	Description
`linear_search_window`	Translation search radius (m)
`angular_search_window`	Rotation search range (rad)
`translation_delta_cost_weight`	Cost weight for translation
`rotation_delta_cost_weight`	Cost weight for rotation

Enabled via use_online_correlative_scan_matching = true.

Ceres Scan Matcher¶

Fine gradient-based optimization:

Parameter	Description
`occupied_space_weight`	Weight for occupied cells
`translation_weight`	Prior weight on translation
`rotation_weight`	Prior weight on rotation
`ceres_solver_options`	Ceres solver config

Motion Filter¶

Throttles range data insertion to avoid redundant work:

Parameter	Description
`max_time_seconds`	Max time between insertions
`max_distance_meters`	Max translation between insertions
`max_angle_radians`	Max rotation between insertions

Insertion occurs if any threshold exceeded.

Pose Extrapolator¶

Predicts pose at sensor timestamps:

Option	Description
`use_imu_based`	Use IMU integration (vs constant velocity)
`constant_velocity`	Constant velocity model params
`imu_based`	IMU integration params

IMU-based params:

pose_queue_duration — Buffer duration for IMU data (s)
gravity_constant — Gravity magnitude (m/s²)
*_weight — Cost function weights for optimization
solver_options — Ceres config for optimization

Submaps¶

Parameter	Description
`num_range_data`	Insertions per submap
`grid_options_2d.grid_type`	`PROBABILITY_GRID` or `TSDF`
`grid_options_2d.resolution`	Grid resolution (m)

Range Data Inserter¶

Probability Grid Inserter:

insert_free_space — Ray-cast free space
hit_probability — Occupancy update for hits
miss_probability — Occupancy update for misses

TSDF Inserter:

truncation_distance — TSDF truncation (m)
maximum_weight — Max fusion weight
update_free_space — Update free space voxels
normal_estimation_options — Surface normal params

Tuning Guide¶

For Large Environments¶

Increase max_range
Increase submaps.num_range_data (larger submaps)
Increase real_time_correlative_scan_matcher.linear_search_window

For Noisy Sensors¶

Increase voxel_filter_size
Decrease adaptive_voxel_filter.min_num_points
Increase ceres_scan_matcher.occupied_space_weight

For Fast Motion¶

Decrease motion_filter thresholds
Enable use_imu_data and pose_extrapolator.use_imu_based
Decrease pose_extrapolator.imu_based.pose_queue_duration