# cszn/usrnet architecture

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

- Interactive diagram: https://gitdiagram.com/cszn/usrnet
- Repository: https://github.com/cszn/usrnet

## Overview

##### Project type and purpose
- This is a research-oriented Python library for non-blind single image super-resolution (SISR) using a deep unfolding network (USRNet).
- It provides evaluation scripts, pretrained models, blur‐kernel definitions, and core modules: data‐term solver, ResUNet prior, and hyper-parameter MLP.

##### Top‐level file structure and architectural implications
- `main_*.py` scripts: entry points for different test scenarios (Table1, bicubic, real application) and model download.
- `models/`: contains network definitions (`network_usrnet.py`, `network_usrnet_v1.py`) and building block (`basicblock.py`).
- `utils/`: image I/O, kernel handling, deblurring and SISR helper functions, logging utilities.
- `kernels/`: MATLAB .mat files defining blur kernels (Gaussian, bicubic).
- `model_zoo/`: pretrained weights and their README.
- `testsets/`: input images grouped by dataset (Set5, Set_real).
- `figs/`: sample input/output visuals used in the paper and README.

##### Core components
a. **CLI & Orchestrator**
- Entry scripts (`main_test_*.py`, `main_download_pretrained_models.py`) parse arguments (LR image path, kernel file, scale factor, noise σ, iteration count).
- They load configuration and call the USRNet pipeline.
b. **Input layer**
- LR image loader (via `utils_image.py`)
- Blur kernel loader (via `utils_deblur.py` reading `.mat`)
- Noise level & scale factor parameters
c. **Hyper-parameter module (H)**
- A small MLP in `network_usrnet.py` that outputs per-iteration weights controlling data/prior fusion.
d. **Data module (D)**
- A closed-form solver for the data consistency subproblem (no trainable parameters).
e. **Prior module (P)**
- A ResUNet denoiser implemented in `network_usrnet.py` using building blocks from `basicblock.py`.
f. **Iteration loop**
- Fixed number of unfolding iterations (e.g., 8).
- In each iteration, feed current estimate into Data module D and Prior module P, combine via H’s outputs.
g. **Output & post-processing**
- Final HR image saved via `utils_image.py`
- PSNR/SSIM metrics computed (in test scripts) and logged via `utils_logger.py`.

##### External dependencies
- PyTorch (model definitions, tensor ops, DataParallel/DistributedDataParallel)
- SciPy (loading `.mat` blur kernels)
- NumPy (numerical ops)
- PIL/OpenCV (image read/write)

##### Relationships and data flow
- Side inputs: model weights loaded from `model_zoo/`; kernel files from `kernels/`; test images from `testsets/`.
- Configuration JSON (in KAIR training code, outside this repo) can be noted as an extension point.

