# rpng/mins architecture

> Architecture diagram of the GitHub repository rpng/mins, 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/rpng/mins
- Repository: https://github.com/rpng/mins

## Overview

##### Project Type and Purpose
- MINS is a ROS-based, C++ multisensor fusion system for inertial navigation.
- It ingests IMU, wheel odometry, camera, GNSS, LiDAR (and optionally VICON or loop-closure) data, runs a tightly-coupled filter to estimate pose, and supports simulation and offline evaluation.

##### High-Level File Structure
- mins/: core catkin package
- config/ – YAML configs for datasets and sensors
- launch/ – ROS launch files (simulation, rosbag replay, subscription)
- src/ – modules broken into:
· core (ROS wrappers & SystemManager)
· init (sensor initializers)
· options (parsing per-sensor options)
· sim (Simulator & visualizer)
· state (state propagation & representation)
· update (sensor-specific update plugins)
· utils (logging, timing, helper routines)
· run_*.cpp (entry points: run_bag, run_simulation, run_subscribe)
- mins_data/: sample datasets, ground truths, floorplans
- mins_eval/: offline evaluation tools (consistency, accuracy, timing)
- thirdparty/: bundled libraries (OpenVINS core & eval, libnabo, libpointmatcher/ikd-tree)
- Top-level: CMakeLists.txt, Dockerfiles, GitHub CI workflow

##### Readme-Inferred Architecture
- At runtime MINS launches one of three ROS nodes:
a) Simulation node (Simulator → publishes synthetic sensor topics)
b) ROS-bag replay node (reads bag → republishes topics)
c) Subscription node (subscribes existing topics)
- All feed into a central SystemManager via ROSSubscriber.
- SystemManager drives a filter that alternates:
- Propagator (integrates IMU on manifold)
- Updaters (camera, GNSS, LiDAR, wheel, VICON plugins)
- State estimates are published via ROSPublisher.
- Evaluation modules (mins_eval) ingest both published estimate and ground truth for offline plots.

##### Main Components
a. Data Sources
– Real sensors (IMU, wheel, camera, GNSS, LiDAR, VICON) via ROS topics
– Simulation engine (Simulator in mins/src/sim)
– ROS-bag replay
b. Middleware
– ROS 1 master & topic bus
– ROSSubscriber / ROSPublisher (mins/src/core)
c. Core Estimator
– SystemManager (mins/src/core)
– State Propagator (mins/src/state)
– Sensor Updaters (mins/src/update/{imu,cam,gps,lidar,wheel,vicon})
– Initializer modules (mins/src/init)
– Options/config loader (mins/src/options)
d. Utilities
– Logging & timing (mins/src/utils)
e. Offline Evaluation
– mins_eval package: alignment, error plots, timing comparisons
f. Third-Party Libraries
– OpenVINS core & eval
– libnabo / ikd-Tree / libpointmatcher for LiDAR ICP

##### Relationships and Data Flow
- Within SystemManager: loop of Propagate → Update(plugin) → Publish
- Options feed into both Initializer and SystemManager at startup
- Simulation node sits parallel to real data sources, publishing onto same topics
- Evaluation tools consume topics/log files offline

##### Architectural Patterns & Principles
- ROS node/component-based modularity
- Plugin style for each sensor updater
- High-order state interpolation on manifold
- Dynamic cloning of states for multiple sensors
- Separation of real vs. simulated data paths

##### Technologies & Dependencies
- ROS 1 (Melodic/Noetic), catkin, CMake
- C++17, Eigen, YAML configs
- Docker for CI images
- Third-party libs (OpenVINS, ikd-Tree, libpointmatcher)

