mola_metric_maps

Advanced metric map classes for LiDAR odometry and SLAM, built on the generic mrpt::maps::CMetricMap interface. All maps are serializable, visualizable, and integrate with the mp2p_icp registration library.

Map classes

Production-quality maps

Experimental / work-in-progress maps

Utility / internal classes

Build and install

Refer to the root MOLA repository.

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 for research and evaluation purposes only. Commercial licenses available upon request, for this package alone or in combination with the complete SLAM system.

Changelog for package mola_metric_maps

3.0.0 (2026-07-17)

• fix: dont crash on empty maps

• feat: --unify-all flag for mm-kf-regroup

• fix(mola_metric_maps): don't restore stale icp_search_kfs cache from serialized maps icp_search_kfs was serialized purely for post-mortem debugging, but serializeFrom() restored it straight into the live cache. Since icp_search_submap (the actual prepared search structure it gates) is never serialized, this let icp_get_prepared_as_global()'s already-up-to-date fast path skip rebuilding the submap whenever the freshly computed active-keyframe selection happened to coincide with the stale, reloaded set. The next nn_search_cov2cov() call would then fail its 'icp_get_prepared_as_global() first' assertion. Reproduced reliably when chaining multi-session/multi-robot maps (loading a previously saved map as the starting point for a new robot/session).

• fix: sort by indices to avoid gcc warnings on ABI changes

• chore: tune default island param

• debug: add env-gated point-density match-stats trace Adds MOLA_KEYFRAME_MAP_DEBUG_MATCH_STATS (off by default), counting per-call accepted / no-candidate-in-range / rejected-by-view-filter totals in nn_search_cov2cov_approximate(). Used to diagnose a localization stall on a real dataset: distinguishes a genuine point-density gap in the map (points with no nearby candidate) from a view-direction-filter rejection or a keyframe-selection problem, which look identical from the ICP goodness trace alone.

• fix(mola_metric_maps): bound island-merge distance; never starve the diverse KF slot Address CodeRabbit review on #174 plus a second, distinct tracking-loss mode found during full-bag testing:

  - regroupKeyframes(): cap island absorption distance at extent_factor * (seed radii sum) so a tiny cluster is not glued to a spatially disjoint neighbor merely because it's the "nearest" one left; islands beyond that bound stay standalone.

  - icp_get_prepared_as_global(): the diverse-keyframe slot's distance limit (3x the nearest primary candidate) could reject every other candidate when a map has only a handful of large super-keyframes, leaving that slot empty and ICP running against a single keyframe. At the edge of that keyframe's own coverage this can permanently stall tracking (quality stuck just under threshold, no fallback). Now falls back to the best-diversity candidate regardless of distance rather than leaving the slot unfilled.

• fix(mola_metric_maps): density-aware nearest-keyframe selection + island merging in regroup A sparse, under-merged keyframe (e.g. a leftover cluster from regroupKeyframes()) could outrank a much better-populated keyframe in icp_get_prepared_as_global()'s proximity search purely because its pose happened to be closer, starving ICP of real geometry and causing localization to get stuck with zero correspondences.

  - KeyframePointCloudMap: add a distance penalty for keyframes below density_penalty_min_points, so sparse candidates no longer win over well-populated ones just by pose proximity.

  - regroupKeyframes(): absorb clusters below island_merge_fraction of the largest cluster's point count into their nearest neighbor instead of emitting them as standalone, near-empty super-keyframes.

  • mm-kf-regroup: expose --island-merge-fraction.

  - Adds env-gated debug traces (MOLA_KEYFRAME_MAP_DEBUG_ACTIVE_KFS, MOLA_KEYFRAME_MAP_DEBUG_DUMP_KFS_ON_LOAD) used to diagnose this.

• Merge pull request #173 from MOLAorg/perf/mm-kf-regroup-tbb-parallel-superkf mm-kf-regroup: parallelize super-keyframe cloud building with TBB

• mm-kf-regroup: parallelize super-keyframe cloud building with TBB Building each super-keyframe's merged/decimated point cloud in regroupKeyframes() was the most expensive step but ran single-threaded. Clusters are independent, so parallelize with tbb::parallel_for (gated by MOLA_METRIC_MAPS_USE_TBB, already a mola_metric_maps dependency), falling back to a serial loop when TBB is unavailable.

• better defaults for regroup KF algorithm

• feat: mm-kf-bake-kdtrees sets approximate cov by default

• Merge pull request #171 from MOLAorg/feat/keyframe-map-persist-covariances-local-tree feat(mola_metric_maps): persist per-KF covariances + query baked local KD-tree in approximate cov2cov

• fix(mola_metric_maps): handle v3 in serializeFrom + clang-format

  - Add [case 3:]{.title-ref} to

File truncated at 100 lines see the full file