Skip to content

Docker Environment

To ensure reproducibility and consistency in the benchmarking process, we provide a Docker environment that contains all the necessary dependencies and configurations for running the SLAM algorithms. This Docker environment allows researchers to easily replicate our benchmarking results and test their own algorithms under the same conditions.

Docker Images

The benchmark uses two Docker images:

Contains the following SLAM algorithms:

  • A-LOAM
  • LeGO-LOAM-BOR
  • LIORF
  • DLIO

Contains the following SLAM algorithms:

  • VineSLAM
  • KISS-ICP
  • GLIM
  • Kinematic-ICP
  • MOLA-LO

Both images include:

  • Visualization tools including RViz
  • All necessary dependencies and configurations

Installation

Prerequisites

  • Docker installed on your system
  • At least 10GB of free disk space
  • 16GB RAM recommended for optimal performance

Guide for installing Docker and other tools in Ubuntu 20.04

For more detailed information about the Docker installation and additional setups, please refer to the Install Docker section.

Setup Instructions

Clone the repository:

git clone https://github.com/JorgeDFR/3d_lidar_slam_benchmark_at_iilab.git
cd 3d_lidar_slam_benchmark_at_iilab/docker

Option 1: Pull Prebuilt Image (faster)

docker pull jorgedfr/3d_slam_ros1:noetic

Option 2: Build Image Locally (slower)

docker compose build ros1_noetic

Start the Docker container:

docker compose up ros1_noetic -d

Access the Docker container:

docker exec -it 3d_slam_ros1 bash

Option 1: Pull Prebuilt Image (faster)

docker pull jorgedfr/3d_slam_ros2:humble

Option 2: Build Image Locally (slower)

docker compose build ros2_humble

Start the Docker container:

docker compose up ros2_humble -d

Access the Docker container:

docker exec -it 3d_slam_ros2 bash

GUI Applications

Before running RViz inside the Docker container, you need to set up xhost: 

./setup_xhost.sh

Dataset Directory

The provided Docker Compose file is configured to mount the ${HOME}/slam_data directory, allowing containerized access to the dataset files. To ensure proper functionality, save your dataset in this directory. Alternatively, you can modify the docker-compose.yml file to specify a different path if needed.

Running SLAM Algorithms

In one terminal, set the enviroment variables to select the algorithm and 3D LiDAR sensor, and start the SLAM algorithm:

# Set environment variables
export SLAM_CONF=<algorithm_name>  
# Options: aloam, lego_loam_bor, liorf, dlio

export SLAM_SENSOR=<sensor_name>  
# Options: velodyne_vlp_16, ouster_os1_64, robosense_rs_helios_5515, livox_mid_360

# Start the SLAM algorithm
roslaunch slam_benchmark_ros1_conf slam_benchmark.launch

In another terminal, play the rosbag of the desired sequence:

rosbag play <rosbag_file_path>

In one terminal, set the enviroment variables to select the algorithm and 3D LiDAR sensor, and start the SLAM algorithm:

# Set environment variables
export SLAM_CONF=<algorithm_name>  
# Options: vineslam, kiss_icp, glim, kinematic_icp, mola_lo

export SLAM_SENSOR=<sensor_name>  
# Options: velodyne_vlp_16, ouster_os1_64, robosense_rs_helios_5515, livox_mid_360

# Start the SLAM algorithm
ros2 launch slam_benchmark_ros2_conf slam_benchmark.launch.xml
In another terminal, play the rosbag of the desired sequence:

ros2 bag play <rosbag_file_path>

VineSLAM Special Case

VineSLAM requires recompilation of its ROS 2 package whenever the LiDAR sensor is changed. Use the -DLIDAR_TYPE CMake argument to specify your sensor:

  • -DLIDAR_TYPE=0 (default) for Velodyne VLP-16
  • -DLIDAR_TYPE=1 for RoboSense RS-Helios-5515
  • -DLIDAR_TYPE=3 for Ouster-OS1-64
  • -DLIDAR_TYPE=4 for Livox Mid-360
cd ros2_ws
colcon build --packages-select vineslam_ros --cmake-args -DLIDAR_TYPE=0

Offline Processing Mode

Alternatively, several SLAM algorithms support an offline mode that processes rosbag files faster than real-time without losing messages:

roslaunch slam_benchmark_ros1_conf slam_benchmark.launch run_offline:=true rosbag_path:=<rosbag_file_path>

ros2 launch slam_benchmark_ros2_conf slam_benchmark.launch.xml run_offline:=true rosbag_path:=<rosbag_file_path>

Supported Algorithms for Offline Mode

The following algorithms currently support offline processing:

  • LeGO-LOAM-BOR
  • GLIM
  • Kinematic-ICP
  • MOLA-LO

Recording Odometry Trajectories

To record the odometry trajectory generated by the SLAM algorithms, run the following command in another terminal:

rosbag record -O <output_bag_file_name> /slam_odom

ros2 bag record -o <output_bag_file_name> /slam_odom

MOLA-LO Special Case

For MOLA-LO, use the following command: 

# Set environment variable to use the LiDAR frame instead of base_link
export MOLA_USE_FIXED_LIDAR_POSE=true

mola-lidar-odometry-cli \
    -c $(ros2 pkg prefix mola_lidar_odometry)/share/mola_lidar_odometry/pipelines/lidar3d-default.yaml \
    --input-rosbag2 <path_to_bag_file> \
    --lidar-sensor-label <lidar_topic> \
    --output-tum-path <output_file_path>

  • <path_to_bag_file>: Path to your input rosbag file
  • <lidar_topic>: LiDAR sensor topic name (/eve/ouster/points for Ouster sequences or /eve/lidar3d for other sensors)
  • <output_file_path>: Desired path for the TUM-formatted trajectory output