cartographer_ros/docs/source/ros_api.rst

.. Copyright 2016 The Cartographer Authors

.. Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

..      http://www.apache.org/licenses/LICENSE-2.0

.. Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.

===============================
ROS API reference documentation
===============================

.. image:: nodes_graph_demo_2d.jpg

Cartographer Node
=================

The `cartographer_node`_ is the SLAM node used for online, real-time SLAM.

.. _cartographer_node: https://github.com/cartographer-project/cartographer_ros/blob/master/cartographer_ros/cartographer_ros/node_main.cc

Command-line Flags
------------------

Call the node with the ``--help`` flag to see all available options.

Subscribed Topics
-----------------

The following range data topics are mutually exclusive. At least one source of
range data is required.

scan (`sensor_msgs/LaserScan`_)
  Supported in 2D and 3D (e.g. using an axially rotating planar laser scanner).
  If *num_laser_scans* is set to 1 in the :doc:`configuration`, this topic will
  be used as input for SLAM. If *num_laser_scans* is greater than 1, multiple
  numbered scan topics (i.e. scan_1, scan_2, scan_3, ...  up to and including
  *num_laser_scans*) will be used as inputs for SLAM.

echoes (`sensor_msgs/MultiEchoLaserScan`_)
  Supported in 2D and 3D (e.g. using an axially rotating planar laser scanner).
  If *num_multi_echo_laser_scans* is set to 1 in the :doc:`configuration`, this
  topic will be used as input for SLAM. Only the first echo is used. If
  *num_multi_echo_laser_scans* is greater than 1, multiple numbered echoes
  topics (i.e. echoes_1, echoes_2, echoes_3, ...  up to and including
  *num_multi_echo_laser_scans*) will be used as inputs for SLAM.

points2 (`sensor_msgs/PointCloud2`_)
  If *num_point_clouds* is set to 1 in the :doc:`configuration`, this topic will
  be used as input for SLAM. If *num_point_clouds* is greater than 1, multiple
  numbered points2 topics (i.e. points2_1, points2_2, points2_3, ...  up to and
  including *num_point_clouds*) will be used as inputs for SLAM.

The following additional sensor data topics may also be provided:

imu (`sensor_msgs/Imu`_)
  Supported in 2D (optional) and 3D (required). This topic will be used as
  input for SLAM.

odom (`nav_msgs/Odometry`_)
  Supported in 2D (optional) and 3D (optional). If *use_odometry* is
  enabled in the :doc:`configuration`, this topic will be used as input for
  SLAM.

.. TODO: add NavSatFix? Landmarks?

Published Topics
----------------

scan_matched_points2 (`sensor_msgs/PointCloud2`_)
  Point cloud as it was used for the purpose of scan-to-submap matching. This
  cloud may be both filtered and projected depending on the
  :doc:`configuration`.

submap_list (`cartographer_ros_msgs/SubmapList`_)
  List of all submaps, including the pose and latest version number of each
  submap, across all trajectories.

Services
--------

All services responses include also a ``StatusResponse`` that comprises a ``code`` and a ``message`` field.
For consistency, the integer ``code`` is equivalent to the status codes used in the `gRPC`_ API.

.. _gRPC: https://developers.google.com/maps-booking/reference/grpc-api/status_codes

submap_query (`cartographer_ros_msgs/SubmapQuery`_)
  Fetches the requested submap.

start_trajectory (`cartographer_ros_msgs/StartTrajectory`_)
  Starts a trajectory using default sensor topics and the provided configuration. 
  An initial pose can be optionally specified. Returns an assigned trajectory ID.

trajectory_query (`cartographer_ros_msgs/TrajectoryQuery`_)
  Returns the trajectory data from the pose graph.

finish_trajectory (`cartographer_ros_msgs/FinishTrajectory`_)
  Finishes the given `trajectory_id`'s trajectory by running a final optimization.

write_state (`cartographer_ros_msgs/WriteState`_)
  Writes the current internal state to disk into `filename`. The file will
  usually end up in `~/.ros` or `ROS_HOME` if it is set. This file can be used
  as input to the `assets_writer_main` to generate assets like probability
  grids, X-Rays or PLY files.

get_trajectory_states (`cartographer_ros_msgs/GetTrajectoryStates`_)
  Returns the IDs and the states of the trajectories.
  For example, this can be useful to observe the state of Cartographer from a separate node.

read_metrics (`cartographer_ros_msgs/ReadMetrics`_)
  Returns the latest values of all internal metrics of Cartographer.
  The collection of runtime metrics is optional and has to be activated with the ``--collect_metrics`` command line flag in the node.

Required tf Transforms
----------------------

.. image:: frames_demo_2d.jpg

Transforms from all incoming sensor data frames to the :doc:`configured
<configuration>` *tracking_frame* and *published_frame* must be available.
Typically, these are published periodically by a `robot_state_publisher` or a
`static_transform_publisher`.

Provided tf Transforms
----------------------

The transformation between the :doc:`configured <configuration>` *map_frame*
and *published_frame* is always provided.

If *provide_odom_frame* is enabled in the :doc:`configuration`, a continuous
(i.e. unaffected by loop closure) transform between the :doc:`configured
<configuration>` *odom_frame* and *published_frame* will be provided.

