# ishitsuka-hikaru/safeuav architecture

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

- Interactive diagram: https://gitdiagram.com/ishitsuka-hikaru/safeuav
- Repository: https://github.com/ishitsuka-hikaru/safeuav

## Overview

##### Project type and purpose
- SafeUAV is a research-driven computer-vision/ML toolkit for UAV depth estimation and safe-landing area prediction.
- It provides training, testing, and inference scripts around deep segmentation and regression models (UNet variants and DeepLabv3+).

##### Main components of the system
a. Data Layer
– Synthetic/real dataset stored as HDF5 files (`.h5`)
– Optional label-export script (`main_export_new_labels.py`)
b. Model Definitions
– `unet_tiny_sum.py`, `unet_classic.py`, `deeplabv3plus_xception.py`, etc.
– Loss functions module (`loss.py`)
c. Training Pipeline
– Orchestrator: `main.py`
– Dataset loader & sampler (`test_dataset.py`)
– Optimizer, scheduler, checkpoint logic
– Plotting metrics & outputs (`plotter.py`)
d. Inference Pipelines
– Video inference: `main_inference_video.py`
– Camera/real-time inference: `main_inference_camera.py`
e. Deployment & Environment
– Docker build (`docker/Dockerfile`, `docker/requirements.txt`)
– Jetson installation prerequisites (`packages.txt`)
– External neural-wrappers dependency

##### Relationships and data flows
- Data Layer → Training Pipeline
– HDF5 dataset is read by `main.py`
– Model definitions and `loss.py` are injected
– Training produces model weights (“.pkl” checkpoints)
- Training Pipeline → Plotter
– Periodic evaluation outputs curves/images via `plotter.py`
- Checkpoint Storage → Inference Pipelines
– `main_inference_video.py` / `main_inference_camera.py` load weights
– Input (video file or camera stream) → model → post-processing → output video/frames
- Entire workflow can be containerized in Docker or deployed on Jetson

##### Architectural patterns and design principles
– Modular separation: model definitions vs. training logic vs. inference logic
– Pipeline orchestration: single-entry scripts for each stage (train/test/infer)
– Configuration-driven experiments: command-line flags control task (classification vs. regression), model, hyperparameters
– Reproducibility via Docker or environment scripts

##### Elements to include for maximum clarity
– Versioned artifacts (e.g., model-checkpoint.pkl)
– Hardware boundary: “GPU / Jetson”
– Container boundary labeled “Docker Image” with exposed volumes

## Diagram (Mermaid)

```mermaid
graph TB
    %% Data Zone
    subgraph "Data Zone"
        Data["HDF5 Dataset"]:::storage
        Export["Label Export: main_export_new_labels.py"]:::script
    end

    %% Model Zone
    subgraph "Model Zone"
        UNET["UNet Tiny Sum: unet_tiny_sum.py"]:::model
        DeepLab["DeepLabV3+ Xception: deeplabv3plus_xception.py"]:::model
        Loss["Loss Functions: loss.py"]:::model
    end

    %% Training Pipeline
    subgraph "Training Pipeline"
        Main["Training Orchestrator: main.py"]:::script
        Loader["Dataset Loader: test_dataset.py"]:::script
        Plot["Metrics Plotter: plotter.py"]:::script
        Checkpoint["Checkpoint Storage (.pkl)"]:::storage
    end

    %% Inference Zone
    subgraph "Inference Pipeline"
        VideoInf["Video Inference: main_inference_video.py"]:::script
        CamInf["Camera Inference: main_inference_camera.py"]:::script
        Output["Output Video/Frames"]:::storage
    end

    %% External Dependencies
    External["External: neural-wrappers"]:::cloud

    %% Deployment Zone
    subgraph "Deployment & Hardware"
        Docker["Docker Image"]:::deployment
        Jetson["GPU / Jetson"]:::hardware
    end

    %% Data flows
    Export -->|"label export"| Data
    Data -->|"HDF5 read"| Main
    Main -->|"loads"| Loader
    Main -->|"injects"| UNET
    Main -->|"injects"| DeepLab
    Main -->|"injects"| Loss
    Main -->|"saves weights"| Checkpoint
    Main -->|"plots metrics"| Plot

    %% Inference flows
    Checkpoint -->|"load weights"| VideoInf
    Checkpoint -->|"load weights"| CamInf
    VideoInf -->|"process frames"| Output
    CamInf -->|"process stream"| Output

    %% External usage
    External --> VideoInf
    External --> CamInf
    External --> Main

    %% Deployment flows
    Docker --> Main
    Docker --> VideoInf
    Docker --> CamInf
    Docker --> Export
    Docker --> Loader
    Docker --> Plot
    Jetson --> VideoInf
    Jetson --> CamInf

    %% Click Events
    click Export "https://github.com/ishitsuka-hikaru/safeuav/blob/jetson_real/main_export_new_labels.py"
    click UNET "https://github.com/ishitsuka-hikaru/safeuav/blob/jetson_real/unet_tiny_sum.py"
    click DeepLab "https://github.com/ishitsuka-hikaru/safeuav/blob/jetson_real/deeplabv3plus_xception.py"
    click Loss "https://github.com/ishitsuka-hikaru/safeuav/blob/jetson_real/loss.py"
    click Main "https://github.com/ishitsuka-hikaru/safeuav/blob/jetson_real/main.py"
    click Loader "https://github.com/ishitsuka-hikaru/safeuav/blob/jetson_real/test_dataset.py"
    click Plot "https://github.com/ishitsuka-hikaru/safeuav/blob/jetson_real/plotter.py"
    click VideoInf "https://github.com/ishitsuka-hikaru/safeuav/blob/jetson_real/main_inference_video.py"
    click CamInf "https://github.com/ishitsuka-hikaru/safeuav/blob/jetson_real/main_inference_camera.py"
    click Docker "https://github.com/ishitsuka-hikaru/safeuav/tree/jetson_real/docker/Dockerfile"
    click Docker "https://github.com/ishitsuka-hikaru/safeuav/blob/jetson_real/docker/requirements.txt"
    click Jetson "https://github.com/ishitsuka-hikaru/safeuav/blob/jetson_real/packages.txt"

    %% Styles
    classDef storage fill:#FFD59E,stroke:#E08E0B,stroke-width:1px,shape:cylinder
    classDef script fill:#9EE5E1,stroke:#0B7E79,stroke-width:1px,shape:rect
    classDef model fill:#E5D99E,stroke:#7E6D0B,stroke-width:1px,shape:hexagon
    classDef cloud fill:#D0DFF0,stroke:#2B4F81,stroke-width:1px,shape:cloud
    classDef deployment fill:#F0D0D0,stroke:#812B2B,stroke-width:1px,shape:rect
    classDef hardware fill:#D0F0D8,stroke:#2B812B,stroke-width:1px,shape:rect
```