##### Essential Elements to Capture
– Clear component labels (with source directories)
– Arrowed data flows (sensor → estimator → output → evaluation)
– Startup/config dependencies (Options, Initializer)
– Distinct runtime nodes (run_simulation, run_bag, run_subscribe)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Sources
    subgraph "Data Sources"
        SimulationNode["Simulation Node"]:::rosnode
        RosbagNode["ROS-bag Replay Node"]:::rosnode
        SubscribeNode["Subscription Node"]:::rosnode
        RealSensors["Real Sensors\n(IMU, Wheel, Camera,\nGNSS, LiDAR, VICON)"]:::datasrc
    end

    %% ROS Middleware
    subgraph "ROS Middleware"
        ROSMaster["ROS 1 Master & Topic Bus"]:::middleware
        ROSSubscriber["ROSSubscriber"]:::middleware
        ROSPublisher["ROSPublisher"]:::middleware
    end

    %% Core Estimator
    subgraph "Core Estimator"
        OptionsLoader["Options & Config Loader"]:::core
        Initializer["Initializer Modules"]:::core
        SystemManager["SystemManager"]:::core
        subgraph "Propagation & Update Loop"
            Propagator["Propagator"]:::core
            State["State"]:::core
            StateHelper["State Helper"]:::core
            subgraph "Sensor Updaters"
                Cam["Camera Updater"]:::plugin
                GPS["GPS Updater"]:::plugin
                LIDAR["LiDAR Updater"]:::plugin
                VICON["VICON Updater"]:::plugin
                Wheel["Wheel Updater"]:::plugin
                Stats["Updater Statistics"]:::plugin
            end
            Publisher["Publish Estimates"]:::middleware
        end
    end

    %% Utilities
    subgraph "Utilities"
        Logging["Logging & Timing"]:::utility
        Helpers["Misc Helpers"]:::utility
    end

    %% Third-Party
    subgraph "Third-Party Libraries"
        OpenVINS["OpenVINS"]:::thirdparty
        Nabo["libnabo"]:::thirdparty
        PM["libpointmatcher/ikd-tree"]:::thirdparty
    end

    %% Offline Evaluation
    subgraph "Offline Evaluation"
        EvalTools["Evaluation Tools"]:::eval
    end

    %% Data Flow
    SimulationNode -->|publishes topics| ROSMaster
    RosbagNode -->|replays topics| ROSMaster
    SubscribeNode -->|forwards topics| ROSMaster
    RealSensors -->|live topics| ROSMaster

    ROSMaster --> ROSSubscriber
    ROSSubscriber --> SystemManager

    OptionsLoader --> Initializer
    OptionsLoader --> SystemManager
    Initializer --> SystemManager

    SystemManager --> Propagator
    Propagator --> State
    State --> StateHelper
    StateHelper --> SystemManager

    SystemManager --> Publisher
    Publisher --> ROSMaster
    ROSMaster --> EvalTools

    Propagator --> Cam
    Propagator --> GPS
    Propagator --> LIDAR
    Propagator --> VICON
    Propagator --> Wheel
    Propagator --> Stats

    SystemManager --> Logging
    SystemManager --> Helpers
    Cam --> OpenVINS
    GPS --> OpenVINS
    LIDAR --> Nabo
    LIDAR --> PM

    %% Click Events
    click SimulationNode "https://github.com/rpng/mins/blob/master/mins/src/run_simulation.cpp"
    click SimulationNode "https://github.com/rpng/mins/tree/master/mins/src/sim"
    click RosbagNode "https://github.com/rpng/mins/blob/master/mins/src/run_bag.cpp"
    click RosbagNode "https://github.com/rpng/mins/blob/master/mins/launch/rosbag.launch"
    click SubscribeNode "https://github.com/rpng/mins/blob/master/mins/src/run_subscribe.cpp"
    click SubscribeNode "https://github.com/rpng/mins/blob/master/mins/launch/subscribe.launch"
    click ROSSubscriber "https://github.com/rpng/mins/blob/master/mins/src/core/ROSSubscriber.cpp"
    click ROSPublisher "https://github.com/rpng/mins/blob/master/mins/src/core/ROSPublisher.cpp"
    click SystemManager "https://github.com/rpng/mins/blob/master/mins/src/core/SystemManager.cpp"
    click Propagator "https://github.com/rpng/mins/blob/master/mins/src/state/Propagator.cpp"
    click State "https://github.com/rpng/mins/blob/master/mins/src/state/State.cpp"
    click StateHelper "https://github.com/rpng/mins/blob/master/mins/src/state/StateHelper.cpp"
    click Cam "https://github.com/rpng/mins/blob/master/mins/src/update/cam/UpdaterCamera.cpp"
    click GPS "https://github.com/rpng/mins/blob/master/mins/src/update/gps/UpdaterGPS.cpp"
    click LIDAR "https://github.com/rpng/mins/blob/master/mins/src/update/lidar/UpdaterLidar.cpp"
    click VICON "https://github.com/rpng/mins/blob/master/mins/src/update/vicon/UpdaterVicon.cpp"
    click Wheel "https://github.com/rpng/mins/blob/master/mins/src/update/wheel/UpdaterWheel.cpp"
    click Stats "https://github.com/rpng/mins/blob/master/mins/src/update/UpdaterStatistics.cpp"
    click Initializer "https://github.com/rpng/mins/blob/master/mins/src/init/Initializer.cpp"
    click OptionsLoader "https://github.com/rpng/mins/blob/master/mins/src/options/Options.h"
    click Logging "https://github.com/rpng/mins/blob/master/mins/src/utils/Print_Logger.cpp"
    click Helpers "https://github.com/rpng/mins/blob/master/mins/src/utils/Jabdongsani.cpp"
    click EvalTools "https://github.com/rpng/mins/blob/master/mins_eval/src/functions/ErrorPlot.cpp"
    click OpenVINS "https://github.com/rpng/mins/tree/master/thirdparty/open_vins/ov_core"

    %% Styles
    classDef rosnode fill:#CFE2F3,stroke:#6C8EBF,color:#0B2240;
    classDef datasrc fill:#E2EFDA,stroke:#6AA84F,color:#274E13;
    classDef middleware fill:#FFF2CC,stroke:#BF9000,color:#7F6000;
    classDef core fill:#FCE5CD,stroke:#E69138,color:#633000;
    classDef plugin fill:#D9D2E9,stroke:#8E7CC3,color:#4C1130;
    classDef utility fill:#D9D9D9,stroke:#7F7F7F,color:#1F1F1F;
    classDef thirdparty fill:#F4CCCC,stroke:#CC4125,color:#6E0202;
    classDef eval fill:#FFF2CC,stroke:#FFD966,color:#7F6000;
```
