# janspiry/image-super-resolution-via-iterative-refinement architecture

> Architecture diagram of the GitHub repository janspiry/image-super-resolution-via-iterative-refinement, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/janspiry/image-super-resolution-via-iterative-refinement
- Repository: https://github.com/janspiry/image-super-resolution-via-iterative-refinement

## Overview

##### Project Type and Purpose
- This is a research-oriented ML pipeline for image super-resolution using diffusion models (DDPM/SR3).
- It provides scripts for data preparation, model training (sr.py for conditional SR, sample.py for unconditional sampling), evaluation, and inference.
- It integrates with Weights & Biases for experiment tracking.

##### Main Architectural Components
a. User Interface / CLI
- Entry points: `sr.py`, `sample.py`, `eval.py`, `infer.py`, `data/prepare_data.py`
- Parses command-line args and a JSON config (from `config/*.json`).
b. Configuration Layer
- JSON files under `config/`
- Hyperparameters, dataset paths, model architecture, resume state.
c. Data Layer
- Raw dataset directories under `dataset/…`
- Data-prep script (`data/prepare_data.py`) generates low-res, high-res, bicubic SR images into `dataset/...`
- Data loader classes (`data/LRHR_dataset.py`, `data/util.py`) wrap LMDB or image folders.
d. Model Layer
- Core diffusion model implementations in `model/ddpm_modules/` and `model/sr3_modules/`
- Building blocks: `model/networks.py` (UNet), `model/base_model.py`, `model/model.py`
- `core/` utilities: `logger.py`, `metrics.py`, `wandb_logger.py`
e. Training Engine
- `sr.py`: orchestrates conditional SR training & validation
- `sample.py`: unconditional generation
- Uses PyTorch DataLoader → Model → Loss → Optimizer loop
- Hooks into `core/metrics.py` and optionally `core/wandb_logger.py`
f. Evaluation Module
- `eval.py`: loads generated results, computes SSIM/PSNR via `core/metrics.py`
g. Inference Module
- `infer.py`: loads a trained model checkpoint and a single LR image → outputs SR image
h. Logging/Monitoring
- Optional Weights & Biases integration via `core/wandb_logger.py` and CLI flags
- Checkpointing (PyTorch `.pt` files) and W&B Artifacts
i. External Dependencies
- PyTorch, torchvision, lmdb (optional), wandb
- Pre-trained model weights (downloaded externally)

##### Relationships & Data Flows
- CLI → reads Config → invokes Data Layer & Model Layer within Training Engine
- Data Layer → feeds mini-batches to Model Layer
- Model Layer → computes outputs → loss → backprop
- Core Logger & Metrics → record training progress → optional W&B API
- Trained checkpoints → stored locally / W&B –> reused by Inference/Evaluation
- Evaluation Module → reads SR results + ground truth → Metrics → report
- Inference Module → reads checkpoint + LR image → Model → outputs SR image

##### Architectural Patterns & Principles
- Clear separation of concerns: Data vs. Model vs. Training vs. Evaluation vs. Logging
- Config-driven design: everything—from model size to dataset paths—is defined in JSON
- Modular diffusion building blocks (DDPM vs. SR3) under respective subpackages
- Pluggable logging (console vs. W&B) via strategy pattern in `core/wandb_logger.py`
- Single responsibility for each script: one for training, one for sampling, one for eval, one for infer

## Diagram (Mermaid)

