Distro	Build dev	Build releases	Stable version
ROS 2 Humble (u22.04)		amd64 arm64
ROS 2 Jazzy @ u24.04		amd64 arm64
ROS 2 Kilted @ u24.04		amd64 arm64
ROS 2 Rolling (u24.04)		amd64 arm64

mola_sm_loop_closure

Offline loop-closure engine for MOLA CSimpleMap files. Given an input simplemap produced by any MOLA odometry front-end, the package re-optimises all keyframe poses by detecting and closing loops, then writes the corrected simplemap back to disk.

Two algorithms

CLI usage

# SimplemapLoopClosure (default algorithm):
mola-sm-lc-cli -i in.simplemap -o out.simplemap \
    -p pipelines/loop-closure-lidar3d-gicp.yaml

# FrameToFrameLoopClosure:
mola-sm-lc-cli -i in.simplemap -o out.simplemap \
    -a mola::FrameToFrameLoopClosure \
    -p pipelines/loop-closure-f2f-lidar3d-gicp.yaml

Available pipelines

Key YAML knobs

SimplemapLoopClosure

• submap_max_absolute_length / submap_min_absolute_length : controls submap granularity.
• assume_planar_world: true enables annealed soft planar constraints (z, roll, pitch).
  • planar_world_initial_sigma_z, planar_world_initial_sigma_ang, planar_world_annealing_rounds : tune the annealing schedule.
  • planar_world_hard_flatten: true restores the old hard-flattening behaviour.
• use_gnss: true / gnss_add_horizontality: true : GNSS-assisted global alignment.
  • gnss_factor_strategy: "submap" (default, scalable) or "per_kf" (sensor-pose-aware, larger graph).
  • gnss_max_uncertainty_horiz (default 20.0 m) : reject GPS readings whose horizontal ENU uncertainty (√(σ_E²+σ_N²)) exceeds this threshold.
  • gnss_max_uncertainty_vert (default 40.0 m) : reject GPS readings whose vertical ENU uncertainty (σ_U) exceeds this threshold.
  • Stats on accepted/rejected GNSS readings are printed at the INFO log level after processing.
• use_imu_gravity: true / imu_gravity_sigma_deg : IMU-derived gravity-alignment factors added in stage 1.

FrameToFrameLoopClosure

• lc_candidate_strategy : DISTANCE_STRATIFIED (default), PROXIMITY_ONLY, or MULTI_OBJECTIVE.
• assume_planar_world: true : planar-world annealing (subset of SM options; IMU-gravity options are not exposed by FrameToFrameLoopClosure::Parameters).
• use_gnss: true : per-keyframe GNSS factors (FactorGnssEnu).
  • gnss_max_uncertainty_horiz (default 20.0 m) : reject GPS readings whose horizontal ENU uncertainty exceeds this threshold.
  • gnss_max_uncertainty_vert (default 40.0 m) : reject GPS readings whose vertical ENU uncertainty exceeds this threshold.
• use_kiss_matcher: true : use KISS-Matcher global registration to seed the ICP initial guess for each loop-closure candidate (default: false; requires the third_party/kiss-matcher submodule to be populated).
  • kiss_matcher_resolution (default 1.0 m) : voxel size for KISS-Matcher feature extraction; controls normal_radius ≈ 3× and fpfh_radius ≈ 5×.
  • kiss_matcher_layer (default "points_to_register_points") : name of the mp2p_icp::metric_map_t layer whose points are fed into KISS-Matcher.

See the online tutorial for a step-by-step example.

License

Copyright (C) 2018-2026 Jose Luis Blanco jlblanco@ual.es, University of Almeria

This package is released under the GNU GPL v3 license as open source, with the main intention of being useful for research and evaluation purposes. Commercial licenses available upon request.

Contributions require acceptance of the Contributor License Agreement (CLA).

Changelog for package mola_sm_loop_closure

1.1.0 (2026-04-29)

• Merge pull request #10 from MOLAorg/refactor/lc-common-helpers refactor: extract lc_common helpers; port planar-world annealing + GNC to SM
• refactor: replace two-pass LM with single GNC pass in SimplemapLoopClosure
• refactor: extract lc_common helpers; port planar-world annealing + GNC to SM
• Merge pull request #9 from MOLAorg/feat/planar-world-in-f2f feat: optional f2f planar world soft-constraints
• feat: optional f2f planar world soft-constraints
• Merge pull request #8 from MOLAorg/feat/manual-lc Support for optional manual hints for LC
• Support for optional manual hints for LC
• Merge pull request #7 from MOLAorg/feat/more-flexible-icp-sigmas-and-logging Expose more env vars
• Expose more env vars
• f2f pipeline file: add env var MOLA_DESKEW_IGNORE_ACCELEROMETER
• Contributors: Jose Luis Blanco-Claraco

1.0.0 (2026-04-14)

• package.xml: add missing test-dep
• add unit tests
• cli: use output directory as default for debug output files, not input
• Install pipelines so they are accessible under 'share'
• Make the package discoverage by ament
• Merge pull request #6 from MOLAorg/save-ram F2F algorithm: save ram in offline runs
• More memory efficient loop
• Bump minimum cmake version to 3.7
• Reuse mp2p_icp::update_velocity_buffer_from_obs() from mp2p_icp Removes duplicated code in this repo now that mp2p_icp>=2.5.0 is available in all distributions
• Fix build against mp2p_icp <2.6.0
• icp debug log files: save only good edges
• F2F algorithm: save ram in offline runs
• sm2mm pipeline yaml: expose more params via env vars
• Expose more parameters for F2F algorithm
• Debug feature: enable saving 3Dscene files per optimization round
• Use Graduated Non-Convexity (GNC) optimizer for superior outlier rejection
• FIX: Reverted logic in formula for adaptive threshold
• Add formal CLA
• Merge pull request #5 from MOLAorg/feat/smart-ram-lazy-unload Lazy unload keyframe clouds to keep RAM usage bounded
• Contributors: Jose Luis Blanco-Claraco

0.2.0 (2026-03-03)

• Fix build against different gtsam versions
• Add optional generation of .3Dscene files with loop-closure visualizations
• Tolerate missing external files without throwing
• Better logging and expose more env var params
• Add GNSS uncertainty multiplier
• Use debug files prefix
• Add more frame-to-frame LC selection algorithms
• Merge pull request #4 from MOLAorg/feat/f2f-fixes Add more parameters to f2f method
• Add new params for f2f method
• pipeline file: expose more params and fix reversed sigma logic
• Fix: prior should be weak for GNSS to transform to ENU frame
• fix copyright headers
• Merge pull request #3 from MOLAorg/feat/new-f2f-algo Add alternative frame-to-frame LC algorithm
• Provide virtual LoopClosureInterface to select the algorithm from a CLI argument
• Add alternative frame-to-frame LC algorithm
• Merge pull request #2 from MOLAorg/feat/add-ci-and-badges Add CI workflows and clang-format linting infrastructure
• package.xml: add FILE tag
• Merge pull request #1 from MOLAorg/feature/refactor-pkg-mola-gtsam-factors Progress moving code to new package mola_gtsam_factors
• Update dependencies after refactorization into mola_georeferencing
• Progress moving code to new package mola_gtsam_factors
• Protect against invalid GPS cov entries
• Add param gnss_minimum_uncertainty_xyz; dump trajectories as TUM files.
• simplify: remove obsolete parameters not used anymore here

File truncated at 100 lines see the full file