# koide3/hdl_graph_slam architecture

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

- Interactive diagram: https://gitdiagram.com/koide3/hdl_graph_slam
- Repository: https://github.com/koide3/hdl_graph_slam

## Overview

##### Project type and purpose
- hdl_graph_slam is a ROS-based full-stack SLAM package for real-time 6DOF mapping with a 3D LiDAR.
- Its core function is to ingest raw point clouds (and optionally IMU, GPS), run odometry, floor detection, loop detection, optimize a pose graph, and produce a consistent 3D map.

##### File structure
- Top-level:
- apps/ – standalone demo nodelets
- / & src/ – core C++ & Python code under hdl_graph_slam and g2o extension
- launch/ – ROS launch files configuring parameters and nodelet loading
- msg/, srv/ – custom ROS messages (FloorCoeffs, ScanMatchingStatus) and services (DumpGraph, SaveMap)
- package.xml, CMakeLists.txt – ROS build/config
- docker/ – containerized build environments
- Patterns:
- Nodelet-based modular pipeline (four nodelets)
- Graph optimization via g2o library
- Python utilities (bag_player.py, ford2bag.py) for data playback/conversion

##### README for insights
- Four nodelets form a processing pipeline:
1) prefiltering_nodelet
2) scan_matching_odometry_nodelet
3) floor_detection_nodelet
4) hdl_graph_slam_nodelet (graph optimizer)
- Supported constraints: odometry, loop closures, GPS, IMU accel/orientation, floor plane
- Publishes optimized poses and map; offers services to dump/ save map.

a. Main components
- Sensors: 3D LiDAR, IMU, GPS
- Nodelets (processing modules)
- Graph Optimizer (g2o backend)
- ROS communication layer (topics, services)
- Output: optimized trajectory & 3D map
- External dependencies: ndt_omp/fast_gicp for scan matching, PCL, suitesparse

