# hviktortsoi/pv-lio architecture

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

- Interactive diagram: https://gitdiagram.com/hviktortsoi/pv-lio
- Repository: https://github.com/hviktortsoi/pv-lio

## Overview

##### Main Components
a. Sensor Input Modules:
- LiDAR Data Input – This includes support for multiple LiDAR sensors (Livox, Velodyne, Robosense, Hesai, etc.) as seen by the different launch files and config files named mapping_avia.launch, mapping_velodyne.launch, mapping_robosense.launch.
- IMU Data Input – The system requires an IMU (internal or external) and expects synchronization with the LiDAR.
b. Data Preprocessing and Conversion:
- Preprocessing Module – Represented in files like src/preprocess.cpp and converters (e.g., pandar_to_velodyne.cpp, rs_to_velodyne.cpp) which reformat sensor data to a unified internal representation.
c. Fusion and Odometry Estimation:
- LiDAR-Inertial Fusion Core – The heart of the system using iterative Kalman filtering (IKFoM) for state estimation. This module likely relies on include libraries such as IKFoM_toolkit and components from VoxelMap (with covariance estimation) that are integrated into the state estimation.
d. Mapping Module:
- Voxel Mapping Engine – Utilizes an adapted version of VoxelMap to manage local maps, including modules to compute and propagate covariances for each LiDAR point-feature correspondence and perform parallel-optimized map updates.
e. Configuration/Parameter Management:
- Configurations - The config directory contains YAML files (like avia_indoor.yaml, hesai.yaml, etc.) which set sensor topics, extrinsics, and operational parameters.
f. Logging and Visualization:
- Log Files and Visualization Tools – There is a Log directory with scripts (e.g., plot.py) and RViz configuration files to allow runtime or offline analysis and visualization of both the voxel map and uncertainty estimates.
g. ROS Launch and Build:
- Launch Files – Multiple launch files provide a streamlined way to initialize sensor drivers and nodes for different LiDAR sensor configurations.
- Build System – The CMakeLists.txt shows the project is built using CMake and integrated into a ROS workspace via package.xml.

##### Relationships and Interactions
- Sensor Data Flow: LiDAR and IMU sensors send raw data to the respective drivers. Their outputs flow through the preprocessing modules where formats are unified and any necessary timing synchronization (or time adjustments) is handled.
- Fusion: The preprocessed data then enters the fusion module that uses IKFoM to combine the LiDAR point cloud features with the IMU inertial measurements. Here, extrinsic calibrations (defined in the config YAML files) are applied.
- Mapping: The fusion output, which contains the state (pose) estimates, is then used by the Voxel Mapping engine to maintain and update the local map. Covariance propagation is applied here to account for measurement uncertainty.
- Configuration: All these components read their parameters (sensor topics, extrinsics, time-sync options, etc.) from the configuration files.
- Data Logging & Visualization: Throughout these processes, logs and visualization tools are engaged to analyze performance and debug issues, with results viewable in RViz, as set by the provided RViz configuration files.

##### Architectural Patterns & Design Principles
- Modular Design: The system separates sensor data acquisition, preprocessing, fusion/estimation, and mapping into distinct modules.
- ROS-based Componentization: Different ROS nodes (as specified in the launch files) handle sensor interfacing and computation, encapsulating functionality.
- Configuration Driven: YAML config files drive sensor parameters and extrinsics, making the system highly configurable for different sensor setups.
- Use of External Libraries: It integrates third-party libraries such as IKFoM for the Kalman filtering and VoxelMap for mapping, promoting code reuse and leveraging enhanced functionality.

##### Relevant Technologies and Frameworks
- Operating Environment: Ubuntu (>=16.04) with ROS (>= Melodic)
- Libraries and Dependencies: PCL, Eigen, IKFoM, VoxelMap, and livox_ros_driver (for Livox LiDAR).
- Build System: CMake and ROS catkin_make build process.

