# mit-spark/kiss-matcher architecture

> Architecture diagram of the GitHub repository mit-spark/kiss-matcher, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mit-spark/kiss-matcher
- Repository: https://github.com/mit-spark/kiss-matcher

## Overview

##### Project Type and Purpose
- KISS-Matcher is primarily a high-performance C++ library for point-cloud registration (core algorithm).
- It provides Python bindings (via Pybind11) and ROS2 nodes for seamless integration into robotics pipelines.
- Auxiliary “example” applications (C++ CLI tools, Python scripts) showcase usage and benchmarking.

##### Top-Level Architectural Components
A. Core C++ Library
- Module: `cpp/kiss_matcher/core/kiss_matcher`
- Subcomponents:
– Feature extraction (FasterPFH)
– Data structures (k-d tree, nanoflann, robin hash tables)
– Solvers (GNC, ROBINMatching)
– Matcher engine (KISSMatcher)
– Point cloud utilities (downsampling, eigen interoperability)
- Build: CMake, third-party pulled via `3rdparty` folders (Eigen, TBB, Robin, TEASER++)
B. Example Applications (C++)
- Directory: `cpp/examples`
- Tools: conversion speed tests, matching demos
- Links to Core via CMake `find_package(kiss_matcher)`
C. Python Binding Layer
- Directory: `python/kiss_matcher/pybind`
- Uses Pybind11 (`kiss_matcher_pybind.cpp`) to expose core functions to Python
- Python utilities and examples (`python/utils`, `python/examples`) import the compiled module
- Packaging: `pyproject.toml`, editable install (`pip install -e`)
D. ROS2 Integration
- Package roots: `ros/` (CMakeLists, package.xml)
- Nodes in `ros/src`: `run_kiss_matcher.cpp`, loop detector, pose graph manager
- Configurations: YAML under `ros/config`
- Launch definitions: `ros/launch/*.launch.yaml` and RViz presets `ros/rviz`
- Rely on Core library via CMake and on ROS2 messaging

##### Relationships & Data Flow
- At runtime, raw point cloud enters one of three “ingress” paths:
1. C++ CLI examples
2. Python scripts
3. ROS2 topic subscription
- All ingress paths call into the Core Library’s entry-point API (`KISSMatcher::match(...)`).
- Core does: downsample → extract features → build k-d tree → robust matching → output correspondences
- Results return to caller (printed/visualized in examples, returned as Python objects, published as ROS2 messages).

##### Architectural Patterns & Technologies
- Layered architecture separating algorithmic core, language bindings, and integration wrappers.
- Build & dependency management via CMake and submodules under `3rdparty`.
- Plugin-style third-party inclusion (Eigen, TBB, ROBIN, TEASER++).
- Pybind11 for cross-language interface.
- ROS2 Component/Node structure for real-time robotics integration.

##### Essential Elements
- Notes flagging configuration files (YAML) and launch scripts under ROS

