# vladyslavusenko/basalt architecture

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

- Interactive diagram: https://gitdiagram.com/vladyslavusenko/basalt
- Repository: https://github.com/vladyslavusenko/basalt

## Overview

##### Project Type and Purpose
- This project is a research-oriented visual-inertial odometry and mapping system that includes utilities for camera/IMU/mocap calibration, visual odometry (with and without inertial data), and simulation tools. It is implemented primarily in C++ (using CMake for builds) with a supplementary Python interface for experiments and evaluation.
- The README also mentions a header-only library version (basalt-headers) that contains several reusable components.

##### Key Architectural Components to Highlight
a. Calibration Tools:
- Modules under directories such as “include/basalt/calibration” and “src/calibration” implement camera, IMU, and motion capture calibration.
- They include files for camera model calibration (e.g., aprilgrid, vignette correction) and calibration helpers.

b. Visual-Inertial Odometry (VIO) and Visual Odometry (VO):
- The core VIO pipeline is in “include/basalt/vi_estimator” and “src/vi_estimator” for estimation and optimization.
- The VO parts (without IMU data) are supported as separate routines (e.g., src/vo.cpp and dataset I/O modules).

c. Data Input/Output and Dataset Handling:
- “include/basalt/io” and “src/io” modules provide functionality to read datasets such as Euroc, KITTI, TUMVI, and UZH.
- These modules abstract the dataset interfaces and provide sensor data (camera images, IMU measurements, etc.) to the pipelines.

d. Optimization and Linearization Modules:
- Components in “include/basalt/linearization” and “src/linearization” implement different block-permutation linearizations, such as square-root and QR-based formulations as well as marginalization, reflecting the optimization backbone.

e. Mapping and Simulation:
- The “src/mapper”, “src/mapper_sim”, and “src/mapper_sim_naive” components are responsible for map building and simulation of the estimation processes.
- Simulation modules also exist to test various components in controlled settings.

f. Device Support:
- Specific modules (e.g., “include/basalt/device/rs_t265.h” and “src/device/rs_t265.cpp”) provide support for devices such as the Intel RealSense T265.

g. External Integrations and Dependencies:
- The project uses several third-party libraries, as evidenced in the “thirdparty” folder (e.g., Pangolin for visualization, apriltag for tag detection, Eigen, OpenGV, TBB, ROS, and even CLI11 for command-line parsing).
- The build and configuration system (CMake, .clang-format, Dockerfiles) indicate an emphasis on cross-platform compatibility and reproducible builds.

h. Evaluation and Batch Processing:
- Python scripts under “python/basalt” and shell scripts under “scripts/batch” facilitate batch evaluations and experiment management.
- There are dedicated tools for generating reports/latex outputs.