##### Architectural patterns and design principles
- Modular decomposition: separation of data consistency (D), prior denoiser (P), hyper-parameter controller (H).
- Iterative unfolding: explicit loop structure in the pipeline.
- Extensibility: additional scripts can plug into the same pipeline; new kernels/models can be added to `kernels/` and `models/`.
- Configurability: CLI arguments drive behavior; MLP weights adapt to different scales/kernels/noise.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI & Orchestrator Layer
    subgraph "CLI & Orchestration" 
        direction TB
        CLI1["main_test_table1.py"]:::cli
        CLI2["main_test_bicubic.py"]:::cli
        CLI3["main_test_realapplication.py"]:::cli
        CLI4["main_download_pretrained_models.py"]:::cli
    end

    %% Input Layer
    subgraph "Input Layer" 
        direction TB
        IMG_LOAD["Image Loader\n(utils/utils_image.py)"]:::io
        KER_LOAD["Kernel Loader\n(utils/utils_deblur.py)"]:::io
        PARAM["Param Handler\n(utils/utils_sisr.py)"]:::io
    end

    %% Core Pipeline
    subgraph "Core Pipeline" 
        direction TB
        CTRL["Pipeline Controller\n(models/network_usrnet.py)"]:::core
        subgraph "Unfolding Loop (N iterations)"
            direction TB
            H["Hyper-parameter MLP (H)\n(models/network_usrnet.py)"]:::core
            D["Data Solver (D)\n(utils/utils_sisr.py)"]:::core
            P1["ResUNet Prior (P)\n(models/network_usrnet.py)"]:::core
            P2["BasicBlock\n(models/basicblock.py)"]:::core
            H -->|"weights"| D
            D -->|"estimate"| P1
            P1 -->|"feature"| D
            P1 -->|"res blocks"| P2
            P2 -->|"features"| P1
        end
    end

    %% Output & Post-processing
    subgraph "Output & Logging"
        direction TB
        SAVE["Image Saver\n(utils/utils_image.py)"]:::io
        LOG["Metrics Logger\n(utils/utils_logger.py)"]:::io
    end

    %% External Data Sources
    subgraph "Data Sources"
        direction TB
        K1["kernels_12.mat"]:::io
        K2["kernels_bicubicx234.mat"]:::io
        MZ["model_zoo/"]:::io
        TS["testsets/"]:::io
    end

    %% External Libraries
    subgraph "External Libraries"
        direction TB
        LIB1["PyTorch"]:::ext
        LIB2["SciPy"]:::ext
        LIB3["NumPy"]:::ext
        LIB4["PIL/OpenCV"]:::ext
    end

    %% Connections
    CLI1 --> IMG_LOAD
    CLI2 --> IMG_LOAD
    CLI3 --> IMG_LOAD
    CLI4 --> IMG_LOAD

    IMG_LOAD --> CTRL
    KER_LOAD --> CTRL
    PARAM --> CTRL

    K1 --> IMG_LOAD
    K2 --> IMG_LOAD
    TS --> IMG_LOAD
    MZ --> P1

    CTRL --> H
    CTRL --> D
    CTRL --> P1

    CTRL --> SAVE
    SAVE --> LOG

    %% External libs usage
    LIB1 --- CTRL
    LIB2 --- KER_LOAD
    LIB3 --- D
    LIB4 --- IMG_LOAD

    %% Click Events
    click CLI1 "https://github.com/cszn/usrnet/blob/master/main_test_table1.py"
    click CLI2 "https://github.com/cszn/usrnet/blob/master/main_test_bicubic.py"
    click CLI3 "https://github.com/cszn/usrnet/blob/master/main_test_realapplication.py"
    click CLI4 "https://github.com/cszn/usrnet/blob/master/main_download_pretrained_models.py"
    click IMG_LOAD "https://github.com/cszn/usrnet/blob/master/utils/utils_image.py"
    click KER_LOAD "https://github.com/cszn/usrnet/blob/master/utils/utils_deblur.py"
    click PARAM "https://github.com/cszn/usrnet/blob/master/utils/utils_sisr.py"
    click CTRL "https://github.com/cszn/usrnet/blob/master/models/network_usrnet.py"
    click H "https://github.com/cszn/usrnet/blob/master/models/network_usrnet.py"
    click D "https://github.com/cszn/usrnet/blob/master/utils/utils_sisr.py"
    click P1 "https://github.com/cszn/usrnet/blob/master/models/network_usrnet.py"
    click P2 "https://github.com/cszn/usrnet/blob/master/models/basicblock.py"
    click SAVE "https://github.com/cszn/usrnet/blob/master/utils/utils_image.py"
    click LOG "https://github.com/cszn/usrnet/blob/master/utils/utils_logger.py"
    click K1 "https://github.com/cszn/usrnet/blob/master/kernels/kernels_12.mat"
    click K2 "https://github.com/cszn/usrnet/blob/master/kernels/kernels_bicubicx234.mat"
    click MZ "https://github.com/cszn/usrnet/tree/master/model_zoo/"
    click TS "https://github.com/cszn/usrnet/tree/master/testsets/"

    %% Styles
    classDef cli fill:#c2f0c2,stroke:#333,stroke-width:1px;
    classDef core fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef io fill:#ffe6cc,stroke:#333,stroke-width:1px;
    classDef ext fill:#d9d9d9,stroke:#333,stroke-width:1px;
```
