# 93won/lidar_odometry architecture

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

- Interactive diagram: https://gitdiagram.com/93won/lidar_odometry
- Repository: https://github.com/93won/lidar_odometry

## Overview

##### Project Type & Purpose
- This is a native C++17 real-time LiDAR odometry/SLAM application (not a web app or microservice) that implements feature‐based ICP registration, sliding‐window and pose‐graph optimization (PKO/PGO), and 3D visualization for KITTI & MID360 datasets.

##### High-Level Architecture from File Structure & README
- Top-level “app/”: two CLI executables (`kitti_lidar_odometry`, `mid360_lidar_odometry`) plus dataset players under `app/player/`.
- “config/”: YAML files for dataset paths and algorithm parameters.
- “src/”: core modules, divided into
- database/ (LidarFrame store)
- processing/ (Estimator, FeatureExtractor, LoopClosureDetector)
- optimization/ (ICP, PoseGraphOptimizer, AdaptiveMEstimator)
- util/ (Config loader, MathUtils, PointCloudUtils, Types)
- viewer/ (PangolinViewer)
- “thirdparty/”: external libraries (Ceres Solver, Pangolin, LidarIris, Sophus, nanoflann, spdlog, etc.).

- Data Sources (KITTI sequence, MID360 PLY files)
- Config Loader (reads YAML → parameter objects)
- Dataset Player (streams raw point clouds / timestamps)
- Database Module (stores keyframes & metadata)
- Processing Pipeline
- FeatureExtractor (computes descriptors)
- Odometry Estimator (frame-to-frame ICP)
- LoopClosure Detector (runs asynchronously on keyframe queue)
- Optimization Module
- ICP Optimizer (refines loop candidates)
- PoseGraphOptimizer (Ceres‐based PKO/PGO)
- Viewer (Pangolin for 3D rendering)
- Logging (spdlog)

- Config → all modules
- Player → raw cloud → FeatureExtractor → OdometryEstimator → Database
- Database keyframes → LoopClosureDetector → ICPOptimizer → PoseGraphOptimizer
- Odometry constraints + loop constraints → PoseGraphOptimizer → updated poses
- Main thread consumes updated poses → Viewer

c. Architectural Patterns & Principles
- Modular, layered pipeline: data ingestion → processing → optimization → visualization
- Asynchronous background thread for loop closure & pose graph (non-blocking odometry)
- Separation of concerns: database vs. processing vs. optimization vs. UI
- Dependency injection of config & utilities

