# ifran-rahman/vcp-ir architecture

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

- Interactive diagram: https://gitdiagram.com/ifran-rahman/vcp-ir
- Repository: https://github.com/ifran-rahman/vcp-ir

## Overview

1. **Repository purpose and boundary**
   - This repo centers on **VCP-IR**, a PyTorch image restoration model for all-in-one restoration tasks such as deblurring, denoising, and deraining.
   - The core boundary is the `vcp_ir/` package; the top-level scripts (`train.py`, `evaluate.py`, `sanity_check.py`) are orchestration entry points around that package.

2. **Core model subsystem**
   - `vcp_ir/model.py` contains the main **VCP_IR_CBAM** architecture.
   - The model is described as a **Restormer-style hierarchical U-Net** with two key additions:
     - **Visual Conditioning Prompts (VCP)**: prompts derived from the degraded input itself.
     - **CBAM attention**: channel + spatial attention used inside the network.

3. **Model data path**
   - The input is a **degraded image**.
   - The model first derives a **visual embedding** from that input and uses it to condition decoder stages.
   - The output is a restored image prediction.
   - This creates a single forward path: degraded image → conditioned encoder/decoder features → restored image.

4. **Prompting and attention mechanism**
   - The VCP block acts as the main adaptive control mechanism: it converts visual information from the input into a conditioning signal that is injected into decoder stages.
   - CBAM refines intermediate features by emphasizing useful channels and spatial regions.
   - Architecturally, this means the network is not just a plain U-Net; decoder behavior is dynamically modulated by the input content.

5. **Dataset and preprocessing boundary**
   - `vcp_ir/dataset.py` provides the restoration dataset logic, named **BlurSharpDataset** in the README.
   - Data is expected in two parallel folders:
     - `degraded/` for input images
     - `gt/` for ground-truth clean images
   - Files are paired by **matching stem names**, so the dataset layer is responsible for image pairing, resizing, and batching-ready sample construction.

6. **Metrics and evaluation logic**
   - The dataset/utility layer also exposes **PSNR** and **SSIM** metrics.
   - These are used in evaluation to quantify restoration quality against the ground truth.
   - The evaluation script likely computes these metrics and also writes visual outputs for qualitative inspection.

7. **Loss subsystem**
   - `vcp_ir/losses.py` contains the training losses.
   - The README identifies the primary objective as:
     - **Charbonnier pixel loss**
     - plus **0.2 × Laplacian high-frequency L1 loss**
   - This means training optimizes both low-level pixel fidelity and edge/detail preservation.

8. **Training workflow**
   - `train.py` is the main experiment runner for model optimization.
   - It takes degraded/GT folders, image size, batch size, learning rate, patience, and checkpoint resume path.
   - The training boundary is: dataset loader → model forward pass → combined loss → optimizer/early stopping → checkpoint output.

9. **Evaluation and visualization workflow**
   - `evaluate.py` loads a trained checkpoint and runs inference over the paired dataset.
   - Outputs are saved as side-by-side comparison grids: **input | prediction | ground truth**.
   - This script is the main inference/reporting boundary for assessing model quality after training.

10. **Sanity and inspection utility**
   - `sanity_check.py` provides a quick forward-pass/model-summary style validation.
   - It is intended to verify the model shape compatibility and basic runtime behavior before full training.

11. **Downstream task analysis area**
   - The `Downstream_Task_Analysis/` folder contains separate subprojects for:
     - **Aerial_Image_Classificaiton**
     - **Cloud_Cover_Estimation**
   - These look like downstream evaluation or adaptation experiments rather than part of the core restoration pipeline.
   - Architecturally, they form a secondary branch of the repo focused on task-specific analysis around the learned representations.

12. **Technology stack and deployment shape**
   - The repo is built around **PyTorch** with image-folder based data loading and checkpoint-based training.
   - There is no sign of a service backend or distributed system; the architecture is a **local research/training pipeline** with standalone scripts and saved artifacts (`.pth` checkpoints, evaluation images).

