mirror of
https://github.com/introlab/rtabmap_ros.git
synced 2026-10-07 02:07:45 +08:00
matlabbeandmathieu86
11edc01d6a
* rtabmap_odom tests and doc * opengv note * added ci checks or humble-latest flaky dep cmake errors * Added real data tests for rgbd_odom and stereo_odom * added real data for icp_odometry's deskewing test * fixing json cmake error on lyrical/rolling * test 2d icp odom deskewing branch * first review of existing OdometryROS tests * testing with imu used as guess * tested imu arrivals sync * Fixed odom reset on right pose when guess frame id is used * fixing header errors in ci >=lyrical * Added support for input rgbd_image topic with features for odom, added multicam rgbd_odometry test * Added stereo odom support for features-only frames. Added multicam stereo tests. * forcing latest rtabmap version * updated OdometryROS API * ci: dont build non-latest docker in pull requests * splitting docker jobs * doc edit * Making publish_null_when_lost:=false continous when guess is provided (using guess covariance when we cannot register yet) * updated stereo doc * ficing rolling ci (rviz Ogre header) * Added test coverage of alll rgbd_image callbacks * fixing rolling ci * making docker ci build/run the tests on pull requests * fixing ros2 ci testing * improved sync callback coverage * improving stereo_odometry test coverage * improved icp_odometry test coverage * lyrical voxel_grid ptr error * make multicam tests working as well without opengv * removing deps of missing packages on rolling * PCL empty cloud conversion compiler errors fix * fixing icp_odometry test failure on ci witohut libpointmatcher * fixing nav2 costmap plugin build on lyrical * joining thread when exiting * updating icp test to work the same on pcl 1.15 (lyrical) * Fix parallel tests seg fault --------- Co-authored-by: mathieu86 <[email protected]>
160 lines
12 KiB
Markdown
160 lines
12 KiB
Markdown
rtabmap_ros
|
|
===========
|
|
|
|
ROS 2 wrapper for [RTAB-Map](https://github.com/introlab/rtabmap), 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](http://wiki.ros.org/rtabmap_ros) for anything not yet covered by the package pages below.
|
|
|
|
#### CI Latest
|
|
|
|
| | Build | Docker |
|
|
|---|---|---|
|
|
| ROS 1 | [](https://github.com/introlab/rtabmap_ros/actions/workflows/ros1.yml) | [](https://github.com/introlab/rtabmap_ros/actions/workflows/docker.yml) |
|
|
| ROS 2 | [](https://github.com/introlab/rtabmap_ros/actions/workflows/ros2.yml) | [](https://github.com/introlab/rtabmap_ros/actions/workflows/docker-ros2.yml) |
|
|
|
|
#### ROS Binaries
|
|
|
|
| | Distro | Ubuntu | Released | In apt | Build |
|
|
|---|---|---|---|---|---|
|
|
| ROS 1 | Noetic (EOL) | 20.04 | [](https://github.com/ros/rosdistro/blob/master/noetic/distribution.yaml) | [](https://index.ros.org/p/rtabmap_ros/#noetic) | |
|
|
| ROS 2 | Humble | 22.04 | [](https://github.com/ros/rosdistro/blob/master/humble/distribution.yaml) | [](https://index.ros.org/p/rtabmap_ros/#humble) | [](http://build.ros2.org/job/Hbin_uJ64__rtabmap_ros__ubuntu_jammy_amd64__binary/) |
|
|
| ROS 2 | Iron (EOL) | 22.04 | [](https://github.com/ros/rosdistro/blob/master/iron/distribution.yaml) | [](https://index.ros.org/p/rtabmap_ros/#iron) | |
|
|
| ROS 2 | Jazzy | 24.04 | [](https://github.com/ros/rosdistro/blob/master/jazzy/distribution.yaml) | [](https://index.ros.org/p/rtabmap_ros/#jazzy) | [](http://build.ros2.org/job/Jbin_uN64__rtabmap_ros__ubuntu_noble_amd64__binary/) |
|
|
| ROS 2 | Kilted | 24.04 | [](https://github.com/ros/rosdistro/blob/master/kilted/distribution.yaml) | [](https://index.ros.org/p/rtabmap_ros/#kilted) | [](http://build.ros2.org/job/Kbin_uN64__rtabmap_ros__ubuntu_noble_amd64__binary/) |
|
|
| ROS 2 | Lyrical | 26.04 | [](https://github.com/ros/rosdistro/blob/master/lyrical/distribution.yaml) | [](https://index.ros.org/p/rtabmap_ros/#lyrical) | [](http://build.ros2.org/job/Lbin_uR64__rtabmap_ros__ubuntu_resolute_amd64__binary/) |
|
|
| ROS 2 | Rolling | 26.04 | [](https://github.com/ros/rosdistro/blob/master/rolling/distribution.yaml) | [](https://index.ros.org/p/rtabmap_ros/#rolling) | |
|
|
| Docker | [rtabmap_ros](https://hub.docker.com/r/introlab3it/rtabmap_ros) | | |  | |
|
|
|
|
*Released* is the version bloomed into [rosdistro](https://github.com/ros/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`](rtabmap_odom/README.md) | Odometry nodes — `rgbd_odometry`, `stereo_odometry` and `icp_odometry`. Any external odometry can be used instead. |
|
|
| [`rtabmap_sync`](rtabmap_sync/README.md) | 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`](rtabmap_util/README.md) | 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`](rtabmap_conversions/README.md) | C++ library converting between RTAB-Map library types and ROS 2 messages. |
|
|
| [`rtabmap_python`](rtabmap_python/README.md) | 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`](https://github.com/introlab/rtabmap_ros/tree/ros2/rtabmap_examples/launch) | Sensor integration examples: stereo and RGB-D cameras, 3D lidar. |
|
|
| [`rtabmap_demos`](rtabmap_demos/README.md) | 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](https://github.com/introlab/rtabmap_ros/tree/master#installation) on the [`master`](https://github.com/introlab/rtabmap_ros/tree/master) branch, which also carries the latest version for Noetic.
|
|
|
|
### Binaries
|
|
|
|
```bash
|
|
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:
|
|
```bash
|
|
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:
|
|
```bash
|
|
colcon build --symlink-install --cmake-args -DRTABMAP_SYNC_MULTI_RGBD=ON -DRTABMAP_SYNC_USER_DATA=ON -DCMAKE_BUILD_TYPE=Release
|
|
```
|
|
|
|
### Testing
|
|
|
|
```bash
|
|
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](https://github.com/introlab/rtabmap_ros/tree/ros2/rtabmap_examples/launch) sub-folder.
|
|
|
|
* For robot integration examples (turtlebot3 and turtlebot4, nav2 integration), see [rtabmap_demos](https://github.com/introlab/rtabmap_ros/tree/ros2/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](https://docs.ros.org/en/jazzy/Concepts/Intermediate/About-Logging.html)" documentation for more info):
|
|
```bash
|
|
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](https://docs.ros.org/en/jazzy/Installation/RMW-Implementations/DDS-Implementations/Working-with-Eclipse-CycloneDDS.html), you can try it by adding this before launching any nodes/launch files (or add to your `.bashrc`):
|
|
```bash
|
|
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](https://docs.ros.org/en/jazzy/p/rtabmap_ros/).
|
|
* **Examples** — [rtabmap_examples](https://github.com/introlab/rtabmap_ros/tree/ros2/rtabmap_examples/launch) for sensors, [rtabmap_demos](rtabmap_demos/README.md) for full robots.
|
|
* **Parameters** — every `Rtabmap/*`, `Grid/*`, `Odom/*` and other core parameter is listed in the [RTAB-Map parameter reference](https://introlab.github.io/rtabmap/api/latest/parameters.html).
|
|
* **Library API** — [RTAB-Map's own API documentation](https://introlab.github.io/rtabmap/api/latest/).
|
|
* **Papers and videos** — [introlab.github.io/rtabmap](https://introlab.github.io/rtabmap/).
|
|
* **Old tutorials** — the [ROS 1 wiki](http://wiki.ros.org/rtabmap_ros/Tutorials), for anything not covered above; parameters and topic names are unchanged.
|
|
|
|
## Building the documentation
|
|
|
|
Each package's API reference is generated with [rosdoc2](https://github.com/ros-infrastructure/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:
|
|
|
|
```bash
|
|
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](LICENSE). RTAB-Map itself may be built with components under other licenses; see the [rtabmap](https://github.com/introlab/rtabmap) repository.
|