```mermaid
graph TB

    subgraph "User Interface / CLI"
        sr["sr.py"]:::internal
        sample["sample.py"]:::internal
        eval["eval.py"]:::internal
        infer["infer.py"]:::internal
        prep["data/prepare_data.py"]:::internal
    end

    subgraph "Configuration Layer"
        cfg1["sr_ddpm_16_128.json"]:::internal
        cfg2["sr_sr3_16_128.json"]:::internal
        cfg3["sr_sr3_64_512.json"]:::internal
        cfg4["sample_ddpm_128.json"]:::internal
        cfg5["sample_sr3_128.json"]:::internal
    end

    subgraph "Data Layer"
        subgraph "Datasets"
            DS1["dataset/celebahq_16_128"]:::data
            DS2["dataset/celebahq_64_512"]:::data
            DS3["dataset/ffhq_64_512"]:::data
        end
        DL1["data/LRHR_dataset.py"]:::internal
        DL2["data/util.py"]:::internal
    end

    subgraph "Model Layer"
        core_model["model/model.py\nmodel/base_model.py\nmodel/networks.py"]:::internal
        subgraph "DDPM Modules"
            DDdiff["model/ddpm_modules/diffusion.py"]:::internal
            DDDUN["model/ddpm_modules/unet.py"]:::internal
        end
        subgraph "SR3 Modules"
            SRdiff["model/sr3_modules/diffusion.py"]:::internal
            SRUN["model/sr3_modules/unet.py"]:::internal
        end
    end

    subgraph "Core Utilities"
        logger["core/logger.py"]:::internal
        metrics["core/metrics.py"]:::internal
        wandb["core/wandb_logger.py"]:::internal
    end

    subgraph "Artifacts"
        CP["Checkpoints (.pt)"]:::data
        SRimgs["SR Images"]:::data
    end

    subgraph "External Services"
        wandb_srv["Weights & Biases"]:::external
        pretrain["Pre-trained Weights"]:::external
    end

    %% Connections
    sr -->|"reads"| cfg1
    sr -->|"reads"| cfg2
    sr -->|"reads"| cfg3
    sample -->|"reads"| cfg4
    sample -->|"reads"| cfg5

    prep --> DS1
    prep --> DS2
    prep --> DS3

    DS1 --> DL1
    DS2 --> DL1
    DS3 --> DL1
    DL1 --> DL2

    sr -->|"uses"| DL1
    sample -->|"uses"| DL1
    DL1 -->|"batches"| core_model

    core_model -->|"computes"| metrics
    core_model -->|"saves"| CP
    core_model -->|"outputs"| SRimgs

    sr -->|"logs"| logger
    sample -->|"logs"| logger
    logger -->|"optionally"| wandb
    wandb -->|"API"| wandb_srv

    metrics -->|"metrics"| logger

    pretrain --> core_model

    eval --> SRimgs
    eval -->|"evaluates via"| metrics

    infer --> CP
    infer --> core_model
    infer -->|"outputs"| SRimgs

    %% Click Events
    click sr "https://github.com/janspiry/image-super-resolution-via-iterative-refinement/blob/master/sr.py"
    click sample "https://github.com/janspiry/image-super-resolution-via-iterative-refinement/blob/master/sample.py"
    click eval "https://github.com/janspiry/image-super-resolution-via-iterative-refinement/blob/master/eval.py"
    click infer "https://github.com/janspiry/image-super-resolution-via-iterative-refinement/blob/master/infer.py"
    click prep "https://github.com/janspiry/image-super-resolution-via-iterative-refinement/blob/master/data/prepare_data.py"
    click cfg1 "https://github.com/janspiry/image-super-resolution-via-iterative-refinement/blob/master/config/sr_ddpm_16_128.json"
    click cfg2 "https://github.com/janspiry/image-super-resolution-via-iterative-refinement/blob/master/config/sr_sr3_16_128.json"
    click cfg3 "https://github.com/janspiry/image-super-resolution-via-iterative-refinement/blob/master/config/sr_sr3_64_512.json"
    click cfg4 "https://github.com/janspiry/image-super-resolution-via-iterative-refinement/blob/master/config/sample_ddpm_128.json"
    click cfg5 "https://github.com/janspiry/image-super-resolution-via-iterative-refinement/blob/master/config/sample_sr3_128.json"
    click DS1 "https://github.com/janspiry/image-super-resolution-via-iterative-refinement/tree/master/dataset/celebahq_16_128"
    click DS2 "https://github.com/janspiry/image-super-resolution-via-iterative-refinement/tree/master/dataset/celebahq_64_512"
    click DS3 "https://github.com/janspiry/image-super-resolution-via-iterative-refinement/tree/master/dataset/ffhq_64_512"
    click DL1 "https://github.com/janspiry/image-super-resolution-via-iterative-refinement/blob/master/data/LRHR_dataset.py"
    click DL2 "https://github.com/janspiry/image-super-resolution-via-iterative-refinement/blob/master/data/util.py"
    click core_model "https://github.com/janspiry/image-super-resolution-via-iterative-refinement/blob/master/model/model.py"
    click DDdiff "https://github.com/janspiry/image-super-resolution-via-iterative-refinement/blob/master/model/ddpm_modules/diffusion.py"
    click DDDUN "https://github.com/janspiry/image-super-resolution-via-iterative-refinement/blob/master/model/ddpm_modules/unet.py"
    click SRdiff "https://github.com/janspiry/image-super-resolution-via-iterative-refinement/blob/master/model/sr3_modules/diffusion.py"
    click SRUN "https://github.com/janspiry/image-super-resolution-via-iterative-refinement/blob/master/model/sr3_modules/unet.py"
    click logger "https://github.com/janspiry/image-super-resolution-via-iterative-refinement/blob/master/core/logger.py"
    click metrics "https://github.com/janspiry/image-super-resolution-via-iterative-refinement/blob/master/core/metrics.py"
    click wandb "https://github.com/janspiry/image-super-resolution-via-iterative-refinement/blob/master/core/wandb_logger.py"

    %% Styles
    classDef internal fill:#B3CDE3,stroke:#6497B1,color:#03396C
    classDef data fill:#C7E9B4,stroke:#74C476,color:#22543D
    classDef external fill:#FDD0A2,stroke:#FB6A4A,color:#7F2704
```
