# hoang-phuong-nguyen/woodscape architecture

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

- Interactive diagram: https://gitdiagram.com/hoang-phuong-nguyen/woodscape
- Repository: https://github.com/hoang-phuong-nguyen/woodscape

## Overview

##### Project Type and Purpose
- This is an open‐source machine‐learning toolkit (named OmniDet) built on top of the WoodScape fisheye dataset for autonomous‐driving perception. It provides data‐preprocessing scripts, a multi‐task surround‐view neural network (backbone + multiple decoders), training entry points, loss definitions, evaluation routines, and ONNX export/verification.

##### High‐Level File Structure Analysis
- Top‐level
– data/             ← local placeholder for downloaded WoodScape dataset
– omnidet/          ← core Python package
– scripts/          ← data‐generation, calibration, config, parser utilities
- omnidet/ sub‐packages
– data/             ← precomputed lookup tables, generation scripts
– data_loader/      ← dataset classes (WoodScape loader)
– models/           ← backbone (ResNet, PoseNet), decoders (detection, semantic, distance, motion, normnet), ONNX export
– losses/           ← per‐task and multi‐task loss functions
– train_utils/      ← helper routines (anchor generation, weighting, pose utils)
– eval/             ← quantitative & qualitative evaluation scripts
– main.py           ← CLI entry point for training/inference
– train_*.py        ← task‐specific training orchestrators
– utils.py          ← general utilities
- scripts/
– annotation generators (semantic_map_generator.py, box_2d_generator.py, polygon_generator.py)
– calibration tools
– config JSONs for mapping classes

##### Key ARCHITECTURAL PATTERNS
- Layered architecture:
Data Layer → Preprocessing Layer (scripts) → DataLoader → Model Layer → Loss Layer → Training Loop → Inference/Export → Evaluation
- Modular separation by concern: data ingestion, model definition, loss computation, training orchestration, evaluation, data‐prep scripts.

