# mbrossar/rins-w architecture

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

- Interactive diagram: https://gitdiagram.com/mbrossar/rins-w
- Repository: https://github.com/mbrossar/rins-w

## Overview

##### Project type and purpose
- This is an open-source scientific/robotics tool (not a web app or full-stack system). It implements RINS-W: a real-time inertial navigation system on wheeled robots. It has two main functions:
- Offline training of a deep neural network to detect zero‐velocity events from IMU data
- Online/inference fusion of IMU measurements and zero‐velocity detections via an iterated extended Kalman filter (IEKF)

##### File structure
- Top‐level directories and files:
- data/Kaist – raw IMU datasets (pickled)
- results/Kaist – trained model checkpoints, hyperparameters, weights
- src/ – library modules: dataset.py, iekf.py, learning.py, lie_algebra.py, losses.py, networks.py, utils.py
- main_Kaist.py & main_Kalman_Kaist.py – entrypoints for training & testing/inference
- dataset.py, iekf.py, etc. mirrored at root—likely quick scripts or legacy
- requirements.txt – dependency list (PyTorch, numpy, etc.)

##### README for additional insights
- Core components:
- “adapter block” = deep neural network (dilated convolutions + CNNs)
- Kalman filter that uses zero‐velocity detector outputs and pseudo‐measurements (no lateral slip, zero vertical vel.)
- Tech stack: Python 3.5+, PyTorch 1.5

##### Detailed component breakdown
- Data Layer (cyan):
- data/Kaist/*.p → src/dataset.py → training engine
- Training Engine (orange):
- src/learning.py integrates dataset, networks, losses → runs backprop → writes results/Kaist/YYYY…
- results/Kaist/.../weights.pt, net_params.yaml, hparams.yaml
- Inference Engine (purple):
- main_Kalman_Kaist.py loads IMU feed & model → src/iekf.py + src/utils.py → publishes state estimates
- Lie‐Algebra & Filter Core (gray):
- src/lie_algebra.py + src/iekf.py hold mathematical routines for propagation & update

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        RawData["Raw IMU Datasets (data/Kaist/*.p)"]:::artifacts
        DatasetModule["Dataset Preprocessing Module\n(src/dataset.py)"]:::data
    end

    %% Training Pipeline
    subgraph "Training Pipeline"
        TrainEntry["Training Entrypoint\n(main_Kaist.py)"]:::training
        Learning["Training Engine\n(src/learning.py)"]:::training
        Networks["Neural Network Definitions\n(src/networks.py)"]:::training
        Losses["Loss Functions\n(src/losses.py)"]:::training
        Utils["Utility Routines\n(src/utils.py)"]:::core
    end

    %% Model Artifacts
    ModelArtifacts["Model Artifacts\n(results/Kaist/<timestamp>/)"]:::artifacts

    %% Inference Pipeline
    subgraph "Inference Pipeline"
        IMUStream["IMU Input Stream"]:::inference
        InferenceEntry["Inference Entrypoint\n(main_Kalman_Kaist.py)"]:::inference
        ZeroVelDetector["Zero-Velocity Detector\n(PyTorch Model)"]:::inference
        PseudoMeas["Pseudo-Measurement Generator"]:::inference
        IEKF["Iterated Extended Kalman Filter\n(src/iekf.py)"]:::core
        LieAlgebra["Lie-Algebra Ops\n(src/lie_algebra.py)"]:::core
        StateEst["State Estimator\n(Position, Orientation, Velocity)"]:::inference
        ResultsLog["Results Logging\n(results/)"]:::artifacts
    end

    %% Data → Training
    RawData -->|loads| DatasetModule
    DatasetModule -->|feeds| TrainEntry
    TrainEntry -->|uses| Learning
    Learning -->|trains| Networks
    Learning -->|uses| Losses
    Learning -->|uses| Utils
    Learning -->|outputs| ModelArtifacts

    %% Training → Inference
    ModelArtifacts -->|provides weights| InferenceEntry

    %% Inference Flow
    IMUStream -->|stream| InferenceEntry
    InferenceEntry -->|loads model| ZeroVelDetector
    ZeroVelDetector -->|detections| PseudoMeas
    PseudoMeas -->|pseudo measurements| IEKF
    IEKF -->|propagate/update| StateEst
    StateEst -->|logs| ResultsLog
    InferenceEntry -->|uses| Utils
    IEKF -->|uses| LieAlgebra

    %% Click Events
    click RawData "https://github.com/mbrossar/rins-w/tree/master/data/Kaist/"
    click DatasetModule "https://github.com/mbrossar/rins-w/blob/master/src/dataset.py"
    click TrainEntry "https://github.com/mbrossar/rins-w/blob/master/main_Kaist.py"
    click Learning "https://github.com/mbrossar/rins-w/blob/master/src/learning.py"
    click Networks "https://github.com/mbrossar/rins-w/blob/master/src/networks.py"
    click Losses "https://github.com/mbrossar/rins-w/blob/master/src/losses.py"
    click Utils "https://github.com/mbrossar/rins-w/blob/master/src/utils.py"
    click ModelArtifacts "https://github.com/mbrossar/rins-w/blob/master/results/Kaist/<timestamp>/weights.pt"
    click InferenceEntry "https://github.com/mbrossar/rins-w/blob/master/main_Kalman_Kaist.py"
    click ZeroVelDetector "https://github.com/mbrossar/rins-w/blob/master/src/networks.py"
    click IEKF "https://github.com/mbrossar/rins-w/blob/master/src/iekf.py"
    click LieAlgebra "https://github.com/mbrossar/rins-w/blob/master/src/lie_algebra.py"

    %% Styles
    classDef data fill:#E0FFFF,stroke:#000
    classDef training fill:#FFE4B5,stroke:#000
    classDef artifacts fill:#98FB98,stroke:#000,stroke-dasharray: 5 5
    classDef inference fill:#D8BFD8,stroke:#000
    classDef core fill:#D3D3D3,stroke:#000
```
