# swz30/restormer architecture

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

- Interactive diagram: https://gitdiagram.com/swz30/restormer
- Repository: https://github.com/swz30/restormer

## Overview

1. **What this repo is**
   This is a multi-task image restoration codebase built around the **Restormer** architecture. The repository is organized by restoration problem domain: **deraining, motion deblurring, defocus deblurring, and denoising**. Each task has its own entry scripts, configs, dataset notes, and pretrained models, but they all share the same core training/inference framework.

2. **Main architectural split**
   The repo has two layers:
   - **Task-specific packages** in `Deraining/`, `Motion_Deblurring/`, `Defocus_Deblurring/`, and `Denoising/`
   - A shared **framework layer** in `basicsr/`
   
   The task folders mostly define options, download/preprocess utilities, evaluation scripts, and per-task test entrypoints. The shared `basicsr` package contains the reusable dataset loaders, model implementations, losses, metrics, logging, and utilities.

3. **Core model layer**
   The actual neural network lives in `basicsr/models/archs/restormer_arch.py`. The model is used through the BasicSR-style model wrapper in `basicsr/models/image_restoration_model.py`, with common training behavior provided by `base_model.py`.
   
   This means the architecture is not “task code = model code”; instead, the model is isolated in the shared framework and reused across all restoration tasks via configuration.

4. **Configuration-driven execution**
   The repository is heavily **YAML-configured**. Each task folder has an `Options/` directory containing one or more experiment configs, such as:
   - single-image vs dual-pixel defocus deblurring
   - grayscale vs color denoising
   - different Gaussian noise levels
   - real vs synthetic denoising
   
   These configs select dataset type, network settings, training schedule, losses, and evaluation behavior. The architecture is therefore controlled primarily by experiment files rather than hardcoded task branches.

5. **Data loading boundary**
   Dataset logic is centralized in `basicsr/data/`. Important loaders include:
   - `paired_image_dataset.py` for aligned input/target restoration pairs
   - `single_image_dataset.py` for single-image input pipelines
   - `video_test_dataset.py` for video benchmark style evaluation
   - `reds_dataset.py`, `vimeo90k_dataset.py`, and `ffhq_dataset.py` for benchmark-specific datasets
   
   Task folders reference these datasets through their YAML options. This creates a clean boundary: task scripts do not implement data loading themselves; they call into BasicSR dataset abstractions.

6. **Training flow**
   Training starts from `basicsr/train.py`, with shared support from:
   - `basicsr/utils/options.py` for parsing experiment configs
   - `basicsr/data/prefetch_dataloader.py` and `data_sampler.py` for loading/sharding
   - `basicsr/models/lr_scheduler.py` for optimization scheduling
   - `basicsr/models/losses/` for training objectives
   
   The training pipeline is therefore: config → dataset → model wrapper → Restormer architecture → losses/optimizer/scheduler. The task folder only chooses the specific config and data source.

7. **Inference and evaluation flow**
   The shared inference entrypoint is `basicsr/test.py`, while each task also provides task-specific test scripts such as:
   - `Motion_Deblurring/test.py`
   - `Deraining/test.py`
   - `Denoising/test_*.py`
   - `Defocus_Deblurring/test_*.py`
   
   Evaluation commonly computes **PSNR/SSIM** through `basicsr/metrics/psnr_ssim.py`. Some tasks also include benchmark-specific MATLAB evaluation scripts, such as `evaluate_sidd.m` and `evaluate_PSNR_SSIM.m`, indicating that official benchmark scoring is part of the workflow for certain datasets.

8. **Task-specific preprocessing and dataset preparation**
   Each task directory includes scripts to fetch or prepare data:
   - `download_data.py` for dataset acquisition
   - patch-generation scripts like `generate_patches_gopro.py`, `generate_patches_sidd.py`, `generate_patches_dpdd.py`, and `generate_patches_dfwb.py`
   
   This shows a two-stage data pipeline in some tasks: raw benchmark data is downloaded, then patch extraction/preprocessing creates training-ready samples. The generated patches feed the shared dataset loaders.

9. **Metrics, utilities, and benchmark support**
   The `basicsr/metrics/` and `basicsr/utils/` packages provide the infrastructure around the model:
   - image-quality metrics like PSNR, SSIM, NIQE, and FID
   - file and LMDB utilities
   - logging, distributed training helpers, image conversion utilities
   - submission bundling and MATLAB interoperability helpers
   
   These are not the model itself, but they are essential to the architecture because they support training at scale, benchmark evaluation, and reproducible result packaging.

