# gg-dema/df-visualodometry architecture

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

- Interactive diagram: https://gitdiagram.com/gg-dema/df-visualodometry
- Repository: https://github.com/gg-dema/df-visualodometry

## Overview

##### Project Type and Purpose
- DFVO is a research‐grade visual odometry system implemented in Python.
- It combines classical geometry‐based tracking (E-tracker and PnP tracker) with neural‐network modules (depth estimation and optical flow) to compute camera motion from monocular video.

##### File Structure to Locate Major Components
- Top‐level orchestrator:
- main.py – command-line interface to run experiments and select dataset, tracker, output options.
- utils.py, camera_module.py, read_bag.py – auxiliary I/O and data loading utilities.
- Neural-network modules (pretrained PyTorch models):
- depth_net/ – depth estimation interface (depth_net.py) + borrowed model definitions and weights.
- flow_net/ – optical‐flow interface (flow_net_ui.py) + correlation and utility scripts + pretrained weights.
- Classical tracking module:
- tracker/tracker_v4.py – implements E-tracker (epipolar fitting) and PnP tracker, plus GRIC‐based model selection.
- Evaluation & output:
- visual_odometry.py – may contain visualization or trajectory plotting routines.
- main.py orchestrates saving the trajectory to disk.

##### Extract Additional Insights from the README
- Two alternative trackers coexist; the system chooses per‐frame via the GRIC metric.
- All neural networks are pretrained on the KITTI dataset; depth_net and flow_net are merely wrapped.
- Target datasets: KITTI (driving) and a top-view drone dataset for evaluation.

1. Input Source
- Live camera (camera_module.py) or ROS bag reader (read_bag.py)
2. Preprocessing
- Frame undistortion, timestamping (utils.py)
3. Depth Estimation Service
- depth_net.depth_net.py → resnet_encoder, depth_decoder
- Pretrained weights (depth.pth)
4. Flow Estimation Service
- flow_net.flow_net_ui.py → correlation.py, flow_utils.py
- Pretrained weights (network-kitti.pytorch)
5. Feature Selection / Matching
- Extract keypoints and descriptors, combine flow + depth cues
6. Dual Tracker Module
- E-tracker (epipolar geometry)
- PnP Tracker (Perspective-n-Point)
7. Model Selection (GRIC computation)
- Computes GRIC score to choose better pose estimate each frame
8. Pose Estimation Output
- Relative pose (R, t) per frame
9. Trajectory Assembly & Visualization
- Writes trajectory file, optional plotting (visual_odometry.py)
10. Experiment Controller / CLI
- main.py – ties everything together, parses args, selects dataset & trackers

- Input Source → Preprocessing
- Preprocessing → {Depth Estimation, Flow Estimation, Feature Selection}
- Depth & Flow services → Feature Selection
- Feature Selection → Dual Tracker Module
- Dual Tracker Module → Model Selection
- Model Selection → Pose Estimation Output
- Pose Estimation → Trajectory Assembly
- CLI / main.py → orchestrates all flows, reads config, invokes each service

c. Architectural Patterns & Design Principles:
- Pipeline architecture: data flows through a sequence of stages.
- Separation of concerns: neural‐network inference is encapsulated in dedicated modules.
- Plug-and-play trackers: two interchangeable classical trackers with runtime selection.
- Modular I/O: camera/ros-bag readers separated from core algorithm.

d. Key Technologies & Frameworks:
- Python 3.x as primary language
- PyTorch for depth_net and flow_net
- NumPy / OpenCV for feature processing and epipolar geometry
- Command-line parser (argparse) in main.py
- ROS bag support via read_bag.py (if needed)

