# cartographer/mapping/trajectory_builder_interface.h

## Overview

`TrajectoryBuilderInterface` defines the interface for local SLAM — constructing submaps from sensor data and producing pose estimates. Separate implementations exist for 2D (`LocalTrajectoryBuilder2D`) and 3D (`LocalTrajectoryBuilder3D`).

## Class: `cartographer::mapping::TrajectoryBuilderInterface`

### Types

#### `SensorId`

```cpp
using SensorId = std::pair<std::string /*type*/, std::string /*id*/>;
```

Identifies a sensor. Type is one of: `"rangefinder"`, `"imu"`, `"odometer"`, `"fixed_frame_pose"`, `"landmark"`.

#### `LocalSlamResultCallback`

```cpp
using LocalSlamResultCallback =
    std::function<void(const LocalSlamResultData&)>;
```

Called when local SLAM produces a result (submap insertion, pose estimate).

#### `LocalSlamResultData`

```cpp
struct LocalSlamResultData {
  int trajectory_id;
  common::Time time;
  transform::Rigid3d local_pose;
  sensor::RangeData range_data_in_local;
  std::vector<std::shared_ptr<const Submap>> submaps;
};
```

Contains the local SLAM result: trajectory ID, timestamp, estimated pose in local map frame, range data transformed to local frame, and updated submaps.

### Pure Virtual Methods

#### `AddSensorData`

```cpp
virtual void AddSensorData(const std::string& sensor_id,
                           std::unique_ptr<Data> data) = 0;
```

Adds sensor data to the trajectory builder. The data is dispatched based on its type (rangefinder, IMU, odometry, etc.).

**Sensor Data Types:**
- `sensor::RangeData` — Lidar/scan data (origin, returns, misses)
- `sensor::ImuData` — IMU measurements (linear acceleration, angular velocity)
- `sensor::OdometryData` — Odometry pose
- `sensor::FixedFramePoseData` — Pose in a fixed frame (e.g., GPS)
- `sensor::LandmarkData` — Landmark observations

#### `AddLocalSlamResultData`

```cpp
virtual void AddLocalSlamResultData(
    std::unique_ptr<LocalSlamResultData> local_slam_result_data) = 0;
```

Used for deserialization: injects pre-computed local SLAM results.

## 2D Implementation: `LocalTrajectoryBuilder2D`

Located in `internal/2d/local_trajectory_builder_2d.h/.cc`.

### Configuration (`TrajectoryBuilderOptions2D`)

Key parameters (from `trajectory_builder_2d.lua`):

| Parameter | Description |
|-----------|-------------|
| `use_imu_data` | Fuse IMU data for pose extrapolation |
| `min_range` / `max_range` | Rangefinder min/max range (meters) |
| `voxel_filter_size` | Voxel filter for point cloud downsampling |
| `adaptive_voxel_filter` | Adaptive filter for variable density scans |
| `real_time_correlative_scan_matcher` | Correlative scan matching config |
| `ceres_scan_matcher` | Ceres-based scan matching config |
| `motion_filter` | Throttles sensor data insertion |
| `submaps` | Submap configuration (count, resolution, inserter) |
| `pose_extrapolator` | Pose extrapolation (constant velocity or IMU-based) |

### Algorithm Flow

1. **Sensor Data Reception** — Data arrives via `AddSensorData`, collated by sensor type
2. **Range Data Processing** — Accumulates `num_accumulated_range_data` scans, applies voxel filtering
3. **Scan Matching** — Matches current scan against local submap:
   - Real-time correlative scan matcher (coarse)
   - Ceres scan matcher (fine, gradient-based optimization)
4. **Submap Insertion** — Inserts matched range data into current submap
5. **Submap Creation** — Creates new submap after `num_range_data` insertions
6. **Pose Extrapolation** — Predicts pose between sensor updates using IMU or constant velocity model

## 3D Implementation: `LocalTrajectoryBuilder3D`

Located in `internal/3d/local_trajectory_builder_3d.h/.cc`.

### Configuration (`TrajectoryBuilderOptions3D`)

Key parameters (from `trajectory_builder_3d.lua`):

| Parameter | Description |
|-----------|-------------|
| `min_range` / `max_range` | Range limits |
| `voxel_filter_size` | Initial voxel filter |
| `high_resolution_adaptive_voxel_filter` | For local scan matching |
| `low_resolution_adaptive_voxel_filter` | For loop closure |
| `real_time_correlative_scan_matcher` | 3D correlative matching |
| `ceres_scan_matcher` | 3D Ceres matching (supports intensity) |
| `motion_filter` | Data throttling |
| `rotational_histogram_size` | For rotational scan matching |
| `submaps` | Hybrid grid submaps (high/low resolution) |
| `use_intensities` | Enable intensity-based matching |

### Algorithm Flow

Similar to 2D but with 3D-specific components:
1. **Point Cloud Accumulation** — Accumulates multiple scans for denser point clouds
2. **Voxel Filtering** — Multi-resolution filtering (high-res for local, low-res for global)
3. **Scan Matching** — 3D Ceres with optional intensity cost function
4. **Hybrid Grid Submaps** — High-res (near) + low-res (far) voxel grids
5. **Rotational Scan Matcher** — Optional rotation-only optimization

## Usage

```cpp
// Typically created via MapBuilder::AddTrajectoryBuilder
auto* traj_builder = map_builder->GetTrajectoryBuilder(traj_id);

// Add rangefinder data
auto range_data = sensor::RangeData{origin, returns, misses};
auto dispatchable = sensor::MakeDispatchable("laser", time, range_data);
traj_builder->AddSensorData("laser", std::move(dispatchable));

// Add IMU data
auto imu_data = sensor::ImuData{time, linear_acceleration, angular_velocity};
traj_builder->AddSensorData("imu", sensor::MakeDispatchable("imu", time, imu_data));
```

## See Also

- [MapBuilder](map_builder.md) — Creates trajectory builders
- [Submaps](submaps.md) — Submap representation