# morancium/image_colorization architecture

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

- Interactive diagram: https://gitdiagram.com/morancium/image_colorization
- Repository: https://github.com/morancium/image_colorization

## Overview

##### Project Type and Purpose
- This is a deep‐learning pipeline for automatic image colorization.
- It uses PyTorch and a cGAN (generator + PatchGAN discriminator) with two generator variants (custom U-Net and ResNet18-backbone U-Net).
- Key workflows: training from scratch, training with pretrained backbone, and inference on new images.

##### File Structure
- config.py – hyperparameters (LR, batch size, epochs, image size, L1 loss weight).
- dataset.py – dataset class & DataLoader (downloads/loads COCO or custom images, converts RGB → L*a*b*).
- generator_model.py – custom U-Net definition.
- pretrained_generator.py – ResNet18-based U-Net definition.
- PatchDiscriminator_model.py – PatchGAN discriminator implementation.
- train.py – training loop orchestrating generator vs. discriminator updates.
- pretrained_model.py – alternate training loop using the pretrained generator.
- test.py – inference script (loads grayscale images, runs generator, recombines L + predicted ab).
- files/ – likely for storing downloaded dataset or interim files.

##### Key Components to Showcase
a. Data Ingestion Layer
- COCO Dataset or Custom Images → dataset.py → transforms (resize, tensor, L*a*b* conversion).
b. Preprocessing → splitting L channel (input) vs. a/b channels (ground truth).
c. Model Definitions
- Generator A: Custom U-Net (generator_model.py)
- Generator B: ResNet18 U-Net (pretrained_generator.py)
- Discriminator: PatchGAN (PatchDiscriminator_model.py)
d. Training Orchestrator
- train.py or pretrained_model.py uses config.py parameters → loops:
1) Discriminator update (real vs. fake patches, BCE loss)
2) Generator update (adversarial BCE + L1 pixel loss)
- Visualization & checkpointing (utils.py functions save example outputs and model weights into evaluations/ or output/).
e. Inference Pipeline
- test.py takes new grayscale images → loads checkpoint → generator → recombines channels → outputs colorized images.
f. Supporting Utilities
- config.py (tunable hyperparameters)
- utils.py (loss functions, image I/O, Lab conversions)

##### Relationships & Data Flows
- Output of Generator → L1 Loss & Adversarial Loss comparators → back to training orchestrator
- Save checkpoints & sample images → Evaluation directory
- Inference branch off the Generator → final colorized images

##### Architectural Patterns & Principles
- Modular separation: data layer, model definitions, training logic, inference logic, configuration, utilities
- cGAN pattern: two cooperating adversarial networks
- U-Net skip connections for fine‐grained pixel mapping

