How swz30/restormer works
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: test.py Test · image_restoration_model.py Model wrapper · train.py Train · paired_image_dataset.py Data loaders
Components 25
Deraining
Task wrapper for rain removal experiments and benchmark evaluation.
- Deraining YAML · Task-specific YAML options for deraining runs.
Deraining/Options/Deraining_Restormer.yml - Deraining test · Task-specific benchmark inference script.
Deraining/test.py - Rain data · Dataset download and preparation for deraining benchmarks.
Deraining/download_data.py - PSNR/SSIM eval · MATLAB evaluation script for deraining results.
Deraining/evaluate_PSNR_SSIM.m
Motion Deblur
Task wrapper for motion deblurring experiments and benchmark evaluation.
- Deblur YAML · Task-specific YAML options for motion deblurring runs.
Motion_Deblurring/Options/Deblurring_Restormer.yml - Deblur test · Task-specific benchmark inference script.
Motion_Deblurring/test.py - GoPro data · Dataset download and patch generation for motion deblurring.
Motion_Deblurring/generate_patches_gopro.py - Deblur 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 · Task-specific YAML options for single-image and dual-pixel defocus deblurring.
Defocus_Deblurring/Options/DefocusDeblur_Single_8bit_Restormer.yml - Defocus test · Task-specific inference script for defocus restoration.
Defocus_Deblurring/test_single_image_defocus_deblur.py - DPDD 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 · Task-specific YAML options for Gaussian and real denoising variants.
Denoising/Options/RealDenoising_Restormer.yml - Denoise tests · Task-specific inference scripts for Gaussian and real denoising.
Denoising/test_real_denoising_sidd.py - Denoise data · Dataset download and patch generation for denoising benchmarks.
Denoising/generate_patches_sidd.py
BasicSR core
Shared training, data, model, metric, and utility framework.
- Train · Shared training driver for all restoration tasks.
basicsr/train.py - Test · Shared inference driver for evaluation and batch testing.
basicsr/test.py - Options · YAML experiment option parsing and runtime setup.
basicsr/utils/options.py - Data loaders · Paired, single-image, video, and benchmark dataset abstractions.
basicsr/data/paired_image_dataset.py - Restormer · Core image restoration network implementation.
basicsr/models/archs/restormer_arch.py - Model wrapper · BasicSR image restoration model orchestration.
basicsr/models/image_restoration_model.py - Losses + sched · Training losses and learning-rate scheduling.
basicsr/models/losses/losses.py - Metrics + utils · PSNR/SSIM, NIQE, FID, logging, distributed, and packaging utilities.
basicsr/metrics/psnr_ssim.py
Demo
Lightweight inference path for arbitrary degraded images.
- Demo · Standalone CLI inference for user-provided degraded images.
demo.py - Demo assets · Input degraded images and restored outputs for demo inference.
demo/degraded - Pretrained models · Task-specific pretrained checkpoints used for inference.
Motion_Deblurring/pretrained_models
Connections 30
- 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.