##### Main Components & Interactions (
- WoodScape raw images & annotations (data/ or external Google Drive)
- Precomputed LUTs, params.yaml (omnidet/data)
B. Data Preprocessing Scripts (Rectangles, light blue)
- semantic_map_generator.py
- box_2d_generator.py
- polygon_generator.py
- calibration scripts
C. Data Loader (Rectangle, green)
- omnidet/data_loader/woodscape_loader.py
––> reads images + processed labels
D. Model (Rectangle, dark green)
- Backbone: ResNet, PoseNet
- Decoders: detection_decoder, semantic_decoder, distance_decoder, motion_decoder, normnet_decoder
- ONNX export/verify (models/onnx)
E. Loss Functions (Rectangle, orange)
- detection_loss, semantic_loss, distance_loss, motion_loss, mtl_losses
F. Training Orchestration (Rectangle, yellow)
- omnidet/main.py (common CLI)
- train_*.py for single/multi‐task setups
––> orchestrates DataLoader → Model → Loss → Optimizer → Backprop
G. Evaluation (Rectangle, red)
- omnidet/eval/*.py (quantitative & qualitative routines)
H. Utilities & Config (Parallelograms, grey)
- train_utils, utils.py, scripts/configs JSONs
- Python packages from requirements.txt (numpy, OpenCV, PyTorch, shapely, Pillow, matplotlib)
- Google Drive dataset/annotations

1. External dataset (Cloud)
→ raw data folder (data/)
2. Data folder
→ Data Preprocessing Scripts
→ processed annotations
3. Processed annotations + images
→ Data Loader
4. Data Loader
→ Training Orchestrator
5. Training Orchestrator
→ Model forward pass
→ Loss functions
→ Optimizer updates
→ (loop)
-–> after convergence
→ ONNX Export
6. Model or ONNX model
→ Evaluation scripts
→ Metrics & visualizations

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Data Source
    External["Cloud: WoodScape Dataset"]:::external

    %% Data Storage
    RawData["Raw WoodScape Data"]:::rawdata
    Precomputed["Precomputed LUTs & Params"]:::rawdata

    %% Data Preprocessing
    subgraph "Data Preprocessing" 
        direction TB
        Semantic["semantic_map_generator.py"]:::preprocess
        Box2D["box_2d_generator.py"]:::preprocess
        Polygon["polygon_generator.py"]:::preprocess
        Calibration["Calibration Scripts"]:::preprocess
    end

    %% Data Loader
    DataLoader["WoodScape Loader"]:::dataloader

    %% Model Layer
    subgraph "Model Layer" 
        direction TB
        Backbone["Backbone\n(ResNet, PoseNet)"]:::model
        Decoders["Decoders\n(detection, semantic, motion, normnet)"]:::model
        ONNX["ONNX Export & Verification"]:::model
    end

    %% Loss Functions
    Losses["Loss Functions\n(detection, semantic, distance, motion, mtl)"]:::loss

    %% Training Orchestration
    Training["Training Orchestrator\n(main.py, train_*.py)"]:::training

    %% Evaluation
    Evaluation["Evaluation Scripts"]:::eval

    %% Utilities & Config
    Utils["Utilities & Config\n(train_utils, utils.py, JSONs)"]:::utils

    %% Data Flow
    External --> RawData
    External --> Precomputed
    RawData --> Semantic
    RawData --> Box2D
    RawData --> Polygon
    RawData --> Calibration
    Semantic --> DataLoader
    Box2D --> DataLoader
    Polygon --> DataLoader
    Calibration --> DataLoader
    Precomputed --> DataLoader
    DataLoader --> Training
    Training --> Backbone
    Training --> Decoders
    Backbone --> Decoders
    Decoders --> Losses
    Losses --> Training
    Training --> ONNX
    ONNX --> Evaluation
    Training --> Evaluation
    Utils --> Training
    Utils --> DataLoader

    %% Click Events
    click RawData "https://github.com/hoang-phuong-nguyen/woodscape/tree/master/data/"
    click Precomputed "https://github.com/hoang-phuong-nguyen/woodscape/tree/master/omnidet/data/"
    click Semantic "https://github.com/hoang-phuong-nguyen/woodscape/blob/master/scripts/semantic_map_generator.py"
    click Box2D "https://github.com/hoang-phuong-nguyen/woodscape/blob/master/scripts/box_2d_generator.py"
    click Polygon "https://github.com/hoang-phuong-nguyen/woodscape/blob/master/scripts/polygon_generator.py"
    click Calibration "https://github.com/hoang-phuong-nguyen/woodscape/tree/master/scripts/calibration/"
    click DataLoader "https://github.com/hoang-phuong-nguyen/woodscape/blob/master/omnidet/data_loader/woodscape_loader.py"
    click Backbone "https://github.com/hoang-phuong-nguyen/woodscape/blob/master/omnidet/models/resnet.py"
    click Decoders "https://github.com/hoang-phuong-nguyen/woodscape/blob/master/omnidet/models/detection_decoder.py"
    click ONNX "https://github.com/hoang-phuong-nguyen/woodscape/blob/master/omnidet/models/onnx/onnx_export.py"
    click Losses "https://github.com/hoang-phuong-nguyen/woodscape/blob/master/omnidet/losses/detection_loss.py"
    click Training "https://github.com/hoang-phuong-nguyen/woodscape/blob/master/omnidet/main.py"
    click Evaluation "https://github.com/hoang-phuong-nguyen/woodscape/blob/master/omnidet/eval/quantitative_detection.py"
    click Utils "https://github.com/hoang-phuong-nguyen/woodscape/tree/master/omnidet/train_utils/"

    %% Styles
    classDef external fill:#E8F0FE,stroke:#4696E0,color:#000
    classDef rawdata fill:#D0E8FF,stroke:#569CD6,color:#000
    classDef preprocess fill:#EDEAEA,stroke:#A6A6A6,color:#000
    classDef dataloader fill:#DFFFD8,stroke:#28A745,color:#000
    classDef model fill:#D1F7D6,stroke:#008000,color:#000
    classDef loss fill:#FFEDD5,stroke:#FB923C,color:#000
    classDef training fill:#FFFAE5,stroke:#FBBF24,color:#000
    classDef eval fill:#FEE2E2,stroke:#DC2626,color:#000
    classDef utils fill:#F3F4F6,stroke:#6B7280,color:#000
```
