OpenLMM

Note

This branch is a generalized version of Uni-Mapper. As the main author has graduated and follow-up work based on this paper is ongoing, the official code release is limited. Instead, we decided to provide OpenLMM, a more generalized version of Uni-Mapper that includes multi-map alignment and dynamic object removal modules.

📌 Uni-Mapper details

Uni-mapper

This repository is the official code of the paper:

Uni-Mapper: Unified Mapping Framework for Multi-modal LiDARs in Complex and Dynamic Environments

Gilhwan Kang, Hogyun Kim, Byunghee Choi, Seokhwan Jeong, Young-Sik Shin*, and Younggun Cho*.
* Corresponding Authors.

Accepted in Transaction on Intelligent Vehicles

Introduction

Uni-mapper is a map-merging framework for multi-modal LiDARs in complex and dynamic environments. Our approach consists of three core components: dynamic object removal, dynamic-aware scene description, and multiple map alignment. A voxel-wise free space hash map is built to remove dynamic objects by combining sequential free spaces. This is integrated with a stable triangle descriptor (STD) to form DynaSTD, which preserves static points and is effective across multi-modal LiDARs. DynaSTD is used for pose graph optimizations in intra-session and inter-map loop closures, with a centralized anchor-node approach to reduce intra-session drift errors.

Table of Contents

Note The code will be released after the paper is accepted.

Setup

• Installation
• Datasets

Example

• Merging multiple maps

How to use

• refer the workshop branch

Updates

• 25.05.31 : Accepted in Transaction on Intelligent Vehicles
• 24.10.09 : Resubmitted to T-IV
• 24.05.08 : Accepted in ICRAW on Future of Construction (3rd prize)

Citation

@article{kang2025uni,
  title={Uni-Mapper: Unified Mapping Framework for Multi-modal LiDARs in Complex and Dynamic Environments},
  author={Kang, Gilhwan and Kim, Hogyun and Choi, Byunghee and Jeong, Seokhwan and Shin, Young-Sik and Cho, Younggun},
  journal={IEEE Transactions on Intelligent Vehicles},
  year={2025},
  publisher={IEEE}
}

Intro

OpenLMM is a modularized LiDAR Map Merging and Long-term Map Management framework, including loop closure detection, robust optimization, and dynamic removal modules for long-term LiDAR mapping.

sample.mp4

Features

• Data Loader
  • Supports pcd, bin, and custom formats for scan data
  • Supports KITTI, TUM, and custom formats for pose data
• Loop Detector
  • Dynamic loading of place recognition (PR) modules
  • Supports k-d tree–based vector search modules (Scan Context, Solid)
• Backend Optimizer
  • Supports iSAM2 based optimization
• Dynamic Remover
  • Dynamic loading of dynamic object removal (DOR) modules
  • Supports online removal modules (HMM-MOS, DUFOMap)
  • Supports offline removal module (ERASOR)

Local Setting

System requirenments

• Ubuntu 22.04
• ROS2 Humble
• GTSAM 4.2a9

Local build

# 1. make your own workspace
mkdir -p ws_OpenLMM/src
cd ws_OpenLMM/src

2. Clone the repository (renaming the directory to `open-lmm` is important!)
git clone https://github.com/sparolab/uni-mapper.git open-lmm

# 3. colcon build
cd ..
colcon build --symlink-install

# 4. Run OpenLMM
source install/setup.bash
ros2 run open_lmm_ros open_lmm_rosnode

Docker Setting

System requirenments

• docker
• docker-compose

Docker build

# 1. make your own workspace in local system
mkdir -p ws_OpenLMM/src
cd ws_OpenLMM/src

2. Clone the repository (renaming the directory to `open-lmm` is important!)
git clone https://github.com/sparolab/uni-mapper.git open-lmm

# 3. Set open-lmm via dockerfile
cd open-lmm
bash run_docker.sh $(YOUR_LOCAL_DATASET_ROOT_PATH)

# 4. colcon build in docker container (via VsCode container extension, Terminal...)
cd /root/workspace
colcon build --symlink-install

# 5. Run OpenLMM
source install/setup.bash
ros2 run open_lmm_ros open_lmm_rosnode

How to use?

Prepare example dataset

Sample dataset collected in our campus (Google Drive link)

Data format

root
├─ dataset_root
│  ├─ agent1
│  │  ├─ Scans
│  │  │  ├─ 000000.pcd
│  │  │  ├─ 000001.pcd
│  │  │  └─ ...
│  │  └─ optimized_poses.txt
│  ├─ agent2
│  │  ├─ Scans
│  │  └─ optimized_poses.txt
│  └─ ...
└─ ...

• Refer to the config/core/data_loader/file_based.json file for detailed usage.
• You can modify the Scans directory name, as well as the file name and extension of poses.txt.
• Supports pcd and bin(KITTI) file formats for scan data.
• Supports both KITTI and TUM pose formats.
• You can also define a custom type for both scan format and pose format.
• Since Uni-Mapper utilizes STD as the base loop descriptor, I also use accumulated scans as keyframes (by accumulating 10 frames of Fast-LIO2 output points).

Config setting

TBD

TODO

• Add visualization support
• Refactor the centralized shared_data structure
• Replace PCL types with Eigen vectors
• Add hash map-based LiDAR descriptors

Acknowledgments

While working on the Uni-Mapper project, I (Gilhwan Kang) found it particularly challenging to tackle dynamic object removal, LiDAR-based place recognition, and map alignment all at once. Originally started as a personal study rather than as a novel research contribution, this project is intended to serve as a practical tool to help other researchers easily test or adapt their own custom datasets and algorithms when working on similar problems.

This project stands on the shoulders of giants—it is built upon a foundation of outstanding prior research and open-source contributions. The following acknowledgments are our gratitude for those invaluable works.

• LT-Mapper – used as the baseline framework of Uni-Mapper
• GLIM – referenced for dynamic loading modules and configuration structure
• KISS-ICP – served as a baseline for the overall codebase structure and modern CMake setup
• KISS-MATCHER – provided essential map-to-map alignment functionalities
• ScanContext – used as the base DB structure for KD-tree-based scan retrieval
• SOLID – contributed insights into light-weight LiDAR descriptor
• Dynamic Benchmark – offered C++-refactored versions of dynamic object removal algorithms such as ERASOR and DUFOMap
• HmmMOS – referred to as a SOTA online dynamic object removal approach

License

Since this repository includes ERASOR (licensed under GPL-3.0), it is also distributed under the same license.

Contact

• Maintainer: Gilhwan Kang ([email protected])