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:

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:

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:

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

msg = SubmapList()

In C++:

#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

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

Contents

Cross-References