# ree1s/dit-sr architecture

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

- Interactive diagram: https://gitdiagram.com/ree1s/dit-sr
- Repository: https://github.com/ree1s/dit-sr

## Overview

##### Project Type and Purpose
- This is a research‐oriented machine-learning toolkit for real-world image super-resolution and blind face restoration. It implements a diffusion transformer (DiT-SR) architecture, integrates BasicSR utilities, and provides end-to-end pipelines for data ingestion, training, checkpointing, inference, and evaluation.

##### File Structure Analysis
- Top-level directories:
- configs – YAML configs for different tasks (realsr_DiT, faceir_DiT).
- basicsr – data utilities, datasets, degradation modules, common image utilities inherited from BasicSR.
- datapipe – custom augmentation and degradation pipelines, dataset definitions.
- ldm – latent diffusion model components: autoencoder, transformer/diffusion modules, quantizers, EMA.
- models – core model definitions (UNet, Swin transformer, diffusion solvers, loss functions).
- utils – shared helper functions: I/O, distributed training, logging, option parsing.
- main.py & trainer.py – entry points for training; evaluate.py & inference.py – entry points for evaluation/inference; sampler.py – sampling/denoising logic.

##### README Insights
- Two training modes (real-world SR, face restoration) invoked via torchrun and distinct config files.
- External checkpoints (autoencoder, loss models) loaded from weights directory.
- Training orchestrated over multi-GPU with PyTorch’s distributed launcher.
- Data lists precomputed in data_list/*.txt and consumed by the data pipeline.

a. Main Components
1. Data Sources
- Raw image datasets (LSDIR, DIV2K, FFHQ) and their path lists in data_list/*.txt.
2. Data Ingestion & Augmentation
- datapipe (aug.py, degradation_bsrgan) + basicsr/data (transforms, samplers, dataloader).
3. Configuration & Launch
- configs/*.yaml loaded by utils/options; torchrun entry in main.py.
4. Model Core
- ldm.autoencoder: encodes images to latents.
- ldm.modules.diffusionmodules + models/unet & swin_transformer: diffusion transformer network.
- ldm.modules.quantize & EMA module.
5. Training Orchestrator
- trainer.py: training loop, loss computation (models/losses), optimizer, scheduler, checkpointing.
- utils/dist_util: multi-GPU sync, logging via utils/logger.
6. Sampling & Inference
- sampler.py + inference.py: denoising loop, checkpoint loading, image reconstruction via autoencoder decoder.
7. Evaluation
- evaluate.py & test scripts (test_realsr.sh, test_faceir.sh): automated benchmarks on real/synthetic datasets.
8. External Dependencies
- PyTorch, CUDA, mmcv, einops, etc. (requirements.txt).

b. Relationships & Data Flow
- Start: User runs torchrun → main.py loads config → instantiate DataModule (datapipe + basicsr/data) → create PyTorch DataLoader → batch of images → pass through autoencoder encoder to produce latents → pass latents + timestep embeddings to diffusion transformer → compute output, decode latents → compute loss via loss modules → optimizer step → periodically save checkpoints → at inference, sampler.py loads checkpoint → reverse diffusion process → decode final latents → save super-resolved images.

c. Architectural Patterns
- Pipeline pattern for data preprocessing and augmentation.
- Modular registry for model components (basicsr.utils.registry).
- Config-driven instantiation (Hydra-style YAML).
- Distributed data-parallel training via torch.distributed.
- Separation of concerns: data, model, training, inference, evaluation.

d. Key Technologies & Frameworks
- PyTorch for tensor operations and model definition.
- BasicSR utilities for standard data handling.
- Custom datapipe for degradations (BSRGAN-style).
- Latent diffusion model architecture in ldm.
- Transformer backbones (UNet, Swin).
- YAML config paradigm, torchrun for multi-GPU.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Sources
    subgraph "Data Sources"
        direction TB
        DS1["Raw Image Datasets\n(LSDIR, DIV2K, FFHQ)"]:::data
        DS2["Data Lists (TXT)"]:::data
    end

    %% Data Ingestion & Augmentation
    subgraph "Data Pipeline" 
        direction TB
        DP1["datapipe/aug.py"]:::data
        DP2["datapipe/datasets.py"]:::data
        DP3["datapipe/degradation_bsrgan/bsrgan.py"]:::data
        DP4["basicsr/data/data_util.py"]:::data
        DP5["basicsr/data/data_sampler.py"]:::data
        DP6["basicsr/data/transforms.py"]:::data
    end

    %% Config & Launch
    subgraph "Config Loader & Launch" 
        direction TB
        CFG1["configs/realsr_DiT.yaml"]:::orchestrate
        CFG2["configs/faceir_DiT.yaml"]:::orchestrate
        CFG3["utils/util_opts.py"]:::orchestrate
        CFG4["main.py"]:::orchestrate
    end

    %% Model Core
    subgraph "Model Core"
        direction TB
        MC1["ldm/models/autoencoder.py"]:::model
        MC2["ldm/modules/diffusionmodules/model.py"]:::model
        MC3["ldm/modules/diffusionmodules/upscaling.py"]:::model
        MC4["ldm/modules/quantize.py"]:::model
        MC5["ldm/modules/vqvae/quantize.py"]:::model
        MC6["ldm/modules/ema.py"]:::model
        MC7["models/unet.py"]:::model
        MC8["models/swin_transformer.py"]:::model
        MC9["models/solvers.py"]:::model
        MC10["models/gaussian_diffusion.py"]:::model
        MC11["models/losses.py"]:::model
    end

    %% Training Orchestrator
    subgraph "Training Orchestrator"
        direction TB
        TR1["trainer.py"]:::orchestrate
        TR2["basicsr/utils/dist_util.py"]:::orchestrate
        TR3["basicsr/utils/logger.py"]:::orchestrate
        TR4["models/losses.py"]:::orchestrate
    end

    %% Sampling & Inference
    subgraph "Inference Pipeline"
        direction TB
        IF1["sampler.py"]:::inference
        IF2["inference.py"]:::inference
    end

    %% Evaluation
    subgraph "Evaluation"
        direction TB
        EV1["evaluate.py"]:::inference
        EV2["test_realsr.sh"]:::inference
        EV3["test_faceir.sh"]:::inference
    end

    %% Utilities & Shared Helpers
    subgraph "Utilities"
        direction TB
        US1["utils/util_common.py"]:::external
        US2["utils/util_image.py"]:::external
        US3["utils/util_net.py"]:::external
        US4["utils/util_sisr.py"]:::external
    end

    %% External Dependencies
    EX["External Dependencies\n(PyTorch, CUDA, mmcv, einops)"]:::external

    %% Connections
    DS2 --> DP1
    DS2 --> DP2
    DS2 --> DP3
    DS1 --> DP1
    DP1 --> MC1
    DP2 --> MC1
    CFG4 --> CFG1
    CFG4 --> CFG2
    CFG4 --> CFG3
    CFG4 --> DP1
    CFG4 --> TR1
    MC1 --> MC2
    MC2 --> MC9
    MC3 --> MC9
    MC4 --> MC2
    MC5 --> MC4
    MC6 --> TR1
    MC7 --> MC2
    MC8 --> MC2
    MC9 --> TR1
    MC10 --> TR1
    MC11 --> TR1
    TR1 -->|"saves checkpoint"| US4
    TR1 -->|"logging"| US3
    TR2 --> TR1
    TR3 --> TR1
    TR1 --> IF1
    IF1 --> IF2
    IF2 --> EV1
    EV1 --> EV2
    EV1 --> EV3
    EX --> MC1
    EX --> TR1
    EX --> IF1

    %% Click Events
    click DP1 "https://github.com/ree1s/dit-sr/blob/main/datapipe/aug.py"
    click DP2 "https://github.com/ree1s/dit-sr/blob/main/datapipe/datasets.py"
    click DP3 "https://github.com/ree1s/dit-sr/blob/main/datapipe/degradation_bsrgan/bsrgan.py"
    click DP4 "https://github.com/ree1s/dit-sr/blob/main/basicsr/data/data_util.py"
    click DP5 "https://github.com/ree1s/dit-sr/blob/main/basicsr/data/data_sampler.py"
    click DP6 "https://github.com/ree1s/dit-sr/blob/main/basicsr/data/transforms.py"
    click CFG1 "https://github.com/ree1s/dit-sr/blob/main/configs/realsr_DiT.yaml"
    click CFG2 "https://github.com/ree1s/dit-sr/blob/main/configs/faceir_DiT.yaml"
    click CFG3 "https://github.com/ree1s/dit-sr/blob/main/utils/util_opts.py"
    click CFG4 "https://github.com/ree1s/dit-sr/blob/main/main.py"
    click MC1 "https://github.com/ree1s/dit-sr/blob/main/ldm/models/autoencoder.py"
    click MC2 "https://github.com/ree1s/dit-sr/blob/main/ldm/modules/diffusionmodules/model.py"
    click MC3 "https://github.com/ree1s/dit-sr/blob/main/ldm/modules/diffusionmodules/upscaling.py"
    click MC4 "https://github.com/ree1s/dit-sr/blob/main/ldm/modules/quantize.py"
    click MC5 "https://github.com/ree1s/dit-sr/blob/main/ldm/modules/vqvae/quantize.py"
    click MC6 "https://github.com/ree1s/dit-sr/blob/main/ldm/modules/ema.py"
    click MC7 "https://github.com/ree1s/dit-sr/blob/main/models/unet.py"
    click MC8 "https://github.com/ree1s/dit-sr/blob/main/models/swin_transformer.py"
    click MC9 "https://github.com/ree1s/dit-sr/blob/main/models/solvers.py"
    click MC10 "https://github.com/ree1s/dit-sr/blob/main/models/gaussian_diffusion.py"
    click MC11 "https://github.com/ree1s/dit-sr/blob/main/models/losses.py"
    click TR1 "https://github.com/ree1s/dit-sr/blob/main/trainer.py"
    click TR2 "https://github.com/ree1s/dit-sr/blob/main/basicsr/utils/dist_util.py"
    click TR3 "https://github.com/ree1s/dit-sr/blob/main/basicsr/utils/logger.py"
    click IF1 "https://github.com/ree1s/dit-sr/blob/main/sampler.py"
    click IF2 "https://github.com/ree1s/dit-sr/blob/main/inference.py"
    click EV1 "https://github.com/ree1s/dit-sr/blob/main/evaluate.py"
    click EV2 "https://github.com/ree1s/dit-sr/blob/main/test_realsr.sh"
    click EV3 "https://github.com/ree1s/dit-sr/blob/main/test_faceir.sh"
    click US1 "https://github.com/ree1s/dit-sr/blob/main/utils/util_common.py"
    click US2 "https://github.com/ree1s/dit-sr/blob/main/utils/util_image.py"
    click US3 "https://github.com/ree1s/dit-sr/blob/main/utils/util_net.py"
    click US4 "https://github.com/ree1s/dit-sr/blob/main/utils/util_sisr.py"

    %% Styles
    classDef data fill:#e0ffe0,stroke:#2d572c;
    classDef model fill:#e0e0ff,stroke:#22356f;
    classDef orchestrate fill:#ffe0b3,stroke:#b56a04;
    classDef inference fill:#f3e0ff,stroke:#6f2f9a;
    classDef external fill:#f2f2f2,stroke-dasharray: 5 5;
```
