# cartographer/configuration_files/map_builder.lua

## Overview

Top-level configuration for the `MapBuilder`. Selects 2D vs 3D SLAM, sets background thread count, and references pose graph configuration.

## Configuration

```lua
include "pose_graph.lua"

MAP_BUILDER = {
  use_trajectory_builder_2d = false,
  use_trajectory_builder_3d = false,
  num_background_threads = 4,
  pose_graph = POSE_GRAPH,
  collate_by_trajectory = false,
}
```

## Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `use_trajectory_builder_2d` | bool | `false` | Enable 2D SLAM (lidar + IMU/odometry) |
| `use_trajectory_builder_3d` | bool | `false` | Enable 3D SLAM (3D lidar + IMU/odometry) |
| `num_background_threads` | int | `4` | Threads for scan matching & optimization |
| `pose_graph` | table | `POSE_GRAPH` | Global optimization config (from pose_graph.lua) |
| `collate_by_trajectory` | bool | `false` | Collate sensor data per trajectory vs globally |

## Usage

Exactly one of `use_trajectory_builder_2d` or `use_trajectory_builder_3d` must be `true`.

### 2D SLAM Example

```lua
include "trajectory_builder_2d.lua"
include "pose_graph.lua"

MAP_BUILDER = {
  use_trajectory_builder_2d = true,
  use_trajectory_builder_3d = false,
  num_background_threads = 4,
  pose_graph = POSE_GRAPH,
  collate_by_trajectory = false,
}
```

### 3D SLAM Example

```lua
include "trajectory_builder_3d.lua"
include "pose_graph.lua"

MAP_BUILDER = {
  use_trajectory_builder_2d = false,
  use_trajectory_builder_3d = true,
  num_background_threads = 7,
  pose_graph = POSE_GRAPH,
  collate_by_trajectory = false,
}
```

## Multi-Session / Multi-Robot

For multiple trajectories (multi-session or multi-robot):

```lua
MAP_BUILDER = {
  use_trajectory_builder_2d = true,
  num_background_threads = 8,
  pose_graph = POSE_GRAPH,
  collate_by_trajectory = true,  -- Separate collator per trajectory
}
```

When `collate_by_trajectory = true`, each trajectory gets its own sensor collator, allowing different sensor configurations per trajectory.

## Thread Count Guidelines

| Platform | Recommended |
|----------|-------------|
| Desktop (8+ cores) | 4-7 |
| Laptop (4 cores) | 2-3 |
| Embedded (2 cores) | 1 |
| Single-threaded | 0 (synchronous) |

## See Also

- [trajectory_builder_2d.lua](trajectory_builder_2d.md) — 2D local SLAM config
- [trajectory_builder_3d.lua](trajectory_builder_3d.md) — 3D local SLAM config
- [pose_graph.lua](pose_graph.md) — Global optimization config
- [MapBuilder](../mapping/map_builder.md) — Uses this configuration