Main entry points: [`train.py`](https://github.com/ifran-rahman/vcp-ir/blob/master/train.py) (Train), [`evaluate.py`](https://github.com/ifran-rahman/vcp-ir/blob/master/evaluate.py) (Evaluate), [`vcp_ir/model.py`](https://github.com/ifran-rahman/vcp-ir/blob/master/vcp_ir/model.py) (Model), [`Downstream_Task_Analysis/Aerial_Image_Classificaiton/Readme.md`](https://github.com/ifran-rahman/vcp-ir/blob/master/Downstream_Task_Analysis/Aerial_Image_Classificaiton/Readme.md) (Aerial classification)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core restoration"]
  node_train_script["Train<br/>entry script<br/>[train.py]"]
  node_eval_script["Evaluate<br/>entry script<br/>[evaluate.py]"]
  node_sanity_script["Sanity check<br/>entry script<br/>[sanity_check.py]"]
  node_pkg["vcp_ir<br/>[__init__.py]"]
  node_dataset["Dataset<br/>data loader<br/>[dataset.py]"]
  node_model_file{{"Model<br/>architecture<br/>[model.py]"}}
  node_losses["Losses<br/>objective<br/>[losses.py]"]
  node_paired_data[("Paired images<br/>dataset scheme")]
  node_vcp_arch{{"VCP-IR CBAM<br/>restoration model"}}
  node_prompts(("Visual prompts<br/>conditioning"))
  node_cbam(("CBAM<br/>attention"))
  node_metrics["PSNR/SSIM<br/>evaluation metrics"]
end

subgraph group_downstream["Downstream analysis"]
  node_air_root["Aerial classification<br/>downstream project<br/>[Readme.md]"]
  node_air_train["Class train<br/>training script<br/>[train.py]"]
  node_air_model{{"Class model<br/>classifier models<br/>[models.py]"}}
  node_air_test["Class test<br/>evaluation script<br/>[test.py]"]
  node_cloud_root["Cloud estimation<br/>downstream project<br/>[Readme.md]"]
  node_cloud_eval["Cloud eval<br/>analysis script<br/>[evaluate.py]"]
  node_cloud_metrics["Cloud metrics<br/>[cloud_metrics.py]"]
end

node_repo{{"VCP-IR<br/>repo root"}}

node_repo -->|"core package"| node_pkg
node_repo -->|"runs"| node_train_script
node_repo -->|"runs"| node_eval_script
node_repo -->|"runs"| node_sanity_script
node_train_script -->|"loads"| node_dataset
node_train_script -->|"optimizes"| node_model_file
node_train_script -->|"minimizes"| node_losses
node_eval_script -->|"loads"| node_dataset
node_eval_script -->|"inference"| node_model_file
node_eval_script -->|"scores"| node_metrics
node_sanity_script -->|"checks"| node_model_file
node_dataset -->|"pairs"| node_paired_data
node_model_file -->|"defines"| node_vcp_arch
node_vcp_arch -->|"conditions on"| node_prompts
node_vcp_arch -->|"refines with"| node_cbam
node_vcp_arch -->|"evaluated by"| node_metrics
node_air_root -->|"contains"| node_air_train
node_air_root -->|"contains"| node_air_model
node_air_root -->|"contains"| node_air_test
node_cloud_root -->|"contains"| node_cloud_eval
node_cloud_root -->|"contains"| node_cloud_metrics

click node_train_script "https://github.com/ifran-rahman/vcp-ir/blob/master/train.py"
click node_eval_script "https://github.com/ifran-rahman/vcp-ir/blob/master/evaluate.py"
click node_sanity_script "https://github.com/ifran-rahman/vcp-ir/blob/master/sanity_check.py"
click node_pkg "https://github.com/ifran-rahman/vcp-ir/blob/master/vcp_ir/__init__.py"
click node_dataset "https://github.com/ifran-rahman/vcp-ir/blob/master/vcp_ir/dataset.py"
click node_model_file "https://github.com/ifran-rahman/vcp-ir/blob/master/vcp_ir/model.py"
click node_losses "https://github.com/ifran-rahman/vcp-ir/blob/master/vcp_ir/losses.py"
click node_air_root "https://github.com/ifran-rahman/vcp-ir/blob/master/Downstream_Task_Analysis/Aerial_Image_Classificaiton/Readme.md"
click node_air_train "https://github.com/ifran-rahman/vcp-ir/blob/master/Downstream_Task_Analysis/Aerial_Image_Classificaiton/train.py"
click node_air_model "https://github.com/ifran-rahman/vcp-ir/blob/master/Downstream_Task_Analysis/Aerial_Image_Classificaiton/models.py"
click node_air_test "https://github.com/ifran-rahman/vcp-ir/blob/master/Downstream_Task_Analysis/Aerial_Image_Classificaiton/test.py"
click node_cloud_root "https://github.com/ifran-rahman/vcp-ir/blob/master/Downstream_Task_Analysis/Cloud_Cover_Estimation/Readme.md"
click node_cloud_eval "https://github.com/ifran-rahman/vcp-ir/blob/master/Downstream_Task_Analysis/Cloud_Cover_Estimation/evaluate.py"
click node_cloud_metrics "https://github.com/ifran-rahman/vcp-ir/blob/master/Downstream_Task_Analysis/Cloud_Cover_Estimation/src/cloud_metrics.py"

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_train_script,node_eval_script,node_sanity_script,node_pkg,node_dataset,node_model_file,node_losses,node_paired_data,node_vcp_arch,node_prompts,node_cbam,node_metrics toneBlue
class node_air_root,node_air_train,node_air_model,node_air_test,node_cloud_root,node_cloud_eval,node_cloud_metrics toneAmber
class node_repo toneNeutral
```

## Components

### Core restoration

Primary VCP-IR training and inference pipeline.

- [Train](https://github.com/ifran-rahman/vcp-ir/blob/master/train.py): entry script · Main training runner for restoration experiments. · `train.py`
- [Evaluate](https://github.com/ifran-rahman/vcp-ir/blob/master/evaluate.py): entry script · Loads checkpoints and runs restoration inference plus reporting. · `evaluate.py`
- [Sanity check](https://github.com/ifran-rahman/vcp-ir/blob/master/sanity_check.py): entry script · Quick forward-pass and shape validation utility. · `sanity_check.py`
- [vcp_ir](https://github.com/ifran-rahman/vcp-ir/blob/master/vcp_ir/__init__.py): package · Core package boundary for model, data, and loss logic. · `vcp_ir/__init__.py`
- [Dataset](https://github.com/ifran-rahman/vcp-ir/blob/master/vcp_ir/dataset.py): data loader · Pairs degraded and ground-truth images by stem name and prepares batches. · `vcp_ir/dataset.py`
- [Model](https://github.com/ifran-rahman/vcp-ir/blob/master/vcp_ir/model.py): architecture · Defines the VCP_IR_CBAM restoration network. · `vcp_ir/model.py`
- [Losses](https://github.com/ifran-rahman/vcp-ir/blob/master/vcp_ir/losses.py): objective · Training losses combining pixel fidelity and high-frequency detail preservation. · `vcp_ir/losses.py`
- **Paired images**: dataset scheme · Degraded input images matched with clean ground truth targets.
- **VCP-IR CBAM**: restoration model · Hierarchical U-Net-style restoration model with visual conditioning prompts and CBAM.
- **Visual prompts**: conditioning · Input-derived prompts that modulate decoder stages.
- **CBAM**: attention · Channel and spatial attention used to refine features.
- **PSNR/SSIM**: evaluation metrics · Restoration quality metrics used during evaluation.

### Downstream analysis

Task-specific experiments built around the learned representations.

- [Aerial classification](https://github.com/ifran-rahman/vcp-ir/blob/master/Downstream_Task_Analysis/Aerial_Image_Classificaiton/Readme.md): downstream project · Separate downstream task branch for aerial image classification. · `Downstream_Task_Analysis/Aerial_Image_Classificaiton/Readme.md`
- [Class train](https://github.com/ifran-rahman/vcp-ir/blob/master/Downstream_Task_Analysis/Aerial_Image_Classificaiton/train.py): training script · Training entry point for aerial classification experiments. · `Downstream_Task_Analysis/Aerial_Image_Classificaiton/train.py`
- [Class model](https://github.com/ifran-rahman/vcp-ir/blob/master/Downstream_Task_Analysis/Aerial_Image_Classificaiton/models.py): classifier models · Classification model definitions for the aerial task. · `Downstream_Task_Analysis/Aerial_Image_Classificaiton/models.py`
- [Class test](https://github.com/ifran-rahman/vcp-ir/blob/master/Downstream_Task_Analysis/Aerial_Image_Classificaiton/test.py): evaluation script · Testing or validation entry point for aerial classification. · `Downstream_Task_Analysis/Aerial_Image_Classificaiton/test.py`
- [Cloud estimation](https://github.com/ifran-rahman/vcp-ir/blob/master/Downstream_Task_Analysis/Cloud_Cover_Estimation/Readme.md): downstream project · Separate downstream task branch for cloud cover estimation. · `Downstream_Task_Analysis/Cloud_Cover_Estimation/Readme.md`
- [Cloud eval](https://github.com/ifran-rahman/vcp-ir/blob/master/Downstream_Task_Analysis/Cloud_Cover_Estimation/evaluate.py): analysis script · Evaluation entry point for cloud cover estimation. · `Downstream_Task_Analysis/Cloud_Cover_Estimation/evaluate.py`
- [Cloud metrics](https://github.com/ifran-rahman/vcp-ir/blob/master/Downstream_Task_Analysis/Cloud_Cover_Estimation/src/cloud_metrics.py): metrics · Task-specific metrics for cloud cover estimation. · `Downstream_Task_Analysis/Cloud_Cover_Estimation/src/cloud_metrics.py`

### Other components

- **VCP-IR**: repo root · PyTorch image restoration research repo centered on the VCP-IR model.

## Connections

- VCP-IR → vcp_ir: core package · The repository is organized around the vcp_ir package.
- VCP-IR → Train: runs · Primary training entry point.
- VCP-IR → Evaluate: runs · Primary inference and reporting entry point.
- VCP-IR → Sanity check: runs · Quick model validation entry point.
- Train → Dataset: loads · Training consumes paired restoration data.
- Train → Model: optimizes · Training forwards data through the restoration model.
- Train → Losses: minimizes · Training uses the composite restoration loss.
- Evaluate → Dataset: loads · Evaluation uses the same paired dataset structure.
- Evaluate → Model: inference · Evaluation restores images with a trained checkpoint.
- Evaluate → PSNR/SSIM: scores · Evaluation reports PSNR and SSIM.
- Sanity check → Model: checks · Sanity script validates model construction and shapes.
- Dataset → Paired images: pairs · Dataset pairs degraded and clean images by matching stems.
- Model → VCP-IR CBAM: defines · Implements the main VCP-IR CBAM architecture.
- VCP-IR CBAM → Visual prompts: conditions on · Decoder stages are modulated by input-derived visual prompts.
- VCP-IR CBAM → CBAM: refines with · Intermediate features are enhanced by channel/spatial attention.
- VCP-IR CBAM → PSNR/SSIM: evaluated by · Restoration output is judged using quality metrics.
- Aerial classification → Class train: contains · Aerial analysis project includes its own training entry.
- Aerial classification → Class model: contains · Classification models live in the aerial project.
- Aerial classification → Class test: contains · Aerial project includes a test/validation script.
- Cloud estimation → Cloud eval: contains · Cloud cover project centers on evaluation.
- Cloud estimation → Cloud metrics: contains · Cloud project provides task-specific metrics.