d. Technologies & Libraries
- Ceres Solver for nonlinear PKO/PGO
- Pangolin for OpenGL visualization
- LidarIris for loop closure descriptors
- Sophus & nanoflann for geometry & nearest neighbor search
- spdlog for logging
- YAML for configuration

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Apps & Config Layer
    subgraph "Apps & Config" 
        direction TB
        KittiApp["kitti_lidar_odometry.exe"]:::apps
        Mid360App["mid360_lidar_odometry.exe"]:::apps
        ConfigLoader["Config Loader"]:::util
        KittiYAML["kitti.yaml"]:::apps
        Mid360YAML["mid360.yaml"]:::apps
    end

    %% Data Ingestion Layer
    subgraph "Data Ingestion" 
        direction TB
        KITTIPlayer["KITTI Player"]:::core
        PLYPlayer["PLY Player"]:::core
        RawCloud["Raw Point Cloud"]:::core
    end

    %% Processing Layer
    subgraph "Processing Pipeline"
        direction TB
        FeatureExtractor["FeatureExtractor"]:::core
        OdometryEstimator["OdometryEstimator"]:::core
    end

    %% Database Layer
    Database["Database (LidarFrame Store)"]:::core

    %% Background Thread
    subgraph "Background Optimization Thread"
        direction TB
        LoopClosure["LoopClosureDetector"]:::core
        ICPOptimizer["ICPOptimizer"]:::core
        PoseGraphOpt["PoseGraphOptimizer"]:::core
    end

    %% Visualization & Logging
    Viewer["PangolinViewer"]:::core
    Logging["Logging (spdlog)"]:::logging

    %% Thirdparty Libraries
    subgraph "Thirdparty Libraries"
        direction TB
        Ceres["Ceres Solver"]:::thirdparty
        PangolinLib["Pangolin"]:::thirdparty
        LidarIris["LidarIris"]:::thirdparty
        Sophus["Sophus"]:::thirdparty
        NanoFlann["nanoflann"]:::thirdparty
    end

    %% Connections
    KittiApp -->|launches| ConfigLoader
    Mid360App -->|launches| ConfigLoader
    ConfigLoader -->|loads| KittiYAML
    ConfigLoader -->|loads| Mid360YAML
    ConfigLoader -->|provides params| KITTIPlayer
    ConfigLoader -->|provides params| PLYPlayer
    KITTIPlayer -->|streams| RawCloud
    PLYPlayer -->|streams| RawCloud
    RawCloud -->|feeds| FeatureExtractor
    FeatureExtractor -->|features| OdometryEstimator
    OdometryEstimator -->|estimates| Database
    Database -->|new keyframes| LoopClosure
    LoopClosure -.->|candidates| ICPOptimizer
    ICPOptimizer -->|refined loops| PoseGraphOpt
    OdometryEstimator -->|odometry edges| PoseGraphOpt
    PoseGraphOpt -->|optimized poses| Database
    Database -->|updated poses| Viewer
    Viewer -->|renders| Viewer

    %% Config to modules
    ConfigLoader -->|config| FeatureExtractor
    ConfigLoader -->|config| OdometryEstimator
    ConfigLoader -->|config| LoopClosure
    ConfigLoader -->|config| ICPOptimizer
    ConfigLoader -->|config| PoseGraphOpt
    ConfigLoader -->|config| Viewer

    %% Logging
    ConfigLoader -->|logs to| Logging
    KITTIPlayer -->|logs to| Logging
    PLYPlayer -->|logs to| Logging
    FeatureExtractor -->|logs to| Logging
    OdometryEstimator -->|logs to| Logging
    LoopClosure -->|logs to| Logging
    ICPOptimizer -->|logs to| Logging
    PoseGraphOpt -->|logs to| Logging
    Viewer -->|logs to| Logging

    %% Thirdparty usage
    PoseGraphOpt -->|uses| Ceres
    Viewer -->|uses| PangolinLib
    LoopClosure -->|uses| LidarIris
    OdometryEstimator -->|uses| Sophus
    OdometryEstimator -->|uses| NanoFlann

    %% Click Events
    click KittiApp "https://github.com/93won/lidar_odometry/blob/main/app/kitti_lidar_odometry.cpp"
    click Mid360App "https://github.com/93won/lidar_odometry/blob/main/app/mid360_lidar_odometry.cpp"
    click ConfigLoader "https://github.com/93won/lidar_odometry/blob/main/src/util/Config.cpp"
    click KittiYAML "https://github.com/93won/lidar_odometry/blob/main/config/kitti.yaml"
    click Mid360YAML "https://github.com/93won/lidar_odometry/blob/main/config/mid360.yaml"
    click KITTIPlayer "https://github.com/93won/lidar_odometry/blob/main/app/player/kitti_player.cpp"
    click PLYPlayer "https://github.com/93won/lidar_odometry/blob/main/app/player/ply_player.cpp"
    click Database "https://github.com/93won/lidar_odometry/blob/main/src/database/LidarFrame.cpp"
    click FeatureExtractor "https://github.com/93won/lidar_odometry/blob/main/src/processing/FeatureExtractor.cpp"
    click OdometryEstimator "https://github.com/93won/lidar_odometry/blob/main/src/processing/Estimator.cpp"
    click LoopClosure "https://github.com/93won/lidar_odometry/blob/main/src/processing/LoopClosureDetector.cpp"
    click ICPOptimizer "https://github.com/93won/lidar_odometry/blob/main/src/optimization/IterativeClosestPointOptimizer.cpp"
    click PoseGraphOpt "https://github.com/93won/lidar_odometry/blob/main/src/optimization/PoseGraphOptimizer.cpp"
    click Viewer "https://github.com/93won/lidar_odometry/blob/main/src/viewer/PangolinViewer.cpp"
    click Logging "https://github.com/93won/lidar_odometry/tree/main/thirdparty/spdlog"

    %% Styles
    classDef apps fill:#F7B267,stroke:#000,stroke-width:1px;
    classDef core fill:#A1C181,stroke:#000,stroke-width:1px;
    classDef util fill:#79A7D3,stroke:#000,stroke-width:1px;
    classDef thirdparty fill:#E76F51,stroke:#000,stroke-width:1px;
    classDef logging fill:#CBC3E3,stroke:#000,stroke-width:1px;
```