##### Capturing Essential Details
- External dependencies next to modules (e.g., “PyTorch,” “KITTI weights”).
- That main.py triggers each stage, passes parameters, and writes results.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data Acquisition"
        I1["Live Camera\n(camera_module.py)"]:::io
        I2["ROS Bag Reader\n(read_bag.py)"]:::io
    end

    subgraph "Preprocessing"
        P["Frame Undistortion & Timestamping\n(utils.py)"]:::io
    end

    subgraph "Neural Inference"
        DNet["Depth Estimation\n(depth_net/depth_net.py)"]:::neural
        Flow["Flow Estimation\n(flow_net/flow_net_ui.py)"]:::neural
        subgraph "Depth Networks"
            Encoder["ResNet Encoder\n(depth_net/networks/resnet_encoder.py)"]:::neural
            Decoder["Depth Decoder\n(depth_net/networks/depth_decoder.py)"]:::neural
            PoseCNN["Pose CNN\n(depth_net/networks/pose_cnn.py)"]:::neural
            PoseDec["Pose Decoder\n(depth_net/networks/pose_decoder.py)"]:::neural
        end
        Layers["Supporting Layers\n(depth_net/layers.py)"]:::neural
        WeightsDepth["Depth Weights\n(depth_net/trained_networks/depth.pth)"]:::data
        subgraph "Flow Networks"
            Corr["Correlation\n(flow_net/correlation.py)"]:::neural
            FlowUtils["Utils\n(flow_net/flow_utils.py)"]:::neural
            WeightsFlow["Flow Weights\n(flow_net/network-kitti.pytorch)"]:::data
        end
    end

    subgraph "Classical Tracking"
        FS["Feature Selection / Matching\n(tracker_v4.py)"]:::classical
        Dual["Dual Tracker\n(E-tracker & PnP)\n(tracker_v4.py)"]:::classical
        GRIC["Model Selection (GRIC)\n(tracker_v4.py)"]:::decision
    end

    Pose["Pose Output\n(tracker_v4.py)"]:::classical
    Vis["Trajectory & Visualization\n(visual_odometry.py)"]:::io
    CLI["Experiment Controller\n(main.py)"]:::io

    I1 --> P
    I2 --> P
    P --> DNet
    P --> Flow
    P --> FS
    DNet --> FS
    Flow --> FS
    FS --> Dual
    Dual --> GRIC
    GRIC --> Pose
    Pose --> Vis
    CLI --> I1
    CLI --> I2
    CLI --> P
    CLI --> DNet
    CLI --> Flow
    CLI --> FS
    CLI --> Dual
    CLI --> GRIC
    CLI --> Pose
    CLI --> Vis

    click I1 "https://github.com/gg-dema/df-visualodometry/blob/main/camera_module.py"
    click I2 "https://github.com/gg-dema/df-visualodometry/blob/main/read_bag.py"
    click P "https://github.com/gg-dema/df-visualodometry/blob/main/utils.py"
    click DNet "https://github.com/gg-dema/df-visualodometry/blob/main/depth_net/depth_net.py"
    click Encoder "https://github.com/gg-dema/df-visualodometry/blob/main/depth_net/networks/resnet_encoder.py"
    click Decoder "https://github.com/gg-dema/df-visualodometry/blob/main/depth_net/networks/depth_decoder.py"
    click PoseCNN "https://github.com/gg-dema/df-visualodometry/blob/main/depth_net/networks/pose_cnn.py"
    click PoseDec "https://github.com/gg-dema/df-visualodometry/blob/main/depth_net/networks/pose_decoder.py"
    click Layers "https://github.com/gg-dema/df-visualodometry/blob/main/depth_net/layers.py"
    click WeightsDepth "https://github.com/gg-dema/df-visualodometry/blob/main/depth_net/trained_networks/depth.pth"
    click Flow "https://github.com/gg-dema/df-visualodometry/blob/main/flow_net/flow_net_ui.py"
    click Corr "https://github.com/gg-dema/df-visualodometry/blob/main/flow_net/correlation.py"
    click FlowUtils "https://github.com/gg-dema/df-visualodometry/blob/main/flow_net/flow_utils.py"
    click WeightsFlow "https://github.com/gg-dema/df-visualodometry/blob/main/flow_net/network-kitti.pytorch"
    click FS "https://github.com/gg-dema/df-visualodometry/blob/main/tracker/tracker_v4.py"
    click Dual "https://github.com/gg-dema/df-visualodometry/blob/main/tracker/tracker_v4.py"
    click GRIC "https://github.com/gg-dema/df-visualodometry/blob/main/tracker/tracker_v4.py"
    click Pose "https://github.com/gg-dema/df-visualodometry/blob/main/tracker/tracker_v4.py"
    click Vis "https://github.com/gg-dema/df-visualodometry/blob/main/visual_odometry.py"
    click CLI "https://github.com/gg-dema/df-visualodometry/blob/main/main.py"

    classDef io fill:#DDDDDD,stroke:#999,stroke-width:1px;
    classDef neural fill:#AEDFF7,stroke:#0B7CA9,stroke-width:1px;
    classDef classical fill:#C2FABC,stroke:#2E8B57,stroke-width:1px;
    classDef decision fill:#FFD699,stroke:#DAA520,stroke-width:1px;
    classDef data fill:#F0E68C,stroke:#B8860B,stroke-width:1px;
```
