# cartographer/mapping/proto/serialization.proto

## Overview

`serialization.proto` defines the on-disk serialization format for a complete Cartographer map state. The format is a sequence of `SerializedData` messages (one per record, framed by the reader/writer), each carrying exactly one piece of the saved state: the pose graph, trajectory builder options, submaps, nodes, per-trajectory sensor data, and trajectory-level metadata. A `SerializationHeader` with a format version starts the stream.

## Format Header

```protobuf
// Header of the serialization format. At the moment it only contains the
// version of the format.
message SerializationHeader {
  uint32 format_version = 1;
}
```

## SerializedData (the record type)

```protobuf
message SerializedData {
  oneof data {
    PoseGraph pose_graph = 1;
    AllTrajectoryBuilderOptions all_trajectory_builder_options = 2;
    Submap submap = 3;
    Node node = 4;
    TrajectoryData trajectory_data = 5;
    ImuData imu_data = 6;
    OdometryData odometry_data = 7;
    FixedFramePoseData fixed_frame_pose_data = 8;
    LandmarkData landmark_data = 9;
  }
}
```

| Field | Type | Purpose |
|-------|------|---------|
| `pose_graph` | `PoseGraph` | Global pose graph: constraints, trajectories, landmark poses |
| `all_trajectory_builder_options` | `AllTrajectoryBuilderOptions` | Configuration of every trajectory builder |
| `submap` | `Submap` | A serialized submap with its ID and grid data |
| `node` | `Node` | A serialized trajectory node with its ID and constant data |
| `trajectory_data` | `TrajectoryData` | Per-trajectory metadata (gravity, IMU calibration, fixed-frame origin) |
| `imu_data` / `odometry_data` / `fixed_frame_pose_data` / `landmark_data` | per-type | Raw sensor data tagged with a trajectory ID |

## Referenced Messages

### Submap (wraps a submap with its ID)

```protobuf
message Submap {
  SubmapId submap_id = 1;
  Submap2D submap_2d = 2;
  Submap3D submap_3d = 3;
}
```

`SubmapId` and `NodeId` are defined in `pose_graph.proto`:

```protobuf
message SubmapId { int32 trajectory_id = 1; int32 submap_index = 2; }
message NodeId   { int32 trajectory_id = 1; int32 node_index = 2; }
```

The concrete submap payloads (`Submap2D`/`Submap3D`) are defined in `submap.proto`.

### Node

```protobuf
message Node {
  NodeId node_id = 1;
  TrajectoryNodeData node_data = 5;
}
```

`TrajectoryNodeData` (from `trajectory_node_data.proto`) stores the timestamp, gravity alignment, compressed point clouds (filtered gravity-aligned, high-resolution, low-resolution), the rotational scan matcher histogram, and the local pose.

### Per-Trajectory Sensor Data

```protobuf
message ImuData {
  int32 trajectory_id = 1;
  sensor.proto.ImuData imu_data = 2;
}
message OdometryData {
  int32 trajectory_id = 1;
  sensor.proto.OdometryData odometry_data = 2;
}
message FixedFramePoseData {
  int32 trajectory_id = 1;
  sensor.proto.FixedFramePoseData fixed_frame_pose_data = 2;
}
message LandmarkData {
  int32 trajectory_id = 1;
  sensor.proto.LandmarkData landmark_data = 2;
}
```

### TrajectoryData

```protobuf
message TrajectoryData {
  int32 trajectory_id = 1;
  double gravity_constant = 2;
  transform.proto.Quaterniond imu_calibration = 3;
  transform.proto.Rigid3d fixed_frame_origin_in_map = 4;
}
```

Holds per-trajectory values needed to resume optimization after loading: the estimated gravity constant, the IMU calibration quaternion, and the transform from the fixed frame into the map.

### LocalSlamResultData

```protobuf
message LocalSlamResultData {
  int64 timestamp = 1;
  TrajectoryNodeData node_data = 2;
  repeated Submap submaps = 3;
}
```

Used to carry local SLAM results (a node plus the affected submaps) — the wire format for the local SLAM result callback when the trajectory builder is deserializing.

### PoseGraph

`PoseGraph` (from `pose_graph.proto`) stores the constraints, per-trajectory nodes/submaps, and landmark poses:

```protobuf
message PoseGraph {
  message Constraint {
    enum Tag { INTRA_SUBMAP = 0; INTER_SUBMAP = 1; }
    SubmapId submap_id = 1;
    NodeId node_id = 2;
    transform.proto.Rigid3d relative_pose = 3;
    double translation_weight = 6;
    double rotation_weight = 7;
    Tag tag = 5;
  }
  message LandmarkPose {
    string landmark_id = 1;
    transform.proto.Rigid3d global_pose = 2;
  }
  repeated Constraint constraint = 2;
  repeated Trajectory trajectory = 4;
  repeated LandmarkPose landmark_poses = 5;
}
```

`Trajectory` (from `trajectory.proto`) stores a trajectory's ID, time-ordered nodes (with timestamps and global poses), and submaps (with global poses).

### AllTrajectoryBuilderOptions

From `trajectory_builder_options.proto`:

```protobuf
message AllTrajectoryBuilderOptions {
  repeated TrajectoryBuilderOptionsWithSensorIds options_with_sensor_ids = 1;
}
```

Each `TrajectoryBuilderOptionsWithSensorIds` pairs the expected `SensorId` list with the 2D/3D `TrajectoryBuilderOptions` (including submaps, scan matchers, motion filter, pose extrapolator, and trimmers).

## Role in the SLAM Pipeline

- **Writing** — `MapBuilder::SerializeState` writes the `SerializationHeader`, then one `SerializedData` per entity (pose graph, options, submaps, nodes, trajectory data, and buffered sensor data).
- **Reading** — `MapBuilder::LoadState` reads records, calls `AddTrajectoryForDeserialization`, and uses `InsertTrajectoryNode`/`InsertSubmap` to restore state, then reruns optimization.

## See Also

- [Submap](submap.md) — Submap2D/Submap3D payloads
- [MapBuilderOptions](map_builder_options.md) — Configuration of the writer
- [MapBuilder](../map_builder.md) — SerializeState / LoadState entry points
- TrajectoryNodeData — Node payload structure (no dedicated page yet)