# hku-mars/fast_lio architecture

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

- Interactive diagram: https://gitdiagram.com/hku-mars/fast_lio
- Repository: https://github.com/hku-mars/fast_lio

## Overview

##### Project Type and Purpose
- FAST-LIO 2 is a LiDAR-inertial odometry package that fuses LiDAR feature points with IMU data using a tightly-coupled iterated Extended Kalman Filter. Its purpose is to provide fast, robust navigation and mapping even in cluttered, high-dynamic environments.
- The README emphasizes direct LiDAR odometry, incremental mapping with the external ikd-Tree library, and integration with external sensors (e.g., Livox, Velodyne, Ouster).

##### Main Components from the File Structure
- Sensor Input & Driver Interfaces:
- External LiDAR drivers (e.g., livox_ros_driver, Velodyne ROS drivers) that supply raw LiDAR point clouds.
- IMU data provided via ROS topics.
- Preprocessing Module:
- Files like src/preprocess.cpp/h and IMU_Processing.hpp indicate initial data conditioning and sensor synchronization.
- Tightly-Coupled Fusion Module:
- Core algorithm implementation in laserMapping.cpp and the Kalman filter utilities available via included IKFoM toolkit (located under include/IKFoM_toolkit).
- Incorporation of on-manifold Kalman filtering techniques and mathematical constructs from the mtk libraries.
- Mapping & Optimization:
- Use of ikd-Tree (present in both the file tree and as a git submodule) for incremental mapping and 3D nearest neighbor search.
- ROS Integration and Launch Infrastructure:
- ROS package artifacts: package.xml, msg definitions (Pose6D.msg), and multiple launch files (in the launch directory) for different sensor configurations (avia, horizon, mid360, ouster64, velodyne).
- Configuration/Parameter Management:
- Configuration files in the config directory determine sensor topics, extrinsic parameters, and other runtime options.
- Auxiliary/Dev Tools:
- Docker scripts and build-related files (CMakeLists.txt) for deployment.
- Visualization aids (rviz_cfg) and log scripts for analyzing system performance.

- Outputs of preprocessing to the Fusion/State Estimation Block. Illustrate this block as comprising the iterated Extended Kalman Filter (leveraging the IKFoM toolkit) that fuses LiDAR and IMU data.
- Link the Fusion Block to the Mapping & Optimization Module where the incremental map is built using the ikd-Tree library. Indicate a bidirectional or iterative flow in some cases between the state estimation and mapping if applicable.
- Connections from these core modules to ROS communication layers. Represent the publication of state estimates, odometry messages, and mapping data to relevant ROS topics.
- External dependencies or utility flows such as configuration management (loading parameters from config files) and visualization/recording outputs (saving data as PCD files, rviz views).
- A container boundary (for Docker workflows) as well as node interactions within the ROS ecosystem.

##### Highlighting Architectural Patterns and Technologies
- Modularity: Clearly separate input handling, pre-processing, fusion, and mapping.
- Key Libraries/Tools: IKFoM for on-manifold filtering, ikd-Tree for rapid KD-Tree searches, PCL and Eigen for point cloud and matrix operations, and ROS for communication.
- Deployment & Configuration: Emphasize the role of configuration files and launch scripts that dynamically switch between sensor setups (e.g., Livox, Velodyne).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Sensor Input & Driver Interfaces
    subgraph "Sensor Input & Driver Interfaces"
        LIDAR["LiDAR Sensor"]:::sensor
        IMU["IMU Sensor"]:::sensor
    end

    %% Data Processing Pipeline
    subgraph "Data Processing Pipeline"
        PRE["Preprocessing & Synchronization Module"]:::processing
        FUS["Fusion / Iterated EKF Module (using IKFoM)"]:::estimation
        MAP["Incremental Mapping Module (using ikd-Tree)"]:::mapping
    end

    %% System Integration
    subgraph "System Integration"
        ROS["ROS Communication Layer"]:::communication
    end

    %% Configuration & Utilities
    subgraph "Configuration & Utilities"
        CONF["Configuration/Parameter Management"]:::config
        AUX["Auxiliary/Dev Tools"]:::aux
    end

    %% Connections between components
    LIDAR -->|"feedsData"| PRE
    IMU -->|"feedsData"| PRE
    PRE -->|"outputsData"| FUS
    FUS -->|"stateEstimates"| MAP
    MAP -->|"mapUpdates"| FUS
    FUS -->|"publishesState"| ROS
    MAP -->|"publishesMap"| ROS
    CONF -->|"providesParams"| PRE
    CONF -->|"providesParams"| FUS
    ROS -->|"communicatesWith"| AUX
    AUX -->|"supportsDeployment"| FUS

    %% Click Events
    click LIDAR "https://github.com/hku-mars/fast_lio/blob/main/config/velodyne.yaml"
    click IMU "https://github.com/hku-mars/fast_lio/blob/main/src/IMU_Processing.hpp"
    click PRE "https://github.com/hku-mars/fast_lio/blob/main/src/preprocess.cpp"
    click FUS "https://github.com/hku-mars/fast_lio/tree/main/include/IKFoM_toolkit"
    click MAP "https://github.com/hku-mars/fast_lio/blob/main/src/laserMapping.cpp"
    click ROS "https://github.com/hku-mars/fast_lio/blob/main/launch/mapping_avia.launch"
    click CONF "https://github.com/hku-mars/fast_lio/tree/main/config"
    click AUX "https://github.com/hku-mars/fast_lio/blob/main/CMakeLists.txt"

    %% Style Definitions
    classDef sensor fill:#ADD8E6,stroke:#000,stroke-width:2px,color:#000;
    classDef processing fill:#90EE90,stroke:#000,stroke-width:2px,color:#000;
    classDef estimation fill:#FFA500,stroke:#000,stroke-width:2px,color:#000;
    classDef mapping fill:#FFFF99,stroke:#000,stroke-width:2px,color:#000;
    classDef communication fill:#FFB6C1,stroke:#000,stroke-width:2px,color:#000;
    classDef config fill:#D3D3D3,stroke:#000,stroke-width:2px,color:#000;
    classDef aux fill:#AFEEEE,stroke:#000,stroke-width:2px,color:#000;
```
