# zm0612/eskf-gps-imu-fusion architecture

> Architecture diagram of the GitHub repository zm0612/eskf-gps-imu-fusion, 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/zm0612/eskf-gps-imu-fusion
- Repository: https://github.com/zm0612/eskf-gps-imu-fusion

## Overview

The project is an algorithmic implementation of an Error-State Kalman Filter (ESKF) designed for fusing GPS and IMU data for navigation/trajectory estimation. In essence, it’s a signal processing application rather than a full-blown full-stack system. The focus is on sensor fusion, filtering, and data processing to improve trajectory estimation, with the ultimate goal of comparing results using IMU integration alone vs. using ESKF fusion.

##### Main Components
- ESKF Core: The central logic implemented in files like src/eskf.cpp and include/eskf.h.
- Data Handling & Tools: Modules related to reading, processing, and analyzing sensor data (e.g., include/gps_data.h, include/imu_data.h, src/gps_tool.cpp, src/imu_tool.cpp).
- Fusion Flow: The higher-level flow managing the integration process across sensors (e.g., src/eskf_flow.cpp, include/eskf_flow.h).
- External Libraries and 3rd Party Components: This includes GeographicLib located under the 3rd directory, and dependencies like Eigen, YAML, and Glog that are integrated via CMake.
- Configuration & I/O: The config folder (with config.yaml) defines parameters for the filter, and the data folder handles both raw sensor data (CSV files) and generated outputs.
- Testing: The test directory ensures the correctness of key components with unit tests for GPS, IMU, and tool functions.

##### Relationships and Data Flow
- Data Acquisition: The raw sensor data is organized in the data/raw_data folder and is fed into the ESKF algorithm via the fusion executable (app/gps_imu_fusion.cpp).
- Sensor Fusion Workflow: The ESKF core (error state calculations, correction, and propagation) is used by an orchestrating flow (eskf_flow) that dynamically fuses IMU and GPS inputs.
- External Libraries: GeographicLib is available in-house (copied under the 3rd folder) and is likely used for geospatial transformations which complement the sensor fusion.
- Input Parameters: The configuration parameters held in config/config.yaml dictate how the fusion process works. The executable takes configuration and data paths as arguments.
- Output & Visualization: After fusion, output trajectory files are produced in the data folder, and display_path.py uses these outputs to generate visualization of trajectories.
- Testing and Validation: Tests in the test folder are crucial for verifying integrity and correctness of the components.

##### Architectural Patterns and Design Principles
- Modular Design: The code is cleanly divided into modules, with distinct directories for application logic (app/ and src/), interfaces (include/), and testing (test/).
- Dependency Management via CMake: The CMake files (top-level CMakeLists, cmake directory scripts) ensure the correct integration of external libraries and internal modules.
- Separation of Concerns: Each module (data processing, filter implementation, visualization) has a dedicated directory or file, allowing for independent development and testing.