- Clearly delineates the C++ algorithmic core and its dependencies
- Shows how Python and ROS2 layers wrap and consume that core
- Highlights the build-time vs. run-time relationships
- Captures the essential modularity that makes KISS-Matcher “simple and scalable.”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers and Components
    subgraph "Core C++ Library" 
        direction TB
        Core["Core Library\ncpp/kiss_matcher/core/kiss_matcher"]:::core
        FE["Feature Extraction\n(FasterPFH)"]:::core
        SD["Solvers\nGNC, ROBINMatching"]:::core
        ME["Matcher Engine\nKISSMatcher"]:::core
        DS["Data Structures\nk-d tree, nanoflann, robin hash"]:::core
        PCU["Point-cloud Utils"]:::core
    end

    subgraph "Third-Party Dependencies"
        direction TB
        EIG["Eigen"]:::thirdparty
        TBB["TBB"]:::thirdparty
        ROB["ROBIN"]:::thirdparty
        TSR["tsl_robin"]:::thirdparty
        TEA["TEASER++"]:::thirdparty
    end

    subgraph "C++ Example Applications"
        direction TB
        EXCLI["CLI Tools\ncpp/examples"]:::examples
    end

    subgraph "Python Binding Layer"
        direction TB
        PYB["Pybind11 Wrapper\npython/kiss_matcher/pybind"]:::python
        PYEX["Python Examples\npython/examples"]:::python
    end

    subgraph "ROS2 Integration"
        direction TB
        ROSPKG["ROS Package\nros/"]:::ros
        ROSN["ROS Nodes\nros/src"]:::ros
        ROSCFG["Configs\nros/config"]:::ros
        ROSL["Launch\nros/launch"]:::ros
        ROSV["RViz Presets\nros/rviz"]:::ros
    end

    Build["Build System\nCMake"]:::build

    %% Runtime Data Flow
    EXCLI -->|"calls match() "| Core
    PYB -->|"imports module"| Core
    PYEX -->|"uses module"| PYB
    ROSN -->|"publishes/subscribes"| Core

    %% Core Internals
    Core --> FE
    Core --> SD
    Core --> ME
    Core --> DS
    Core --> PCU

    %% Build-Time Dependencies
    Core -.-> EIG
    Core -.-> TBB
    Core -.-> ROB
    Core -.-> TSR
    Core -.-> TEA

    Build -.-> Core
    Build -.-> EXCLI
    Build -.-> PYB
    Build -.-> ROSPKG

    %% Click Events
    click Core "https://github.com/mit-spark/kiss-matcher/tree/main/cpp/kiss_matcher/core/kiss_matcher"
    click FE "https://github.com/mit-spark/kiss-matcher/blob/main/cpp/kiss_matcher/core/kiss_matcher/FasterPFH.hpp"
    click FE "https://github.com/mit-spark/kiss-matcher/blob/main/cpp/kiss_matcher/core/kiss_matcher/FasterPFH.cpp"
    click SD "https://github.com/mit-spark/kiss-matcher/blob/main/cpp/kiss_matcher/core/kiss_matcher/GncSolver.hpp"
    click SD "https://github.com/mit-spark/kiss-matcher/blob/main/cpp/kiss_matcher/core/kiss_matcher/GncSolver.cpp"
    click SD "https://github.com/mit-spark/kiss-matcher/blob/main/cpp/kiss_matcher/core/kiss_matcher/ROBINMatching.hpp"
    click SD "https://github.com/mit-spark/kiss-matcher/blob/main/cpp/kiss_matcher/core/kiss_matcher/ROBINMatching.cpp"
    click ME "https://github.com/mit-spark/kiss-matcher/blob/main/cpp/kiss_matcher/core/kiss_matcher/KISSMatcher.hpp"
    click ME "https://github.com/mit-spark/kiss-matcher/blob/main/cpp/kiss_matcher/core/kiss_matcher/KISSMatcher.cpp"
    click DS "https://github.com/mit-spark/kiss-matcher/blob/main/cpp/kiss_matcher/core/kiss_matcher/kdtree/kdtree.hpp"
    click DS "https://github.com/mit-spark/kiss-matcher/blob/main/cpp/kiss_matcher/core/kiss_matcher/kdtree/kdtree_tbb.hpp"
    click DS "https://github.com/mit-spark/kiss-matcher/blob/main/cpp/kiss_matcher/core/kiss_matcher/kdtree/nanoflann.hpp"
    click DS "https://github.com/mit-spark/kiss-matcher/blob/main/cpp/kiss_matcher/core/kiss_matcher/kdtree/nanoflann_tbb.hpp"
    click PCU "https://github.com/mit-spark/kiss-matcher/blob/main/cpp/kiss_matcher/core/kiss_matcher/points/downsampling.hpp"
    click PCU "https://github.com/mit-spark/kiss-matcher/blob/main/cpp/kiss_matcher/core/kiss_matcher/points/eigen.hpp"
    click PCU "https://github.com/mit-spark/kiss-matcher/blob/main/cpp/kiss_matcher/core/kiss_matcher/points/fast_floor.hpp"
    click PCU "https://github.com/mit-spark/kiss-matcher/blob/main/cpp/kiss_matcher/core/kiss_matcher/points/point_cloud.hpp"
    click PCU "https://github.com/mit-spark/kiss-matcher/blob/main/cpp/kiss_matcher/core/kiss_matcher/points/traits.hpp"
    click PCU "https://github.com/mit-spark/kiss-matcher/blob/main/cpp/kiss_matcher/core/kiss_matcher/points/vector3i_hash.hpp"
    click EIG "https://github.com/mit-spark/kiss-matcher/tree/main/cpp/kiss_matcher/3rdparty/eigen"
    click TBB "https://github.com/mit-spark/kiss-matcher/tree/main/cpp/kiss_matcher/3rdparty/tbb"
    click ROB "https://github.com/mit-spark/kiss-matcher/tree/main/cpp/kiss_matcher/3rdparty/robin"
    click TSR "https://github.com/mit-spark/kiss-matcher/tree/main/cpp/kiss_matcher/3rdparty/tsl_robin"
    click TEA "https://github.com/mit-spark/kiss-matcher/tree/main/cpp/kiss_matcher/3rdparty/teaserpp"
    click Build "https://github.com/mit-spark/kiss-matcher/blob/main/cpp/kiss_matcher/CMakeLists.txt"
    click Build "https://github.com/mit-spark/kiss-matcher/blob/main/cpp/kiss_matcher/cmake/CompilerOptions.cmake"
    click Build "https://github.com/mit-spark/kiss-matcher/blob/main/cpp/kiss_matcher/kiss_matcherConfig.cmake"
    click EXCLI "https://github.com/mit-spark/kiss-matcher/blob/main/cpp/examples/CMakeLists.txt"
    click EXCLI "https://github.com/mit-spark/kiss-matcher/blob/main/cpp/examples/README.md"
    click PYB "https://github.com/mit-spark/kiss-matcher/blob/main/python/kiss_matcher/pybind/kiss_matcher_pybind.cpp"
    click PYB "https://github.com/mit-spark/kiss-matcher/blob/main/python/kiss_matcher/pybind/stl_vector_eigen.h"
    click PYB "https://github.com/mit-spark/kiss-matcher/blob/main/python/kiss_matcher/pybind/CMakeLists.txt"
    click PYEX "https://github.com/mit-spark/kiss-matcher/blob/main/python/examples/run_kiss_matcher.py"
    click PYEX "https://github.com/mit-spark/kiss-matcher/blob/main/python/utils/bin2pcd.py"
    click PYEX "https://github.com/mit-spark/kiss-matcher/blob/main/python/utils/download_datasets.py"
    click PYEX "https://github.com/mit-spark/kiss-matcher/blob/main/python/pyproject.toml"
    click PYEX "https://github.com/mit-spark/kiss-matcher/blob/main/python/CMakeLists.txt"
    click ROSPKG "https://github.com/mit-spark/kiss-matcher/blob/main/ros/CMakeLists.txt"
    click ROSPKG "https://github.com/mit-spark/kiss-matcher/blob/main/ros/package.xml"
    click ROSN "https://github.com/mit-spark/kiss-matcher/blob/main/ros/src/run_kiss_matcher.cpp"
    click ROSN "https://github.com/mit-spark/kiss-matcher/blob/main/ros/src/inter_frame_alignment.cpp"
    click ROSN "https://github.com/mit-spark/kiss-matcher/blob/main/ros/src/registration_visualizer.cpp"
    click ROSN "https://github.com/mit-spark/kiss-matcher/blob/main/ros/src/slam/loop_closure.cpp"
    click ROSN "https://github.com/mit-spark/kiss-matcher/blob/main/ros/src/slam/loop_detector.cpp"
    click ROSN "https://github.com/mit-spark/kiss-matcher/blob/main/ros/src/slam/pose_graph_manager.cpp"
    click ROSCFG "https://github.com/mit-spark/kiss-matcher/tree/main/ros/config"
    click ROSL "https://github.com/mit-spark/kiss-matcher/tree/main/ros/launch"
    click ROSV "https://github.com/mit-spark/kiss-matcher/tree/main/ros/rviz"

    %% Styles
    classDef core fill:#AED6F1,stroke:#3498DB,color:#1B4F72
    classDef examples fill:#F9E79F,stroke:#F1C40F,color:#7D6608
    classDef python fill:#A9DFBF,stroke:#27AE60,color:#145A32
    classDef ros fill:#F5B7B1,stroke:#E74C3C,color:#641E16
    classDef thirdparty fill:#D7BDE2,stroke:#8E44AD,color:#4A235A
    classDef build fill:#D5D8DC,stroke:#566573,color:#1C2833
```
