# molaorg/mola_lidar_odometry architecture

> Architecture diagram of the GitHub repository molaorg/mola_lidar_odometry, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/molaorg/mola_lidar_odometry
- Repository: https://github.com/molaorg/mola_lidar_odometry

## Overview

##### Project Type and Purpose
- This is a C++ robotics package providing a core LIDAR odometry library (`mola_lidar_odometry`), a command-line tool (`mola-lidar-odometry-cli`), and a ROS 2 node, all based on the MOLA/MRPT frameworks. It ingests either live ROS 2 LIDAR topics or offline datasets, computes odometry (pose + map), and publishes results (files or ROS 2 topics) for downstream use/visualization.

##### File-Structure Analysis
Top-level directories and their roles:
- module/          ← Core C++ library (include/ + src/ implementing LidarOdometry classes)
- apps/            ← `mola-lidar-odometry-cli.cpp` (offline CLI entry point)
- ros2-launchs/    ← ROS 2 launch scripts (`.launch.py`) for live runs
- pipelines/       ← YAML pipeline definitions (scan filter, mapping, registration strategies)
- state-estimator-params/ ← EKF/ smoother config for pose estimation
- rviz2/           ← RViz2 visualization configs
- scripts/         ← small shell launchers for common datasets
- eval/            ← benchmarking scripts against datasets
- docs/, CHANGELOG, package.xml, CMakeLists.txt, .github/… ← CI, build, docs

##### Key Architectural Insights from README
- Separates sensor ingestion (MOLA components) from odometry core.
- Supports two front-ends: CLI for batch runs on recorded data and a ROS 2 node for live systems.
- Configurable pipelines allow swapping mapping / scan-matching strategies at runtime via YAML.

##### Components
a. Main Components
1. Data Source
- Live LIDAR sensor → ROS 2 topic or
- Offline dataset (KITTI, rawlog, ROS2 bag2)
2. Front-Ends
- CLI (`mola-lidar-odometry-cli`)
- ROS 2 Node (`mola_lidar_odometry` package, launched via `ros2-launchs/*.launch.py`)
3. Core Library (`module/`)
- LidarOdometry class hierarchy (Initialize, ProcessScan, MapServer, Publish, etc.)
- Adaptive variables, sensor callbacks, relocalization modules
4. Pipeline Manager
- Loads YAML from `pipelines/` + `state-estimator-params/`
- Configures the sequence: voxel grid, normal estimation, matcher (ICP, NDT…), EKF optional
5. Dependencies / Frameworks
- MOLA sensor handling
- MRPT for maps & math
- ROS 2 (rclcpp, message types, TF2)
6. Outputs
- CLI → TUM-format trajectory files
- ROS 2 Node → Odometry topics, TF2 frames, point-cloud map topics
- RViz2 configs for visualization (`rviz2/*.rviz`)

b. Relationships & Data Flow
- Data Source feeds Front-End (CLI or ROS 2 Node).
- Front-End invokes Core Library APIs.
- Core Library calls Pipeline Manager to set up filters & matchers.
- Core Library uses MOLA → MRPT internally; publishes back to Front-End.
- Front-End writes files or publishes ROS 2 topics.
- RViz2 subscribes to these topics for visualization.
- Evaluation scripts wrap around CLI or ROS 2 Node to benchmark performance.

c. Architectural Patterns & Design Principles
- Modular core library: clear separation between odometry logic and I/O (CLI vs ROS 2).
- Plugin-like pipeline loader via YAML for flexibility (open/closed principle).
- Use of CMake + package.xml for ROS 2 composable nodes and dependency management.
- CI pipeline (.github) for formatting, style, and multi-distro builds.

d. Key Technologies
- CMake, ROS 2 (rclcpp, launch_py), YAML configuration
- MOLA (sensor abstraction), MRPT (mapping/math)
- Eigen, PCL (implicitly via MRPT), Boost

