commerge 2.0.0__tar.gz

commerge-2.0.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, SPARO LAB
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

commerge-2.0.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: commerge
+Version: 2.0.0
+Summary: Commerge: communication-efficient multi-robot map merging by selecting a few scans
+Author-email: Hogyun Kim <hg.kim@inha.edu>
+License: BSD-3-Clause
+Project-URL: Homepage, https://github.com/sparolab/Commerge
+Project-URL: Documentation, https://github.com/sparolab/Commerge/blob/main/docs/GUIDE.md
+Project-URL: Project page, https://sparolab.github.io/research/commerge/
+Project-URL: Paper, https://arxiv.org/abs/2606.25386
+Project-URL: Issues, https://github.com/sparolab/Commerge/issues
+Keywords: map merging,multi-robot,multi-robot slam,lidar,slam,place recognition,point cloud,registration,communication-efficient,vertex cover,maximum clique,gurobi,highs,solid,kiss-matcher,robotics
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy>=1.9
+Requires-Dist: matplotlib
+Requires-Dist: kiss-matcher>=1.0.2; python_version < "3.13"
+Requires-Dist: small-gicp>=1.0
+Provides-Extra: gurobi
+Requires-Dist: gurobipy; extra == "gurobi"
+Provides-Extra: solid
+Requires-Dist: solid-descriptor; extra == "solid"
+Provides-Extra: compare
+Requires-Dist: scikit-learn; extra == "compare"
+Dynamic: license-file
+
+<div align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/sparolab/Commerge/main/assets/logo_dark.svg" />
+    <img src="https://raw.githubusercontent.com/sparolab/Commerge/main/assets/logo_light.svg" alt="Commerge: Communication-Efficient Map Merging" width="560" />
+  </picture>
+  <br />
+  <a href="https://github.com/sparolab/Commerge/tree/main/commerge"><img src="https://img.shields.io/badge/Python-3670A0?logo=python&logoColor=ffdd54" /></a>
+  <a href="https://pypi.org/project/commerge/"><img src="https://img.shields.io/pypi/v/commerge?logo=pypi&logoColor=white&label=PyPI" /></a>
+  <a href="#prerequisites"><img src="https://img.shields.io/badge/Gurobi-EE3524" /></a>
+  <a href="#prerequisites"><img src="https://img.shields.io/badge/HiGHS-license--free-2E7D32" /></a>
+  <a href="https://github.com/sparolab/SOLiD"><img src="https://img.shields.io/badge/SOLiD-descriptor-3F51B5" /></a>
+  <a href="#installation"><img src="https://img.shields.io/badge/Ubuntu-E95420?logo=ubuntu&logoColor=white" /></a>
+  <a href="#installation"><img src="https://img.shields.io/badge/macOS-000000?logo=apple&logoColor=white" /></a>
+  <a href="#docker"><img src="https://img.shields.io/badge/Docker-2496ED?logo=docker&logoColor=white" /></a>
+  <a href="https://github.com/sparolab/Commerge/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-BSD--3--Clause-green" /></a>
+  <a href="https://github.com/sparolab/Commerge/actions/workflows/ci.yml"><img src="https://github.com/sparolab/Commerge/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI" /></a>
+  <br />
+  <a href="https://sparolab.github.io/research/commerge/"><img src="https://img.shields.io/badge/Project-Page-6f42c1" /></a>
+  <a href="https://arxiv.org/abs/2606.25386"><img src="https://img.shields.io/badge/arXiv-b33737?logo=arXiv" /></a>
+  <a href="https://sparolab.github.io/research/commerge/"><img src="https://img.shields.io/badge/IJRR-2026-1f6feb" /></a>
+  <a href="https://youtu.be/LV_8_jZbHV8"><img src="https://img.shields.io/badge/YouTube-FF0000?logo=youtube&logoColor=white" /></a>
+  <a href="#robot-run-with-your-agent"><img src="https://img.shields.io/badge/Claude%20Code-ready-D97757?logo=claude&logoColor=white" alt="Claude Code ready" /></a>
+  <a href="#robot-run-with-your-agent"><img src="https://img.shields.io/badge/Codex-ready-000000?logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHJlY3QgeD0iMS41IiB5PSIzIiB3aWR0aD0iMjEiIGhlaWdodD0iMTgiIHJ4PSIzIiBmaWxsPSJub25lIiBzdHJva2U9IndoaXRlIiBzdHJva2Utd2lkdGg9IjIiLz48cGF0aCBkPSJNNiA5bDMuNSAzTDYgMTUiIGZpbGw9Im5vbmUiIHN0cm9rZT0id2hpdGUiIHN0cm9rZS13aWR0aD0iMiIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIi8+PHBhdGggZD0iTTEyIDE1LjVoNiIgc3Ryb2tlPSJ3aGl0ZSIgc3Ryb2tlLXdpZHRoPSIyIiBzdHJva2UtbGluZWNhcD0icm91bmQiLz48L3N2Zz4=" alt="Codex ready" /></a>
+  <br />
+  <a href="https://pypi.org/project/commerge/"><img src="https://readme-typing-svg.demolab.com?background=0D1117&color=22C55E&font=Fira+Code&size=14&duration=2500&pause=800&center=true&vCenter=true&width=230&height=24&lines=%24+pip+install+commerge" alt="pip install commerge" /></a>
+  <br />
+  <img src="https://raw.githubusercontent.com/sparolab/Commerge/main/assets/commerge_demo.gif" alt="Commerge on KITTI 00 split into two robots: the affinity of their SOLiD descriptors goes through step (A) sequential matching, step (B) balanced minimum vertex cover and step (C) maximum edge-weighted clique; the most consistent region's scans (magenta) are the only ones exchanged, and the transform registered from them merges the two maps." width="95%" />
+  <p>
+    <strong>[IJRR 2026] Commerge: Communication-Efficient, Robust, and Fast LiDAR Map Merging Framework<br />
+    for Multi-Robot Coordination in Resource-Constrained Scenarios</strong>
+  </p>
+</div>
+
+______________________________________________________________________
+
+Robots that map on their own must exchange scans to merge their maps, and over a weak link that exchange is the bottleneck. Commerge picks the few scans that carry the overlap and sends only those, in three steps:
+
+- :robot: **Before the steps, each robot runs its own SLAM with [SOLiD](https://github.com/sparolab/SOLiD)**: keyframe scans, poses and SOLiD descriptors, saved as a session.
+- :link: **Step (A) Sequential matching**: regions of the inter-robot affinity matrix where both robots saw the same places in sequence.
+- :balance_scale: **Step (B) Balanced minimum vertex cover**: the fewest keyframes that still touch every candidate match, shared fairly between the robots.
+- :gem: **Step (C) Maximum edge-weighted clique**: among those, only the pairs that agree with each other geometrically.
+- :handshake: **Exchange and merge**: the robots exchange the scans of the most consistent region only; their submaps are registered ([KISS-Matcher](https://github.com/MIT-SPARK/KISS-Matcher) + GICP) and the transform merges the whole maps.
+- :package: **MB, not GB**: up to 99.98 % less data exchanged (7,000 MB → 1.3 MB on HeLiPR) with comparable alignment, also on a Jetson Nano.
+
+<p align="center"><img src="https://raw.githubusercontent.com/sparolab/Commerge/main/assets/summary.png" alt="Data exchanged after each step on HeLiPR: 7,000 MB for the whole map, 60 MB after step (A), 26 MB after step (B) and 1.3 MB after step (C)" width="95%" /></p>
+
+______________________________________________________________________
+
+## :package: Prerequisites
+
+- **Python 3.9+**. `pip install commerge` brings NumPy, SciPy, Matplotlib and the registration ([KISS-Matcher](https://github.com/MIT-SPARK/KISS-Matcher), wheels for Python 3.9-3.12, and [small_gicp](https://github.com/koide3/small_gicp)).
+- **Solver: [Gurobi](https://www.gurobi.com/academia/academic-program-and-licenses/), free for academic use**, as in the paper (`pip install gurobipy`, then `grbgetkey <key>`). **No license? HiGHS** ships with SciPy and returns the same selection, only slower on the largest regions (`--solver highs`; `auto`, the default, picks Gurobi when it is licensed).
+- **One session per robot** from [SOLiD](https://github.com/sparolab/SOLiD) (`thirdparty/SOLiD`): keyframe scans, poses and SOLiD descriptors.
+
+## :hammer_and_wrench: Installation
+
+```bash
+pip install commerge          # + "commerge[gurobi]" for gurobipy, "commerge[compare]" for the AutoMerge comparison
+# or from a clone, with SOLiD and KISS-Matcher as submodules:
+git clone --recursive https://github.com/sparolab/Commerge.git && cd Commerge && pip install .
+# KISS-Matcher from the submodule instead of the wheel: pip install thirdparty/KISS-Matcher/python
+commerge --version
+```
+
+Ubuntu and macOS (Python only, no ROS needed for Commerge itself).
+
+### Docker
+
+```bash
+docker pull ghcr.io/sparolab/commerge     # or: docker build -f docker/Dockerfile -t ghcr.io/sparolab/commerge .
+docker run --rm -v $HOME/robot_a:/a -v $HOME/robot_b:/b -v $PWD/merged:/out ghcr.io/sparolab/commerge \
+    commerge /a /b --threshold 0.96 --min-area 2000 --out /out --plot
+# Gurobi: add -v $HOME/gurobi.lic:/opt/gurobi/gurobi.lic (otherwise HiGHS)
+```
+
+## :rocket: Run
+
+**1. One session per robot** with SOLiD, with any odometry it supports ([FAST-LIO, KISS-ICP, GeoRIO, …](https://github.com/sparolab/SOLiD/tree/main/slam)) or without ROS:
+
+```bash
+cd thirdparty/SOLiD
+roslaunch solid_ros run.launch odometry:=fast_lio save_dir:=$HOME/robot_a     # ROS 1, while the bag of robot A plays
+ros2 launch solid_ros run.launch.py odometry:=kiss_icp save_dir:=$HOME/robot_b  # ROS 2
+python slam/common/mac/solid_loops.py --kitti <sequence> --config slam/config/kitti.yaml --out $HOME/robot_a  # no ROS
+```
+
+**2. Select the scans to exchange, register them and merge:**
+
+```bash
+commerge $HOME/robot_a $HOME/robot_b --threshold 0.96 --min-area 2000 --out merged/ --plot [--gt-a gt_a.txt --gt-b gt_b.txt]
+```
+
+```
+[commerge] kitti00_a: 1011 keyframes | kitti00_b: 1701 keyframes
+[commerge] steps (A)+(B)+(C), solver gurobi: (A) 4 region(s) (threshold 0.96, min area 2000) in 0.021 s
+[commerge] region 2: A 250-381 x B 899-1027: (A) 1077 candidate pairs -> (B) 66+66 keyframes -> (C) 24 pairs = 14 A + 17 B scans, (B) 0.34 s, (C) 0.13 s
+...
+[commerge] registered B to A: 540 KISS-Matcher inliers, GICP in 1.3 s; vs ground truth: 0.35 m, 0.06 deg (B keyframes 0.15 m off on average)
+[commerge] exchanged 14 A + 17 B scans (1.1 % of 2712, 4.6 MB) from region(s) [2] of 4 -> merged/
+```
+
+All outputs, options and the Python API: [docs/GUIDE.md](https://github.com/sparolab/Commerge/blob/main/docs/GUIDE.md).
+
+## :bar_chart: Compare
+
+`commerge-compare` runs Commerge, its ablations and AutoMerge on the same sessions. On KITTI 00 split into two robots, Commerge sends **31 of 2,712 scans (4.6 MB)** and merges the maps within **0.35 m**; AutoMerge's region sends 156 scans and merges within 1.05 m. Details and the ablations: [docs/GUIDE.md](https://github.com/sparolab/Commerge/blob/main/docs/GUIDE.md#compare-commerge-compare).
+
+______________________________________________________________________
+
+## :robot: Run with your agent
+
+Open [Claude Code](https://claude.com/claude-code) or [Codex](https://openai.com/codex/) in an empty folder and paste:
+
+```text
+Clone https://github.com/sparolab/Commerge, read its AGENTS.md, and follow it to install Commerge and merge KITTI 00 split into two robots on this machine. Ask me what you need along the way.
+```
+
+The agent follows [`AGENTS.md`](https://github.com/sparolab/Commerge/blob/main/AGENTS.md): it installs Commerge with Gurobi or HiGHS, makes one SOLiD session per robot, selects and exchanges the scans, merges the maps, and checks the result.
+
+______________________________________________________________________
+
+## :warning: Limitation: heterogeneous LiDARs
+
+Commerge selects scans from the affinity of the two robots' descriptors. With the same LiDAR on both robots, SOLiD gives an affinity whose overlapping regions stand out. With different LiDARs (a spinning Ouster and a Livox Avia with a 70° field of view, for instance), SOLiD describes the same place differently and step (A) finds hundreds of regions with no structure. A descriptor made for heterogeneous LiDARs, such as [InLiER](https://github.com/LTU-RAI/InLiER), passed with `--affinity` (and `--enhance`), brings the right region back; registering the few scans exchanged across such different fields of view is still unreliable (`--registration grid` is experimental). Contributions are welcome.
+
+______________________________________________________________________
+
+## Citation
+
+If you use Commerge in your research, please cite our [paper](https://arxiv.org/abs/2606.25386).
+
+<details>
+  <summary><strong>See bibtex</strong></summary>
+
+```bibtex
+@article{kim2026commerge,
+  author  = {Kim, Hogyun and Choi, Jiwon and Kim, Juwon and Yang, Geonmo and Jeong, Seokhwan and Lim, Hyungtae and Cho, Younggun},
+  title   = {Commerge: Communication-Efficient, Robust, and Fast LiDAR Map Merging Framework for Multi-Robot Coordination in Resource-Constrained Scenarios},
+  journal = {International Journal of Robotics Research (IJRR)},
+  year    = {2026}
+}
+```
+
+</details>
+
+## Contributing
+
+Issues and pull requests are welcome.
+
+<a href="https://github.com/sparolab/Commerge/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=sparolab/Commerge" />
+</a>
+
+## Acknowledgements
+
+Commerge uses [SOLiD](https://github.com/sparolab/SOLiD) for inter-robot place recognition. The comparison re-implements the region selection of [AutoMerge](https://github.com/MetaSLAM/AutoMerge_Server), which builds on [SeqSLAM](https://doi.org/10.1109/ICRA.2012.6224623). Related research: [KISS-Matcher](https://github.com/MIT-SPARK/KISS-Matcher), [SKiD-SLAM](https://github.com/sparolab/SKiD-SLAM).
+
+## Special Thanks
+
+We thank [Minwoo Jung](https://github.com/minwoo0611) for the [HeLiPR](https://sites.google.com/view/heliprdataset) dataset, and [Nikolaos Stathoulopoulos](https://github.com/nstathou) for [InLiER](https://github.com/LTU-RAI/InLiER), learning-free heterogeneous LiDAR place recognition.

commerge-2.0.0/README.md

@@ -0,0 +1,160 @@
+<div align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/sparolab/Commerge/main/assets/logo_dark.svg" />
+    <img src="https://raw.githubusercontent.com/sparolab/Commerge/main/assets/logo_light.svg" alt="Commerge: Communication-Efficient Map Merging" width="560" />
+  </picture>
+  <br />
+  <a href="https://github.com/sparolab/Commerge/tree/main/commerge"><img src="https://img.shields.io/badge/Python-3670A0?logo=python&logoColor=ffdd54" /></a>
+  <a href="https://pypi.org/project/commerge/"><img src="https://img.shields.io/pypi/v/commerge?logo=pypi&logoColor=white&label=PyPI" /></a>
+  <a href="#prerequisites"><img src="https://img.shields.io/badge/Gurobi-EE3524" /></a>
+  <a href="#prerequisites"><img src="https://img.shields.io/badge/HiGHS-license--free-2E7D32" /></a>
+  <a href="https://github.com/sparolab/SOLiD"><img src="https://img.shields.io/badge/SOLiD-descriptor-3F51B5" /></a>
+  <a href="#installation"><img src="https://img.shields.io/badge/Ubuntu-E95420?logo=ubuntu&logoColor=white" /></a>
+  <a href="#installation"><img src="https://img.shields.io/badge/macOS-000000?logo=apple&logoColor=white" /></a>
+  <a href="#docker"><img src="https://img.shields.io/badge/Docker-2496ED?logo=docker&logoColor=white" /></a>
+  <a href="https://github.com/sparolab/Commerge/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-BSD--3--Clause-green" /></a>
+  <a href="https://github.com/sparolab/Commerge/actions/workflows/ci.yml"><img src="https://github.com/sparolab/Commerge/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI" /></a>
+  <br />
+  <a href="https://sparolab.github.io/research/commerge/"><img src="https://img.shields.io/badge/Project-Page-6f42c1" /></a>
+  <a href="https://arxiv.org/abs/2606.25386"><img src="https://img.shields.io/badge/arXiv-b33737?logo=arXiv" /></a>
+  <a href="https://sparolab.github.io/research/commerge/"><img src="https://img.shields.io/badge/IJRR-2026-1f6feb" /></a>
+  <a href="https://youtu.be/LV_8_jZbHV8"><img src="https://img.shields.io/badge/YouTube-FF0000?logo=youtube&logoColor=white" /></a>
+  <a href="#robot-run-with-your-agent"><img src="https://img.shields.io/badge/Claude%20Code-ready-D97757?logo=claude&logoColor=white" alt="Claude Code ready" /></a>
+  <a href="#robot-run-with-your-agent"><img src="https://img.shields.io/badge/Codex-ready-000000?logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHJlY3QgeD0iMS41IiB5PSIzIiB3aWR0aD0iMjEiIGhlaWdodD0iMTgiIHJ4PSIzIiBmaWxsPSJub25lIiBzdHJva2U9IndoaXRlIiBzdHJva2Utd2lkdGg9IjIiLz48cGF0aCBkPSJNNiA5bDMuNSAzTDYgMTUiIGZpbGw9Im5vbmUiIHN0cm9rZT0id2hpdGUiIHN0cm9rZS13aWR0aD0iMiIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIi8+PHBhdGggZD0iTTEyIDE1LjVoNiIgc3Ryb2tlPSJ3aGl0ZSIgc3Ryb2tlLXdpZHRoPSIyIiBzdHJva2UtbGluZWNhcD0icm91bmQiLz48L3N2Zz4=" alt="Codex ready" /></a>
+  <br />
+  <a href="https://pypi.org/project/commerge/"><img src="https://readme-typing-svg.demolab.com?background=0D1117&color=22C55E&font=Fira+Code&size=14&duration=2500&pause=800&center=true&vCenter=true&width=230&height=24&lines=%24+pip+install+commerge" alt="pip install commerge" /></a>
+  <br />
+  <img src="https://raw.githubusercontent.com/sparolab/Commerge/main/assets/commerge_demo.gif" alt="Commerge on KITTI 00 split into two robots: the affinity of their SOLiD descriptors goes through step (A) sequential matching, step (B) balanced minimum vertex cover and step (C) maximum edge-weighted clique; the most consistent region's scans (magenta) are the only ones exchanged, and the transform registered from them merges the two maps." width="95%" />
+  <p>
+    <strong>[IJRR 2026] Commerge: Communication-Efficient, Robust, and Fast LiDAR Map Merging Framework<br />
+    for Multi-Robot Coordination in Resource-Constrained Scenarios</strong>
+  </p>
+</div>
+
+______________________________________________________________________
+
+Robots that map on their own must exchange scans to merge their maps, and over a weak link that exchange is the bottleneck. Commerge picks the few scans that carry the overlap and sends only those, in three steps:
+
+- :robot: **Before the steps, each robot runs its own SLAM with [SOLiD](https://github.com/sparolab/SOLiD)**: keyframe scans, poses and SOLiD descriptors, saved as a session.
+- :link: **Step (A) Sequential matching**: regions of the inter-robot affinity matrix where both robots saw the same places in sequence.
+- :balance_scale: **Step (B) Balanced minimum vertex cover**: the fewest keyframes that still touch every candidate match, shared fairly between the robots.
+- :gem: **Step (C) Maximum edge-weighted clique**: among those, only the pairs that agree with each other geometrically.
+- :handshake: **Exchange and merge**: the robots exchange the scans of the most consistent region only; their submaps are registered ([KISS-Matcher](https://github.com/MIT-SPARK/KISS-Matcher) + GICP) and the transform merges the whole maps.
+- :package: **MB, not GB**: up to 99.98 % less data exchanged (7,000 MB → 1.3 MB on HeLiPR) with comparable alignment, also on a Jetson Nano.
+
+<p align="center"><img src="https://raw.githubusercontent.com/sparolab/Commerge/main/assets/summary.png" alt="Data exchanged after each step on HeLiPR: 7,000 MB for the whole map, 60 MB after step (A), 26 MB after step (B) and 1.3 MB after step (C)" width="95%" /></p>
+
+______________________________________________________________________
+
+## :package: Prerequisites
+
+- **Python 3.9+**. `pip install commerge` brings NumPy, SciPy, Matplotlib and the registration ([KISS-Matcher](https://github.com/MIT-SPARK/KISS-Matcher), wheels for Python 3.9-3.12, and [small_gicp](https://github.com/koide3/small_gicp)).
+- **Solver: [Gurobi](https://www.gurobi.com/academia/academic-program-and-licenses/), free for academic use**, as in the paper (`pip install gurobipy`, then `grbgetkey <key>`). **No license? HiGHS** ships with SciPy and returns the same selection, only slower on the largest regions (`--solver highs`; `auto`, the default, picks Gurobi when it is licensed).
+- **One session per robot** from [SOLiD](https://github.com/sparolab/SOLiD) (`thirdparty/SOLiD`): keyframe scans, poses and SOLiD descriptors.
+
+## :hammer_and_wrench: Installation
+
+```bash
+pip install commerge          # + "commerge[gurobi]" for gurobipy, "commerge[compare]" for the AutoMerge comparison
+# or from a clone, with SOLiD and KISS-Matcher as submodules:
+git clone --recursive https://github.com/sparolab/Commerge.git && cd Commerge && pip install .
+# KISS-Matcher from the submodule instead of the wheel: pip install thirdparty/KISS-Matcher/python
+commerge --version
+```
+
+Ubuntu and macOS (Python only, no ROS needed for Commerge itself).
+
+### Docker
+
+```bash
+docker pull ghcr.io/sparolab/commerge     # or: docker build -f docker/Dockerfile -t ghcr.io/sparolab/commerge .
+docker run --rm -v $HOME/robot_a:/a -v $HOME/robot_b:/b -v $PWD/merged:/out ghcr.io/sparolab/commerge \
+    commerge /a /b --threshold 0.96 --min-area 2000 --out /out --plot
+# Gurobi: add -v $HOME/gurobi.lic:/opt/gurobi/gurobi.lic (otherwise HiGHS)
+```
+
+## :rocket: Run
+
+**1. One session per robot** with SOLiD, with any odometry it supports ([FAST-LIO, KISS-ICP, GeoRIO, …](https://github.com/sparolab/SOLiD/tree/main/slam)) or without ROS:
+
+```bash
+cd thirdparty/SOLiD
+roslaunch solid_ros run.launch odometry:=fast_lio save_dir:=$HOME/robot_a     # ROS 1, while the bag of robot A plays
+ros2 launch solid_ros run.launch.py odometry:=kiss_icp save_dir:=$HOME/robot_b  # ROS 2
+python slam/common/mac/solid_loops.py --kitti <sequence> --config slam/config/kitti.yaml --out $HOME/robot_a  # no ROS
+```
+
+**2. Select the scans to exchange, register them and merge:**
+
+```bash
+commerge $HOME/robot_a $HOME/robot_b --threshold 0.96 --min-area 2000 --out merged/ --plot [--gt-a gt_a.txt --gt-b gt_b.txt]
+```
+
+```
+[commerge] kitti00_a: 1011 keyframes | kitti00_b: 1701 keyframes
+[commerge] steps (A)+(B)+(C), solver gurobi: (A) 4 region(s) (threshold 0.96, min area 2000) in 0.021 s
+[commerge] region 2: A 250-381 x B 899-1027: (A) 1077 candidate pairs -> (B) 66+66 keyframes -> (C) 24 pairs = 14 A + 17 B scans, (B) 0.34 s, (C) 0.13 s
+...
+[commerge] registered B to A: 540 KISS-Matcher inliers, GICP in 1.3 s; vs ground truth: 0.35 m, 0.06 deg (B keyframes 0.15 m off on average)
+[commerge] exchanged 14 A + 17 B scans (1.1 % of 2712, 4.6 MB) from region(s) [2] of 4 -> merged/
+```
+
+All outputs, options and the Python API: [docs/GUIDE.md](https://github.com/sparolab/Commerge/blob/main/docs/GUIDE.md).
+
+## :bar_chart: Compare
+
+`commerge-compare` runs Commerge, its ablations and AutoMerge on the same sessions. On KITTI 00 split into two robots, Commerge sends **31 of 2,712 scans (4.6 MB)** and merges the maps within **0.35 m**; AutoMerge's region sends 156 scans and merges within 1.05 m. Details and the ablations: [docs/GUIDE.md](https://github.com/sparolab/Commerge/blob/main/docs/GUIDE.md#compare-commerge-compare).
+
+______________________________________________________________________
+
+## :robot: Run with your agent
+
+Open [Claude Code](https://claude.com/claude-code) or [Codex](https://openai.com/codex/) in an empty folder and paste:
+
+```text
+Clone https://github.com/sparolab/Commerge, read its AGENTS.md, and follow it to install Commerge and merge KITTI 00 split into two robots on this machine. Ask me what you need along the way.
+```
+
+The agent follows [`AGENTS.md`](https://github.com/sparolab/Commerge/blob/main/AGENTS.md): it installs Commerge with Gurobi or HiGHS, makes one SOLiD session per robot, selects and exchanges the scans, merges the maps, and checks the result.
+
+______________________________________________________________________
+
+## :warning: Limitation: heterogeneous LiDARs
+
+Commerge selects scans from the affinity of the two robots' descriptors. With the same LiDAR on both robots, SOLiD gives an affinity whose overlapping regions stand out. With different LiDARs (a spinning Ouster and a Livox Avia with a 70° field of view, for instance), SOLiD describes the same place differently and step (A) finds hundreds of regions with no structure. A descriptor made for heterogeneous LiDARs, such as [InLiER](https://github.com/LTU-RAI/InLiER), passed with `--affinity` (and `--enhance`), brings the right region back; registering the few scans exchanged across such different fields of view is still unreliable (`--registration grid` is experimental). Contributions are welcome.
+
+______________________________________________________________________
+
+## Citation
+
+If you use Commerge in your research, please cite our [paper](https://arxiv.org/abs/2606.25386).
+
+<details>
+  <summary><strong>See bibtex</strong></summary>
+
+```bibtex
+@article{kim2026commerge,
+  author  = {Kim, Hogyun and Choi, Jiwon and Kim, Juwon and Yang, Geonmo and Jeong, Seokhwan and Lim, Hyungtae and Cho, Younggun},
+  title   = {Commerge: Communication-Efficient, Robust, and Fast LiDAR Map Merging Framework for Multi-Robot Coordination in Resource-Constrained Scenarios},
+  journal = {International Journal of Robotics Research (IJRR)},
+  year    = {2026}
+}
+```
+
+</details>
+
+## Contributing
+
+Issues and pull requests are welcome.
+
+<a href="https://github.com/sparolab/Commerge/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=sparolab/Commerge" />
+</a>
+
+## Acknowledgements
+
+Commerge uses [SOLiD](https://github.com/sparolab/SOLiD) for inter-robot place recognition. The comparison re-implements the region selection of [AutoMerge](https://github.com/MetaSLAM/AutoMerge_Server), which builds on [SeqSLAM](https://doi.org/10.1109/ICRA.2012.6224623). Related research: [KISS-Matcher](https://github.com/MIT-SPARK/KISS-Matcher), [SKiD-SLAM](https://github.com/sparolab/SKiD-SLAM).
+
+## Special Thanks
+
+We thank [Minwoo Jung](https://github.com/minwoo0611) for the [HeLiPR](https://sites.google.com/view/heliprdataset) dataset, and [Nikolaos Stathoulopoulos](https://github.com/nstathou) for [InLiER](https://github.com/LTU-RAI/InLiER), learning-free heterogeneous LiDAR place recognition.

commerge-2.0.0/commerge/__init__.py

@@ -0,0 +1,6 @@
+"""Commerge: communication-efficient multi-robot LiDAR map merging."""
+__version__ = "2.0.0"
+
+from .selection import STEPS, Selection, cosine_affinity, enhance_affinity, extract_regions, select  # noqa: E402,F401
+from .session import Session, read_pcd, write_pcd  # noqa: E402,F401
+from .merge import POLICIES, alignment_error, choose_regions, register, register_exchanged, register_grid  # noqa: E402,F401

commerge-2.0.0/commerge/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

commerge-2.0.0/commerge/baselines/automerge.py

@@ -0,0 +1,157 @@
+"""AutoMerge-style region selection (our re-implementation, for comparison).
+
+AutoMerge (P. Yin et al., "AutoMerge: A Framework for Map Assembling and Smoothing in City-Scale
+Environments", IEEE T-RO 2023) finds overlapping sequences with SeqSLAM. This module follows that
+idea on the same affinity matrix Commerge uses:
+
+1. local contrast enhancement of the difference matrix D = 1 - affinity (SeqSLAM);
+2. sequence matching along constant-velocity trajectories, with a ratio test;
+3. K-means on the good matches, a line RANSAC per cluster;
+4. each cluster's padded bounding box is a region; the best region is exchanged whole.
+
+It is not the authors' code. All scans of the chosen region are sent, which is what Commerge's
+selection is compared against.
+"""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import List, Tuple
+
+import numpy as np
+
+from ..selection import Region, Selection
+
+
+@dataclass
+class AutoMergeParams:
+    min_area: int = 20000
+    contrast_r: int = 50          # rows of the local contrast window
+    ds: int = 50                  # sequence length
+    vmin: float = 0.8             # trajectory slopes searched
+    vmax: float = 1.2
+    r_window: int = 10            # window excluded around the best match for the ratio test
+    ratio: float = 0.8            # keep matches with best / second-best below this
+    n_clusters: int = 5
+    ransac_iters: int = 100
+    padding: int = 20             # region padding (keyframes)
+    best_only: bool = True        # exchange only the best region (as AutoMerge does)
+    seed: int = 0
+
+
+def enhance_contrast(D: np.ndarray, r: int) -> np.ndarray:
+    """SeqSLAM local contrast enhancement along the rows (reference keyframes)."""
+    DD = np.empty_like(D, dtype=float)
+    n = D.shape[0]
+    for i in range(n):
+        a, b = max(0, i - r // 2), min(n, i + r // 2 + 1)
+        v = D[a:b]
+        std = v.std(axis=0, ddof=1) if b - a > 1 else np.ones(D.shape[1])
+        std[std == 0] = 1.0
+        DD[i] = (D[i] - v.mean(axis=0)) / std
+    return DD - DD.min()
+
+
+def sequence_matches(DD: np.ndarray, p: AutoMergeParams) -> np.ndarray:
+    """(Nb, 2): for each query column, the best reference row and the ratio to the second best."""
+    ds = p.ds + (p.ds % 2)
+    rows, cols = DD.shape
+    matches = np.full((cols, 2), np.nan)
+    move = np.arange(int(p.vmin * ds), int(p.vmax * ds) + 1)
+    v = move / ds
+    steps = np.floor(np.arange(ds + 1)[None, :] * v[:, None]).astype(int)  # (V, ds+1)
+    padded = np.vstack([DD, np.full((1, cols), np.inf)])                     # out-of-bounds row
+    starts = np.arange(rows)
+    for n in range(ds // 2, cols - ds // 2):
+        x = np.arange(n - ds // 2, n + ds // 2 + 1)                          # ds+1 query columns
+        y = np.minimum(starts[:, None, None] + steps[None], rows)            # (S, V, ds+1)
+        scores = padded[y, x[None, None, :]].sum(axis=2).min(axis=1)         # (S,)
+        if not np.isfinite(scores).any():
+            continue
+        k = int(np.argmin(scores))
+        mask = np.ones(rows, bool)
+        mask[max(0, k - p.r_window // 2): min(rows, k + p.r_window // 2)] = False
+        second = scores[mask].min() if mask.any() else np.inf
+        matches[n] = (k + ds // 2, scores[k] / second if second > 0 else 1.0)
+    return matches
+
+
+def _kmeans(points: np.ndarray, k: int, seed: int) -> np.ndarray:
+    try:
+        from sklearn.cluster import KMeans
+
+        return KMeans(n_clusters=k, random_state=seed, n_init=10).fit_predict(points)
+    except ImportError:
+        from scipy.cluster.vq import kmeans2
+
+        return kmeans2(points.astype(float), k, seed=seed, minit="++")[1]
+
+
+def _ransac_line(pts: np.ndarray, iters: int, rng: np.random.Generator) -> np.ndarray:
+    if len(pts) < 4:
+        return np.arange(len(pts))
+    best = np.arange(0)
+    tol = max(10.0, 0.1 * len(pts))
+    for _ in range(iters):
+        i, j = rng.choice(len(pts), 2, replace=False)
+        if abs(pts[j, 0] - pts[i, 0]) < 1e-6:
+            continue
+        a = (pts[j, 1] - pts[i, 1]) / (pts[j, 0] - pts[i, 0])
+        b = pts[i, 1] - a * pts[i, 0]
+        inl = np.nonzero(np.abs(pts[:, 1] - (a * pts[:, 0] + b)) < tol)[0]
+        if len(inl) > len(best):
+            best = inl
+    return best if len(best) else np.arange(len(pts))
+
+
+def automerge_regions(affinity: np.ndarray, p: AutoMergeParams = AutoMergeParams()
+                      ) -> List[Tuple[Tuple[int, int, int, int], float]]:
+    """Regions (a0, a1, b0, b1) with their mean match ratio, best first."""
+    DD = enhance_contrast(np.clip(1.0 - affinity, 0, 1), p.contrast_r)
+    m = sequence_matches(DD, p)
+    good = [(int(m[q, 0]), q, m[q, 1]) for q in range(len(m)) if np.isfinite(m[q, 0]) and m[q, 1] < p.ratio]
+    if not good:
+        return []
+    pts = np.array([(a, b) for a, b, _ in good], dtype=float)
+    k = max(2, min(p.n_clusters, len(good) // 10))
+    labels = _kmeans(pts, k, p.seed) if len(good) >= k else np.zeros(len(good), int)
+    rng = np.random.default_rng(p.seed)
+    regions = []
+    for c in range(labels.max() + 1):
+        idx = np.nonzero(labels == c)[0]
+        if len(idx) <= 2:
+            continue
+        idx = idx[_ransac_line(pts[idx], p.ransac_iters, rng)]
+        if len(idx) < 3:
+            continue
+        a0, a1 = pts[idx, 0].min(), pts[idx, 0].max()
+        b0, b1 = pts[idx, 1].min(), pts[idx, 1].max()
+        box = (int(max(0, a0 - p.padding)), int(min(affinity.shape[0], a1 + p.padding)),
+               int(max(0, b0 - p.padding)), int(min(affinity.shape[1], b1 + p.padding)))
+        if (box[1] - box[0]) * (box[3] - box[2]) >= p.min_area:
+            regions.append((box, float(np.mean([good[i][2] for i in idx]))))
+
+    def score(r):  # as in our comparison: similar sequences and large overlap first
+        (a0, a1, b0, b1), ratio = r
+        sim = float(affinity[a0:a1, b0:b1].mean())
+        return 0.7 * sim + 0.3 * min((a1 - a0) * (b1 - b0) / 50000.0, 1.0)
+
+    return sorted(regions, key=score, reverse=True)
+
+
+def automerge_select(affinity: np.ndarray, p: AutoMergeParams = AutoMergeParams(), log=print) -> Selection:
+    """The chosen region(s), every keyframe of which is exchanged."""
+    t = time.perf_counter()
+    regions = automerge_regions(affinity, p)
+    if p.best_only:
+        regions = regions[:1]
+    out = []
+    for (a0, a1, b0, b1), _ in regions:
+        r = Region((a0, a1, b0, b1))
+        r.scans_a, r.scans_b = list(range(a0, a1)), list(range(b0, b1))
+        r.candidates = int((affinity[a0:a1, b0:b1] > 0).sum())
+        r.seconds["automerge"] = time.perf_counter() - t
+        out.append(r)
+    log(f"[automerge] {len(out)} region(s), {sum(len(r.keyframes_a) + len(r.keyframes_b) for r in out)} scans "
+        f"in {time.perf_counter() - t:.2f} s")
+    return Selection(out, "", "-")