# cartographer/configuration_files/trajectory_builder_2d.lua

## Overview

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

## Configuration

```lua
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`

## See Also

- [TrajectoryBuilderInterface](../mapping/trajectory_builder_interface.md) — Local SLAM implementation
- [ImuBasedPoseExtrapolator](../sensor/imu_data.md) — IMU integration