Skip to content

Installation

Jump to bottom
matlabbe edited this page Apr 6, 2024 · 279 revisions

Latest releases here!

This page shows how to install RTAB-Map on different systems. For previous releases, visit here.

ROS Ubuntu Mac OS X iOS Windows Google Tango Raspberry Pi Docker

ROS version ROS

Visit rtabmap_ros for installation instructions.

Standalone version

Ubuntu Ubuntu

If ROS is already installed

  • If ROS is installed, dependencies should already be satisfied. You can follow instructions on rtabmap_ros.
    1. For the standalone, execute the application ($ rtabmap).
    2. See Tutorials for a simple example of usage.

If ROS is not installed

  1. System dependencies

    1. Ubuntu 16.04

      $ sudo apt-get update
$ sudo apt-get install libsqlite3-dev libpcl-dev libopencv-dev git cmake libproj-dev libqt5svg5-dev

    2. Ubuntu 14.04

      $ sudo apt-get install libsqlite3-dev libpcl-1.7-all libopencv-dev
      • To install libpcl-1.7-all, you may need to add ROS repositories by doing steps 1.2, 1.3 and 1.4 of this page (on step 1.3, use trusty instead of raring if you are on Ubuntu 14.04):
      $ sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu trusty main" > /etc/apt/sources.list.d/ros-latest.list'
$ wget http://packages.ros.org/ros.key -O - | sudo apt-key add -
$ sudo apt-get update
      • Alternatively ( without ROS Repository ). If pcl-1.7-all errors with not found simply add the PCL repository for access to the binaries:
      $ sudo add-apt-repository ppa:v-launchpad-jochen-sprickerhof-de/pcl
$ sudo apt-get update

    3. Ubuntu 12.04

      $ sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu precise main" > /etc/apt/sources.list.d/ros-latest.list'
$ wget http://packages.ros.org/ros.key -O - | sudo apt-key add -
$ sudo apt-get update

  2. Other dependencies:

    • (Optional) OpenCV with SIFT/SURF: If you want SURF/SIFT features enabled in RTAB-Map, you will also have to build OpenCV from source to have access to nonfree module (build with opencv_contrib for OpenCV3 and OpenCV4): 
      $ cd opencv
$ mkdir build
$ cd build
$ cmake -DCMAKE_BUILD_TYPE=Release ..
$ make -j4
$ sudo make install
    • (Recommended) g2o: 
      $ git clone https://github.com/RainerKuemmerle/g2o.git 
$ cd g2o
$ mkdir build
$ cd build
$ cmake -DBUILD_WITH_MARCH_NATIVE=OFF -DG2O_BUILD_APPS=OFF -DG2O_BUILD_EXAMPLES=OFF -DG2O_USE_OPENGL=OFF ..
$ make -j4
$ sudo make install
    • (Recommended) GTSAM:
      • Install via PPA to avoid building from source. If you install from source (version>=4), make sure to build with cmake -DGTSAM_BUILD_WITH_MARCH_NATIVE=OFF -DGTSAM_USE_SYSTEM_EIGEN=ON.
    • (Optional) cvsba: Follow installation instructions from here. Their installation is not standard CMake, you need these extra steps so RTAB-Map can find it: 
      $ mkdir /usr/local/lib/cmake/cvsba 
$ mv /usr/local/lib/cmake/Findcvsba.cmake /usr/local/lib/cmake/cvsba/cvsbaConfig.cmake

  3. Download RTAB-Map source: get latest release or current source

    $ git clone https://github.com/introlab/rtabmap.git rtabmap
$ cd rtabmap/build
$ cmake ..
$ make -j4
$ sudo make install

  4. Execute the application (named "rtabmap").

    • If you receive error while loading shared libraries: librtabmap_core.so.0.10 remember to run ldconfig!

  5. See Tutorials for a simple example of usage.

Update code

If you want the latest changes after the git clone is done, you can update the code like this:

$ cd rtabmap
$ git pull origin master
$ cd build
$ cmake ..
$ make -j4
$ sudo make install

Docker Docker

  • Docker repository: intolab3it/rtabmap
  • Docker files: https://github.com/introlab/rtabmap/tree/master/docker
  • Images available from introlab3it/rtabmap:
    • xenial, 16.04 (amd64)
    • bionic, 18.04 (amd64, arm64)
    • focal, 20.04, latest (amd64, arm64)
    • jammy, 22.04 (amd64, arm64)
    • android24, android26, android30 (amd64)
    • tango (android23), tango-api19 (amd64)
    • jfr2018 (amd64)

      M. Labbé and F. Michaud, “RTAB-Map as an Open-Source Lidar and Visual SLAM Library for Large-Scale and Long-Term Online Operation,” in Journal of Field Robotics, vol. 36, no. 2, pp. 416–446, 2019. (pdf) (Wiley)

