# tinhvu11235/unet_colorization architecture

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

- Interactive diagram: https://gitdiagram.com/tinhvu11235/unet_colorization
- Repository: https://github.com/tinhvu11235/unet_colorization

## Overview

##### Project Type & Purpose
- Primary goal: train the UNet (with checkpointing via WandB) and provide a lightweight demo inference script.

##### Main Components
a. Configuration Layer
- config.py – defines hyperparameters and dataset paths for scratch vs. resume modes.
b. Data Ingestion
- data_loader.py – reads images from TRAIN/VAL folders, applies transformations, outputs PyTorch DataLoader objects.
c. Model Definition
- model.py – implements the UNet architecture for Lab-space colorization.
d. Training Orchestration
- train.py – runs the training loop (forward/backward), scheduler, optimizer, and periodically saves checkpoints.
- main.py – entry point: parses CLI args (`--mode scratch` or `--mode continue`), loads config, invokes WandB artifact loading for resumes, then calls train.py.
e. Checkpointing & Experiment Tracking
- Weights & Biases (WandB) – used to log metrics, store checkpoints as artifacts, and retrieve latest checkpoints when resuming.
f. Inference / Demo
- demo_release.py – lightweight script that pulls the latest model artifact, loads the trained UNet, accepts a grayscale image, outputs a colorized image.

##### External Services & Storage
- Dataset Storage (local or network file system)
- WandB Cloud for run tracking and artifact storage
- Local filesystem for temporary downloads (artifact_dir) and output images

##### Relationships & Data Flow
[config.py] –> feeds hyperparameters to → [main.py]
[main.py] –> loads WandB checkpoint (if `continue` mode) → downloads artifact → passes model & optimizer states to → [train.py]
[config.py] –> provides paths to → [data_loader.py] –> yields batches to → [train.py]
[model.py] –> defines network used by → [train.py]
[train.py] –> pushes checkpoints & metrics to → [WandB Cloud]
Inference Flow (Bottom):
[demo_release.py] –> uses WandB API to pull latest model artifact → loads UNet from [model.py] → processes input grayscale image → writes colorized output to disk

##### Architectural Patterns & Design Principles
- Modular separation: config, data, model, training, inference
- Single responsibility per script
- Cloud-native experiment tracking & artifact management via WandB
- CLI-driven entry points for reproducibility

##### Technologies & Frameworks
- Python 3.x, PyTorch, torchvision
- numpy, scikit-image, matplotlib, tqdm
- Weights & Biases (wandb)
- gdown (for optional dataset download)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Training Flow"
        config["config.py"]:::codeModule
        main["main.py"]:::codeModule
        data["data_loader.py"]:::codeModule
        model["model.py"]:::codeModule
        train["train.py"]:::codeModule
        wandb["WandB Cloud"]:::wandb
        dataset["Dataset Store"]:::storage
        localfs["Local FS"]:::storage

        config -->|"hyperparams"| main
        config -->|"paths"| data
        data -->|"batches"| train
        model --> train
        main -->|"start_training"| train
        train -->|"checkpoint.pth"| wandb
        wandb -->|"artifact_download"| main
    end

    subgraph "Inference Flow"
        demo["demo_release.py"]:::codeModule
        demo -->|"pull_latest_artifact"| wandb
        demo -->|"load_UNet"| model
        demo -->|"colorized_image"| localfs
    end

    subgraph "Project Docs"
        readme["README.md"]:::codeModule
        req["requirements.txt"]:::codeModule
    end

    classDef codeModule fill:#add8e6,stroke:#000
    classDef storage fill:#9f6,stroke:#000
    classDef wandb fill:#ffa500,stroke:#000

    click config "https://github.com/tinhvu11235/unet_colorization/blob/main/config.py"
    click data "https://github.com/tinhvu11235/unet_colorization/blob/main/data_loader.py"
    click model "https://github.com/tinhvu11235/unet_colorization/blob/main/model.py"
    click main "https://github.com/tinhvu11235/unet_colorization/blob/main/main.py"
    click train "https://github.com/tinhvu11235/unet_colorization/blob/main/train.py"
    click demo "https://github.com/tinhvu11235/unet_colorization/blob/main/demo_release.py"
    click readme "https://github.com/tinhvu11235/unet_colorization/blob/main/README.md"
    click req "https://github.com/tinhvu11235/unet_colorization/blob/main/requirements.txt"
```
