# stephansturges/waldo architecture

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

- Interactive diagram: https://gitdiagram.com/stephansturges/waldo
- Repository: https://github.com/stephansturges/waldo

## Overview

##### Project type and purpose
- This is an open-source AI model distribution and inference toolkit (“WALDO v3.0”) built around a YOLO-v8 detection backbone and a synthetic-data pipeline.
- It provides:
- Multiple pre-trained model variants (V7-base, V7-e6e, V7-tiny)
- Inference scripts (playground) for images/videos via PyTorch/ONNX/OpenVINO
- A Python package (setup.py) to bundle the core loader and helpers

##### File structure
- Top-level:
- playground – utility scripts for local testing: running inference on images/videos, making demo videos, testing GPU/ONNX runtime
- setup.py – defines the Python package for installing WALDO as a library
- Patterns:
- Model variants are separated by directory (clear modular plugin pattern)
- Inference code is grouped under playground and occasionally inside weight folders (e.g., main.py under Luxonis_OpenVino)
- No traditional “frontend/backend” split; instead, it’s a library + CLI/scripts

##### README for additional insights
- WALDO is a pure-inference tool: detect 12 object classes in aerial/satellite imagery
- Depends on YOLO-v8 (Ultralytics), Supervision (Roboflow), ONNX Runtime or OpenVINO for edge
- Encourages fine-tuning, sliding-window inference, quantization as extension points

##### Elements
- Clear labels for each component block (Model Repo, Inference Engine, Data Pipeline, etc.)
- Download models → load weights → run inference → produce outputs
- Rectangles for code modules
- Parallelograms for input/output (images, videos)
- Clouds for external services (Hugging Face, Gumroad)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Model Repository
    subgraph "Model Repository"
        direction TB
        V7base["V7-base"]:::cylinder
        V7e6e["V7-e6e"]:::cylinder
        V7tiny["V7-tiny"]:::cylinder
    end

    %% Inference Engine
    subgraph "Inference Engine"
        direction TB
        PTy["PyTorch YOLOv8 Loader"]:::rectangle
        ONNXrt["ONNX Runtime"]:::rectangle
        OVI["OpenVINO Runtime"]:::rectangle
    end

    %% Data Pipeline
    subgraph "Data Pipeline"
        direction TB
        Img["Images"]:::parallelogram
        Vid["Video Streams"]:::parallelogram
        Tile["Sliding-Window Tiling"]:::parallelogram
        Pre["Pre-processing\n(resize, normalize)"]:::rectangle
    end

    %% Annotation & Output
    subgraph "Annotation & Output"
        direction TB
        SUP["Supervision\n(Roboflow)"]:::rectangle
        OutFile["Export to File/Video"]:::parallelogram
    end

    %% CLI / Script Layer
    subgraph "CLI / Script Layer"
        direction TB
        mkVideo["make_video_pan.py"]:::rectangle
        runImgONNX["run_local_network_on_images_onnxruntime.py"]:::rectangle
        runVidONNX["run_local_network_on_videos_onnxruntime.py"]:::rectangle
        testGPU["test_onnx_gpu.py"]:::rectangle
        baseOVIex["main.py (V7-base OpenVINO)"]:::rectangle
        tinyOVIex["main.py (V7-tiny OpenVINO)"]:::rectangle
        compressVid["compress_video.py"]:::rectangle
    end

    %% Packaging & Distribution
    subgraph "Packaging & Distribution"
        direction TB
        Setup["setup.py"]:::rectangle
    end

    %% External Services
    subgraph "External Services"
        direction TB
        HF["Hugging Face Hub"]:::cloud
        Gum["Gumroad"]:::cloud
    end

    %% Relationships
    HF -->|"download weights"| V7base
    HF -->|"download weights"| V7e6e
    HF -->|"download weights"| V7tiny
    Gum -->|"purchase/download"| V7e6e
    Gum -->|"purchase/download"| V7tiny

    Img --> Pre
    Vid --> Pre
    Tile --> Pre

    Pre --> PTy
    Pre --> ONNXrt
    Pre --> OVI

    V7base --> PTy
    V7e6e --> PTy
    V7tiny --> PTy

    V7base --> ONNXrt
    V7e6e --> ONNXrt
    V7tiny --> ONNXrt

    V7base --> OVI
    V7tiny --> OVI

    PTy --> SUP
    ONNXrt --> SUP
    OVI --> SUP

    SUP --> OutFile

    mkVideo --> ONNXrt
    runImgONNX --> ONNXrt
    runVidONNX --> ONNXrt
    testGPU --> ONNXrt

    baseOVIex --> OVI
    tinyOVIex --> OVI

    OutFile --> compressVid

    Setup --> PTy

    %% Click Events
    click V7base "https://github.com/stephansturges/waldo/tree/master/V7-base/"
    click V7e6e "https://github.com/stephansturges/waldo/tree/master/V7-e6e/"
    click V7tiny "https://github.com/stephansturges/waldo/tree/master/V7-tiny/"
    click runImgONNX "https://github.com/stephansturges/waldo/blob/master/playground/run_local_network_on_images_onnxruntime.py"
    click runVidONNX "https://github.com/stephansturges/waldo/blob/master/playground/run_local_network_on_videos_onnxruntime.py"
    click testGPU "https://github.com/stephansturges/waldo/blob/master/playground/test_onnx_gpu.py"
    click baseOVIex "https://github.com/stephansturges/waldo/blob/master/V7-base/square/yolov7-W25-416-newDefaults-bs196/weights/OpenVINO-2021-4_Luxonis_models/main.py"
    click tinyOVIex "https://github.com/stephansturges/waldo/blob/master/V7-tiny/square/yolov7-tiny-W25-512-newDefaults-bs256/weights/luxonis_OpenVino/main.py"
    click mkVideo "https://github.com/stephansturges/waldo/blob/master/playground/make_video_pan.py"
    click compressVid "https://github.com/stephansturges/waldo/blob/master/playground/output_vids/compress_video.py"
    click Setup "https://github.com/stephansturges/waldo/blob/master/setup.py"
    click OutFile "https://github.com/stephansturges/waldo/tree/master/playground/output_vids/"

    %% Styles
    classDef cylinder fill:#ffebcc,stroke:#d58512,stroke-width:2px;
    classDef rectangle fill:#cce5ff,stroke:#4a90e2,stroke-width:2px;
    classDef parallelogram fill:#e6ffe6,stroke:#33a02c,stroke-width:2px;
    classDef cloud fill:#f2e6ff,stroke:#9b59b6,stroke-width:2px;
```
