solid-descriptor 2.1.0

[IEEE RA-L 2024] Narrowing your FOV with SOLiD: Spatially Organized and Lightweight
Global Descriptor for FOV-constrained LiDAR Place Recognition

A robot recognizes where it has been before, even when its sensor sees only a narrow or partly blocked slice of the world, and uses it to close loops and to merge runs from different days and robots:

• 🎯 FOV-aware: points are binned by range, elevation and azimuth inside the sensor's real vertical field of view.
• 🧭 Two signatures: R-SOLiD (range) finds the place, A-SOLiD (azimuth) recovers the yaw between the two visits.
• ⚡ Lightweight: about 1.5 ms per keyframe on a CPU, with no GPU and no training.
• 📡 Any range sensor: spinning or solid-state LiDAR, and sparse 4D radar through submaps of consecutive scans.
• 🔁 Online loop closing: candidates are checked with GICP and added to an iSAM2 pose graph while the robot runs.
• 🗺️ Multi-session SLAM: sessions from different days are aligned into one map (guide).
• 👥 Multi-robot: map merging from a few exchanged scans (Commerge) and distributed multi-robot SLAM (SKiD-SLAM).

It runs on top of the odometry you already have, on cars, legged robots and humanoids:

💾 Datasets

The examples use KITTI odometry sequence 00 (velodyne scans, poses and calibration). The integrations were tested on Kimera-Multi, SNAIL-Radar, the GaRLILEO dataset, the Leg-KILO dataset and KILVO. The macOS tool reads the sequence folder directly; for ROS, turn it into a bag with /cloud and /odom (ground-truth poses):

cd slam/common/mac
python kitti_to_bag.py /path/to/kitti/sequences/00 kitti00.bag --voxel 0.4        # ROS 1
python kitti_to_bag.py /path/to/kitti/sequences/00 kitti00_ros2 --voxel 0.4       # ROS 2

📦 Installation

git clone --recursive https://github.com/sparolab/SOLiD.git     # --recursive also gets the odometries in thirdparty/

Everything is built on one C++ library, cpp/: the ROS 1 and ROS 2 packages (slam/common/ros1/, slam/common/ros2/) and the macOS tools (slam/common/mac/) are thin wrappers around it, so they run the same code and give the same loops. Odometry integrations (FAST-LIO, KISS-ICP, GeoRIO, GaRLILEO, Leg-KILO) live per platform in slam/ with their own Docker images in docker/slam.

Docker

xhost +local:docker

# ROS 1: pull the prebuilt image (or build it: docker build -f docker/Dockerfile.noetic -t ghcr.io/sparolab/solid:noetic .)
docker pull ghcr.io/sparolab/solid:noetic
docker run -it --rm --net=host -e DISPLAY=$DISPLAY \
  -v /tmp/.X11-unix:/tmp/.X11-unix -v /path/to/bags:/data ghcr.io/sparolab/solid:noetic

# ROS 2: pull the prebuilt image (or build it: docker build -f docker/Dockerfile.humble -t ghcr.io/sparolab/solid:humble .)
docker pull ghcr.io/sparolab/solid:humble
docker run -it --rm --net=host -e DISPLAY=$DISPLAY \
  -v /tmp/.X11-unix:/tmp/.X11-unix -v /path/to/bags:/data ghcr.io/sparolab/solid:humble

From source

sudo add-apt-repository ppa:borglab/gtsam-release-4.0
sudo apt install libeigen3-dev libyaml-cpp-dev libgtsam-dev libgtsam-unstable-dev

# clone into ~/catkin_ws/src; to add an odometry, link it next to SOLiD (see thirdparty/README.md):
# ln -s ~/catkin_ws/src/SOLiD/thirdparty/FAST_LIO ~/catkin_ws/src/
cd ~/catkin_ws && catkin_make -DCMAKE_BUILD_TYPE=Release

sudo apt install libeigen3-dev libyaml-cpp-dev ros-humble-gtsam

# clone into ~/ros2_ws/src
# add an odometry with its folder, e.g. src/SOLiD/thirdparty/GeoRIO (see thirdparty/README.md)
cd ~/ros2_ws && colcon build --base-paths src/SOLiD/slam/common/ros2 src/SOLiD/tools/multi-session-slam/ros2 --cmake-args -DCMAKE_BUILD_TYPE=Release

xcode-select --install && brew install cmake eigen pcl yaml-cpp
python3 -m venv .venv && source .venv/bin/activate     # or: uv venv && source .venv/bin/activate
pip install solid-descriptor rosbags matplotlib          # front-end (Python binding, import solid; or `pip install .` from the clone)

# GTSAM is not in Homebrew: build it once (tested: 4.3.0 with Homebrew Eigen 5)
git clone --branch 4.3.0 --depth 1 https://github.com/borglab/gtsam.git ~/gtsam-src
cmake -S ~/gtsam-src -B ~/gtsam-build -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=$HOME/gtsam-install \
  -DGTSAM_USE_SYSTEM_EIGEN=ON -DGTSAM_WITH_TBB=OFF -DGTSAM_BUILD_TESTS=OFF -DGTSAM_BUILD_EXAMPLES_ALWAYS=OFF \
  -DGTSAM_BUILD_UNSTABLE=OFF -DGTSAM_BUILD_PYTHON=OFF -DGTSAM_ENABLE_BOOST_SERIALIZATION=OFF -DGTSAM_USE_BOOST_FEATURES=OFF
