search

suchetanrs / ORB-SLAM3-ROS2-Docker

This repository contains a full wrapper class for running ORB-SLAM3 on a docker container with ROS2 Humble with Ubuntu 22.04.
116 stars 19 forks source link

readme

ORB-SLAM3 ROS2 Wrapper Docker

This repository contains a dockerized comprehensive wrapper for ORB-SLAM3 on ROS 2 Humble for Ubuntu 22.04.

Demo GIF

ORBSLAM3-GIF

Steps to use this wrapper

1. Clone this repository

  1. git clone https://github.com/suchetanrs/ORB-SLAM3-ROS2-Docker
  2. cd ORB-SLAM3-ROS2-Docker
  3. git submodule update --init --recursive --remote

2. Install Docker on your system

cd ORB-SLAM3-ROS2-Docker
sudo chmod +x container_root/shell_scripts/docker_install.sh
./container_root/shell_scripts/docker_install.sh

3. Build the image with ORB_SLAM3

  1. Build the image: sudo docker build -t orb-slam3-humble:22.04 .
  2. Add xhost + to your .bashrc to support correct x11-forwarding using echo "xhost +" >> ~/.bashrc
  3. source ~/.bashrc
  4. You can see the built images on your machine by running sudo docker images.

4. Running the container

  1. cd ORB-SLAM3-ROS2-Docker (ignore if you are already in the folder)
  2. sudo docker compose run orb_slam3_22_humble
  3. This should take you inside the container. Once you are inside, run the command xeyes and a pair of eyes should pop-up. If they do, x11 forwarding has correctly been setup on your computer.

5. Building the ORB-SLAM3 Wrapper

Launch the container using steps in (4).

cd /root/colcon_ws/
colcon build --symlink-install
source install/setup.bash

Launching ORB-SLAM3

Launch the container using steps in (4). If you are inside the container, run the following:

  1. ros2 launch orb_slam3_ros2_wrapper unirobot.launch.py
  2. You can adjust the initial co-ordinates of the robot along with its namespace in the unirobot.launch.py file.

Running this with a Gazebo Classic simulation.

  1. Setup the ORB-SLAM3 ROS2 Docker using the steps above. Once you do (1) step in the Launching ORB-SLAM3 section, you should see a window popup which is waiting for images. This is partially indicative of the setup correctly done.
  2. Setup the simulation by following the README here
  3. Once you are able to teleop the robot, you should be able to run ORB-SLAM3 with both the containers (simulation and wrapper) running parallely.

Potential issues you may face.

The simulation and the wrapper both have their ROS_DOMAIN_ID set to 55 so they are meant to work out of the box. However, you may face issues if this environment variable is not set properly. Before you start the wrapper, run ros2 topic list and make sure the topics namespaced with scout_2 are visible inside the ORB-SLAM3 container provided the simulation is running along the side.

Important notes

ORB-SLAM3 is launched from orb_slam3_docker_20_humble/orb_slam3_ros2_wrapper/launch/rgbd.launch.py which inturn is launched from orb_slam3_docker_20_humble/orb_slam3_ros2_wrapper/launch/unirobot.launch.py

Currently the rgbd.launch.py launch file defaults to orb_slam3_ros2_wrapper/params/scout_v2_rgbd.yaml. You can modify this with your own parameter file in case you wish to use your own camera.

The very initial versions of this code were derived from thien94/orb_slam3_ros_wrapper and zang9/ORB_SLAM3_ROS2

ROS Parameter descriptions

Parameter Name Default Value Description
robot_base_frame base_footprint The name of the frame attached to the robot's base.
global_frame map The name of the global frame of reference. It represents a fixed world coordinate frame in which the robot navigates.
odom_frame odom The name of the odometry frame.
robot_x 0.0 The robot's initial x-coordinate in the global frame. Specifies the starting position along the x-axis. The SLAM Wrapper will assume this to be the initial x position
robot_y 0.0 The robot's initial y-coordinate in the global frame. Specifies the starting position along the y-axis. The SLAM Wrapper will assume this to be the initial y position
visualization true A boolean flag to enable or disable visualization. When set to true, the ORB-SLAM3 viewer will show up with the tracked points and the keyframe trajectories.
ros_visualization false A boolean flag to control ROS-based visualization. If set to true, it enables ROS tools like RViz to visualize the robot's data. (3D position of the tracked points etc.) This feature is unstable and not tested as of now
no_odometry_mode false A boolean flag to toggle odometry mode. When true, the system operates without relying on odometry data, which might be used in scenarios where odometry information is unavailable or unreliable. In this case, it publishes the transform directly between the global_frame and the robot_base_frame