Quick-start reference for AI agents and new contributors.
How to maintain this file: keep it factual and high level: project layout, core data structures, invariants that must not be broken, and where to look. Do not document every feature, and do not write narrative about why or how things evolved over time (that belongs in commit messages and code comments). Update it only when something listed here changes.
mp2p_icp (Multi Primitive-to-Primitive ICP): C++ library and CLI toolkit for point
cloud registration and map building, part of the MOLA
framework. BSD-3-Clause. Version: see package.xml.
Three sibling ROS packages, split so headless consumers don't pull GUI deps:
mp2p_icp/ (repo root)
├── mp2p_icp_core/ # headless libs + CLI apps
│ ├── mp2p_icp_common/ # base utilities, Parameterizable
│ ├── mp2p_icp_map/ # metric_map_t, .mm I/O, georeferencing
│ ├── mp2p_icp/ # ICP: Matchers, Solvers, QualityEvaluators
│ ├── mp2p_icp_filters/ # filters, generators, voxel grid utilities
│ ├── python/ # Python bindings (see below)
│ ├── apps/ tests/ demos/ 3rdparty/ scripts/
├── mp2p_icp_viz/ # GUI apps (mm-viewer, icp-log-viewer) and mm-render
├── mp2p_icp/ # metapackage (backward compat, no code)
├── packaging/pip/ # Python wheel (mp2p-icp on PyPI)
└── docs/ # Sphinx sources
Build via colcon only (except the Python wheel). Each library exports its own CMake target (e.g.
mola::mp2p_icp_map). Headless consumers depend on mp2p_icp_core.
mp2p_icp_map/include/mp2p_icp/metricmap.h: named point cloud layers (CMetricMap),
lines, planes, optional id / label / metadata / georeferencing
(geo_coord + T_enu_to_map). Standard layer names: PT_LAYER_* constants.
.mm files: gzip-compressed MRPT CSerializable (load_from_file() / save_to_file()).
Argument parsing uses CLI11. Core: mm2kml, mm2las, mm2ply, mm2txt, mm2grid, mm-filter,
mm-info, mm-georef, mm-merge, sm2mm, sm-cli, icp-run, kitti2mm, txt2mm,
rawlog-filter. Viz: mm-viewer, mm-render (off-screen, no GUI), icp-log-viewer.
The PLY, LAS and TXT writers of mm2ply, mm2las and mm2txt live in mp2p_icp_map
(point_cloud_export.h), shared with the Python API.
Dear ImGui (from the mrpt_imgui_vendor ROS package, target imgui::imgui). Shared code
in apps/imgui_app_common/; 3D views use mrpt::imgui::CImGuiSceneView.
ImGuiAppShell merges the vendor's Material Symbols font into the default one, so
ICON_MS_* macros work in labels; only a curated subset of icons is embedded (see the
vendor's scripts/regenerate_icon_font.py), others render as missing glyphs.
Do not delete as dead code: the axis-corner mini-viewports in mm-viewer are kept in
sync but invisible, because MRPT 2.x only renders the "main" viewport.
metric_map_t (local) + metric_map_t (global) + CPose3D (initial guess)
→ Matchers → Solvers → QualityEvaluators → iterate until convergence
All components are Parameterizable, configured via YAML.
Determinism is a hard invariant: offline runs must be byte-reproducible. Never use
tbb::parallel_reduce; use tbb::parallel_deterministic_reduce with an explicit grain
size. Guarded by test-mp2p_solver_determinism.
Pose covariance conventions: Results::optimal_tf.cov (every covariance() method)
is in the CPose3DPDFGaussian layout [x y z yaw pitch roll], translation in the global
frame. The solvers linearize in the right SE(3) tangent pose·exp([rho, omega]), and the
GN prior information is applied in that tangent of the prior mean. Convert between the
two only with the helpers in covariance.h. Guarded by test-mp2p_covariance_conventions.
Filters are chained and applied in-place to metric_map_t, configured via YAML
(filters: list of class_name + params). Invariants:
- Voxel keys come from
coord2idx, which divides by the resolution (never multiply by a precomputed reciprocal) and rounds down withstd::floor: a plain integer cast rounds toward zero and merges the two voxels on each side of an axis plane into one of double width. Guarded bytest-mp2p_voxel_grid_indexing. - Voxel hash functors return the full 32-bit hash, never masked to fewer bits: a bounded
hash makes
tsl::robin_mapgrow without limit once it holds that many keys. - Never
insertPointFast()into a layer with registered per-point fields: useinsertPointFrom(), or field vectors fall out of sync with x/y/z. - Load YAML files with
mp2p_icp::load_yaml_file()(yaml_variables.h), neveryaml::FromFile(), so${VAR|default}variables get expanded.
One pybind11 extension module, mp2p_icp._core (src/), wrapping the four libraries, plus
the pure Python package mp2p_icp (mp2p_icp/: re-exports, align() and its bundled
configs/, PLY/PCD readers, interop, render). Tests: tests/ (pytest, ctest
python_mp2p_icp). Built only if pybind11 is found, installed into
lib/pythonX.Y/site-packages (override: MP2P_ICP_PYTHON_INSTALL_DIR).
- It shares types and the MRPT class registry with the
mrptPython package: use the same libmrpt_*.so and the same pybind11 version as MRPT's bindings, never bundled copies. Return and accept MRPT types (mrpt.maps,mrpt.poses...) instead of re-binding them, and import their Python modules first (done in_coreand__init__.py). Parameterizableobjects and theirParameterSourcehold raw pointers to each other: the PythonICP,FilterPipelineandGeneratorsare holder structs owning both, never copied nor exposing the pipeline modules.- Release the GIL around long C++ calls (ICP, filters, I/O); acquire it in callbacks (the ICP
iteration hook), whose Python exceptions are re-raised after
align(). - Loaders of maps, ICP logs and pipelines import the
mola_metric_mapsPython module (once, if installed) when amola::class is not registered (load_with_class_plugins(),require_registered_classes()inpy_common.h). Pipeline loaders validate the YAML structure first (ValueError); MRPT exceptions become RuntimeError with the clean message and the full text incpp_traceback(module-local translator). - After changing bindings, regenerate the committed
mp2p_icp/_core.pyiwithscripts/generate_stubs.py. Docs:docs/source/mp2p_icp_python.rst. - pip wheel
mp2p-icp(packaging/pip/, read itsREADME-dev.md): a scikit-build-core superbuild against the C++ SDK of themrpt3wheel, whoselibmrpt_*.soand oneTBB it links via RPATH and must never bundle. It ships its own C++ SDK (mp2p_icp/sdk: the four libraries, headers, relocatable CMake configs and the mola_common CMake functions; acmake.prefixentry point) for downstream wheels such asmola-metric-maps, checked bytests/sdk_consumer. CI:.github/workflows/python-wheels.yml.packaging/COLCON_IGNOREkeeps colcon away from it.
cd ~/ros2_ws
colcon build --packages-select mp2p_icp # everything (metapackage)
colcon test --packages-select mp2p_icp_core # gtest, one file per component in tests/LTO is disabled for GCC < 12 (it miscompiles devirtualized calls into MRPT classes).
MRPT 3.x, CLI11, TBB (optional), mola_common (colcon
workspace), mola_imu_preintegration (optional, for FilterDeskew).
MRPT 2.x is obsolete: do not add code paths, workarounds or features for it. The "stable"
CI jobs use the older MRPT 3.x of the ROS main repos, so APIs from newer releases must be
guarded (feature macros such as MRPT_HAS_METRIC_MAP_POINTS_VIEW, or MRPT_VERSION).
- Public headers in
<module>/include/mp2p_icp/, implementations in<module>/src/ - Register classes with
DEFINE_MRPT_OBJECT/IMPLEMENTS_MRPT_OBJECT - Numeric parameters a user might write as a formula must use
DECLARE_PARAMETER_*, neverMCP_LOAD_*(which silently truncates expressions) - Frame naming:
T_A_to_B= pose of {B} as seen from {A} - Always brace
if/for/while; one variable per declaration; anonymous namespaces instead ofstatic; American spelling; no en/em dashes; clang-format-14 - Don't sign commits as an AI agent
- New/updated
mp2p_icp_filtersclasses (new classes, parameters, behavior): keepdocs/source/mp2p_icp_filters.rstin sync, and~/code/mp2p-pipeline-editor-sourcesif it exists (read itsREADME.md) - New/updated CLI apps (new apps, arguments, behavior): keep
docs/source/app_<name>.rst(including the--helpoutput it embeds),mp2p_icp_applications.rst, the app'sREADME.md, the rootREADME.mdapp list and the app list above in sync. A new app page also needs its.. include::stub in the MOLAorg/mola repo (docs/source/, plus its listings inmap-tools.rst/why-mola.rst), or the docs CI fails
Once ported to MRPT 3, drop the glut/freeglut3-dev dependency and delete this section.