# cartographer/mapping/proto/submap.proto

## Overview

`submap.proto` defines the serialized state of a `Submap2D` and a `Submap3D`. These messages are embedded in the serialization format (via `proto::Submap` in `serialization.proto`) and are produced by `Submap2D::ToProto` / `Submap3D::ToProto` and consumed by their corresponding constructors.

## Submap2D

```protobuf
// Serialized state of a Submap2D.
message Submap2D {
  transform.proto.Rigid3d local_pose = 1;
  int32 num_range_data = 2;
  bool finished = 3;
  Grid2D grid = 4;
}
```

| Field | Type | Meaning |
|-------|------|---------|
| `local_pose` | `transform.proto.Rigid3d` | Pose of the submap in the local (tracking) frame |
| `num_range_data` | int32 | Number of range data scans inserted so far |
| `finished` | bool | Whether the submap is finished (no more insertions) |
| `grid` | `Grid2D` | The underlying grid (ProbabilityGrid or TSDF2D) |

`Grid2D` (from `grid_2d.proto`) carries the grid's `MapLimits`, the flat `cells` array (values are actually int16 stored as int32), the `known_cells_box`, a oneof choosing `probability_grid_2d` or `tsdf_2d`, and the min/max correspondence costs:

```protobuf
message Grid2D {
  message CellBox { int32 max_x = 1; int32 max_y = 2; int32 min_x = 3; int32 min_y = 4; }
  MapLimits limits = 1;
  repeated int32 cells = 2;            // int16 values
  CellBox known_cells_box = 3;
  oneof grid {
    ProbabilityGrid probability_grid_2d = 4;
    TSDF2D tsdf_2d = 5;
  }
  float min_correspondence_cost = 6;
  float max_correspondence_cost = 7;
}
```

## Submap3D

```protobuf
// Serialized state of a Submap3D.
message Submap3D {
  transform.proto.Rigid3d local_pose = 1;
  int32 num_range_data = 2;
  bool finished = 3;
  HybridGrid high_resolution_hybrid_grid = 4;
  HybridGrid low_resolution_hybrid_grid = 5;
  repeated float rotational_scan_matcher_histogram = 6;
}
```

| Field | Type | Meaning |
|-------|------|---------|
| `local_pose` | `transform.proto.Rigid3d` | Pose of the submap in the local frame |
| `num_range_data` | int32 | Number of inserted range data scans |
| `finished` | bool | Submap finished flag |
| `high_resolution_hybrid_grid` | `HybridGrid` | Dense occupancy voxel grid at high resolution |
| `low_resolution_hybrid_grid` | `HybridGrid` | Sparse occupancy voxel grid at low resolution |
| `rotational_scan_matcher_histogram` | repeated float | Histogram used by the rotational scan matcher for 3D loop closure |

`HybridGrid` (from `hybrid_grid.proto`) stores a sparse voxel grid as parallel arrays:

```protobuf
message HybridGrid {
  float resolution = 1;
  repeated sint32 x_indices = 3;  // '{x,y,z}_indices[i]' is the index of 'values[i]'
  repeated sint32 y_indices = 4;
  repeated sint32 z_indices = 5;
  repeated int32 values = 6;      // uint16 values stored as int32
}
```

## Role in the SLAM Pipeline

- **Serialization** — `Submap2D`/`Submap3D` are written as part of `SerializedData.submap` inside the serialization stream.
- **Deserialization** — the submaps' constructors rebuild the grid(s) from the proto, restoring the local pose, range count, and finished flag so the pose graph can resume optimization.
- **Submap query / visualization** — grid data also feeds the submap query response used by rviz and the map server.

## See Also

- [Serialization](serialization.md) — Embeds these messages in the map state stream
- [Submap2D](../2d/submap_2d.md) — C++ type serialized here
- [Submap3D](../3d/submap_3d.md) — C++ type serialized here
- [ProbabilityGrid](../2d/probability_grid.md) — Grid payload for 2D submaps
- [HybridGrid](../3d/hybrid_grid.md) — Grid payload for 3D submaps