# niconielsen32/yolo-3d architecture

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

- Interactive diagram: https://gitdiagram.com/niconielsen32/yolo-3d
- Repository: https://github.com/niconielsen32/yolo-3d

## Overview

##### File Structure
- Top-level scripts:
- run.py: orchestrates the entire pipeline, parses configuration & CLI.
- detection_model.py: wraps YOLOv11 inference.
- depth_model.py: wraps Depth Anything v2 inference.
- load_camera_params.py: handles retrieval and caching of camera intrinsics/extrinsics.
- requirements.txt: lists external dependencies (PyTorch, OpenCV, NumPy, etc.).
- No front-end directory—pure CLI/Python application.

##### README for Insights
- Feature toggles: tracking, BEV, pseudo-3D overlays.
- Supported inputs: video file or live webcam.
- Automatic model weights download on first run.

##### Main Components & Their Interactions
a. Input Layer
- Source selector in run.py: Video file reader (OpenCV) or Webcam capture.
b. Inference Layer
1. Detection Service (detection_model.py)
2. Depth Service (depth_model.py)
- Takes same frame → returns depth map (per-pixel depth).
c. Fusion Layer
- bbox3d_utils.py
d. Visualization & Tracking Layer
- Optional tracker (could be internal to run.py or detection_model).
- 3D overlay renderer (OpenCV drawing).
e. Output Layer
- Frame writer (OpenCV VideoWriter) or on-screen display.
- Optionally saves to file via path configured in run.py.

##### Architectural Patterns & Design Principles
- Pipeline pattern: sequential, stage-based processing of video frames.
- Single orchestration script (run.py) with pluggable modules for each stage.
- Separation of concerns: detection, depth estimation, fusion, rendering each in its own module.
- Configurable feature toggles promote open/closed principle—able to extend visualization modes without rewriting core loop.

##### Relevant Technologies & Frameworks
- PyTorch: deep‐learning inference for YOLOv11 & Depth Anything v2.
- OpenCV: video I/O, frame capture, drawing utilities.
- NumPy: numerical operations and tensor manipulation.
- Optional tracker library (if enabled).
- Python 3.8+, pip-managed dependencies via requirements.txt.

6. Branch from fusion to optional Tracker module and Visualization module (BEV + 3D overlay).
8. A side note for “model weights auto-download” feeding into both model services.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Run["run.py<br/>(CLI, config parser, main loop)"]:::orchestrator
    subgraph "Inference"
        DET["detection_model.py<br/>(YOLOv11 inference)"]:::inference
        DEP["depth_model.py<br/>(Depth Anything v2)"]:::inference
    end
    subgraph "Fusion & Utilities"
        CAM["load_camera_params.py"]:::utility
        FUS["bbox3d_utils.py<br/>(3D box fusion)"]:::utility
        MW["Model Weights Auto-Download"]:::utility
    end
    subgraph "Visualization & Tracking"
        VIS["Visualization & Tracking<br/>(3D overlay & BEV)"]:::visualization
    end
    Output["Output<br/>(VideoWriter / Display)"]:::dataSource
    Doc["README.md"]:::doc
    Req["requirements.txt"]:::doc

    Run -->|"frame"| DET
    Run -->|"frame"| DEP
    DET -->|"2D boxes + confidences"| FUS
    DEP -->|"depth map"| FUS
    CAM -->|"camera params"| FUS
    FUS -->|"3D boxes"| VIS
    VIS -->|"annotated frame"| Output

    Run -.->DET
    Run -.->DEP
    Run -.->FUS
    Run -.->VIS

    MW -.->DET
    MW -.->DEP

    click Run "https://github.com/niconielsen32/yolo-3d/blob/main/run.py"
    click DET "https://github.com/niconielsen32/yolo-3d/blob/main/detection_model.py"
    click DEP "https://github.com/niconielsen32/yolo-3d/blob/main/depth_model.py"
    click FUS "https://github.com/niconielsen32/yolo-3d/blob/main/bbox3d_utils.py"
    click CAM "https://github.com/niconielsen32/yolo-3d/blob/main/load_camera_params.py"
    click Req "https://github.com/niconielsen32/yolo-3d/blob/main/requirements.txt"
    click Doc "https://github.com/niconielsen32/yolo-3d/blob/main/README.md"

    classDef orchestrator fill:#D3D3FF,stroke:#000
    classDef dataSource fill:#AED6F1,stroke:#000
    classDef inference fill:#A9DFBF,stroke:#000
    classDef utility fill:#F9E79F,stroke:#000
    classDef visualization fill:#F5B041,stroke:#000
    classDef doc fill:#D5D8DC,stroke:#000
```
