# ethz-asl/okvis architecture

> Architecture diagram of the GitHub repository ethz-asl/okvis, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ethz-asl/okvis
- Repository: https://github.com/ethz-asl/okvis
- Video tour (about a minute): https://gitdiagram.com/ethz-asl/okvis/video

## Overview

OKVIS is a keyframe-based visual-inertial SLAM/odometry system. Its principal workflow ingests timestamped camera and IMU data, synchronizes and processes frames, tracks features and initializes landmarks, then optimizes a sliding-window state and reports poses, velocity, and IMU biases. The README also documents configurable camera/IMU calibration and a synchronous dataset demo. The excerpts expose parts of orchestration and optimization; links for unsampled subsystems are limited to the documented workflow.

Main entry points: [`okvis_multisensor_processing/src/ThreadedKFVio.cpp`](https://github.com/ethz-asl/okvis/blob/master/okvis_multisensor_processing/src/ThreadedKFVio.cpp) (Threaded VIO), [`okvis_ceres/src/Estimator.cpp`](https://github.com/ethz-asl/okvis/blob/master/okvis_ceres/src/Estimator.cpp) (Window estimator), [`okvis_apps/src/okvis_app_synchronous.cpp`](https://github.com/ethz-asl/okvis/blob/master/okvis_apps/src/okvis_app_synchronous.cpp) (Synchronous demo), [`okvis_frontend/src/Frontend.cpp`](https://github.com/ethz-asl/okvis/blob/master/okvis_frontend/src/Frontend.cpp) (Feature frontend)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Inputs and calibration"]
  node_parameters["Parameter reader"]
  node_camera["Camera models<br/>[NCameraSystem.hpp]"]
end

subgraph group_vision["Visual frontend"]
  node_frames["Frame containers<br/>[MultiFrame.hpp]"]
  node_frontend["Feature frontend<br/>[Frontend.cpp]"]
  node_matcher["Dense matcher<br/>[DenseMatcher.cpp]"]
  node_triangulation["Stereo triangulation"]
end

subgraph group_backend["State estimation"]
  node_estimator["Window estimator<br/>[Estimator.cpp]"]
  node_map["Optimization map<br/>[Map.cpp]"]
  node_factors["Measurement errors<br/>[ImuError.hpp]"]
  node_marginalization["Window marginalization"]
end

subgraph group_runtime["Processing and outputs"]
  node_app["Synchronous demo"]
  node_vio["VIO interface<br/>[VioInterface.hpp]"]
  node_threaded["Threaded VIO<br/>[ThreadedKFVio.cpp]"]
  node_sync["Frame synchronizer"]
  node_imu_sync["IMU synchronizer"]
  node_visualizer["VIO visualizer<br/>[VioVisualizer.cpp]"]
end

node_dataset[("Sensor dataset")]
node_config["Estimator config"]
node_state["Pose and motion state"]

node_dataset -->|"supplies measurements"| node_app
node_config -->|"provides settings"| node_parameters
node_app -->|"loads config"| node_parameters
node_app -->|"starts processing"| node_vio
node_parameters -->|"configures cameras"| node_camera
node_parameters -->|"provides parameters"| node_vio
node_vio -->|"delegates processing"| node_threaded
node_app -->|"submits sensor data"| node_threaded
node_threaded -->|"synchronizes frames"| node_sync
node_threaded -->|"synchronizes IMU"| node_imu_sync
node_sync -->|"forms multiframes"| node_frames
node_threaded -->|"processes frames"| node_frontend
node_frontend -->|"matches features"| node_matcher
node_frontend -->|"initializes landmarks"| node_triangulation
node_threaded -->|"runs optimization"| node_estimator
node_frontend -->|"updates visual states"| node_estimator
node_estimator -->|"maintains optimization map"| node_map
node_estimator -->|"adds residuals"| node_factors
node_estimator -->|"marginalizes window"| node_marginalization
node_estimator -->|"reports estimates"| node_state
node_threaded -->|"publishes visualization"| node_visualizer
node_visualizer -->|"displays estimates"| node_state
node_state -->|"returns via callbacks"| node_app

click node_app "https://github.com/ethz-asl/okvis/blob/master/okvis_apps/src/okvis_app_synchronous.cpp"
click node_parameters "https://github.com/ethz-asl/okvis/blob/master/okvis_common/src/VioParametersReader.cpp"
click node_camera "https://github.com/ethz-asl/okvis/blob/master/okvis_cv/include/okvis/cameras/NCameraSystem.hpp"
click node_vio "https://github.com/ethz-asl/okvis/blob/master/okvis_common/include/okvis/VioInterface.hpp"
click node_threaded "https://github.com/ethz-asl/okvis/blob/master/okvis_multisensor_processing/src/ThreadedKFVio.cpp"
click node_sync "https://github.com/ethz-asl/okvis/blob/master/okvis_multisensor_processing/src/FrameSynchronizer.cpp"
click node_imu_sync "https://github.com/ethz-asl/okvis/blob/master/okvis_multisensor_processing/src/ImuFrameSynchronizer.cpp"
click node_frames "https://github.com/ethz-asl/okvis/blob/master/okvis_cv/include/okvis/MultiFrame.hpp"
click node_frontend "https://github.com/ethz-asl/okvis/blob/master/okvis_frontend/src/Frontend.cpp"
click node_matcher "https://github.com/ethz-asl/okvis/blob/master/okvis_matcher/src/DenseMatcher.cpp"
click node_triangulation "https://github.com/ethz-asl/okvis/blob/master/okvis_frontend/src/ProbabilisticStereoTriangulator.cpp"
click node_estimator "https://github.com/ethz-asl/okvis/blob/master/okvis_ceres/src/Estimator.cpp"
click node_map "https://github.com/ethz-asl/okvis/blob/master/okvis_ceres/src/Map.cpp"
click node_factors "https://github.com/ethz-asl/okvis/blob/master/okvis_ceres/include/okvis/ceres/ImuError.hpp"
click node_marginalization "https://github.com/ethz-asl/okvis/blob/master/okvis_ceres/src/MarginalizationError.cpp"
click node_visualizer "https://github.com/ethz-asl/okvis/blob/master/okvis_multisensor_processing/src/VioVisualizer.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_parameters,node_camera toneBlue
class node_frames,node_frontend,node_matcher,node_triangulation,node_dataset toneAmber
class node_estimator,node_map,node_factors,node_marginalization toneMint
class node_app,node_vio,node_threaded,node_sync,node_imu_sync,node_visualizer toneRose
class node_config,node_state toneIndigo
```

## Components

### Inputs and calibration

- [Parameter reader](https://github.com/ethz-asl/okvis/blob/master/okvis_common/src/VioParametersReader.cpp): `okvis_common/src/VioParametersReader.cpp`
- [Camera models](https://github.com/ethz-asl/okvis/blob/master/okvis_cv/include/okvis/cameras/NCameraSystem.hpp): `okvis_cv/include/okvis/cameras/NCameraSystem.hpp`

### Visual frontend

- [Frame containers](https://github.com/ethz-asl/okvis/blob/master/okvis_cv/include/okvis/MultiFrame.hpp): `okvis_cv/include/okvis/MultiFrame.hpp`
- [Feature frontend](https://github.com/ethz-asl/okvis/blob/master/okvis_frontend/src/Frontend.cpp): `okvis_frontend/src/Frontend.cpp`
- [Dense matcher](https://github.com/ethz-asl/okvis/blob/master/okvis_matcher/src/DenseMatcher.cpp): `okvis_matcher/src/DenseMatcher.cpp`
- [Stereo triangulation](https://github.com/ethz-asl/okvis/blob/master/okvis_frontend/src/ProbabilisticStereoTriangulator.cpp): `okvis_frontend/src/ProbabilisticStereoTriangulator.cpp`

### State estimation

- [Window estimator](https://github.com/ethz-asl/okvis/blob/master/okvis_ceres/src/Estimator.cpp): `okvis_ceres/src/Estimator.cpp`
- [Optimization map](https://github.com/ethz-asl/okvis/blob/master/okvis_ceres/src/Map.cpp): `okvis_ceres/src/Map.cpp`
- [Measurement errors](https://github.com/ethz-asl/okvis/blob/master/okvis_ceres/include/okvis/ceres/ImuError.hpp): `okvis_ceres/include/okvis/ceres/ImuError.hpp`
- [Window marginalization](https://github.com/ethz-asl/okvis/blob/master/okvis_ceres/src/MarginalizationError.cpp): `okvis_ceres/src/MarginalizationError.cpp`

### Processing and outputs

- [Synchronous demo](https://github.com/ethz-asl/okvis/blob/master/okvis_apps/src/okvis_app_synchronous.cpp): `okvis_apps/src/okvis_app_synchronous.cpp`
- [VIO interface](https://github.com/ethz-asl/okvis/blob/master/okvis_common/include/okvis/VioInterface.hpp): `okvis_common/include/okvis/VioInterface.hpp`
- [Threaded VIO](https://github.com/ethz-asl/okvis/blob/master/okvis_multisensor_processing/src/ThreadedKFVio.cpp): `okvis_multisensor_processing/src/ThreadedKFVio.cpp`
- [Frame synchronizer](https://github.com/ethz-asl/okvis/blob/master/okvis_multisensor_processing/src/FrameSynchronizer.cpp): `okvis_multisensor_processing/src/FrameSynchronizer.cpp`
- [IMU synchronizer](https://github.com/ethz-asl/okvis/blob/master/okvis_multisensor_processing/src/ImuFrameSynchronizer.cpp): `okvis_multisensor_processing/src/ImuFrameSynchronizer.cpp`
- [VIO visualizer](https://github.com/ethz-asl/okvis/blob/master/okvis_multisensor_processing/src/VioVisualizer.cpp): `okvis_multisensor_processing/src/VioVisualizer.cpp`

### Other components

- **Sensor dataset**
- **Estimator config**
- **Pose and motion state**

## Connections

- Sensor dataset → Synchronous demo: supplies measurements
- Estimator config → Parameter reader: provides settings
- Synchronous demo → Parameter reader: loads config
- Synchronous demo → VIO interface: starts processing
- Parameter reader → Camera models: configures cameras
- Parameter reader → VIO interface: provides parameters
- VIO interface → Threaded VIO: delegates processing
- Synchronous demo → Threaded VIO: submits sensor data
- Threaded VIO → Frame synchronizer: synchronizes frames
- Threaded VIO → IMU synchronizer: synchronizes IMU
- Frame synchronizer → Frame containers: forms multiframes
- Threaded VIO → Feature frontend: processes frames
- Feature frontend → Dense matcher: matches features
- Feature frontend → Stereo triangulation: initializes landmarks
- Threaded VIO → Window estimator: runs optimization
- Feature frontend → Window estimator: updates visual states
- Window estimator → Optimization map: maintains optimization map
- Window estimator → Measurement errors: adds residuals
- Window estimator → Window marginalization: marginalizes window
- Window estimator → Pose and motion state: reports estimates
- Threaded VIO → VIO visualizer: publishes visualization
- VIO visualizer → Pose and motion state: displays estimates
- Pose and motion state → Synchronous demo: returns via callbacks
