ORB-SLAM3-ROS

June 30, 2026 · View on GitHub

A ROS implementation of ORB-SLAM3 V1.0 that focuses on the ROS part.

This package uses catkin build. Tested on Ubuntu 20.04.

1. Prerequisites

Eigen3

sudo apt install libeigen3-dev

Epoxy

Required by recent Pangolin releases (OpenGL binding). Missing this causes Could NOT find epoxy during Pangolin configuration.

sudo apt install libepoxy-dev

Pangolin

cd ~
git clone https://github.com/stevenlovegrove/Pangolin.git
cd Pangolin
mkdir build && cd build
cmake ..
make
sudo make install

OpenCV

Check the OpenCV version on your computer (required at least 3.0):

python3 -c "import cv2; print(cv2.__version__)"

On a freshly installed Ubuntu 20.04.4 LTS with desktop image, OpenCV 4.2.0 is already included. If a newer version is required (>= 3.0), follow installation instruction and change the corresponding OpenCV version in CMakeLists.txt

(Optional) hector-trajectory-server

Install hector-trajectory-server to visualize the real-time trajectory of the camera/imu. Note that this real-time trajectory might not be the same as the keyframes' trajectory.

sudo apt install ros-[DISTRO]-hector-trajectory-server

2. Installation

cd ~/catkin_ws/src
git clone https://github.com/thien94/orb_slam3_ros.git
cd ../
catkin build

3. Run Examples

Mono mode with NTU VIRAL's eee_01.bag:

# In one terminal:
roslaunch orb_slam3_ros ntuviral_mono.launch
# In another terminal:
rosbag play eee_01.bag -s 50 # The UAV starts moving at t~50s

Stereo mode with KITTI's 2011_09_26:

  • First, download KITTI dataset and convert the raw data into bag file following this instruction. You can automate the downloading process using this script.
  • Run the example:
# In one terminal:
roslaunch orb_slam3_ros kitti_stereo.launch
# In another terminal:
rosbag play kitti_2011_09_26_drive_0002_synced.bag

Mono-inertial mode with EuRoC's MH_01_easy.bag:

# In one terminal:
roslaunch orb_slam3_ros euroc_mono_inertial.launch
# In another terminal:
rosbag play MH_01_easy.bag

Stereo-inertial mode with TUM-VI's dataset-corridor1_512_16.bag

# In one terminal:
roslaunch orb_slam3_ros tum_vi_stereo_inertial.launch
# In another terminal:
rosbag play dataset-corridor1_512_16.bag

RGB-D mode with TUM's rgbd_dataset_freiburg1_xyz.bag

# In one terminal:
roslaunch orb_slam3_ros tum_rgbd.launch
# In another terminal:
rosbag play rgbd_dataset_freiburg1_xyz.bag
  • Note: change TUMX.yaml to TUM1.yaml,TUM2.yaml or TUM3.yaml for freiburg1, freiburg2 and freiburg3 sequences respectively.

RGB-D-Inertial mode with VINS-RGBD's Normal.bag

  • Download the bag files, for example Normal.bag.
  • Decompress the bag, run rosbag decompress Normal.bag.
  • Change the calibration params in RealSense_D435i.yaml if necessary.
# In one terminal:
roslaunch orb_slam3_ros rs_d435i_rgbd_inertial.launch.launch
# In another terminal:
rosbag play Normal.bag

Live stereo-inertial mode with Realsense T265

  • Modify the original rs_t265.launch to enable fisheye images and imu data (change unite_imu_method to linear_interpolation).
  • Run rs-enumerate-devices -c to get the calibration parameters and modify config/Stereo-Inertial/RealSense_T265.yaml accordingly. A detailed explaination can be found here.
  • Run:
# In one terminal:
roslaunch realsense2_camera rs_t265.launch
# In another terminal:
roslaunch orb_slam3_ros rs_t265_stereo_inertial.launch

Save and load map

The map file will have .osa extension, and is located in the ROS_HOME folder (~/.ros/ by default).

