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¶

// 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)¶

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)¶

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

SubmapId and NodeId are defined in pose_graph.proto:

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¶

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¶

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¶

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¶

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:

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:

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.