Skip to content

Latest commit

 

History

History
175 lines (136 loc) · 9.23 KB

agents.md

File metadata and controls

175 lines (136 loc) · 9.23 KB

mp2p_icp: Agent Context Guide

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.

Project identity

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.

Repository layout

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.

Core data structure: metric_map_t

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()).

CLI applications

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.

GUI apps (mp2p_icp_viz)

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.

ICP pipeline

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.

Filter pipeline

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 with std::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 by test-mp2p_voxel_grid_indexing.
  • Voxel hash functors return the full 32-bit hash, never masked to fewer bits: a bounded hash makes tsl::robin_map grow without limit once it holds that many keys.
  • Never insertPointFast() into a layer with registered per-point fields: use insertPointFrom(), or field vectors fall out of sync with x/y/z.
  • Load YAML files with mp2p_icp::load_yaml_file() (yaml_variables.h), never yaml::FromFile(), so ${VAR|default} variables get expanded.

Python bindings (mp2p_icp_core/python/)

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 mrpt Python 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 _core and __init__.py).
  • Parameterizable objects and their ParameterSource hold raw pointers to each other: the Python ICP, FilterPipeline and Generators are 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_maps Python module (once, if installed) when a mola:: class is not registered (load_with_class_plugins(), require_registered_classes() in py_common.h). Pipeline loaders validate the YAML structure first (ValueError); MRPT exceptions become RuntimeError with the clean message and the full text in cpp_traceback (module-local translator).
  • After changing bindings, regenerate the committed mp2p_icp/_core.pyi with scripts/generate_stubs.py. Docs: docs/source/mp2p_icp_python.rst.
  • pip wheel mp2p-icp (packaging/pip/, read its README-dev.md): a scikit-build-core superbuild against the C++ SDK of the mrpt3 wheel, whose libmrpt_*.so and 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; a cmake.prefix entry point) for downstream wheels such as mola-metric-maps, checked by tests/sdk_consumer. CI: .github/workflows/python-wheels.yml. packaging/COLCON_IGNORE keeps colcon away from it.

Build and test

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).

Dependencies

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).

Coding conventions

  • 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_*, never MCP_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 of static; American spelling; no en/em dashes; clang-format-14
  • Don't sign commits as an AI agent

Update rules

  • New/updated mp2p_icp_filters classes (new classes, parameters, behavior): keep docs/source/mp2p_icp_filters.rst in sync, and ~/code/mp2p-pipeline-editor-sources if it exists (read its README.md)
  • New/updated CLI apps (new apps, arguments, behavior): keep docs/source/app_<name>.rst (including the --help output it embeds), mp2p_icp_applications.rst, the app's README.md, the root README.md app 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 in map-tools.rst / why-mola.rst), or the docs CI fails

MRPT3 to-do

Once ported to MRPT 3, drop the glut/freeglut3-dev dependency and delete this section.