Load map:

  • Set the name of the map file to be loaded with System.LoadAtlasFromFile param in the settings file (.yaml).
  • If the map file is not available, System.LoadAtlasFromFile param should be commented out otherwise there will be error.

Save map:

  • Option 1: If System.SaveAtlasToFile is set in the settings file, the map file will be automatically saved when you kill the ros node.
  • Option 2: You can also call the following ros service at the end of the session
rosservice call /orb_slam3/save_map [file_name]

4. ROS topics, params and services

Transforms use tf2. Pose topics and the camera TF use the same composition:

T(world→camera) = world2initial * robot2camera * T_orb(world→camera)

By default world2initial and robot2camera are identity, so behaviour matches a plain ORB-SLAM3 Twc. The stereo node can set them from TF (base_link→camera) and an optional get_first_pose service (see uji_stereo.launch / cabrera_stereo.launch).

Subscribed topics

  • /camera/image_raw for Mono(-Inertial) node
  • /camera/left/image_raw for Stereo(-Inertial) node
  • /camera/right/image_raw for Stereo(-Inertial) node
  • /imu for Mono/Stereo/RGBD-Inertial node
  • /camera/rgb/image_raw and /camera/depth_registered/image_raw for RGBD node

Published topics

  • /orb_slam3/camera_pose, left camera pose in the configured world frame, at camera rate
  • /orb_slam3/robot_pose, base/robot pose in the world frame (same composition; equals camera_pose when robot2camera is identity)
  • /orb_slam3/body_odom, imu-body odometry in world frame, published at camera rate (IMU modes)
  • /orb_slam3/tracking_image, processed image from the left camera with key points and status text
  • /orb_slam3/tracked_points, map points currently tracked
  • /orb_slam3/tracked_key_points, corresponding 2D keypoints (z=0 in the point cloud)
  • /orb_slam3/all_points, all key points in the active map
  • /orb_slam3/kf_markers, markers for all keyframes' positions
  • /tf, camera (and imu-body in IMU modes) poses in the world frame; camera TF matches /camera_pose

Params

  • voc_file: path to vocabulary file required by ORB-SLAM3 (orb_slam3/Vocabulary/ORBvoc.txt.bin; underwater setups may use UORBvoc.txt.bin)
  • settings_file: path to settings file required by ORB-SLAM3
  • enable_pangolin: enable/disable ORB-SLAM3's Pangolin viewer and interface (true by default)
  • world_frame_id, cam_frame_id, imu_frame_id: TF / message frames
  • base_link_frame_id, working_path (stereo node): robot frame for extrinsics lookup and directory for optional KF / loop-closure dumps

Services

  • rosservice call /orb_slam3/save_map [file_name]: save the map as [file_name].osa in ROS_HOME folder.
  • rosservice call /orb_slam3/save_traj [file_name]: save the estimated trajectory of camera and keyframes as [file_name]_cam_traj.txt and [file_name]_kf_traj.txt in ROS_HOME folder. Prefer calling after bag playback / when the camera is idle (or right before stopping the node). Invoking save_traj while tracking is actively processing frames can block the node for a long time because trajectory export locks internal SLAM state.

Extra nodes (optional)

  • initial_pose_server_node: serves get_pose (often remapped to get_first_pose) from parameters or TF, for aligning the first stereo pose to a prior frame.
  • clock_extender: after bag playback with --clock, keeps publishing /clock briefly so nodes can finish shutdown with use_sim_time.

Docker

Provided Dockerfile sets up an image based a ROS noetic environment including RealSense SDK

To access a USB device (such as RealSense camera) inside docker container use:

docker run --network host --privileged -v /dev:/dev -it [image_name]

NOTE: --network host is recommended to listen to rostopics outside the container

To-do:

  • Publish basic topics (camera pose, tracking image and point cloud)
  • Publish more topics (odom, full map pointcloud, keyframe, etc.)
  • Add other functions as services (map save/load, save estimated trajectory, etc.)
  • Add docker support