# yulunzhang/rcan architecture

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

- Interactive diagram: https://gitdiagram.com/yulunzhang/rcan
- Repository: https://github.com/yulunzhang/rcan

## Overview

##### Overall Architecture Components
- Data Preparation & Preprocessing:
- Inputs include high-resolution (HR) training/test images and low-resolution (LR) images.
- MATLAB scripts (e.g., Prepare_TestData_HR_LR.m) convert or prepare the test datasets.
- External datasets such as DIV2K are mentioned in the README for training.
- Training Pipeline:
- Located in RCAN_TrainCode (with subdirectories for code, model, experiment, and scripts).
- The “code” folder includes modules for data handling (data utilities, dataloader), model definitions (RCAN and related architectures inside the model folder), loss functions (including adversarial, discriminator, VGG-based losses), trainer logic, and supporting utilities.
- Training scripts (e.g., TrainRCAN_scripts.sh) manage command-line execution and parameter settings.
- Testing/Inference Pipeline:
- Found in RCAN_TestCode (with similar subdirectory structure as training).
- Contains scripts for model inference, evaluation, and result saving.
- Evaluation scripts (Evaluate_PSNR_SSIM.m) and predicted results organized under SR directories.
- Model & Experiment Management:
- Pre-trained models are loaded from designated directories (e.g., experiment/model for training and model for testing).
- Both pipelines reference the same underlying RCAN model code with repeated modules in separate directories.
- External Libraries/Environment:
- PyTorch for model implementation.
- CUDA and cuDNN dependencies (as noted in the README and supported by the Dockerfile).
- MATLAB for specific evaluation tasks.
- Shell scripts facilitating execution and orchestration.

##### Relationships and Interactions
- Data flows from raw images (or prepared datasets) into the data loader modules in both training and testing pipelines.
- The training component integrates the model, loss, optimizer, and trainer modules – using a customized option module for experiment configuration.
- During inference, pre-trained models are loaded, and low-resolution images are processed through the network to generate high-resolution outputs. These outputs are subsequently post-processed and evaluated (both quantitatively with PSNR/SSIM and visually).
- The training and testing pipelines, though similar in structure, are logically separated; the training pipeline focuses on learning and model optimization, while the testing pipeline uses the frozen, pre-trained model for predictions.
- External services like image dataset repositories (DIV2K) or downloaded pre-trained model archives (from Dropbox, GoogleDrive, etc.) are integrated into the overall workflow.

##### Key Architectural Patterns and Principles
- Modular Design: Clear separation between model, data, training, and testing modules.
- Reusability: Similar folder structures in training and testing underline reuse of core components – especially the model architecture and loss functions.
- Scalability & Extensibility: Multiple degradation models (BI, BD) and the implementation of self-ensemble mechanisms (RCAN vs. RCAN+) suggest a design that allows easy extension to new SR modules or strategies.
- Layered Abstraction: Data handling, model definition, training loop, and evaluation are clearly demarcated.

##### Technologies, Frameworks, and Libraries Involved
- Python and MATLAB play crucial roles.
- PyTorch is the deep learning framework.
- CUDA and cuDNN for hardware acceleration.
- Shell scripting for automation (e.g., TestRCAN_scripts.sh, TrainRCAN_scripts.sh).
- Docker for an isolated environment.
- Standard Python modules for file handling, logging, and utility functions.