cmake --build ~/gtsam-build -j && cmake --install ~/gtsam-build

# back-end tools: loop closing (solid_close_loops) and multi-session (solid_align_sessions)
cmake -S cpp -B build -DSOLID_USE_PCL=OFF -DSOLID_BUILD_BACKEND=ON -DGTSAM_DIR=$HOME/gtsam-install/lib/cmake/GTSAM
cmake --build build -j && export SOLID_TOOLS=$PWD/build

🚀 Run

Pick an odometry; it runs live and SOLiD closes loops on its output online:

# ROS 1: odometry = fast_lio | kiss_icp | legkilo | fast_lio_mid360
roslaunch solid_ros run.launch odometry:=fast_lio save_dir:=$HOME/solid_results
rosbag play --clock <bag>

# ROS 2: odometry = fast_lio | kiss_icp | georio | garlileo | legkilo | fast_lio_mid360
ros2 launch solid_ros run.launch.py odometry:=georio save_dir:=$HOME/solid_results
ros2 bag play <bag> --clock

# Your own odometry: give SOLiD its cloud and odometry topics
roslaunch solid_ros solid.launch config:=kitti cloud_topic:=/cloud odom_topic:=/odom

# macOS: the same front-end and back-end, from a bag or a KITTI folder
cd slam/common/mac && python solid_loops.py --kitti /path/to/kitti/sequences/00 --config ../../config/kitti.yaml --out $HOME/solid_results --close-loops

See the guides for all arguments, outputs and the odometry integrations: Run · Integrations.

🧰 Tools

Multi-session SLAM

Each run is saved as a session; sessions from different days are aligned into one map:

roslaunch solid_multi_session align.launch sessions:="$HOME/day1 $HOME/day2" save_dir:=$HOME/aligned       # ROS 1
ros2 launch solid_multi_session align.launch.py sessions:="$HOME/day1 $HOME/day2" save_dir:=$HOME/aligned  # ROS 2
tools/multi-session-slam/mac/align.sh $HOME/aligned $HOME/day1 $HOME/day2    # macOS

See the multi-session SLAM guide for all arguments, outputs, results and the configuration.

Multi-Robot Map Merging

Each robot sends its SOLiD descriptors to a server, which picks the few scans that carry the overlap; only those are exchanged, registered and merged:

See Commerge (IJRR 2026): it reads the sessions SOLiD saves, commerge robot_a/ robot_b/ --out merged/.

Distributed Multi-Robot SLAM

Robots share SOLiD descriptors peer to peer to recognize where their maps overlap and merge them into one:

See SKiD-SLAM (IEEE T-FR 2026): distributed multi-robot LiDAR SLAM built on SOLiD, with field deployments at planetary analog sites.

🤖 Run with your agent

Open Claude Code or Codex in an empty folder and paste:

Clone https://github.com/sparolab/SOLiD, read its AGENTS.md, and follow it to build SOLiD and run it on KITTI 00 on this machine. Ask me what you need along the way.

The agent follows AGENTS.md: it builds SOLiD for ROS 1, ROS 2 or macOS, prepares the data, runs loop closing, and checks the loops.

⚙️ Configuration

All parameters are read at runtime from one YAML file per sensor (kitti, ouster64, vlp16, livox_mid360, radar_4d): descriptor, keyframes, submaps, loop candidates and loop closing. See the configuration guides: Sensors and loop closing · Multi-session SLAM.

📝 TODO

• iPhone LiDAR: SOLiD on iPhone LiDAR scans with ARKit poses (indoor config for the ~5 m range)
• IMU odometry: loop closing on top of an inertial odometry such as KISS-IMU

Citation

If you use SOLiD in your research, please cite our paper (supplementary material: appendix/Appendix.pdf).

@article{kim2024narrowing,
  title     = {Narrowing your FOV with SOLiD: Spatially Organized and Lightweight Global Descriptor for FOV-constrained LiDAR Place Recognition},
  author    = {Kim, Hogyun and Choi, Jiwon and Sim, Taehu and Kim, Giseop and Cho, Younggun},
  journal   = {IEEE Robotics and Automation Letters},
  year      = {2024},
  publisher = {IEEE}
}

Contributing

We envision SOLiD as a community-driven project and love to see it grow through contributions from the community. We would love to see your face in the list below, just open a Pull Request!

Acknowledgements

SOLiD runs with FAST-LIO, KISS-ICP, GeoRIO, GaRLILEO and Leg-KILO, was tested on Kimera-Multi, SNAIL-Radar, the GaRLILEO dataset, the Leg-KILO dataset and KILVO, and builds on nanoflann, GTSAM and PCL. We thank the authors for open-sourcing their work.

Special Thanks

We sincerely thank Giseop Kim for open-sourcing LT-mapper, whose session format and multi-session design our multi-session SLAM follows.