# cartographer/mapping/map_builder_interface.h

## Overview

`MapBuilderInterface` defines the abstract interface for the top-level SLAM system. Both the library implementation (`MapBuilder`) and RPC implementations (e.g., for distributed SLAM) implement this interface.

## Class: `cartographer::mapping::MapBuilderInterface`

### Types

#### `LocalSlamResultCallback`

```cpp
using LocalSlamResultCallback = TrajectoryBuilderInterface::LocalSlamResultCallback;
```

Callback invoked when local SLAM produces a result. Signature:
```cpp
void(const TrajectoryBuilderInterface::LocalSlamResultData& data);
```

#### `SensorId`

```cpp
using SensorId = TrajectoryBuilderInterface::SensorId;
```

Sensor identifier: `std::pair<std::string /*type*/, std::string /*id*/>`. Types include `"rangefinder"`, `"imu"`, `"odometer"`, `"fixed_frame_pose"`, `"landmark"`.

### Pure Virtual Methods

#### `AddTrajectoryBuilder`

```cpp
virtual int AddTrajectoryBuilder(
    const std::set<SensorId>& expected_sensor_ids,
    const proto::TrajectoryBuilderOptions& trajectory_options,
    LocalSlamResultCallback local_slam_result_callback) = 0;
```

Creates a new trajectory for live SLAM. Returns trajectory ID.

#### `AddTrajectoryForDeserialization`

```cpp
virtual int AddTrajectoryForDeserialization(
    const proto::TrajectoryBuilderOptionsWithSensorIds&
        options_with_sensor_ids_proto) = 0;
```

Creates a trajectory placeholder for loading serialized state.

#### `GetTrajectoryBuilder`

```cpp
virtual mapping::TrajectoryBuilderInterface* GetTrajectoryBuilder(
    int trajectory_id) const = 0;
```

Returns trajectory builder or `nullptr` if none exists for this ID.

#### `FinishTrajectory`

```cpp
virtual void FinishTrajectory(int trajectory_id) = 0;
```

Marks trajectory as finished. No more sensor data accepted.

#### `SubmapToProto`

```cpp
virtual std::string SubmapToProto(const SubmapId& submap_id,
                                  proto::SubmapQuery::Response* response) = 0;
```

Fills submap data for visualization.

#### `SerializeState`

```cpp
virtual void SerializeState(bool include_unfinished_submaps,
                            io::ProtoStreamWriterInterface* writer) = 0;
```

Serializes complete SLAM state to a proto stream.

#### `SerializeStateToFile`

```cpp
virtual bool SerializeStateToFile(bool include_unfinished_submaps,
                                  const std::string& filename) = 0;
```

Serializes to a file. Returns `true` on success.

#### `LoadState`

```cpp
virtual std::map<int, int> LoadState(
    io::ProtoStreamReaderInterface* reader, bool load_frozen_state) = 0;
```

Loads state from a proto stream. Returns trajectory ID remapping.

#### `LoadStateFromFile`

```cpp
virtual std::map<int, int> LoadStateFromFile(
    const std::string& filename, bool load_frozen_state) = 0;
```

Loads state from a file. Returns trajectory ID remapping.

#### `num_trajectory_builders`

```cpp
virtual int num_trajectory_builders() const = 0;
```

Returns the number of active trajectory builders.

#### `pose_graph`

```cpp
virtual mapping::PoseGraphInterface* pose_graph() = 0;
```

Returns the pose graph for global optimization access.

#### `GetAllTrajectoryBuilderOptions`

```cpp
virtual const std::vector<proto::TrajectoryBuilderOptionsWithSensorIds>&
GetAllTrajectoryBuilderOptions() const = 0;
```

Returns options for all trajectories (used for serialization).

### Helper Function

#### `CreateMapBuilderOptions`

```cpp
proto::MapBuilderOptions CreateMapBuilderOptions(
    common::LuaParameterDictionary* const parameter_dictionary);
```

Creates `MapBuilderOptions` proto from a Lua parameter dictionary. Used to parse Lua configuration files into the protobuf format expected by `MapBuilder`.

## Implementation Notes

- The interface is designed to support both in-process and RPC-based implementations.
- All methods are pure virtual; derived classes must implement the full SLAM stack wiring.
- The `SensorId` and `LocalSlamResultCallback` types are shared with `TrajectoryBuilderInterface` for consistency.

## See Also

- [MapBuilder](map_builder.md) — Library implementation
- [TrajectoryBuilderInterface](trajectory_builder_interface.md) — Local SLAM interface
- [PoseGraphInterface](pose_graph_interface.md) — Global optimization interface
- [MapBuilderBridge (cartographer_ros)](../../cartographer_ros/cartographer_ros/src/map_builder_bridge.cpp.md) — ROS wrapper around this interface