# cartographer_ros_msgs

## Overview

`cartographer_ros_msgs` is the ROS interface definition package for Cartographer ROS. It contains the ROS message types (`.msg`) and service types (`.srv`) that the Cartographer ROS nodelets use to exchange data with the rest of the ROS system.

The package is built as an ament-based ROS 2 package using `rosidl_default_generators`, which turns the `.msg` and `.srv` definitions into language bindings (C++, Python, and others) at build time. It depends on `builtin_interfaces`, `geometry_msgs`, and `std_msgs` for the standard types referenced by the definitions.

The message set covers the following areas:

- **Mapping state**: `SubmapList`, `SubmapEntry`, and `SubmapTexture` describe the submaps that Cartographer produces, including their poses, texture data, and versioning.
- **Trajectory state**: `TrajectoryStates` reports the status of each trajectory, and `BagfileProgress` reports progress while processing bagfiles.
- **Landmark data**: `LandmarkList` and `LandmarkEntry` carry landmark observations with configurable translation and rotation weights.
- **Metrics**: `Metric`, `MetricFamily`, `MetricLabel`, and `HistogramBucket` expose internal Cartographer metrics (counters, gauges, and histograms).
- **Status reporting**: `StatusCode` and `StatusResponse` provide a common, gRPC-compatible status convention for service calls.

The service set provides the primary control interface to the Cartographer ROS node:

- `StartTrajectory` and `FinishTrajectory` manage trajectory lifecycles.
- `GetTrajectoryStates` and `TrajectoryQuery` report trajectory state and poses.
- `SubmapQuery` retrieves submap textures.
- `ReadMetrics` exports metric families.
- `WriteState` serializes the full Cartographer state to disk.

## Quickstart

### Dependencies

The package requires a ROS 2 distribution with the `rosidl_default_generators`, `builtin_interfaces`, `geometry_msgs`, and `std_msgs` packages installed. It also requires `ament_cmake` as the build toolchain.

### Building

Add the package to an ament workspace and build it with `colcon`:

```sh
mkdir -p cartographer_ws/src
# place this package under cartographer_ws/src/cartographer_ros/cartographer_ros_msgs
cd cartographer_ws
colcon build --packages-select cartographer_ros_msgs
```

Source the install environment to make the generated interfaces available to other packages:

```sh
source install/setup.bash
```

### Using the interfaces

After sourcing the workspace, the generated types are available under the `cartographer_ros_msgs` namespace. For example, in Python:

```python
from cartographer_ros_msgs.msg import SubmapList
from cartographer_ros_msgs.srv import SubmapQuery

msg = SubmapList()
```

In C++:

```cpp
#include "cartographer_ros_msgs/msg/submap_list.hpp"
#include "cartographer_ros_msgs/srv/submap_query.hpp"

auto msg = cartographer_ros_msgs::msg::SubmapList{};
```

### Service calls

The typical workflow for controlling a running Cartographer node is to start a trajectory, query the resulting submaps, and finish the trajectory:

1. Call `StartTrajectory` with the configuration directory and basename for the desired SLAM mode.
2. Call `GetTrajectoryStates` or `SubmapQuery` as mapping progresses.
3. Call `FinishTrajectory` with the returned `trajectory_id`.
4. Call `WriteState` to persist the final map state.

## Directory Layout

```text
cartographer_ros_msgs/
├── CMakeLists.txt
├── package.xml
├── msg/
│   ├── BagfileProgress.msg
│   ├── HistogramBucket.msg
│   ├── LandmarkEntry.msg
│   ├── LandmarkList.msg
│   ├── Metric.msg
│   ├── MetricFamily.msg
│   ├── MetricLabel.msg
│   ├── StatusCode.msg
│   ├── StatusResponse.msg
│   ├── SubmapEntry.msg
│   ├── SubmapList.msg
│   ├── SubmapTexture.msg
│   └── TrajectoryStates.msg
└── srv/
    ├── FinishTrajectory.srv
    ├── GetTrajectoryStates.srv
    ├── ReadMetrics.srv
    ├── StartTrajectory.srv
    ├── SubmapQuery.srv
    ├── TrajectoryQuery.srv
    └── WriteState.srv
```

```{toctree}
:maxdepth: 2
:caption: Contents

package.xml
CMakeLists
msg/index
srv/index
```

## Cross-References

- [cartographer_ros](../cartographer_ros/overview.md) — Main ROS 2 integration package
- [cartographer_rviz](../cartographer_rviz/index.md) — RViz visualization plugin
- [Cartographer Core Library](../../index.md) — Underlying SLAM library