.. _robot_state_publisher: http://wiki.ros.org/robot_state_publisher
.. _static_transform_publisher: http://wiki.ros.org/tf#static_transform_publisher
.. _cartographer_ros_msgs/FinishTrajectory: https://github.com/cartographer-project/cartographer_ros/blob/master/cartographer_ros_msgs/srv/FinishTrajectory.srv
.. _cartographer_ros_msgs/SubmapList: https://github.com/cartographer-project/cartographer_ros/blob/master/cartographer_ros_msgs/msg/SubmapList.msg
.. _cartographer_ros_msgs/SubmapQuery: https://github.com/cartographer-project/cartographer_ros/blob/master/cartographer_ros_msgs/srv/SubmapQuery.srv
.. _cartographer_ros_msgs/StartTrajectory: https://github.com/cartographer-project/cartographer_ros/blob/master/cartographer_ros_msgs/srv/StartTrajectory.srv
.. _cartographer_ros_msgs/TrajectoryQuery: https://github.com/cartographer-project/cartographer_ros/blob/master/cartographer_ros_msgs/srv/TrajectoryQuery.srv
.. _cartographer_ros_msgs/WriteState: https://github.com/cartographer-project/cartographer_ros/blob/master/cartographer_ros_msgs/srv/WriteState.srv
.. _cartographer_ros_msgs/GetTrajectoryStates: https://github.com/cartographer-project/cartographer_ros/blob/master/cartographer_ros_msgs/srv/GetTrajectoryStates.srv
.. _cartographer_ros_msgs/ReadMetrics: https://github.com/cartographer-project/cartographer_ros/blob/master/cartographer_ros_msgs/srv/ReadMetrics.srv
.. _nav_msgs/OccupancyGrid: http://docs.ros.org/api/nav_msgs/html/msg/OccupancyGrid.html
.. _nav_msgs/Odometry: http://docs.ros.org/api/nav_msgs/html/msg/Odometry.html
.. _sensor_msgs/Imu: http://docs.ros.org/api/sensor_msgs/html/msg/Imu.html
.. _sensor_msgs/LaserScan: http://docs.ros.org/api/sensor_msgs/html/msg/LaserScan.html
.. _sensor_msgs/MultiEchoLaserScan: http://docs.ros.org/api/sensor_msgs/html/msg/MultiEchoLaserScan.html
.. _sensor_msgs/PointCloud2: http://docs.ros.org/api/sensor_msgs/html/msg/PointCloud2.html

Offline Node
============

The `offline_node`_ is the fastest way of SLAMing a bag of sensor data.
It does not listen on any topics, instead it reads TF and sensor data out of a set of bags provided on the commandline.
It also publishes a clock with the advancing sensor data, i.e. replaces ``rosbag play``.
In all other regards, it behaves like the ``cartographer_node``.
Each bag will become a separate trajectory in the final state.
Once it is done processing all data, it writes out the final Cartographer state and exits.

.. _offline_node: https://github.com/cartographer-project/cartographer_ros/blob/master/cartographer_ros/cartographer_ros/offline_node_main.cc


Published Topics
----------------

In addition to the topics that are published by the online node, this node also publishes:

~bagfile_progress (`cartographer_ros_msgs/BagfileProgress`_)
  Bag files processing progress including detailed information about the bag currently being processed which will be published with a predefined
  interval that can be specified using ``~bagfile_progress_pub_interval`` ROS parameter.

.. _cartographer_ros_msgs/BagfileProgress: https://github.com/cartographer-project/cartographer_ros/blob/master/cartographer_ros_msgs/msg/BagfileProgress.msg

Parameters
----------

~bagfile_progress_pub_interval (double, default=10.0):
  The interval of publishing bag files processing progress in seconds.


Occupancy grid Node
===================

The `occupancy_grid_node`_ listens to the submaps published by SLAM, builds an ROS occupancy_grid out of them and publishes it.
This tool is useful to keep old nodes that require a single monolithic map to work happy until new nav stacks can deal with Cartographer's submaps directly.
Generating the map is expensive and slow, so map updates are in the order of seconds.
You can can selectively include/exclude submaps from frozen (static) or active trajectories with a command line option.
Call the node with the ``--help`` flag to see these options.

.. _occupancy_grid_node: https://github.com/cartographer-project/cartographer_ros/blob/master/cartographer_ros/cartographer_ros/occupancy_grid_node_main.cc

Subscribed Topics
-----------------

It subscribes to Cartographer's ``submap_list`` topic only.

Published Topics
----------------

map (`nav_msgs/OccupancyGrid`_)
  If subscribed to, the node will continuously compute and publish the map. The
  time between updates will increase with the size of the map. For faster
  updates, use the submaps APIs.


Pbstream Map Publisher Node
===========================

The `pbstream_map_publisher`_ is a simple node that creates a static occupancy grid out of a serialized Cartographer state (pbstream format).
It is an efficient alternative to the occupancy grid node if live updates are not important.

.. _pbstream_map_publisher: https://github.com/cartographer-project/cartographer_ros/blob/master/cartographer_ros/cartographer_ros/pbstream_map_publisher_main.cc

Subscribed Topics
-----------------

None.

Published Topics
----------------

map (`nav_msgs/OccupancyGrid`_)
  The published occupancy grid topic is latched.