- Auxiliary dependencies: Connect the configuration file to the Fusion Engine module; show the external dependency modules (GeographicLib, Eigen, YAML, Glog) branching into the Fusion Engine.
- Testing components separately: Illustrate that unit tests monitor the individual modules within the sensor data processing and fusion modules.
- “build and deploy” references: Optionally annotate the build process via CMake as part of the setup and dependency resolution.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Subgraph: Data Acquisition & Preprocessing
    subgraph "Data Acquisition & Preprocessing"
        raw_data["\"Raw Sensor Data\""]:::storage
        acquisition["\"Data Acquisition Module\""]:::processing
        data_tools["\"Data Handling & Tools\""]:::processing
        configurator["\"Configuration\""]:::storage
    end

    %% Subgraph: Fusion Engine
    subgraph "Fusion Engine"
        eskf_core["\"ESKF Core\""]:::processing
        fusion_flow["\"Fusion Flow Manager\""]:::processing
    end

    %% Subgraph: Output & Visualization
    subgraph "Output & Visualization"
        output_data["\"Trajectory Output\""]:::storage
        visualization["\"Visualization Module\""]:::processing
    end

    %% Subgraph: External Libraries
    subgraph "External Libraries"
        geographiclib["\"GeographicLib\""]:::external
        eigen["\"Eigen\""]:::external
        yaml["\"YAML\""]:::external
        glog["\"Glog\""]:::external
    end

    %% Subgraph: Testing Suite
    subgraph "Testing Suite"
        test_gps["\"GPS Test\""]:::testing
        test_imu["\"IMU Test\""]:::testing
        test_tool["\"Tool Test\""]:::testing
    end

    %% Data Flow Connections
    raw_data -->|"feeds"| acquisition
    acquisition -->|"processes"| data_tools
    data_tools -->|"supplies data to"| eskf_core
    configurator -->|"configures"| eskf_core
    eskf_core -->|"integrates with"| fusion_flow
    fusion_flow -->|"generates"| output_data
    output_data -->|"visualized by"| visualization

    %% External Libraries Connections to Fusion Engine
    geographiclib -->|"used_by"| eskf_core
    eigen -->|"used_by"| eskf_core
    yaml -->|"used_by"| eskf_core
    glog -->|"used_by"| eskf_core

    %% Testing Connections
    test_gps ---|"validates"| data_tools
    test_imu ---|"validates"| data_tools
    test_tool ---|"validates"| fusion_flow

    %% Click Events
    click acquisition "https://github.com/zm0612/eskf-gps-imu-fusion/blob/main/app/gps_imu_fusion.cpp"
    
    click data_tools "https://github.com/zm0612/eskf-gps-imu-fusion/blob/main/include/gps_data.h"
    click data_tools "https://github.com/zm0612/eskf-gps-imu-fusion/blob/main/include/imu_data.h"
    click data_tools "https://github.com/zm0612/eskf-gps-imu-fusion/blob/main/src/gps_tool.cpp"
    click data_tools "https://github.com/zm0612/eskf-gps-imu-fusion/blob/main/src/imu_tool.cpp"
    
    click eskf_core "https://github.com/zm0612/eskf-gps-imu-fusion/blob/main/src/eskf.cpp"
    click eskf_core "https://github.com/zm0612/eskf-gps-imu-fusion/blob/main/include/eskf.h"
    
    click fusion_flow "https://github.com/zm0612/eskf-gps-imu-fusion/blob/main/src/eskf_flow.cpp"
    click fusion_flow "https://github.com/zm0612/eskf-gps-imu-fusion/blob/main/include/eskf_flow.h"
    
    click geographiclib "https://github.com/zm0612/eskf-gps-imu-fusion/tree/main/3rd/GeographicLib"
    click eigen "https://github.com/zm0612/eskf-gps-imu-fusion/blob/main/cmake/eigen.cmake"
    click yaml "https://github.com/zm0612/eskf-gps-imu-fusion/blob/main/cmake/YAML.cmake"
    click glog "https://github.com/zm0612/eskf-gps-imu-fusion/blob/main/cmake/glog.cmake"
    
    click configurator "https://github.com/zm0612/eskf-gps-imu-fusion/blob/main/config/config.yaml"
    click output_data "https://github.com/zm0612/eskf-gps-imu-fusion/tree/main/data"
    click visualization "https://github.com/zm0612/eskf-gps-imu-fusion/blob/main/data/display_path.py"
    
    click test_gps "https://github.com/zm0612/eskf-gps-imu-fusion/blob/main/test/test_gps.cpp"
    click test_imu "https://github.com/zm0612/eskf-gps-imu-fusion/blob/main/test/test_imu.cpp"
    click test_tool "https://github.com/zm0612/eskf-gps-imu-fusion/blob/main/test/test_tool.cpp"
    
    %% Styles
    classDef processing fill:#AED6F1,stroke:#2874A6,stroke-width:2px;
    classDef storage fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef external fill:#D2B4DE,stroke:#7D3C98,stroke-width:2px;
    classDef testing fill:#A9DFBF,stroke:#239B56,stroke-width:2px;
```
