# hkust-aerial-robotics/vins-fusion architecture

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

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

## Overview

##### Project type and purpose
- VINS-Fusion is a ROS-based, optimization-driven multi-sensor (camera + IMU + optional GPS) state estimator for drones, cars, AR/VR.
- It comprises several ROS packages:
- vins_estimator (core VIO),
- loop_fusion (visual loop closure),
- global_fusion (GPS fusion),
- camera_models (calibration utilities),
- config (device YAMLs),
- docker (containerization).

##### Main components
a. Sensors & data sources
– Cameras (mono/stereo)
– IMU
– (Optional) GPS
– Rosbag recordings
b. Core nodes
– vins_node (in vins_estimator)
– loop_fusion_node
– global_fusion_node
c. Algorithm modules
– Feature Tracker
– Estimator (factor graph construction)
– Ceres Solver (non-linear optimizer)
– DBoW2 (loop detection)
– GeographicLib (global optimization)
d. Support
– Config YAML files
– camera_models library
– Docker container for environment consistency
– RViz for visualization

##### Relationships & data flow
- Sensor drivers / rosbag → publish raw image & IMU topics
- vins_node subscribes → feature tracking → factor graph → optimization → publishes pose
- loop_fusion_node subscribes to poses → builds pose graph with DBoW2 → optimizes → publishes corrected poses
- global_fusion_node optionally fuses GPS + VIO poses → publishes global poses
- All pose streams → RViz for display

##### Architectural patterns & design principles
- Modular ROS node structure (single-responsibility nodes)
- Publisher/Subscriber data flow with clear topic boundaries
- Library reuse: camera_models for calibration, Ceres for optimization, DBoW2 for loop closure, GeographicLib for geodesy
- Configuration-driven behavior via YAMLs and ROS launch files
- Containerized build/runtime via Docker

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% SENSORS
  subgraph "Sensors"
    style Sensors fill:#E8F0FE,stroke:#3182CE
    Cam["Camera"]:::sensor
    IMU["IMU"]:::sensor
    Bag["Rosbag"]:::sensor
    Cam -->|"images"| ImgTopic[/camera/image_raw/]:::topic
    IMU -->|"imu data"| ImuTopic[/imu/data/]:::topic
    Bag -->|replay| Cam
    Bag -->|replay| IMU
  end

  %% CORE VINS ESTIMATOR
  subgraph "vins_estimator (vins_node)"
    style vins_estimator fill:#E6F4EA,stroke:#2F855A
    FT["Feature Tracker"]:::compute
    EST["Estimator\n(factor graph)"]:::compute
    CERES["Ceres Solver"]:::compute
    PUB_VIO["VIO Pose Publisher"]:::topic
    Configs -->|config| FT
    Configs -->|config| EST
    CamModels -.->|calibration| FT
    ImgTopic --> FT
    ImuTopic --> FT
    FT --> EST
    EST --> CERES
    CERES --> PUB_VIO
  end

  %% LOOP CLOSURE
  subgraph "loop_fusion (loop_fusion_node)"
    style loop_fusion fill:#FFF5E5,stroke:#DD6B20
    DBoW2["DBoW2\n(loop detection)"]:::compute
    PGOpt["Pose Graph\nOptimizer"]:::compute
    PUB_LC["Loop-corrected Pose Publisher"]:::topic
    PUB_VIO --> DBoW2
    DBoW2 --> PGOpt
    PGOpt --> PUB_LC
    Configs -.-> DBoW2
  end

  %% GLOBAL FUSION
  subgraph "global_fusion (global_fusion_node)"
    style global_fusion fill:#F8F0FC,stroke:#805AD5
    GPS["GPS Reader"]:::compute
    GOpt["Global Optimizer\n(GeographicLib)"]:::compute
    PUB_GPS["Global Pose Publisher"]:::topic
    GPS --> GOpt
    PUB_VIO --> GOpt
    GOpt --> PUB_GPS
    Configs -.-> GPS
  end

  %% VISUALIZATION
  subgraph "Visualization"
    style Visualization fill:#FEF3F2,stroke:#E53E3E
    RViz["RViz"]:::visual
    PUB_VIO --> RViz
    PUB_LC --> RViz
    PUB_GPS --> RViz
  end

  %% CONFIG & DOCKER
  subgraph "Configuration"
    style Configuration fill:#F0FFF4,stroke:#38A169
    Configs["config/*.yaml"]:::config
  end

  subgraph "Docker Container"
    style Docker fill:#EDF2F7,stroke:#718096
    Docker["Docker"]:::docker
    Docker --> vins_estimator
    Docker --> loop_fusion
    Docker --> global_fusion
  end

  %% Click Events
  click CamModels "https://github.com/hkust-aerial-robotics/vins-fusion/tree/master/camera_models/src"
  click Configs "https://github.com/hkust-aerial-robotics/vins-fusion/tree/master/config/"
  click Docker "https://github.com/hkust-aerial-robotics/vins-fusion/tree/master/docker/Dockerfile"
  click RViz "https://github.com/hkust-aerial-robotics/vins-fusion/blob/master/vins_estimator/launch/vins_rviz.launch"
  click vins_estimator "https://github.com/hkust-aerial-robotics/vins-fusion/blob/master/vins_estimator/src/rosNodeTest.cpp"
  click FT "https://github.com/hkust-aerial-robotics/vins-fusion/blob/master/vins_estimator/src/featureTracker/feature_tracker.cpp"
  click EST "https://github.com/hkust-aerial-robotics/vins-fusion/blob/master/vins_estimator/src/estimator/estimator.cpp"
  click CERES "https://github.com/hkust-aerial-robotics/vins-fusion/blob/master/vins_estimator/CMakeLists.txt"
  click DBoW2 "https://github.com/hkust-aerial-robotics/vins-fusion/blob/master/loop_fusion/src/ThirdParty/DBoW/DBoW2.h"
  click loop_fusion "https://github.com/hkust-aerial-robotics/vins-fusion/blob/master/loop_fusion/src/pose_graph_node.cpp"
  click PGOpt "https://github.com/hkust-aerial-robotics/vins-fusion/blob/master/loop_fusion/src/pose_graph.cpp"
  click global_fusion "https://github.com/hkust-aerial-robotics/vins-fusion/blob/master/global_fusion/src/globalOptNode.cpp"
  click GOpt "https://github.com/hkust-aerial-robotics/vins-fusion/tree/master/global_fusion/ThirdParty/GeographicLib"

  %% Styles
  classDef sensor fill:#BEE3F8,stroke:#3182CE
  classDef topic fill:#C6F6D5,stroke:#2F855A,stroke-dasharray: 5 5
  classDef compute fill:#FEEBC8,stroke:#DD6B20
  classDef visual fill:#FED7D7,stroke:#E53E3E
  classDef config fill:#ECFCCB,stroke:#38A169
  classDef docker fill:#E2E8F0,stroke:#718096
```