##### Final Recommendations to the Principal Software Engineer
- Within each pipeline block, further subdivide to display:
- Data Loader (pointing to “data” scripts)
- Model (with a note about RCAN’s use of residual and attention mechanisms)
- Loss functions and Trainer (for the training pipeline)
- Inference process and result output (for the testing pipeline)
- That each module such as “option”, “utility”, “script runner”, etc. is labeled or at least grouped under the appropriate pipeline block.
- Use annotations and legends to clarify technologies and components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External/Environment Subgraph
    subgraph "External/Environment"
        Ex1["Docker Environment (Dockerfile)"]:::external
        Ex2["PyTorch, CUDA & cuDNN"]:::external
        Ex3["MATLAB Environment"]:::external
    end

    %% Data Preparation & Preprocessing Subgraph
    subgraph "Data Preparation"
        D1["High-resolution & Low-resolution Images"]:::data
        D2["MATLAB Script: Prepare_TestData_HR_LR.m"]:::data
    end

    %% Training Pipeline Subgraph
    subgraph "Training Pipeline"
        T1["Training Code (RCAN_TrainCode/code)"]:::code
        T2["Trainer (trainer.py)"]:::code
        T3["Loss Functions (loss)"]:::code
        T4["Utility Functions (utility.py)"]:::code
        T5["Experiment Option (option.py)"]:::code
        T6["RCAN Model (Training) (rcan.py)"]:::model
        T7["Pre-trained Model & Experiment Data"]:::code
    end

    %% Testing/Inference Pipeline Subgraph
    subgraph "Testing Pipeline"
        Te1["Testing Code (RCAN_TestCode/code)"]:::code
        Te2["RCAN Model (Testing) (rcan.py)"]:::model
        Te3["Evaluation Script (Evaluate_PSNR_SSIM.m)"]:::evaluation
        Te4["SR Results Organization"]:::evaluation
    end

    %% Data Flow Connections
    D1 -->|"preprocess"| D2
    D2 -->|"training_input"| T1
    D2 -->|"inference_input"| Te1

    %% Training Pipeline Internal Flow
    T1 -->|"invoke"| T2
    T1 -->|"invoke"| T3
    T1 -->|"invoke"| T4
    T1 -->|"invoke"| T5
    T1 -->|"build"| T6
    T6 -->|"save_model"| T7

    %% Testing Pipeline Internal Flow
    Te1 -->|"load_pretrained_model"| Te2
    T7 -->|"provide_pretrained"| Te2
    Te2 -->|"generate_results"| Te4
    Te4 -->|"evaluate"| Te3

    %% External Dependencies Connections
    Ex1 ---|"supports"| T1
    Ex1 ---|"supports"| Te1
    Ex2 ---|"accelerates"| T6
    Ex2 ---|"accelerates"| Te2
    Ex3 ---|"evaluates"| Te3
    Ex3 ---|"assists"| D2

    %% Link between Core Model Definitions (Training and Testing)
    T6 ---|"shared architecture"| Te2

    %% Click Events for Component Mapping
    click D2 "https://github.com/yulunzhang/rcan/blob/master/RCAN_TestCode/Prepare_TestData_HR_LR.m"
    click T1 "https://github.com/yulunzhang/rcan/tree/master/RCAN_TrainCode/code"
    click T2 "https://github.com/yulunzhang/rcan/blob/master/RCAN_TrainCode/code/trainer.py"
    click T3 "https://github.com/yulunzhang/rcan/tree/master/RCAN_TrainCode/code/loss"
    click T4 "https://github.com/yulunzhang/rcan/blob/master/RCAN_TrainCode/code/utility.py"
    click T5 "https://github.com/yulunzhang/rcan/blob/master/RCAN_TrainCode/code/option.py"
    click T7 "https://github.com/yulunzhang/rcan/tree/master/RCAN_TrainCode/experiment/model"
    click T6 "https://github.com/yulunzhang/rcan/blob/master/RCAN_TrainCode/code/model/rcan.py"
    click Te1 "https://github.com/yulunzhang/rcan/tree/master/RCAN_TestCode/code"
    click Te2 "https://github.com/yulunzhang/rcan/blob/master/RCAN_TestCode/code/model/rcan.py"
    click Te3 "https://github.com/yulunzhang/rcan/blob/master/RCAN_TestCode/Evaluate_PSNR_SSIM.m"
    click Te4 "https://github.com/yulunzhang/rcan/tree/master/RCAN_TestCode/SR"

    %% Styles
    classDef external fill:#FFCC00,stroke:#333,stroke-width:2px
    classDef data fill:#A2D9CE,stroke:#333,stroke-width:2px
    classDef code fill:#AED6F1,stroke:#333,stroke-width:2px
    classDef model fill:#F5B7B1,stroke:#333,stroke-width:2px
    classDef evaluation fill:#D7BDE2,stroke:#333,stroke-width:2px
```
