# taeyoung96/visual-odometry-tutorial architecture

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

- Interactive diagram: https://gitdiagram.com/taeyoung96/visual-odometry-tutorial
- Repository: https://github.com/taeyoung96/visual-odometry-tutorial

## Overview

##### Project type and purpose
- This is a Python-based computer-vision tutorial repository (“Visual-odometry-tutorial”) that demonstrates basic stereo/monocular vision techniques (feature matching, epipolar geometry) and a lightweight visual-odometry (VO) pipeline using two popular datasets (KITTI and TUM). It is neither a web app nor a microservice: it’s essentially a CLI-driven pipeline with modular scripts.

##### File structure
- Top-level directories and their roles:
- cv_basics/ – contains two demo scripts (feature_matching.py, epipolar.py) for low-level CV visualization.
- visual-odometry/ – contains vo.py (main VO pipeline) plus pose_evaluation_utils.py for trajectory evaluation and plotting.
- data/ – holds minimal KITTI and TUM dataset subsets.
- result/ – stores output images (feature matching, epipolar lines, VO trajectories).
- slides/ – tutorial slides (VO Tutorial.pdf).
- requirements.txt – Python dependencies.
- Patterns & config:
- Each module is a stage in a linear data-processing pipeline.
- vo.py is parameterized via CLI arguments (--data_dir_root, --dataset_type, --len_trajMap).

##### README for additional insights
- Confirms the pipeline stages, example commands, and that results are purely estimated (no optimization).
- Specifies environment (Anaconda, Python 3.8), dependencies (OpenCV, NumPy, Matplotlib, etc.), and dataset layout expectations.

a. Main components to represent:
1. CLI Interface / Runner – parses arguments, dispatches to selected script.
2. Data Loader – reads images and ground-truth files from data/kitti-odom or data/tum.
3. CV Baseline Module – two sub-components:
- Feature Matching (cv_basics/feature_matching.py)
- Epipolar Geometry (cv_basics/epipolar.py)
4. VO Pipeline Module (visual-odometry/vo.py) – comprising:
- Feature Extraction & Matching
- Pose Estimation (PnP or Essential‐matrix decomposition)
- Trajectory Accumulation
5. Evaluation & Visualization (pose_evaluation_utils.py + Matplotlib) – generates Trajectory.png, feature_matching.png, epipolar.png.
6. Result Store – writes image files to result/ and .txt outputs.

b. Relationships & data flow
- From Data Loader to CV Baseline Module (feature & epipolar) and/or VO Pipeline.

c. Architectural patterns & design principles
- Linear processing pipeline (sequential stages).
- Modular separation (cv_basics vs. visual-odometry).
- CLI-driven configuration for reproducibility.

d. Technologies & frameworks
- Python 3.8, OpenCV (cv2), NumPy, Matplotlib.
- Anaconda environment.
- Datasets hosted externally (KITTI, TUM).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Sources
    CLI["CLI Interface<br/>vo.py<br/>args: --data_dir_root, --dataset_type, --len_trajMap"]:::processing
    click CLI "https://github.com/taeyoung96/visual-odometry-tutorial/blob/master/visual-odometry/vo.py"
    DataLoader["Data Loader<br/>data/kitti-odom/, data/tum/"]:::data
    click DataLoader "https://github.com/taeyoung96/visual-odometry-tutorial/tree/master/data/kitti-odom/"
    click DataLoader "https://github.com/taeyoung96/visual-odometry-tutorial/tree/master/data/tum/"

    %% Branching CV Baseline
    FeatureMatching["Feature Matching<br/>feature_matching.py"]:::processing
    click FeatureMatching "https://github.com/taeyoung96/visual-odometry-tutorial/blob/master/cv_basics/feature_matching.py"
    Epipolar["Epipolar Geometry<br/>epipolar.py"]:::processing
    click Epipolar "https://github.com/taeyoung96/visual-odometry-tutorial/blob/master/cv_basics/epipolar.py"

    %% VO Pipeline and evaluation
    VO["VO Pipeline<br/>vo.py"]:::processing
    click VO "https://github.com/taeyoung96/visual-odometry-tutorial/blob/master/visual-odometry/vo.py"
    Eval["Evaluation & Visualization<br/>pose_evaluation_utils.py"]:::visualization
    click Eval "https://github.com/taeyoung96/visual-odometry-tutorial/blob/master/visual-odometry/pose_evaluation_utils.py"
    Result["Result Store<br/>result/"]:::storage
    click Result "https://github.com/taeyoung96/visual-odometry-tutorial/tree/master/result/"

    %% Extras
    Slides["Tutorial Slides<br/>VO Tutorial.pdf"]:::external
    click Slides "https://github.com/taeyoung96/visual-odometry-tutorial/blob/master/slides/VO Tutorial.pdf"
    Requirements["Dependency Config<br/>requirements.txt"]:::external
    click Requirements "https://github.com/taeyoung96/visual-odometry-tutorial/blob/master/requirements.txt"

    %% Flow
    CLI -->|"dataset path"| DataLoader
    DataLoader -.->|"raw images"| FeatureMatching
    DataLoader -.->|"raw images"| Epipolar
    DataLoader -->|"raw images"| VO
    VO -->|"feature keypoints & matches"| VO_FE["Feature Extraction"]:::processing
    VO_FE -->|"pose estimates"| VO_PE["Pose Estimation"]:::processing
    VO_PE -->|"trajectory data"| VO_TA["Trajectory Accumulation"]:::processing
    VO_TA -->|"poses & trajectory"| Eval
    Eval -->|"plots & images"| Result

    %% Styles
    classDef data fill:#E0F7FA,stroke:#006064,color:#004D40;
    classDef processing fill:#E8F5E9,stroke:#2E7D32,color:#1B5E20;
    classDef visualization fill:#FFF3E0,stroke:#EF6C00,color:#E65100;
    classDef storage fill:#ECEFF1,stroke:#607D8B,color:#455A64;
    classDef external fill:#F3E5F5,stroke:#6A1B9A,color:#4A148C;
    class VO_FE,VO_PE,VO_TA processing
```