##### Elements
- Use clearly labeled components (e.g., "LiDAR Driver", "IMU Driver", "Preprocessing Module", "IKFoM Fusion Module", "Voxel Mapping Engine", "ROS Launch Manager").
- A note on the build/integration process (CMake, package.xml) as a supporting subsystem, though focus primarily on runtime architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration and Launch Layer
    subgraph "Configuration and Launch Layer"
        Config["\"Configurations\""]:::config
        Launch["\"ROS Launch Manager\""]:::launch
        Build["\"Build System\""]:::build
    end

    %% Sensor Input Layer
    subgraph "Sensor Input Layer"
        subgraph "LiDAR Drivers"
            LiDARAvia["\"Mapping Avia\""]:::sensor
            LiDARHesai["\"Mapping Hesai\""]:::sensor
            LiDARRobosense["\"Mapping Robosense\""]:::sensor
            LiDARVelodyne["\"Mapping Velodyne\""]:::sensor
        end
        IMU["\"IMU Data Input\""]:::sensor
    end

    %% Data Preprocessing Layer
    subgraph "Data Preprocessing Layer"
        Preproc["\"Preprocessing Module\""]:::preproc
        Converters["\"Data Converters\""]:::preproc
    end

    %% Fusion and Odometry Estimation Layer
    subgraph "Fusion and Odometry Estimation Layer"
        Fusion["\"LiDAR-Inertial Fusion Core\""]:::fusion
    end

    %% Mapping Layer
    subgraph "Mapping Layer"
        Mapping["\"Voxel Mapping Engine\""]:::mapping
    end

    %% Logging and Visualization Layer
    subgraph "Logging and Visualization Layer"
        Logging["\"Log & Visualization Tools\""]:::logging
    end

    %% Data Flow Connections
    Config --> Launch
    Config --> Preproc
    Config --> Fusion
    Config --> Mapping

    Build --> Launch

    Launch --> LiDARAvia
    Launch --> LiDARHesai
    Launch --> LiDARRobosense
    Launch --> LiDARVelodyne
    Launch --> IMU

    LiDARAvia --> Preproc
    LiDARHesai --> Preproc
    LiDARRobosense --> Preproc
    LiDARVelodyne --> Preproc
    IMU --> Preproc

    Preproc --> Converters
    Converters --> Fusion
    Preproc --> Fusion

    Fusion --> Mapping
    Fusion --> Logging
    Mapping --> Logging

    %% Click Events
    click LiDARAvia "https://github.com/hviktortsoi/pv-lio/blob/master/launch/mapping_avia.launch"
    click LiDARHesai "https://github.com/hviktortsoi/pv-lio/blob/master/launch/mapping_hesai.launch"
    click LiDARRobosense "https://github.com/hviktortsoi/pv-lio/blob/master/launch/mapping_robosense.launch"
    click LiDARVelodyne "https://github.com/hviktortsoi/pv-lio/blob/master/launch/mapping_velodyne.launch"
    click IMU "https://github.com/hviktortsoi/pv-lio/blob/master/src/IMU_Processing.hpp"
    click Preproc "https://github.com/hviktortsoi/pv-lio/blob/master/src/preprocess.cpp"
    click Converters "https://github.com/hviktortsoi/pv-lio/tree/master/src/converter"
    click Fusion "https://github.com/hviktortsoi/pv-lio/tree/master/include/IKFoM_toolkit"
    click Mapping "https://github.com/hviktortsoi/pv-lio/blob/master/src/voxelMapping.cpp"
    click Config "https://github.com/hviktortsoi/pv-lio/tree/master/config"
    click Logging "https://github.com/hviktortsoi/pv-lio/blob/master/Log/plot.py"
    click Launch "https://github.com/hviktortsoi/pv-lio/tree/master/launch"
    click Build "https://github.com/hviktortsoi/pv-lio/blob/master/CMakeLists.txt"

    %% Styles
    classDef sensor fill:#ff9999,stroke:#cc0000,stroke-width:2px;
    classDef preproc fill:#99ccff,stroke:#003366,stroke-width:2px;
    classDef fusion fill:#ccffcc,stroke:#006600,stroke-width:2px;
    classDef mapping fill:#ffffcc,stroke:#999900,stroke-width:2px;
    classDef config fill:#e0ccff,stroke:#660099,stroke-width:2px;
    classDef launch fill:#d9ead3,stroke:#38761d,stroke-width:2px;
    classDef build fill:#fce5cd,stroke:#bf9000,stroke-width:2px;
    classDef logging fill:#ffd9b3,stroke:#ff6600,stroke-width:2px;
```