b. Relationships and interactions
- LiDAR → /velodyne_points (Topic) → prefiltering_nodelet
- Prefiltered cloud → scan_matching_odometry_nodelet → publishes odometry (Edge: odometry constraint)
- Same cloud → floor_detection_nodelet → publishes floor_coeffs (Edge: floor constraint)
- IMU → /imu_data → hdl_graph_slam_nodelet (accel/orientation constraints)
- GPS → /gps/* → hdl_graph_slam_nodelet (GPS constraint)
- scan_matching_odometry + floor_detection + loop detection → pose graph → g2o optimizer
- Optimizer → publishes corrected poses → map generator → /map → rviz / pcd file via SaveMap service

c. Architectural patterns/design principles
- Nodelet pipeline for zero-copy intra-process communication
- Modular constraint-based graph SLAM
- Separation of concerns: sensor filtering, odometry, environment feature detection, global optimization
- Extensibility via ROS messages/services and g2o edge definitions

d. Key technologies/frameworks/libraries
- ROS (nodelets, topics, services, launch files)
- PCL for point cloud processing
- ndt_omp / fast_gicp for scan matching
- g2o for graph optimization
- OpenMP, SuiteSparse for linear solvers

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Sensors
    subgraph "Sensor Inputs"
        direction TB
        LiDAR["3D LiDAR"]:::sensor
        IMU["IMU"]:::sensor
        GPS["GPS"]:::sensor
    end

    %% Nodelet Pipeline
    subgraph "Nodelet Pipeline"
        direction TB
        Prefiltering["Prefiltering Nodelet"]:::nodelet
        ScanOdo["Scan Matching Odometry Nodelet"]:::nodelet
        FloorDet["Floor Detection Nodelet"]:::nodelet
        GraphOpt["hdl_graph_slam Nodelet\n(Graph Optimizer)"]:::nodelet
        MapGen["Map Cloud Generator"]:::nodelet
    end

    %% External Backend
    subgraph "Backend Libraries"
        direction TB
        g2oExt["g2o Extensions & Robust Kernel IO"]:::backend
        CoreGraph["Core Graph SLAM Pipeline"]:::backend
    end

    %% Outputs & Services
    subgraph "Outputs & Services"
        direction TB
        RViz["RViz (/map)"]:::output
        SaveMap["SaveMap Service"]:::service
        DumpGraph["DumpGraph Service"]:::service
        LoadGraph["LoadGraph Service"]:::service
    end

    %% Utilities & Configuration
    subgraph "Utilities & Config"
        direction TB
        PythonUtils["Python Utilities"]:::util
        LaunchFiles["ROS Launch Configs"]:::config
        Plugins["nodelet_plugins.xml"]:::config
        Docker["Docker Environments"]:::config
        PackageBuild["package.xml\nCMakeLists.txt\nsetup.py"]:::config
    end

    %% Connections
    LiDAR -->|"/velodyne_points"| Prefiltering
    Prefiltering --> ScanOdo
    Prefiltering --> FloorDet
    ScanOdo --> GraphOpt
    FloorDet --> GraphOpt
    IMU -->|"/imu_data"| GraphOpt
    GPS -->|"/gps/*"| GraphOpt
    GraphOpt --> g2oExt
    GraphOpt --> CoreGraph
    GraphOpt --> MapGen
    MapGen -->|"/map"| RViz
    GraphOpt -->|"pcd file"| SaveMap
    GraphOpt -->|"pose graph"| DumpGraph
    GraphOpt -->|"load graph"| LoadGraph

    %% Utilities & Config Links
    PythonUtils --> Prefiltering
    PythonUtils --> ScanOdo
    LaunchFiles --> Prefiltering
    LaunchFiles --> ScanOdo
    LaunchFiles --> FloorDet
    LaunchFiles --> GraphOpt
    Plugins --> Prefiltering
    Plugins --> ScanOdo
    Plugins --> FloorDet
    Plugins --> GraphOpt
    Docker --> PackageBuild

    %% Click Events for Component Mapping
    click Prefiltering "https://github.com/koide3/hdl_graph_slam/blob/master/apps/prefiltering_nodelet.cpp"
    click ScanOdo "https://github.com/koide3/hdl_graph_slam/blob/master/apps/scan_matching_odometry_nodelet.cpp"
    click FloorDet "https://github.com/koide3/hdl_graph_slam/blob/master/apps/floor_detection_nodelet.cpp"
    click GraphOpt "https://github.com/koide3/hdl_graph_slam/blob/master/apps/hdl_graph_slam_nodelet.cpp"
    click g2oExt "https://github.com/koide3/hdl_graph_slam/blob/master/include/g2o/robust_kernel_io.hpp"
    click g2oExt "https://github.com/koide3/hdl_graph_slam/blob/master/src/g2o/robust_kernel_io.cpp"
    click CoreGraph "https://github.com/koide3/hdl_graph_slam/blob/master/include/hdl_graph_slam/graph_slam.hpp"
    click CoreGraph "https://github.com/koide3/hdl_graph_slam/blob/master/include/hdl_graph_slam/keyframe.hpp"
    click CoreGraph "https://github.com/koide3/hdl_graph_slam/blob/master/include/hdl_graph_slam/keyframe_updater.hpp"
    click CoreGraph "https://github.com/koide3/hdl_graph_slam/blob/master/include/hdl_graph_slam/loop_detector.hpp"
    click CoreGraph "https://github.com/koide3/hdl_graph_slam/blob/master/include/hdl_graph_slam/map_cloud_generator.hpp"
    click CoreGraph "https://github.com/koide3/hdl_graph_slam/blob/master/include/hdl_graph_slam/information_matrix_calculator.hpp"
    click CoreGraph "https://github.com/koide3/hdl_graph_slam/blob/master/include/hdl_graph_slam/registrations.hpp"
    click CoreGraph "https://github.com/koide3/hdl_graph_slam/blob/master/include/hdl_graph_slam/ros_time_hash.hpp"
    click CoreGraph "https://github.com/koide3/hdl_graph_slam/blob/master/include/hdl_graph_slam/ros_utils.hpp"
    click CoreGraph "https://github.com/koide3/hdl_graph_slam/blob/master/include/hdl_graph_slam/nmea_sentence_parser.hpp"
    click CoreGraph "https://github.com/koide3/hdl_graph_slam/blob/master/src/hdl_graph_slam/graph_slam.cpp"
    click CoreGraph "https://github.com/koide3/hdl_graph_slam/blob/master/src/hdl_graph_slam/keyframe.cpp"
    click CoreGraph "https://github.com/koide3/hdl_graph_slam/blob/master/src/hdl_graph_slam/map_cloud_generator.cpp"
    click CoreGraph "https://github.com/koide3/hdl_graph_slam/blob/master/src/hdl_graph_slam/information_matrix_calculator.cpp"
    click CoreGraph "https://github.com/koide3/hdl_graph_slam/blob/master/src/hdl_graph_slam/registrations.cpp"
    click SaveMap "https://github.com/koide3/hdl_graph_slam/blob/master/srv/SaveMap.srv"
    click DumpGraph "https://github.com/koide3/hdl_graph_slam/blob/master/srv/DumpGraph.srv"
    click LoadGraph "https://github.com/koide3/hdl_graph_slam/blob/master/srv/LoadGraph.srv"
    click PythonUtils "https://github.com/koide3/hdl_graph_slam/blob/master/src/hdl_graph_slam/bag_player.py"
    click PythonUtils "https://github.com/koide3/hdl_graph_slam/blob/master/src/hdl_graph_slam/ford2bag.py"
    click PythonUtils "https://github.com/koide3/hdl_graph_slam/blob/master/src/hdl_graph_slam/map2odom_publisher.py"
    click LaunchFiles "https://github.com/koide3/hdl_graph_slam/blob/master/launch/hdl_graph_slam.launch"
    click LaunchFiles "https://github.com/koide3/hdl_graph_slam/blob/master/launch/hdl_graph_slam_400.launch"
    click LaunchFiles "https://github.com/koide3/hdl_graph_slam/blob/master/launch/hdl_graph_slam_501.launch"
    click LaunchFiles "https://github.com/koide3/hdl_graph_slam/blob/master/launch/hdl_graph_slam_imu.launch"
    click LaunchFiles "https://github.com/koide3/hdl_graph_slam/blob/master/launch/hdl_graph_slam_kitti.launch"
    click LaunchFiles "https://github.com/koide3/hdl_graph_slam/blob/master/launch/msf_config.yaml"
    click Plugins "https://github.com/koide3/hdl_graph_slam/blob/master/nodelet_plugins.xml"
    click Docker "https://github.com/koide3/hdl_graph_slam/blob/master/docker/build.sh"
    click Docker "https://github.com/koide3/hdl_graph_slam/blob/master/docker/run.sh"
    click Docker "https://github.com/koide3/hdl_graph_slam/tree/master/docker/kinetic/Dockerfile"
    click Docker "https://github.com/koide3/hdl_graph_slam/tree/master/docker/melodic/Dockerfile"
    click Docker "https://github.com/koide3/hdl_graph_slam/tree/master/docker/noetic/Dockerfile"
    click PackageBuild "https://github.com/koide3/hdl_graph_slam/blob/master/package.xml"
    click PackageBuild "https://github.com/koide3/hdl_graph_slam/blob/master/CMakeLists.txt"
    click PackageBuild "https://github.com/koide3/hdl_graph_slam/blob/master/setup.py"

    %% Styles
    classDef sensor fill:#AED6F1,stroke:#1B4F72,color:#1B4F72
    classDef nodelet fill:#ABEBC6,stroke:#196F3D,color:#196F3D
    classDef backend fill:#F5B041,stroke:#B9770E,color:#B9770E
    classDef output fill:#D7BDE2,stroke:#6C3483,color:#6C3483
    classDef service fill:#D2B4DE,stroke:#76448A,color:#76448A
    classDef util fill:#F9E79F,stroke:#B7950B,color:#B7950B
    classDef config fill:#EDBB99,stroke:#A04000,color:#A04000
    class CoreGraph,g2oExt backend
    class Prefiltering,ScanOdo,FloorDet,GraphOpt,MapGen nodelet
```
