A modularized multi-robot SLAM system with elevation mapping and a costmap converter for easy navigation. Different odometry and loop closure algorithms can be easily integrated into the system.
View Demo
·
Report Bug
·
Request Feature
This is a C++ library with ROS interfaces to manage multi-robot maps. It contains a pluggable front-end FAST-LIO2 / A-LOAM, pluggable loop closure methods DiSCO / RING / RING++ / ScanContext. and a global manager that handles submaps, loop candidates and optimization results. The optimizer is mainly based on GTSAM and dist-mapper. The system provides a 3D pointcloud map and an optional 2.5D elevation map output. The output elevation map can be easily converted to a costmap for navigation.
Author: Peter XU (Xuecheng XU)
Affiliation: ZJU-Robotics Lab
Maintainer: Peter XU, xuechengxu@zju.edu.cn
(Sept, 2023): Support front-end odometry - A-LOAM.
(Aug, 2023): RING++ is accepted for T-RO! For detailed evaluation, please refer to RING/RING++.
(July, 2023) Support RING++ in LoopDetection.
(April, 2023) Support single robot application.
(Jan, 2023) Support PCM (Pairwise Consistent Measurement) for robustness.
A Chinese version of Tutorial is posted on my blog.
Here, we provide an example to demonstrate the system. Some parameters can be changed to fit your needs.
This software is built on the Robotic Operating System (ROS tested on kinetic, melodic and noetic), which needs to be installed first. Additionally, the MR_SLAM depends on the following software:
Eigen (linear algebra library, tested on 3.2.9 & 3.3.4; elevation_mapping failed on 3.3.9)
CUDA (gpu process, failed to infer normally with CUDA>11.1 on 30-series GPU)
Cython (C extensions for Python)
pip install cython
GTSAM (pose optimization, tested on 4.0.0-alpha2)
git clone https://github.com/borglab/gtsam.git -b 4.0.0-alpha2
Follow the README in https://github.com/borglab/gtsam.git
Grid Map (grid map library for mobile robots)
sudo apt install ros-$ROS_DISTRO-grid-map*
DiSCO (pluggable loop detector)
Follow https://github.com/MaverickPeter/DiSCO-pytorch
You can also use c++ version in LoopDetection/src/disco_ros/tools/multi-layer-polar-cpu/
RING & RING++ (pluggable loop detector)
Follow the README in LoopDetection/src/RING_ros or https://github.com/lus6-Jenny/RING
torch-radon v2 (radon transform)
# Failed to infer normally with CUDA>11.1 on 30-series GPU
cd LoopDetection/torch-radon
python setup.py install
livox_ros_driver (for FAST_LIO2)
Follow https://github.com/Livox-SDK/livox_ros_driver
Fast GICP (for ICP refine)
# Fast GICP is already included in the repo with .gitmodules.
# You can use --recursive when cloning this repo or
git submodule sync
git submodule update --init --recursive
# or you can clone the repo and put them in the same place
Follow https://github.com/SMRT-AIST/fast_gicp
(optional - for elevation_mapping) OctoMap (octomap library for multi-resolution)
sudo apt install ros-$ROS_DISTRO-octomap*
(optional - for elevation_mapping) Kindr
Follow https://github.com/anybotics/kindr
(optional - for docker use) nvidia-docker
git clone --recursive https://github.com/MaverickPeter/MR_SLAM.git
cd Mapping && catkin_make -DBUILD_PYTHON_BINDINGS=ON
Make Localization
# In Noetic with Ubuntu 20.04, you need to make some modifications to the original codes in A-LOAM.
# 1. modify the "/camera_init in all cpp files to "camera_init".
# 2. modify the #include <opencv/cv.h> in scanRegistration.cpp to #include <opencv2/imgproc.hpp>.
# 3. modify the CV_LOAD_IMAGE_GRAYSCALE to cv::IMREAD_GRAYSCALE
# 4. modify the set(CMAKE_CXX_FLAGS "-std=c++11") to set(CMAKE_CXX_STANDARD 14) in Cmakelists.txt
cd Localization && catkin_make
cd Costmap && catkin_make
Make LoopDetection
cd LoopDetection && catkin_make -DBUILD_PYTHON_BINDINGS=ON
# If you encounter the PyInit__tf2 issue, use catkin_make with your python3 environment
catkin_make --cmake-args \
-DCMAKE_BUILD_TYPE=Release -DPYTHON_EXECUTABLE=/home/client/miniconda3/envs/py38/bin/python3.8 \
-DPYTHON_INCLUDE_DIR=/home/client/miniconda3/envs/py38/include/python3.8 \
-DPYTHON_LIBRARY=/home/client/miniconda3/envs/py38/lib/libpython3.8.so \
-DBUILD_PYTHON_BINDINGS=ON
Get rosbag from Google Drive or Baidu Pan with extract code: gupx
Run roscore
Run bag
rosbag play 3_dog.bag --clock --pause
Run DiSCO / RING / RING++ / Scan Context (If you encountered the error 'ImportError: dynamic module does not define module export function' you can refer to https://github.com/MaverickPeter/MR_SLAM/issues/4)
# !!!!! You need to change the Python interpreter to your environment The default is mine: #!/home/client/miniconda3/envs/disco/bin/python3
cd LoopDetection && source devel/setup.bash
# DiSCO
rosrun disco_ros main.py
# Scan Context
cd src/RING_ros
python main_SC.py
# RING: If you encounter the PyInit__tf2 issue, use catkin_make with your python3 environment. Check installation section.
cd src/RING_ros
python main_RING.py
# or RING++
python main_RINGplusplus.py
# Note that if you add #!/xxx/python3 in the first line of RING_ros/main.py you can also use rosrun RING_ros main.py to start the node.
Run global_manager
cd Mapping && source devel/setup.bash
roslaunch global_manager global_manager.launch
Visualization
rviz -d Visualization/vis.rviz
Get rosbag from Google Drive and decompress the bags using
rosbag decompress xxx.bag
Run roscore
Run bags (in 3 terminals)
rosbag play loop_22.bag --clock --pause
rosbag play loop_30.bag
rosbag play loop_31.bag
Run Odometry Fast-LIO/A-LOAM (in 3 terminals)
# Set parameters in Localization/src/FAST_LIO/launch/ and Localization/src/FAST_LIO/config/ !!You need to set the scan_publish_en to true to send submaps
cd Localization && source devel/setup.bash
roslaunch fast_lio robot_1.launch
roslaunch fast_lio robot_2.launch
roslaunch fast_lio robot_3.launch
# Set parameters in Localization/src/A-LOAM/launch/ !!You need to set the scan_publish_en to true to send submaps
cd Localization && source devel/setup.bash
roslaunch aloam robot_1.launch
roslaunch aloam robot_2.launch
roslaunch aloam robot_3.launch
Run elevation_mapping (in 3 terminals)
# Set parameters in Mapping/src/elevation_mapping_periodical/elevation_mapping_demos/launch/ and Mapping/src/elevation_mapping_periodical/elevation_mapping_demos/config/
cd Mapping && source devel/setup.bash
roslaunch elevation_mapping_demos robot_1.launch
roslaunch elevation_mapping_demos robot_2.launch
roslaunch elevation_mapping_demos robot_3.launch
Run preprocess tools (in 3 terminals)
# If robots don't have cameras, you have to create fake images for elevation_mapping
cd Tool/Fake_img
python robot_1.py
python robot_2.py
python robot_3.py
# If robots' point cloud are too large for real-time processing, you have to launch filters to accelerate.
cd Tool/Filters
roslaunch filter_robot_1.launch
roslaunch filter_robot_2.launch
roslaunch filter_robot_3.launch
Run loop detection module
# You may need to change the Python interpreter to your environment The default is: #!/usr/bin/python3
cd LoopDetection && source devel/setup.bash
# DiSCO
rosrun disco_ros main.py
# Scan Context
cd src/RING_ros
python main_SC.py
# RING
cd src/RING_ros
python main_RING.py
# or RING++
python main_RINGplusplus.py
Run global_manager
# Set parameters in Mapping/src/global_manager/launch/
cd Mapping && source devel/setup.bash
roslaunch global_manager global_manager.launch
Run costmap converter
# Set parameters in Costmap/src/costmap/params/
cd Costmap && source devel/setup.bash
roslaunch costmap_converter create_costmap.launch
Visualization
rviz -d Visualization/vis.rviz
Build docker from Dockerfile.
or you can just pull our docker from dockerhub.
docker pull maverickp/mrslam:noetic
# The codes are deployed in /home directory. You can follow the usage above to start nodes.
# The code of A-LOAM, Costmap is modified to fit in Ubuntu 20.04 with ros noetic.
See the open issues for a full list of proposed features (and known issues).
If you find this repo useful to your project, please consider to cite it with the following bib:
@article{xu2023ring++,
title={RING++: Roto-Translation-Invariant Gram for Global Localization on a Sparse Scan Map},
author={Xu, Xuecheng and Lu, Sha and Wu, Jun and Lu, Haojian and Zhu, Qiuguo and Liao, Yiyi and Xiong, Rong and Wang, Yue},
journal={IEEE Transactions on Robotics},
year={2023},
publisher={IEEE}
}
@inproceedings{lu2022one,
title={One RING to Rule Them All: Radon Sinogram for Place Recognition, Orientation and Translation Estimation},
author={Lu, Sha and Xu, Xuecheng and Yin, Huan and Chen, Zexi and Xiong, Rong and Wang, Yue},
booktitle={2022 IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS)},
pages={2778-2785},
year={2022},
organization={IEEE}
}
@article{xu2021disco,
title={Disco: Differentiable scan context with orientation},
author={Xu, Xuecheng and Yin, Huan and Chen, Zexi and Li, Yuehua and Wang, Yue and Xiong, Rong},
journal={IEEE Robotics and Automation Letters},
volume={6},
number={2},
pages={2791--2798},
year={2021},
publisher={IEEE}
}
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!
git checkout -b feature/AmazingFeature
)git commit -m 'Add some AmazingFeature'
)git push origin feature/AmazingFeature
)Distributed under the MIT License. See LICENSE.txt
for more information.
Xuecheng Xu - xuechengxu@zju.edu.cn
Project Link: MR_SLAM
Related Link: RING/RING++ / DiSCO / Scan Context / Fast-LIO2 / A-LOAM / GTSAM