RTAB-Map Desktop (ubuntu 18.04, 20.04, 22.04)

$ docker pull introlab3it/rtabmap:jammy
or
$ docker pull introlab3it/rtabmap:focal
or
$ docker pull introlab3it/rtabmap:bionic

  • To be able to run rtabmap, we should install opengl support in the image. To do so, visit this tutorial for details if you have a nvidia GPU (if you don't have a nvidia GPU, see if the open source approach explained in 16.04 below is working for you or see intel/AMD instructions on this page):

    • Install nvidia-docker2: 
      sudo apt install -y nvidia-docker2
sudo systemctl daemon-reload
sudo systemctl restart docker

  • Run image:

     # those following 3 lines would need to be done only one time
 export XAUTH=/tmp/.docker.xauth
 touch $XAUTH
 xauth nlist $DISPLAY | sed -e 's/^..../ffff/' | xauth -f $XAUTH nmerge -

 docker run -it --rm \
   --privileged \
   --env="DISPLAY=$DISPLAY" \
   --env="QT_X11_NO_MITSHM=1" \
   --volume="/tmp/.X11-unix:/tmp/.X11-unix:rw" \
   --env="XAUTHORITY=$XAUTH" \
   --volume="$XAUTH:$XAUTH" \
   -e NVIDIA_VISIBLE_DEVICES=all \
   -e NVIDIA_DRIVER_CAPABILITIES=all \
   --runtime=nvidia \
   --network host \
   -v ~/Documents/RTAB-Map:/root/Documents/RTAB-Map \
   introlab3it/rtabmap:focal \
   rtabmap
    • On nvidia jetpack, add -e LD_LIBRARY_PATH=/opt/ros/noetic/lib:/opt/ros/noetic/lib/aarch64-linux-gnu:/usr/lib/aarch64-linux-gnu/tegra to command line above if you are using 20.04 image. Change noetic to melodic or humble if you use 18.04 or 22.04 image respectively.

RTAB-Map console tools

RTAB-Map ARCore (APK)

$ docker pull introlab3it/rtabmap:android26

To install the APK, we should uninstall the version of RTAB-Map ARCore from the phone (installed by Play Store), drag and drop app to uninstall, or do:

adb uninstall com.introlab.rtabmap

  • For API <= 26, 2 choices:

    1. Copy file on host computer then install it with adb from there: 
      docker run --name=rtabmap-android introlab3it/rtabmap:android26
docker cp rtabmap-android:/root/rtabmap-tango/build/arm64-v8a/app/android/bin/RTABMap-debug.apk .
docker rm rtabmap-android # cleanup container
adb install -r RTABMap-debug.apk
    2. Call adb from container: 
      docker run --privileged --network=host -i -t --rm introlab3it/rtabmap:android26 adb install -r rtabmap-tango/build/arm64-v8a/app/android/bin/RTABMap-debug.apk

  • For API >= 30, the apk should be signed with a debug key (the keystore password is android):

    docker run --privileged --network=host -i -t --rm introlab3it/rtabmap:android30
# from inside the container:
/opt/android-sdk/build-tools/30.0.3/apksigner sign --ks ~/.android/debug.keystore  rtabmap-tango/build/arm64-v8a/app/android/bin/RTABMap-debug.apk
adb install -r rtabmap-tango/build/arm64-v8a/app/android/bin/RTABMap-debug.apk

RTAB-Map Tango (APK)

$ docker pull introlab3it/rtabmap:tango

To install the APK, we should uninstall the version of RTAB-Map tango from the phone (installed by Play Store), drag and drop app to uninstall, or do:

$ adb uninstall com.introlab.rtabmap
  • Install APK, 2 choices (Asus Zenfone AR, Lenovo Phab2Pro):
    1. Copy file on host computer then install it with adb from there: 
      $ docker run --name=rtabmap-tango introlab3it/rtabmap:tango
$ docker cp rtabmap-tango:/root/rtabmap-tango/build/arm64-v8a/app/android/bin/RTABMap-debug.apk .
$ docker rm rtabmap-tango # cleanup container
$ adb install -r RTABMap-debug.apk
    2. Call adb from container: 
      $ docker run --privileged --network=host -i -t --rm introlab3it/rtabmap:tango adb install -r rtabmap-tango/build/arm64-v8a/app/android/bin/RTABMap-debug.apk

Note that arm64-v8a APK contains both armeabi-v7a and arm64-v8a binaries.

  • For Google Project Tango tablet, use introlab3it/rtabmap:tango-api19 image and replace arm64-v8a by armeabi-v7a:

    $ docker run --name=rtabmap-tango introlab3it/rtabmap:tango-api19
$ docker cp rtabmap-tango:/root/rtabmap-tango/build/armeabi-v7a/app/android/bin/RTABMap-debug.apk .
$ docker rm rtabmap-tango # cleanup container
$ adb install -r RTABMap-debug.apk

Build images

All docker files can be found under docker directory. You should launch docker build from the root of this repository. Example:

cd rtabmap
docker build -t rtabmap_focal -f docker/focal/Dockerfile .

Raspberry Pi Raspberry Pi

This walkthrough should be updated for Raspberry Pi 4. (the link to OpenCV source does not work and should be updated)

The installation steps are similar to Ubuntu:

  1. System dependencies

    $ sudo apt-get install libpcl-dev libopencv-dev cmake libfreenect-dev libopenni2-dev libsqlite3-dev libvtk6-qt-dev

    • Kinect for Xbox 360: Freenect binaries may not work out-of-the-box on RPI3B+ (see this issue), we should build it from source before building rtabmap:

      $ sudo apt-get remove libfreenect*
$ git clone https://github.com/OpenKinect/libfreenect.git
$ cd libfreenect
$ mkdir build
$ cd build
$ cmake ..
$ make
$ sudo make install

    • If you want SURF/SIFT features enabled in RTAB-Map, you will also have to build OpenCV from source to have access to nonfree module:

    $ cd opencv
$ mkdir build
$ cd build
$ cmake -DCMAKE_BUILD_TYPE=Release ..
$ make 
$ sudo make install

  2. Download RTAB-Map source: get latest release or current source

    $ git clone https://github.com/introlab/rtabmap.git rtabmap
$ cd rtabmap/build
$ cmake ..
$ make 
$ sudo make install
$ sudo ldconfig
$ rtabmap
    • Note that RPi default swap size (100 MB) may be too small for compilation. You can increase the size by setting CONF_SWAPFILE=1000 of this file /etc/dphys-swapfile.

  3. See Tutorials for a simple example of usage.

    • Do not expect high frame rate on Raspberry Pi, you may have to move slowly the camera. For example on RPi3, we can have around 5-6 Hz odometry frame rate by tuning some parameters. Without ROS, load the following settings rpi3.ini (see Preferences dialog) to get smoother mapping on RPI3. The Odometry panel can be closed if the GUI is lagging too much.

Mac OS X Mac OS X

Binaries

Source

Updated March 2023

Dependencies

For packages built from source, normally they should build from their latest version, otherwise you can see the git version I used for each of them at the time I tested it.

  • Homebrew:

    brew install pcl opencv cmake octomap g2o pdal
# For issue cmake not finding Qt5 correctly (when PCL is not able to find VTK, for visualization module):
export PATH=/opt/homebrew/opt/qt@5/bin:$PATH
 # or (depending how homebrew is configured)
export PATH=/usr/local/Cellar/qt@5/5.15.8_2/bin:$PATH

  • Optional but recommended: Build/install gtsam.

    git clone https://github.com/borglab/gtsam.git
cd gtsam 
git checkout ab92779b25b04b376fbbd1846bbbd21904c50e7a
mkdir build
cd build
cmake -DGTSAM_BUILD_WITH_MARCH_NATIVE=OFF -DGTSAM_WITH_TBB=OFF -DGTSAM_BUILD_EXAMPLES_ALWAYS=OFF -DGTSAM_BUILD_TESTS=OFF -DGTSAM_BUILD_UNSTABLE=OFF -DGTSAM_USE_SYSTEM_EIGEN=ON .. 
make -j$(sysctl -n hw.logicalcpu)
sudo make install

  • Optional but recommended if you use ICP: Build/install libpointmatcher.

    git clone https://github.com/ethz-asl/libnabo.git
cd libnabo 
git checkout 3cab7eed92bd5d4aed997347b8c8a2692a83a532
mkdir build
cd build
cmake .. 
make -j$(sysctl -n hw.logicalcpu)
sudo make install

git clone https://github.com/ethz-asl/libpointmatcher.git
cd libpointmatcher 
git checkout 76f99fce0fe69e6384102a0343fdf8d262626e1f
mkdir build
cd build
cmake .. 
make -j$(sysctl -n hw.logicalcpu)
sudo make install

  • Install SDK of the camera you want to use.

Build RTAB-Map

  1. Download RTAB-Map source: get latest release or current source 
    git clone https://github.com/introlab/rtabmap.git rtabmap
cd rtabmap/build
cmake ..
make -j$(sysctl -n hw.logicalcpu)
sudo make install
  2. Execute the application (named "rtabmap" in rtabmap/build/bin directory).
  3. See Tutorials for a simple example of usage.

Deployment

  • Call package target:

    cmake -DBUILD_AS_BUNDLE=ON ..
make package

# Packaging will be finished but the resulting App 
# cannot be started because signature issue (killed on start).
# Find a valid xcode certificate in "keychain Access" app,
# then use full common name. Example:
cd _CPack_Packages/Darwin/DragNDrop/RTABMap-0.21.0-Darwin/ALL_IN_ONE
codesign --deep --force -s "Apple Development: FIRSTNAME LASTNAME (XXXXXXXXXX)" RTABMap.app

# Create image manually:
cd ..
hdiutil create -volname RTABMap-0.21.0 -srcfolder ALL_IN_ONE -ov -format UDZO RTABMap-0.21.0-Darwin.dmg

  • Packaging issues:

    • If the RTABMap.app is built with pdal, there was a crash because it could not find libpdal_util.15.dylib:
    cd RTABMap.app/Contents/Frameworks
otool -L libpdalcpp.15.2.0.dylib 
libpdalcpp.15.2.0.dylib:
    ...
    @rpath/libpdal_util.15.dylib (compatibility version 15.0.0, current version 15.2.0, reexport)
    ...

    Change @rpath to @executable_path inside the package:

    install_name_tool -change @rpath/libpdal_util.15.dylib @executable_path/../Frameworks/libpdal_util.15.dylib libpdalcpp.15.2.0.dylib

    • If cpack cannot resolve an item with @loader_path prefix like @loader_path/libcom_err.3.0.dylib, the file may be local in one of the subdirectory dependencies under /opt/homebrew. Find the file and copy/symlink it inside /opt/homebrew/lib directory so that fixup_bundle can find it.

    • With Qt6, we can ignore errors like ERROR: Cannot resolve rpath "@rpath/QtGui.framework/Versions/A/QtGui" on qt deploy step.

iOS iOS

Download on App Store:

https://apps.apple.com/ca/app/rtab-map-3d-lidar-scanner/id1564774365

To build from source:

For iOS build, no need to build MacOS version above. Begin by building all dependencies for iOS (curl, cmake, git and XCode should be manually installed):

$ git clone https://github.com/introlab/rtabmap.git rtabmap
$ cd rtabmap/app/ios/RTABMapApp
$ ./install_deps.sh

Note that the installation script has been tested on Apple Silicon only. Then open XCode project located in rtabmap/app/ios. Connect your iPhone/iPad with LiDAR, select it in XCode then press "Play" button. It should build, install and launch the App on your device.

Windows Windows

Win64 Binaries

Source

Updated March 2023

vcpkg

You can download and install rtabmap using the vcpkg dependency manager (use this pull request: https://github.com/microsoft/vcpkg/pull/30254 till it is merged). Set environment variable VCPKG_DEFAULT_TRIPLET=x64-windows for convenience. Instructions below will assume you are using x64-windows triplet by default. From a "x64 visual studio command prompt" (Administrator mode):

git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
bootstrap-vcpkg.bat
vcpkg integrate install
vcpkg install rtabmap --clean-after-build

The rtabmap port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please create an issue or pull request on the vcpkg repository.

To build rtabmap with camera drivers or other dependencies not available in vcpkg, you may use vcpkg just for those dependencies:

vcpkg install ceres g2o octomap zlib sqlite3 opencv[contrib,nonfree] pcl[qt,vtk] yaml-cpp --clean-after-build

Then build rtabmap manually (with a Visual Studio solution):

git clone https://github.com/introlab/rtabmap.git
cd rtabmap/build
cmake -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake ..
cmake --build . --config Release

Execute the application (named "RTABMap.exe").

See Tutorials for a simple example of usage.

Optional dependencies

  • GTSAM: download 4.0.0-alpha2 version from https://github.com/borglab/gtsam/releases and this patch gtsam-4.0.0-alpha2-MSVC.patch.

     vcpkg install boost-format --clean-after-build
 git clone --branch 4.0.0-alpha2 https://github.com/borglab/gtsam.git
 cd gtsam
 git apply gtsam-4.0.0-alpha2-MSVC.patch
 mkdir build
 cd build
 cmake -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake -DGTSAM_BUILD_EXAMPLES_ALWAYS=OFF -DGTSAM_BUILD_TESTS=OFF -DGTSAM_BUILD_STATIC_LIBRARY=ON -DGTSAM_BUILD_UNSTABLE=OFF -DGTSAM_INSTALL_CPPUNILITE=OFF -DGTSAM_USE_SYSTEM_EIGEN=ON ..
 cmake --build . --config Release --target install

  • libpointmatcher (download this patch pointmatcher_windows_dll.patch)

     vcpkg install boost-assign boost-program-options boost-timer --clean-after-build
 git clone https://github.com/ethz-asl/libnabo.git
 git clone https://github.com/ethz-asl/libpointmatcher.git

 cd libnabo
 git checkout c925c47
 mkdir build
 cmake ..
 cmake --build . --config Release --target install
 
 cd libpointmatcher
 git checkout 7dc58e5
 git apply pointmatcher_windows_dll.patch
 mkdir build
 cmake -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake ..
 cmake --build . --config Release --target install
 # Delete libpointmatcher config files in installed CMake directory, we will use only the ones in installed share\libpointmatcher\cmake folder.

  • depthai: make sure to use -DBUILD_SHARED_LIBS=ON on the first cmake so that all hunter's dependencies are built as shared libraries.

  • realsense2: you can use the binaries, but for this T265 issue, you can add this patch to vcpkg realsense2 port (vcpkg install realsense2[core,tm2]).

  • CCCoreLib: make nanoflann interface PRIVATE instead of PUBLIC.

Deployment

cmake -DBUILD_AS_BUNDLE=ON ..
cmake --build . --config Release --target package

Issues

Depth not registered to RGB

  • If you see a misalignment between the depth and the RGB or the point cloud is mirrored when using source from OpenNI-PCL, see this page on PCL project.

  • On my machine, the SamplesConfig.xml is located here /etc/openni/SamplesConfig.xml, it should look like this (note GlobalMirror=False, RegistrationType and Registration are set) after modifications:

    <OpenNI>
<Licenses>
</Licenses>
<Log writeToConsole="false" writeToFile="false">
	<LogLevel value="3"/>
	<Masks>
		<Mask name="ALL" on="true"/>
	</Masks>
	<Dumps>
	</Dumps>
</Log>
<ProductionNodes>
	<GlobalMirror on="false"/> <!-- Disable mirror -->
	<Node type="Depth" name="MyDepth">
		<Configuration>
			<!-- Kinect works only with RegistrationType 2. Asus works only with RegistrationType 1. -->
            		<Property type="int" name="RegistrationType" value="2"/>
            		<Property type="int" name="Registration" value="1"/>
		</Configuration>
	</Node>
	<Node type="Image" stopOnError="false" />
</ProductionNodes>
</OpenNI>

Image is mirrored

  • From version 0.8.5, you can check option "Mirroring" under the Source panel in the Preferences dialog.

Low performance of ASUS Xtion with OpenNI2 on USB3

  • If the Xtion is not detected on USB3: try updating the firmware of the Xtion.

  • If the Xtion is connected on an USB3 and there is a very low acquisition performance, try this by editing the PS1080.ini file located in OpenNI2 installation folder (if RTAB-Map is installed with binaries, the file is in bin/OpenNI2/Drivers/PS1080.ini). Uncomment lines:

    USB interface=2 (line 28)
Input format=1 (line 50)
Input format=5 (line 117)

    On Windows, you can also just uncomment Input format=1.

Uninstall

Ubuntu (or built from source)

  1. If built from source, from the build directory, you can do make uninstall.
  2. Remove the RTAB-Map's source directory.
  3. Remove RTAB-Map's working directory in "~/Documents/RTAB-Map".
  4. Remove RTAB-Map's configuration file in "~/.rtabmap/rtabmap.ini".

Mac OS X (standalone)

  1. If built from source, from the build directory, you can do make uninstall.
  2. Drag-and-drop the application in the trash.
  3. Remove RTAB-Map's working directory in "~/Documents/RTAB-Map".
  4. Remove RTAB-Map's configuration file in "~/.rtabmap/rtabmap.ini".

Windows (standalone)

  1. Use the uninstaller provided.
  2. Remove RTAB-Map's working directory in "User's directory/Documents/RTAB-Map".
  3. Remove RTAB-Map's configuration file in "User's directory/.rtabmap/rtabmap.ini".
Clone this wiki locally