##### Relationships and Interactions
- From sensor/dataset input (Layer 1) to calibration modules (Layer 2).
- Calibration outputs feed into both VO and VIO pipelines (Layer 3).
- Within the core processing, illustrate the iterative loop between the pose estimation modules and the optimization backends (linearization and marginalization).
- Out feedback loops common in optimization (e.g., sliding window BA and recurrent marginalization).
- Integration with third-party libraries and external submodules, emphasizing dependencies (e.g., drawing borders or labels that show “external libs: Pangolin, Eigen, etc.”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layer 1: Input & Data Sources
    subgraph "Layer 1: Input & Data Sources"
        Sensors["Sensors: Camera, IMU, Mocap"]:::input
        IOHeaders["Dataset I/O (Headers)"]:::io
        IOSources["Dataset I/O (Sources)"]:::io
    end

    Sensors --> IOHeaders
    Sensors --> IOSources

    %% Layer 2: Calibration & Initialization
    subgraph "Layer 2: Calibration & Initialization"
        CalibHeaders["Calibration Tools (Headers)"]:::calibration
        CalibSources["Calibration Tools (Sources)"]:::calibration
    end

    IOHeaders --> CalibHeaders
    IOSources --> CalibHeaders
    IOHeaders --> CalibSources
    IOSources --> CalibSources

    %% Layer 3: Core Processing
    subgraph "Layer 3: Core Processing"
        %% Visual-Inertial Odometry Pipeline
        subgraph "Visual-Inertial Odometry Pipeline"
            VIOHeaders["VIO Estimator (Headers)"]:::vio
            VIOSources["VIO Estimator (Sources)"]:::vio
            LinearHeaders["Linearization (Headers)"]:::optimization
            LinearSources["Linearization (Sources)"]:::optimization
            OptHeaders["Optimization (Headers)"]:::optimization
            MappingSim["Mapping & Simulation"]:::mapping
        end

        %% Visual Odometry Pipeline
        subgraph "Visual Odometry Pipeline"
            VOHeader["VO Routines (Header)"]:::vo
            VOSource["VO Routines (Source)"]:::vo
            VOHeader --> VOSource
        end

        DeviceHeaders["Device Support (Headers)"]:::device
        DeviceSources["Device Support (Sources)"]:::device
    end

    %% Data flow among Layers
    CalibHeaders --> VIOHeaders
    CalibSources --> VIOHeaders
    CalibHeaders --> VOHeader
    CalibSources --> VOHeader

    Sensors --> DeviceHeaders
    Sensors --> DeviceSources
    DeviceHeaders --> VIOSources
    DeviceSources --> VIOSources

    VIOHeaders --> VIOSources
    VIOSources --> LinearHeaders
    LinearHeaders --> LinearSources
    LinearSources --> OptHeaders
    OptHeaders --> MappingSim
    VIOHeaders --> MappingSim
    %% Feedback loop from optimization back to VIO
    LinearSources -- "feedback" --> VIOSources

    %% Layer 4: Output & Visualization
    subgraph "Layer 4: Output & Visualization"
        Visualization["Visualization (Pangolin)"]:::visualization
        EvalScripts["Python Evaluation Scripts"]:::evaluation
        BatchScripts["Batch & Eval Scripts"]:::evaluation
    end

    MappingSim --> Visualization
    VOSource --> Visualization
    MappingSim --> EvalScripts
    MappingSim --> BatchScripts

    %% External Integrations
    External["Third-party & Build Config"]:::external
    Sensors --- External
    CalibSources --- External
    VIOSources --- External
    LinearSources --- External

    %% Click Events for Component Mapping
    click CalibHeaders "https://github.com/vladyslavusenko/basalt/tree/master/include/basalt/calibration"
    click CalibSources "https://github.com/vladyslavusenko/basalt/tree/master/src/calibration"
    click IOHeaders "https://github.com/vladyslavusenko/basalt/tree/master/include/basalt/io"
    click IOSources "https://github.com/vladyslavusenko/basalt/tree/master/src/io"
    click VIOHeaders "https://github.com/vladyslavusenko/basalt/tree/master/include/basalt/vi_estimator"
    click VIOSources "https://github.com/vladyslavusenko/basalt/tree/master/src/vi_estimator"
    click VOHeader "https://github.com/vladyslavusenko/basalt/blob/master/include/basalt/vi_estimator/sqrt_keypoint_vo.h"
    click VOSource "https://github.com/vladyslavusenko/basalt/blob/master/src/vi_estimator/sqrt_keypoint_vo.cpp"
    click LinearHeaders "https://github.com/vladyslavusenko/basalt/tree/master/include/basalt/linearization"
    click LinearSources "https://github.com/vladyslavusenko/basalt/tree/master/src/linearization"
    click OptHeaders "https://github.com/vladyslavusenko/basalt/tree/master/include/basalt/optimization"
    click MappingSim "https://github.com/vladyslavusenko/basalt/blob/master/src/mapper.cpp"
    click DeviceHeaders "https://github.com/vladyslavusenko/basalt/tree/master/include/basalt/device"
    click DeviceSources "https://github.com/vladyslavusenko/basalt/tree/master/src/device"
    click External "https://github.com/vladyslavusenko/basalt/tree/master/thirdparty"
    click EvalScripts "https://github.com/vladyslavusenko/basalt/tree/master/python/basalt"
    click BatchScripts "https://github.com/vladyslavusenko/basalt/tree/master/scripts/batch"

    %% Class Definitions for Colors
    classDef input fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef io fill:#aed6f1,stroke:#333,stroke-width:2px;
    classDef calibration fill:#a9dfbf,stroke:#333,stroke-width:2px;
    classDef vio fill:#f7dc6f,stroke:#333,stroke-width:2px;
    classDef optimization fill:#82e0aa,stroke:#333,stroke-width:2px;
    classDef mapping fill:#f5b7b1,stroke:#333,stroke-width:2px;
    classDef vo fill:#d6eaf8,stroke:#333,stroke-width:2px;
    classDef device fill:#d7bde2,stroke:#333,stroke-width:2px;
    classDef visualization fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef evaluation fill:#fadbd8,stroke:#333,stroke-width:2px;
    classDef external fill:#d5dbdb,stroke:#333,stroke-width:2px;
```