##### Final Checklist
- Clear labels on all components and files
- External dependencies:
– PyTorch & CUDA (GPU)
– COCO dataset (or custom dataset input)
- Hyperparameter configuration from config.py
- Two training paths (from-scratch vs. pretrained) converging on evaluation outputs

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DATA["COCO / Custom Images"]:::external
        DATA -->|"ingest"| DATASET["Dataset & Preprocessing\ndataset.py"]:::dataLayer
        CONFIG["Hyperparameters\nconfig.py"]:::dataLayer
    end

    %% Models
    subgraph "Model Definitions"
        direction TB
        GEN_A["Generator A\nCustom U-Net\ngenerator_model.py"]:::modelDef
        GEN_B["Generator B\nResNet18 U-Net\npretrained_generator.py"]:::modelDef
        DISC["PatchGAN Discriminator\nPatchDiscriminator_model.py"]:::modelDef
    end

    %% Training Orchestrator
    subgraph "Training Orchestrator"
        direction TB
        TRAIN_SCRATCH["Train from Scratch\ntrain.py"]:::orchestrator
        TRAIN_PRETRAIN["Train with Pretrained Backbone\npretrained_model.py"]:::orchestrator
    end

    %% Inference
    subgraph "Inference Pipeline"
        direction TB
        TEST["Inference Script\ntest.py"]:::inference
    end

    %% Utilities
    subgraph "Supporting Utilities"
        direction TB
        UTILS["Utils\nutils.py"]:::util
    end

    %% Static & Storage
    subgraph "Static & Storage"
        direction TB
        ASSETS["Assets Directory\nassets/"]:::storage
        FILES["Data Storage\nfiles/"]:::storage
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        REQ["requirements.txt"]:::external
        PYTORCH["PyTorch & CUDA"]:::external
    end

    %% Data Flow
    DATASET -->|"L channel & ab channels"| TRAIN_SCRATCH
    DATASET -->|"L channel & ab channels"| TRAIN_PRETRAIN
    DATASET -->|"grayscale L"| TEST

    CONFIG --> TRAIN_SCRATCH
    CONFIG --> TRAIN_PRETRAIN
    CONFIG --> TEST

    %% Training connections
    TRAIN_SCRATCH -->|"train"| GEN_A
    TRAIN_PRETRAIN -->|"train"| GEN_B

    GEN_A -->|"generate fake images"| DISC
    GEN_B -->|"generate fake images"| DISC
    DISC -->|"adversarial loss"| TRAIN_SCRATCH
    DISC -->|"adversarial loss"| TRAIN_PRETRAIN

    %% Utilities usage
    UTILS --> TRAIN_SCRATCH
    UTILS --> TRAIN_PRETRAIN
    UTILS --> TEST
    UTILS --> DATASET

    %% Checkpoints and Outputs
    TRAIN_SCRATCH -->|"save checkpoints & samples"| FILES
    TRAIN_PRETRAIN -->|"save checkpoints & samples"| FILES
    TRAIN_SCRATCH -->|"save example outputs"| ASSETS
    TRAIN_PRETRAIN -->|"save example outputs"| ASSETS

    TEST -->|"load checkpoint & predict"| GEN_A
    TEST -->|"load checkpoint & predict"| GEN_B
    TEST -->|"output colorized images"| ASSETS

    %% External usage
    PYTORCH --> GEN_A
    PYTORCH --> GEN_B
    PYTORCH --> DISC
    PYTORCH --> TRAIN_SCRATCH
    PYTORCH --> TRAIN_PRETRAIN
    PYTORCH --> TEST

    %% Click Events
    click DATASET "https://github.com/morancium/image_colorization/blob/main/dataset.py"
    click CONFIG "https://github.com/morancium/image_colorization/blob/main/config.py"
    click GEN_A "https://github.com/morancium/image_colorization/blob/main/generator_model.py"
    click GEN_B "https://github.com/morancium/image_colorization/blob/main/pretrained_generator.py"
    click DISC "https://github.com/morancium/image_colorization/blob/main/PatchDiscriminator_model.py"
    click TRAIN_SCRATCH "https://github.com/morancium/image_colorization/blob/main/train.py"
    click TRAIN_PRETRAIN "https://github.com/morancium/image_colorization/blob/main/pretrained_model.py"
    click TEST "https://github.com/morancium/image_colorization/blob/main/test.py"
    click UTILS "https://github.com/morancium/image_colorization/blob/main/utils.py"
    click ASSETS "https://github.com/morancium/image_colorization/tree/main/assets/"
    click FILES "https://github.com/morancium/image_colorization/tree/main/files/"
    click REQ "https://github.com/morancium/image_colorization/blob/main/requirements.txt"

    %% Styles
    classDef dataLayer fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef modelDef fill:#90EE90,stroke:#333,stroke-width:1px
    classDef orchestrator fill:#FFD580,stroke:#333,stroke-width:1px
    classDef inference fill:#D8BFD8,stroke:#333,stroke-width:1px
    classDef util fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef storage fill:#EEEEEE,stroke:#333,stroke-width:1px
    classDef external fill:#F0F8FF,stroke:#333,stroke-width:1px
```
