# hkust-aerial-robotics/g3reg architecture

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

- Interactive diagram: https://gitdiagram.com/hkust-aerial-robotics/g3reg
- Repository: https://github.com/hkust-aerial-robotics/g3reg

## Overview

##### Project type and purpose
- G3Reg is a C++ open-source library and CLI tool for robust global registration of outdoor LiDAR point clouds. It provides a modular pipeline—from point-cloud loading to segmentation, feature extraction, matching, graph-based verification, and final pose estimation—configurable via YAML files and extensible via plugins.

##### File structure
- Top-level directories:
- /src: core implementation, split into front_end, back_end, utils, datasets
- Thirdparty: embedded external libraries (clique_solver, fpfh_matcher, robot_utils, backward-cpp)
- configs: parameter sets for different datasets and matching methods
- examples: demo and benchmark executables
- cmake: build tool modules
- docs: user guide, benchmarks, demo instructions
- Patterns:
- Modular separation: “front_end” for feature/descriptor, “back_end” for estimation/verification
- CMake‐driven build with find-package wrappers for Boost, Eigen, GTSAM, PCL, etc.
- Config-driven behavior (YAML files under configs/).

##### README for additional insights
- The pipeline graphic (assets/pipeline.png) highlights: segmentation-based matching with Gaussian Ellipsoid Model (GEM), distrust-and-verify via Pyramid Compatibility Graph (PAGOR), integration points for alternative matchers (FPFH, TEASER, RANSAC).
- Core features: fast GEM matching, robust PAGOR verification, generic plugin support.

##### Detail level
- Every module is annotated with its directory path (e.g., front_end/gem, back_end/pagor).
- Call out extensibility APIs (e.g., function signatures in utils/config.h, datasets_init.h).
- Configuration inputs (configs/*.yaml) feeding into each stage.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Pipeline stages
    subgraph "Pipeline"
        direction TB
        CLI["CLI & Configuration"]:::config
        Loader["Dataset Loader"]:::coreModule
        Preprocessing["Preprocessing/Segmentation (GEM)"]:::coreModule
        Features["Front-End Feature Extractors"]:::coreModule
        Matching["Matching Engine"]:::coreModule
        Verification["Verification Engine (PAGOR)"]:::coreModule
        Estimator["Transformation Estimator & Pose Output"]:::coreModule
        MapMerge["Optional Map Merging Module"]:::coreModule
        CLI -->|"reads configs/*.yaml"| Loader
        Loader -->|"raw PointCloud"| Preprocessing
        Preprocessing -->|"Segments"| Features
        Features -->|"descriptors"| Matching
        Matching -->|"Candidate Matches"| Verification
        Verification -->|"Verified Transform"| Estimator
        Estimator -->|"Final Pose"| MapMerge
    end

    %% Utilities support
    Utilities["Utilities (logging, evaluation, timing)"]:::coreModule
    Utilities -.-> CLI
    Utilities -.-> Loader
    Utilities -.-> Preprocessing
    Utilities -.-> Features
    Utilities -.-> Matching
    Utilities -.-> Verification
    Utilities -.-> Estimator
    Utilities -.-> MapMerge

    %% Build system
    subgraph "Build System"
        CMake["CMake Modules"]:::third
    end
    CMake --> CLI
    CMake --> Utilities
    CMake --> Loader
    CMake --> Preprocessing
    CMake --> Features
    CMake --> Matching
    CMake --> Verification
    CMake --> Estimator
    CMake --> MapMerge

    %% Third-party dependencies
    subgraph "Third-Party Libraries"
        direction TB
        Backward["backward-cpp"]:::third
        CliqueSolver["clique_solver"]:::third
        FPFHMatcher["fpfh_matcher"]:::third
        RobotUtils["robot_utils"]:::third
    end
    CliqueSolver --- Matching
    FPFHMatcher --- Features
    RobotUtils --- Utilities
    Backward --- Utilities
    Backward --- CMake

    %% Click Events
    click CLI "https://github.com/hkust-aerial-robotics/g3reg/blob/main/include/utils/config.h"
    click Loader "https://github.com/hkust-aerial-robotics/g3reg/blob/main/include/datasets/dataloader.h"
    click Preprocessing "https://github.com/hkust-aerial-robotics/g3reg/blob/main/include/front_end/gem/aos.hpp"
    click Features "https://github.com/hkust-aerial-robotics/g3reg/blob/main/include/front_end/fpfh_utils.h"
    click Matching "https://github.com/hkust-aerial-robotics/g3reg/blob/main/include/front_end/gem/gem_matching.h"
    click Verification "https://github.com/hkust-aerial-robotics/g3reg/blob/main/include/back_end/pagor/pagor.h"
    click Estimator "https://github.com/hkust-aerial-robotics/g3reg/blob/main/include/back_end/mac3d/mac_reg.h"
    click MapMerge "https://github.com/hkust-aerial-robotics/g3reg/blob/main/include/back_end/reglib.h"
    click Utilities "https://github.com/hkust-aerial-robotics/g3reg/blob/main/include/utils/evaluation.h"
    click CMake "https://github.com/hkust-aerial-robotics/g3reg/tree/main/cmake/"
    click Backward "https://github.com/hkust-aerial-robotics/g3reg/tree/main/Thirdparty/backward-cpp"
    click CliqueSolver "https://github.com/hkust-aerial-robotics/g3reg/tree/main/Thirdparty/clique_solver"
    click FPFHMatcher "https://github.com/hkust-aerial-robotics/g3reg/tree/main/Thirdparty/fpfh_matcher"
    click RobotUtils "https://github.com/hkust-aerial-robotics/g3reg/tree/main/Thirdparty/robot_utils"

    %% Styles
    classDef coreModule fill:#D6EAF8,stroke:#1B4F72,stroke-width:1px
    classDef data fill:#ABEBC6,stroke:#196F3D,stroke-width:1px
    classDef third fill:#D5D8DC,stroke:#626567,stroke-width:1px
    classDef config fill:#FCF3CF,stroke:#7D6608,stroke-width:1px
```
