rtabmap_ros/README.md

rtabmap_ros

ROS 2 wrapper for RTAB-Map, a graph-based SLAM library with appearance-based loop closure detection. It builds and maintains a 3D map from RGB-D, stereo or lidar data, closes loops on revisited places and exports the result as an occupancy grid, a point cloud or an OctoMap.

ROS 2 Humble minimum required. The interface matches ROS 1: parameters and topic names still follow the ROS 1 documentation for anything not yet covered by the package pages below.

CI Latest

	Build	Docker
ROS 1
ROS 2

ROS Binaries

	Distro	Ubuntu	Released	In apt	Build
ROS 1	Noetic (EOL)	20.04
ROS 2	Humble	22.04
ROS 2	Iron (EOL)	22.04
ROS 2	Jazzy	24.04
ROS 2	Kilted	24.04
ROS 2	Lyrical	26.04
ROS 2	Rolling	26.04
Docker	rtabmap_ros

Released is the version bloomed into rosdistro; In apt is what apt install actually gives you today. They differ while a release is waiting on a buildfarm sync.

Packages

The stack is split into small packages so a pipeline only pulls in what it uses. Package names link to their documentation where it exists; the rest are being written and will be linked as they land.

SLAM

Package	Description
rtabmap_slam	The rtabmap node itself: appearance-based loop closure detection, graph optimization, memory management and map assembly.
rtabmap_odom	Odometry nodes — rgbd_odometry, stereo_odometry and icp_odometry. Any external odometry can be used instead.
rtabmap_sync	Synchronizes camera and lidar topics into a single message so they reach the SLAM node together — rgbd_sync, stereo_sync, rgbdx_sync.

Sensor processing

Package	Description
rtabmap_util	Utility nodes around the pipeline: format conversions, point cloud filtering and assembly, obstacle detection, map assembly, database replay. Most are useful on their own.
rtabmap_costmap_plugins	A variant of nav2's voxel layer that follows the robot along z, keeping the voxel grid centered on the base frame. For robots that change altitude, e.g. drones.

Interfaces and libraries

Package	Description
rtabmap_msgs	Message, service and action definitions used across the stack.
rtabmap_conversions	C++ library converting between RTAB-Map library types and ROS 2 messages.
rtabmap_python	Python helpers for RTAB-Map's own binary formats, currently the compressed matrices carried in rtabmap_msgs fields and database blobs.

Visualization

Package	Description
rtabmap_viz	RTAB-Map's own GUI as a ROS 2 node: live graph, loop closures, feature matches and the parameter panel.
rtabmap_rviz_plugins	RViz displays for the map graph, the assembled cloud and the SLAM info.

Launch files

Package	Description
rtabmap_launch	rtabmap.launch.py, the one-line way to bring up the whole stack.
rtabmap_examples	Sensor integration examples: stereo and RGB-D cameras, 3D lidar.
rtabmap_demos	Full robot demos: turtlebot3 and turtlebot4, nav2 integration, multi-session mapping.

Installation

These instructions are for ROS 2. For ROS 1, follow the installation instructions on the master branch, which also carries the latest version for Noetic.

Binaries

sudo apt install ros-$ROS_DISTRO-rtabmap-ros

From Source

• Make sure to uninstall any rtabmap binaries:

  sudo apt remove ros-$ROS_DISTRO-rtabmap*
  

• RTAB-Map ROS2 package:

  cd ~/ros2_ws
  git clone https://github.com/introlab/rtabmap.git src/rtabmap
  git clone --branch ros2 https://github.com/introlab/rtabmap_ros.git src/rtabmap_ros
  rosdep update && rosdep install --from-paths src --ignore-src -r -y
  export MAKEFLAGS="-j6" # Can be ignored if you have a lot of RAM (>16GB)
  colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release
  

• To build with rgbd_cameras>1 support and/or subscribe_user_data support:

  colcon build --symlink-install --cmake-args -DRTABMAP_SYNC_MULTI_RGBD=ON -DRTABMAP_SYNC_USER_DATA=ON -DCMAKE_BUILD_TYPE=Release
  

Testing

cd ~/ros2_ws
colcon build --base-paths src/rtabmap_ros
colcon test --base-paths src/rtabmap_ros
colcon test-result --verbose

Usage

• For sensor integration examples (stereo and RGB-D cameras, 3D LiDAR), see rtabmap_examples sub-folder.

• For robot integration examples (turtlebot3 and turtlebot4, nav2 integration), see rtabmap_demos sub-folder.

Logging

To make RTAB-Map's logs appear ordered with RCLCPP's logs, set the following environment variables in your .bashrc (see official "About Logging" documentation for more info):

export RCUTILS_LOGGING_USE_STDOUT=1
export RCUTILS_LOGGING_BUFFERED_STREAM=1
# Optional, but if you like colored logs:
export RCUTILS_COLORIZED_OUTPUT=1

Recommended DDS

If RTAB-Map's GUI or topic frequency feel laggy (even if processing time looks fast enough), it may be caused by the DDS. I recommend to use Cyclone DDS, you can try it by adding this before launching any nodes/launch files (or add to your .bashrc):

export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
# Cyclone prefers multicast by default, if your router got too much spammed, 
# disable multicast with (https://github.com/ros2/rmw_cyclonedds/issues/489):
export CYCLONEDDS_URI="<Disc><DefaultMulticastAddress>0.0.0.0</></>"

Documentation

• Package documentation — the tables above, and the API reference on docs.ros.org.
• Examples — rtabmap_examples for sensors, rtabmap_demos for full robots.
• Parameters — every Rtabmap/*, Grid/*, Odom/* and other core parameter is listed in the RTAB-Map parameter reference.
• Library API — RTAB-Map's own API documentation.
• Papers and videos — introlab.github.io/rtabmap.
• Old tutorials — the ROS 1 wiki, for anything not covered above; parameters and topic names are unchanged.

Building the documentation

Each package's API reference is generated with rosdoc2 from the Doxygen comments in its public headers, and published to docs.ros.org. rosdoc2 documents one package per invocation, so building the whole stack is a loop over them — run it from the repository root:

for pkg in rtabmap_*/; do
  rosdoc2 build --package-path "$pkg" --output-directory doc_output || break
done

Each package lands in doc_output/<package>/index.html.

License

BSD-3-Clause, see LICENSE. RTAB-Map itself may be built with components under other licenses; see the rtabmap repository.