# gongsta/vslam-py architecture

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

- Interactive diagram: https://gitdiagram.com/gongsta/vslam-py
- Repository: https://github.com/gongsta/vslam-py

## Overview

##### Project Type and Purpose
- This is a research-oriented, Python-based Visual Odometry (VO) and Visual SLAM system.
- It supports both monocular and stereo modes and benchmarks against standard datasets (KITTI, TUM).
- It is structured as a collection of scripts for different modes (VO vs. SLAM, monocular vs. stereo) plus core processing modules, helpers, evaluation, and visualization components.

##### High-Level Component Identification
a. Data Input & Dataset Management
- Scripts: main_kitti.py, main_tum.py, main_mono_vo.py, main_stereo_vo.py, main_stereo_slam.py
- Data folders: KITTI_sequence_1/, eval/groundtruth.txt
- Helpers: helpers/play.py, helpers/record_zed.py
b. Core Processing
- vo.py: frame-to-frame odometry (feature detection, matching, PnP)
- slam.py: stereo SLAM pipeline (keyframe selection, local mapping)
- optimizer.py: graph optimization (g2o bindings)
- loop_closure.py: place recognition & global pose‐graph updates
c. Utilities & Support
- utils.py: camera calibration, timestamp management, data structures
- visualization.py: Pangolin (real-time 3D) + Matplotlib fallback
d. Evaluation & Benchmarking
- eval/associate.py, eval/evaluate_ate.py: align estimated vs. ground-truth poses
- results/: logged pose outputs for tracking improvements
e. Third-Party Dependencies
- OpenCV (feature extraction, matching)
- g2o-python (optimizer)
- Pangolin (3D visualization)
- third_party/opencv_vpi (optional hardware acceleration)

##### Relationships & Data Flow
1. Dataset Loader →
2. Frame Preprocessing (undistort, rectify) →
3. Feature Detection & Matching (vo.py) →
4. Pose Estimation
- Monocular VO: PnP + epipolar geometry
- Stereo SLAM: keyframe insertion, local BA
5. Loop Closure (loop_closure.py) → pose-graph updates via optimizer.py
6. Visualization (visualization.py / Pangolin)
7. Logging & Evaluation (save poses → eval/evaluate_ate.py)

##### Architectural Patterns
- Modular pipeline: clear separation of concerns (VO vs. SLAM vs. optimization)
- Data-flow architecture: each major step outputs data for the next stage
- Optional hardware acceleration: plug-in folder for OpenCV VPI
- Script-based entry points: distinct mains for each mode

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data I/O Layer
    subgraph "Data I/O" 
        direction TB
        A1["main_kitti.py"]:::dataio
        A2["main_tum.py"]:::dataio
        A3["main_mono_vo.py"]:::dataio
        A4["main_stereo_vo.py"]:::dataio
        A5["main_stereo_slam.py"]:::dataio
        DF["KITTI_sequence_1/"]:::dataio
        GT["eval/groundtruth.txt"]:::dataio
    end

    %% Preprocessor & Utilities
    subgraph "Preprocessing & Utilities"
        direction TB
        U["utils.py\n(OpenCV, NumPy)"]:::dataio
    end

    %% Core SLAM Pipeline
    subgraph "Core Pipeline" 
        direction TB
        V["vo.py\n(feature detection, PnP)\n(OpenCV)"]:::core
        S["slam.py\n(stereo SLAM)\n(OpenCV)"]:::core
    end

    %% Optimization & Loop Closure
    subgraph "Optimization & Loop Closure"
        direction TB
        L["loop_closure.py\n(place recognition)"]:::optimize
        O["optimizer.py\ng2o-python"]:::optimize
    end

    %% Visualization & Evaluation
    subgraph "Visualization & Evaluation"
        direction TB
        VZ["visualization.py\n(Pangolin, Matplotlib)"]:::viz
        R["results/"]:::viz
        EA["eval/associate.py"]:::viz
        EB["eval/evaluate_ate.py"]:::viz
    end

    %% Helpers & Plugins
    subgraph "Helpers & Plugins"
        direction TB
        H1["helpers/play.py"]:::helper
        H2["helpers/record_zed.py"]:::helper
        PVI["third_party/opencv_vpi"]:::third
    end

    %% Data Flow
    A1 --> DF
    A2 --> DF
    A3 --> DF
    A4 --> DF
    A5 --> DF
    DF --> U
    U --> V
    U --> S
    V --> L
    S --> L
    L --> O
    O --> VZ
    O --> R
    R -.-> EA
    R -.-> EB
    H1 --> DF
    H2 --> DF
    PVI -.-> V
    PVI -.-> S

    %% Click Events
    click A1 "https://github.com/gongsta/vslam-py/blob/main/main_kitti.py"
    click A2 "https://github.com/gongsta/vslam-py/blob/main/main_tum.py"
    click A3 "https://github.com/gongsta/vslam-py/blob/main/main_mono_vo.py"
    click A4 "https://github.com/gongsta/vslam-py/blob/main/main_stereo_vo.py"
    click A5 "https://github.com/gongsta/vslam-py/blob/main/main_stereo_slam.py"
    click DF "https://github.com/gongsta/vslam-py/tree/main/KITTI_sequence_1/"
    click GT "https://github.com/gongsta/vslam-py/blob/main/eval/groundtruth.txt"
    click U "https://github.com/gongsta/vslam-py/blob/main/utils.py"
    click V "https://github.com/gongsta/vslam-py/blob/main/vo.py"
    click S "https://github.com/gongsta/vslam-py/blob/main/slam.py"
    click L "https://github.com/gongsta/vslam-py/blob/main/loop_closure.py"
    click O "https://github.com/gongsta/vslam-py/blob/main/optimizer.py"
    click VZ "https://github.com/gongsta/vslam-py/blob/main/visualization.py"
    click EA "https://github.com/gongsta/vslam-py/blob/main/eval/associate.py"
    click EB "https://github.com/gongsta/vslam-py/blob/main/eval/evaluate_ate.py"
    click H1 "https://github.com/gongsta/vslam-py/blob/main/helpers/play.py"
    click H2 "https://github.com/gongsta/vslam-py/blob/main/helpers/record_zed.py"
    click PVI "https://github.com/gongsta/vslam-py/tree/main/third_party/opencv_vpi"

    %% Styles
    classDef dataio fill:#9f6,stroke:#393,stroke-width:1px
    classDef core fill:#6cf,stroke:#039,stroke-width:1px
    classDef optimize fill:#f96,stroke:#c60,stroke-width:1px
    classDef viz fill:#c6f,stroke:#639,stroke-width:1px
    classDef helper fill:#6c9,stroke:#069,stroke-width:1px
    classDef third fill:#faa,stroke:#a33,stroke-width:1px
```