1. Sketch the two entry points (CLI & ROS 2) on left, core library in center, outputs on right.
2. Pipeline loader/config between front-end and core.
3. Surround core with external dependencies (MOLA, MRPT, ROS 2 runtime).
7. Validate against the file tree: ensure each major directory’s role is reflected.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Sources
    subgraph "Data Sources"
        direction TB
        DS1["Offline Dataset: KITTI"]:::data
        DS2["Offline Dataset: ROS2 bag2"]:::data
        DS3["Live LIDAR Sensor → /scan_in"]:::data
    end

    %% Front-Ends
    subgraph "Front-Ends"
        direction TB
        CLI["CLI: mola-lidar-odometry-cli"]:::frontend
        ROSNode["ROS2 Node Launcher"]:::frontend
    end

    %% Pipeline Manager & Config
    subgraph "Pipeline Manager & Config" 
        direction TB
        P1["Default Pipeline YAML"]:::config
        P2["Alternative Pipeline YAML"]:::config
        P3["State-Estimator Config"]:::config
    end

    %% Core Library
    subgraph "Core Library"
        direction TB
        CoreAPI["Public Headers"]:::core
        CoreImpl["Implementation Sources"]:::core
    end

    %% External Frameworks
    subgraph "External Frameworks"
        direction TB
        F1["MOLA Sensor Handling"]:::ext
        F2["MRPT Maps & Math"]:::ext
        F3["ROS2 Runtime (rclcpp, TF2)"]:::ext
        F4["Eigen / PCL / Boost"]:::ext
    end

    %% Outputs & Support
    subgraph "Outputs & Support"
        direction TB
        O1["TUM-format Trajectory Files"]:::output
        O2["ROS2 Topics: /odom, /map"]:::output
        O3["RViz2 Visualization"]:::output
        Eval["Evaluation Scripts"]:::support
        GUI["Dataset GUI Launcher"]:::support
        Doc1["Docs: Core Overview"]:::support
        Doc2["Docs: ROS2 Node"]:::support
        CI["CI & Formatting"]:::support
    end

    %% Connections
    DS1 -->|PointCloud2| CLI
    DS2 -->|PointCloud2| CLI
    DS3 -->|PointCloud2| ROSNode

    CLI -->|"calls API"| CoreAPI
    ROSNode -->|"calls API"| CoreAPI

    CLI --> P1
    CLI --> P2
    CLI --> P3
    ROSNode --> P1
    ROSNode --> P2
    ROSNode --> P3

    P1 --> CoreImpl
    P2 --> CoreImpl
    P3 --> CoreImpl

    CoreAPI --> CoreImpl

    CoreImpl -->|uses| F1
    CoreImpl -->|uses| F2
    CoreImpl -->|uses| F3
    CoreImpl -->|uses| F4

    CoreImpl --> O1
    ROSNode --> O2
    O2 --> O3

    CLI --> Eval
    CLI --> GUI

    CLI --> Doc1
    ROSNode --> Doc2
    CI --> CoreImpl

    %% Click Events
    click DS1 "https://github.com/molaorg/mola_lidar_odometry/blob/develop/mola-cli-launchs/lidar_odometry_from_kitti.yaml"
    click DS2 "https://github.com/molaorg/mola_lidar_odometry/blob/develop/mola-cli-launchs/lidar_odometry_from_rosbag2.yaml"
    click DS3 "https://github.com/molaorg/mola_lidar_odometry/blob/develop/ros2-launchs/ros2-lidar-odometry.launch.py"
    click CLI "https://github.com/molaorg/mola_lidar_odometry/blob/develop/apps/mola-lidar-odometry-cli.cpp"
    click ROSNode "https://github.com/molaorg/mola_lidar_odometry/blob/develop/ros2-launchs/kitti-ros2-lidar-odometry.launch.py"
    click CoreAPI "https://github.com/molaorg/mola_lidar_odometry/blob/develop/module/include/mola_lidar_odometry/LidarOdometry.h"
    click CoreImpl "https://github.com/molaorg/mola_lidar_odometry/blob/develop/module/src/LidarOdometry_ProcessScan.cpp"
    click P1 "https://github.com/molaorg/mola_lidar_odometry/blob/develop/pipelines/lidar3d-default.yaml"
    click P2 "https://github.com/molaorg/mola_lidar_odometry/blob/develop/pipelines/extras/icp-pipeline_no_motion_model.yaml"
    click P3 "https://github.com/molaorg/mola_lidar_odometry/blob/develop/state-estimator-params/state-estimation-simple.yaml"
    click O3 "https://github.com/molaorg/mola_lidar_odometry/blob/develop/rviz2/lidar-odometry.rviz"
    click Eval "https://github.com/molaorg/mola_lidar_odometry/blob/develop/eval/cli_kitti.sh"
    click GUI "https://github.com/molaorg/mola_lidar_odometry/tree/develop/scripts/mola-lo-gui-kitti"
    click Doc1 "https://github.com/molaorg/mola_lidar_odometry/blob/develop/docs/mola_lidar_odometry.rst"
    click Doc2 "https://github.com/molaorg/mola_lidar_odometry/blob/develop/docs/mola_lo_ros_node.rst"
    click CI "https://github.com/molaorg/mola_lidar_odometry/blob/develop/.github/workflows/build-ros.yml"

    %% Styles
    classDef data fill:#ccf,stroke:#88a,stroke-width:1px
    classDef frontend fill:#cfc,stroke:#8a8,stroke-width:1px
    classDef config fill:#fcf,stroke:#a8a,stroke-width:1px
    classDef core fill:#cce,stroke:#88a,stroke-width:1px
    classDef ext fill:#eec,stroke:#aa8,stroke-width:1px
    classDef output fill:#fee,stroke:#a88,stroke-width:1px
    classDef support fill:#eee,stroke:#888,stroke-width:1px
```
