# cartographer/mapping/proto/map_builder_options.proto

## Overview

`MapBuilderOptions` is the top-level configuration message for the SLAM system, passed to the `MapBuilder` constructor. It selects the SLAM mode (2D or 3D), controls background thread usage, embeds the pose graph options, and chooses the sensor collation strategy. The message is populated from the `map_builder.lua` configuration file.

## Message Structure

```protobuf
message MapBuilderOptions {
  bool use_trajectory_builder_2d = 1;
  bool use_trajectory_builder_3d = 2;

  // Number of threads to use for background computations.
  int32 num_background_threads = 3;
  PoseGraphOptions pose_graph_options = 4;
  // Sort sensor input independently for each trajectory.
  bool collate_by_trajectory = 5;
}
```

| Field | Type | Meaning |
|-------|------|---------|
| `use_trajectory_builder_2d` | bool | Enable 2D SLAM (trajectory builders and pose graph run 2D) |
| `use_trajectory_builder_3d` | bool | Enable 3D SLAM (trajectory builders and pose graph run 3D) |
| `num_background_threads` | int32 | Thread count for the background thread pool (scan matching, constraint building, optimization) |
| `pose_graph_options` | `PoseGraphOptions` | Options for the pose graph (optimization schedule, constraint builder, matchers, etc.) |
| `collate_by_trajectory` | bool | If true, collate sensor input independently per trajectory (`TrajectoryCollator`); otherwise use a single `Collator` |

### PoseGraphOptions

`PoseGraphOptions` (from `pose_graph_options.proto`) bundles the pose graph configuration: the optimization problem type and optimization schedule, matcher resolution/matching thresholds, `constraint_builder_options`, the loop-closure translation/rotation weights, `max_num_final_iterations`, the global localization strategy, and the initial/final pose graph log output flags.

## Configuration

From `map_builder.lua`:

```lua
MAP_BUILDER = {
  use_trajectory_builder_2d = false,
  use_trajectory_builder_3d = true,
  num_background_threads = 4,
  pose_graph = {
    optimize_every_n_nodes = 3,
    ...
  },
  collate_by_trajectory = false,
}
```

Exactly one of `use_trajectory_builder_2d` / `use_trajectory_builder_3d` must be enabled; the corresponding pose graph implementation is instantiated accordingly.

## Role in the SLAM Pipeline

`MapBuilder::MapBuilder` reads these options to:

1. Create the background `ThreadPool` with `num_background_threads`.
2. Instantiate `PoseGraph2D` or `PoseGraph3D` from `pose_graph_options`.
3. Build the sensor collator: a single `Collator` when `collate_by_trajectory` is false, or a `TrajectoryCollator` when true.
4. Select the 2D or 3D trajectory builder factory when trajectories are added.

## See Also

- [MapBuilder](../map_builder.md) — Consumes these options
- [MapBuilderOptions Lua config](../../configuration_files/map_builder.md) — `map_builder.lua` reference
- [CollatorInterface](../../sensor/collator_interface.md) — Chosen based on `collate_by_trajectory`
- [PoseGraphInterface](../pose_graph_interface.md) — Pose graph configured by `pose_graph_options`