10. **Demo and pretrained inference path**
   The root-level `demo.py` provides a unified command-line inference path for user images. It routes input images from `demo/degraded/` to outputs under `demo/restored/`, using pretrained weights stored under each task’s `pretrained_models/` directory.
   
   This demo path is separate from benchmark evaluation: it is a lightweight deployment-style flow for running a chosen restoration task on arbitrary images.

11. **External dependencies and framework provenance**
   The repository is built on **BasicSR** and references ideas from **HINet**. That matters architecturally because the codebase inherits a standard restoration-framework structure: dataset registries, model registries, option parsing, metric utilities, and distributed training support. The repo is therefore best understood as a task-adapted specialization of a general-purpose restoration framework.

12. **How to draw the architecture diagram**
   A correct diagram should show:
   - task folders at the edge as experiment wrappers
   - shared `basicsr` framework in the center
   - YAML options feeding train/test/demo entrypoints
   - datasets and preprocessing scripts feeding the data loaders
   - Restormer model at the core of `basicsr/models/archs`
   - metrics/evaluation scripts as the output/assessment layer
   - pretrained models and demo assets as the inference side path

Main entry points: [`basicsr/test.py`](https://github.com/swz30/restormer/blob/main/basicsr/test.py) (Test), [`basicsr/models/image_restoration_model.py`](https://github.com/swz30/restormer/blob/main/basicsr/models/image_restoration_model.py) (Model wrapper), [`basicsr/train.py`](https://github.com/swz30/restormer/blob/main/basicsr/train.py) (Train), [`basicsr/data/paired_image_dataset.py`](https://github.com/swz30/restormer/blob/main/basicsr/data/paired_image_dataset.py) (Data loaders)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_task_deraining["Deraining"]
  node_deraining_options["Deraining YAML<br/>experiment config"]
  node_deraining_test["Deraining test<br/>eval entrypoint<br/>[test.py]"]
  node_deraining_prep["Rain data<br/>data prep<br/>[download_data.py]"]
  node_deraining_metrics["PSNR/SSIM eval<br/>benchmark metric"]
end

subgraph group_task_motion["Motion Deblur"]
  node_motion_options["Deblur YAML<br/>experiment config"]
  node_motion_test["Deblur test<br/>eval entrypoint<br/>[test.py]"]
  node_motion_prep["GoPro data<br/>data prep"]
  node_motion_eval["Deblur eval<br/>benchmark eval"]
end

subgraph group_task_defocus["Defocus Deblur"]
  node_defocus_options["Defocus YAML<br/>experiment config"]
  node_defocus_test["Defocus test<br/>eval entrypoint"]
  node_defocus_prep["DPDD prep<br/>data prep"]
end

subgraph group_task_denoising["Denoising"]
  node_denoise_options["Denoise YAML<br/>experiment config"]
  node_denoise_test["Denoise tests<br/>eval entrypoint"]
  node_denoise_prep["Denoise data<br/>data prep"]
end

subgraph group_core_framework["BasicSR core"]
  node_train_entry["Train<br/>shared entrypoint<br/>[train.py]"]
  node_test_entry["Test<br/>shared entrypoint<br/>[test.py]"]
  node_options_parser["Options<br/>config parser<br/>[options.py]"]
  node_data_loaders[("Data loaders<br/>dataset layer")]
  node_restormer_arch["Restormer<br/>nn architecture<br/>[restormer_arch.py]"]
  node_restoration_model["Model wrapper<br/>training wrapper"]
  node_losses_sched["Losses + sched<br/>optimization<br/>[losses.py]"]
  node_metrics_utils(("Metrics + utils<br/>eval infra<br/>[psnr_ssim.py]"))
end

subgraph group_demo_path["Demo"]
  node_demo_script["Demo<br/>inference entrypoint<br/>[demo.py]"]
  node_demo_assets[("Demo assets<br/>input/output assets")]
  node_pretrained_models[("Pretrained models<br/>weights")]
end

node_deraining_options -->|"configure"| node_train_entry
node_deraining_options -->|"configure"| node_test_entry
node_deraining_test -->|"wraps"| node_test_entry
node_deraining_prep -->|"feeds"| node_data_loaders
node_deraining_test -->|"scores"| node_deraining_metrics
node_motion_options -->|"configure"| node_train_entry
node_motion_options -->|"configure"| node_test_entry
node_motion_test -->|"wraps"| node_test_entry
node_motion_prep -->|"feeds"| node_data_loaders
node_motion_test -->|"scores"| node_motion_eval
node_defocus_options -->|"configure"| node_train_entry
node_defocus_options -->|"configure"| node_test_entry
node_defocus_test -->|"wraps"| node_test_entry
node_defocus_prep -->|"feeds"| node_data_loaders
node_denoise_options -->|"configure"| node_train_entry
node_denoise_options -->|"configure"| node_test_entry
node_denoise_test -->|"wraps"| node_test_entry
node_denoise_prep -->|"feeds"| node_data_loaders
node_options_parser -->|"parses"| node_train_entry
node_options_parser -->|"parses"| node_test_entry
node_train_entry -->|"loads"| node_data_loaders
node_train_entry -->|"builds"| node_restoration_model
node_restoration_model -->|"runs"| node_restormer_arch
node_restoration_model -->|"optimizes"| node_losses_sched
node_test_entry -->|"loads"| node_restoration_model
node_restoration_model -->|"evaluates"| node_metrics_utils
node_demo_script -->|"reads/writes"| node_demo_assets
node_demo_script -->|"loads"| node_pretrained_models
node_demo_script -->|"invokes"| node_restoration_model
node_restoration_model -->|"logs"| node_metrics_utils

click node_deraining_options "https://github.com/swz30/restormer/blob/main/Deraining/Options/Deraining_Restormer.yml"
click node_deraining_test "https://github.com/swz30/restormer/blob/main/Deraining/test.py"
click node_deraining_prep "https://github.com/swz30/restormer/blob/main/Deraining/download_data.py"
click node_deraining_metrics "https://github.com/swz30/restormer/blob/main/Deraining/evaluate_PSNR_SSIM.m"
click node_motion_options "https://github.com/swz30/restormer/blob/main/Motion_Deblurring/Options/Deblurring_Restormer.yml"
click node_motion_test "https://github.com/swz30/restormer/blob/main/Motion_Deblurring/test.py"
click node_motion_prep "https://github.com/swz30/restormer/blob/main/Motion_Deblurring/generate_patches_gopro.py"
click node_motion_eval "https://github.com/swz30/restormer/blob/main/Motion_Deblurring/evaluate_realblur.py"
click node_defocus_options "https://github.com/swz30/restormer/blob/main/Defocus_Deblurring/Options/DefocusDeblur_Single_8bit_Restormer.yml"
click node_defocus_test "https://github.com/swz30/restormer/blob/main/Defocus_Deblurring/test_single_image_defocus_deblur.py"
click node_defocus_prep "https://github.com/swz30/restormer/blob/main/Defocus_Deblurring/generate_patches_dpdd.py"
click node_denoise_options "https://github.com/swz30/restormer/blob/main/Denoising/Options/RealDenoising_Restormer.yml"
click node_denoise_test "https://github.com/swz30/restormer/blob/main/Denoising/test_real_denoising_sidd.py"
click node_denoise_prep "https://github.com/swz30/restormer/blob/main/Denoising/generate_patches_sidd.py"
click node_train_entry "https://github.com/swz30/restormer/blob/main/basicsr/train.py"
click node_test_entry "https://github.com/swz30/restormer/blob/main/basicsr/test.py"
click node_options_parser "https://github.com/swz30/restormer/blob/main/basicsr/utils/options.py"
click node_data_loaders "https://github.com/swz30/restormer/blob/main/basicsr/data/paired_image_dataset.py"
click node_restormer_arch "https://github.com/swz30/restormer/blob/main/basicsr/models/archs/restormer_arch.py"
click node_restoration_model "https://github.com/swz30/restormer/blob/main/basicsr/models/image_restoration_model.py"
click node_losses_sched "https://github.com/swz30/restormer/blob/main/basicsr/models/losses/losses.py"
click node_metrics_utils "https://github.com/swz30/restormer/blob/main/basicsr/metrics/psnr_ssim.py"
click node_demo_script "https://github.com/swz30/restormer/blob/main/demo.py"
click node_demo_assets "https://github.com/swz30/restormer/tree/main/demo/degraded"
click node_pretrained_models "https://github.com/swz30/restormer/tree/main/Motion_Deblurring/pretrained_models"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_deraining_options,node_deraining_test,node_deraining_prep,node_deraining_metrics toneBlue
class node_motion_options,node_motion_test,node_motion_prep,node_motion_eval toneAmber
class node_defocus_options,node_defocus_test,node_defocus_prep toneMint
class node_denoise_options,node_denoise_test,node_denoise_prep toneRose
class node_train_entry,node_test_entry,node_options_parser,node_data_loaders,node_restormer_arch,node_restoration_model,node_losses_sched,node_metrics_utils toneIndigo
class node_demo_script,node_demo_assets,node_pretrained_models toneTeal
```

## Components

### Deraining

Task wrapper for rain removal experiments and benchmark evaluation.

- [Deraining YAML](https://github.com/swz30/restormer/blob/main/Deraining/Options/Deraining_Restormer.yml): experiment config · Task-specific YAML options for deraining runs. · `Deraining/Options/Deraining_Restormer.yml`
- [Deraining test](https://github.com/swz30/restormer/blob/main/Deraining/test.py): eval entrypoint · Task-specific benchmark inference script. · `Deraining/test.py`
- [Rain data](https://github.com/swz30/restormer/blob/main/Deraining/download_data.py): data prep · Dataset download and preparation for deraining benchmarks. · `Deraining/download_data.py`
- [PSNR/SSIM eval](https://github.com/swz30/restormer/blob/main/Deraining/evaluate_PSNR_SSIM.m): benchmark metric · MATLAB evaluation script for deraining results. · `Deraining/evaluate_PSNR_SSIM.m`

### Motion Deblur

Task wrapper for motion deblurring experiments and benchmark evaluation.

- [Deblur YAML](https://github.com/swz30/restormer/blob/main/Motion_Deblurring/Options/Deblurring_Restormer.yml): experiment config · Task-specific YAML options for motion deblurring runs. · `Motion_Deblurring/Options/Deblurring_Restormer.yml`
- [Deblur test](https://github.com/swz30/restormer/blob/main/Motion_Deblurring/test.py): eval entrypoint · Task-specific benchmark inference script. · `Motion_Deblurring/test.py`
- [GoPro data](https://github.com/swz30/restormer/blob/main/Motion_Deblurring/generate_patches_gopro.py): data prep · Dataset download and patch generation for motion deblurring. · `Motion_Deblurring/generate_patches_gopro.py`
- [Deblur eval](https://github.com/swz30/restormer/blob/main/Motion_Deblurring/evaluate_realblur.py): benchmark eval · Benchmark evaluation for GoPro/RealBlur-style results. · `Motion_Deblurring/evaluate_realblur.py`

### Defocus Deblur

Task wrapper for defocus deblurring experiments and benchmark evaluation.

- [Defocus YAML](https://github.com/swz30/restormer/blob/main/Defocus_Deblurring/Options/DefocusDeblur_Single_8bit_Restormer.yml): experiment config · Task-specific YAML options for single-image and dual-pixel defocus deblurring. · `Defocus_Deblurring/Options/DefocusDeblur_Single_8bit_Restormer.yml`
- [Defocus test](https://github.com/swz30/restormer/blob/main/Defocus_Deblurring/test_single_image_defocus_deblur.py): eval entrypoint · Task-specific inference script for defocus restoration. · `Defocus_Deblurring/test_single_image_defocus_deblur.py`
- [DPDD prep](https://github.com/swz30/restormer/blob/main/Defocus_Deblurring/generate_patches_dpdd.py): data prep · Dataset download and patch generation for defocus deblurring. · `Defocus_Deblurring/generate_patches_dpdd.py`

### Denoising

Task wrapper for synthetic and real denoising experiments.

- [Denoise YAML](https://github.com/swz30/restormer/blob/main/Denoising/Options/RealDenoising_Restormer.yml): experiment config · Task-specific YAML options for Gaussian and real denoising variants. · `Denoising/Options/RealDenoising_Restormer.yml`
- [Denoise tests](https://github.com/swz30/restormer/blob/main/Denoising/test_real_denoising_sidd.py): eval entrypoint · Task-specific inference scripts for Gaussian and real denoising. · `Denoising/test_real_denoising_sidd.py`
- [Denoise data](https://github.com/swz30/restormer/blob/main/Denoising/generate_patches_sidd.py): data prep · Dataset download and patch generation for denoising benchmarks. · `Denoising/generate_patches_sidd.py`

### BasicSR core

Shared training, data, model, metric, and utility framework.

- [Train](https://github.com/swz30/restormer/blob/main/basicsr/train.py): shared entrypoint · Shared training driver for all restoration tasks. · `basicsr/train.py`
- [Test](https://github.com/swz30/restormer/blob/main/basicsr/test.py): shared entrypoint · Shared inference driver for evaluation and batch testing. · `basicsr/test.py`
- [Options](https://github.com/swz30/restormer/blob/main/basicsr/utils/options.py): config parser · YAML experiment option parsing and runtime setup. · `basicsr/utils/options.py`
- [Data loaders](https://github.com/swz30/restormer/blob/main/basicsr/data/paired_image_dataset.py): dataset layer · Paired, single-image, video, and benchmark dataset abstractions. · `basicsr/data/paired_image_dataset.py`
- [Restormer](https://github.com/swz30/restormer/blob/main/basicsr/models/archs/restormer_arch.py): nn architecture · Core image restoration network implementation. · `basicsr/models/archs/restormer_arch.py`
- [Model wrapper](https://github.com/swz30/restormer/blob/main/basicsr/models/image_restoration_model.py): training wrapper · BasicSR image restoration model orchestration. · `basicsr/models/image_restoration_model.py`
- [Losses + sched](https://github.com/swz30/restormer/blob/main/basicsr/models/losses/losses.py): optimization · Training losses and learning-rate scheduling. · `basicsr/models/losses/losses.py`
- [Metrics + utils](https://github.com/swz30/restormer/blob/main/basicsr/metrics/psnr_ssim.py): eval infra · PSNR/SSIM, NIQE, FID, logging, distributed, and packaging utilities. · `basicsr/metrics/psnr_ssim.py`

### Demo

Lightweight inference path for arbitrary degraded images.

- [Demo](https://github.com/swz30/restormer/blob/main/demo.py): inference entrypoint · Standalone CLI inference for user-provided degraded images. · `demo.py`
- [Demo assets](https://github.com/swz30/restormer/tree/main/demo/degraded): input/output assets · Input degraded images and restored outputs for demo inference. · `demo/degraded`
- [Pretrained models](https://github.com/swz30/restormer/tree/main/Motion_Deblurring/pretrained_models): weights · Task-specific pretrained checkpoints used for inference. · `Motion_Deblurring/pretrained_models`

## Connections

- Deraining YAML → Train: configure · Deraining YAML drives shared training.
- Deraining YAML → Test: configure · Deraining YAML drives shared evaluation.
- Deraining test → Test: wraps · Task-specific test script delegates to shared test flow.
- Rain data → Data loaders: feeds · Prepared benchmark data is consumed by shared datasets.
- Deraining test → PSNR/SSIM eval: scores · Task evaluation uses PSNR/SSIM benchmark scoring.
- Deblur YAML → Train: configure · Motion deblurring YAML drives shared training.
- Deblur YAML → Test: configure · Motion deblurring YAML drives shared evaluation.
- Deblur test → Test: wraps · Task-specific test script delegates to shared test flow.
- GoPro data → Data loaders: feeds · Generated patches and downloaded data feed shared loaders.
- Deblur test → Deblur eval: scores · Task evaluation runs benchmark-specific scoring.
- Defocus YAML → Train: configure · Defocus YAML drives shared training.
- Defocus YAML → Test: configure · Defocus YAML drives shared evaluation.
- Defocus test → Test: wraps · Task-specific test script delegates to shared test flow.
- DPDD prep → Data loaders: feeds · Prepared defocus patches feed shared loaders.
- Denoise YAML → Train: configure · Denoising YAML drives shared training.
- Denoise YAML → Test: configure · Denoising YAML drives shared evaluation.
- Denoise tests → Test: wraps · Task-specific test scripts delegate to shared test flow.
- Denoise data → Data loaders: feeds · Prepared denoising patches feed shared loaders.
- Options → Train: parses · Training starts by parsing experiment options.
- Options → Test: parses · Inference starts by parsing experiment options.
- Train → Data loaders: loads · Training uses shared dataset abstractions.
- Train → Model wrapper: builds · Training instantiates the shared restoration model wrapper.
- Model wrapper → Restormer: runs · Model wrapper executes the Restormer network.
- Model wrapper → Losses + sched: optimizes · Wrapper coordinates losses and learning-rate scheduling.
- Test → Model wrapper: loads · Inference loads the shared restoration model wrapper.
- Model wrapper → Metrics + utils: evaluates · Model outputs are assessed with shared metrics and utilities.
- Demo → Demo assets: reads/writes · Demo consumes degraded images and writes restored outputs.
- Demo → Pretrained models: loads · Demo uses pretrained task checkpoints.
- Demo → Model wrapper: invokes · Demo routes inference through the shared model wrapper.
- Model wrapper → Metrics + utils: logs · Shared utilities support logging, packaging, and benchmark exports.
