# dachunkai/ev-deblurvsr architecture

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

- Interactive diagram: https://gitdiagram.com/dachunkai/ev-deblurvsr
- Repository: https://github.com/dachunkai/ev-deblurvsr

## Overview

##### Project type and purpose
- This is a research‐oriented, full-pipeline deep-learning application for “Event-Enhanced Blurry Video Super-Resolution.”
- It builds on the BasicSR framework, implements custom neural network architectures, and provides training/testing scripts, configuration files, and custom CUDA ops.

##### File structure
- Top-level code lives under the `basicsr/` package—split into subpackages for architectures (`archs/`), data handling (`data/`), models (`models/`), losses (`losses/`), metrics (`metrics/`), operations (`ops/`), utilities (`utils/`), plus entrypoints (`train.py`, `test.py`).
- Custom CUDA extensions are in `basicsr/ops/*/src/`.
- Configurations reside in `options/train/...` and `options/test/...` as YAML files.
- Shell scripts for distributed launch are in `scripts/`.
- Dockerfile, requirements, setup files support reproducibility and packaging.

##### Core components
a. Data Ingestion & Preparation
– Raw event & video data stored in HDF5 under `datasets/`
– Metadata files in `basicsr/data/meta_info/`
– Data sampler, transforms, prefetch dataloader
b. Model Architecture Layer
– Network modules defined in `basicsr/archs/evdeblurvsr_arch.py` plus helper architectures (SPyNet, VGG, deformable conv).
– Dynamic registry loading of backbone & event modules
c. Training & Inference Engine
– `train.py` / `test.py` drive the end-to-end loops
– Configuration loader reads YAML (options/) → builds datasets, models, optimizers, schedulers
– Loss computation (`basicsr/losses/`), metric evaluation (`basicsr/metrics/`)
– Checkpoint save / load (`basicsr/models/base_model.py`)
d. Custom CUDA Operations
– Deformable conv, fused activations, upfirdn2d under `basicsr/ops/`
– Exposed via Python wrappers for performance
e. External Interfaces & Packaging
– Command-line scripts (`scripts/dist_train.sh`, `scripts/dist_test.sh`) for multi-GPU
– Docker container environment
– Python packaging (`setup.py`, `setup.cfg`) for `pip install -e .`

##### Relationships and data-flow
1. Data source (HDF5) → Data transforms & sampler → PrefetchDataLoader
2. Batch → Model forward pass (event frames + blurry frames → SR output)
3. Output + ground truth → Loss modules → Scalar losses
4. Backward pass → Optimizer → Parameter update → Scheduler
5. During test: Model forward → Metric modules → Results saved to disk
6. Throughout: Custom CUDA ops accelerate convolutions and activations

##### Architectural patterns & design principles
- Modular ML-pipeline pattern: clear separation of data, model, loss, metric, utils
- Plugin/registry system for easy architecture extension
- Configuration-driven instantiation (YAML files)
- Reusable CUDA kernels packaged alongside Python code

##### Final checklist
– Components: Data, DataLoader & transforms, Model architectures, Loss & metrics, Training/test scripts, Custom CUDA ops, Configuration & Docker.
– Detail level: include subfolders (e.g., `archs/evdeblurvsr_arch.py`, `ops/dcn/`) to capture essential architecture.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Data Ingestion & Preparation"
        direction TB
        Datasets["datasets/"]:::data
        Meta["basicsr/data/meta_info/"]:::data
        Sampler["data_sampler.py"]:::data
        Transforms["transforms.py"]:::data
        Loader["prefetch_dataloader.py"]:::data
    end

    subgraph "Model Architecture Layer"
        direction TB
        EvArch["evdeblurvsr_arch.py"]:::model
        SPyNet["spynet_arch.py"]:::model
        VGG["vgg_arch.py"]:::model
        ArchUtil["arch_util.py"]:::model
        AttnUtil["attn_util.py"]:::model
        Registry["registry.py"]:::model
    end

    subgraph "Training & Inference Engine"
        direction TB
        Train["train.py"]:::engine
        Test["test.py"]:::engine
        BaseModel["base_model.py"]:::engine
        BlurModel["blurvsr_model.py"]:::engine
        Recurrent["video_recurrent_model.py"]:::engine
        SRUtil["sr_model.py"]:::engine
        LRSched["lr_scheduler.py"]:::engine
    end

    subgraph "Losses"
        direction TB
        BasicLoss["basic_loss.py"]:::loss
        GANLoss["gan_loss.py"]:::loss
        LossUtil["loss_util.py"]:::loss
    end

    subgraph "Metrics"
        direction TB
        PSNR["psnr_ssim.py"]:::metric
        LPIPS["lpips.py"]:::metric
        FID["fid.py"]:::metric
        NIQE["niqe.py"]:::metric
        MetricUtil["metric_util.py"]:::metric
    end

    subgraph "Custom CUDA Ops"
        direction TB
        DCN{"Deformable Conv"}:::ops
        DCNPy["deform_conv.py"]:::ops
        DCNSrc["dcn/src/"]:::ops
        Fused{"Fused Act"}:::ops
        FusedPy["fused_act.py"]:::ops
        FusedSrc["fused_act/src/"]:::ops
        UpDown{"upfirdn2d"}:::ops
        UpPy["upfirdn2d.py"]:::ops
        UpSrc["upfirdn2d/src/"]:::ops
    end

    subgraph "External Interfaces & Packaging"
        direction TB
        Scripts["scripts/"]:::scripts
        DistTrain["dist_train.sh"]:::scripts
        DistTest["dist_test.sh"]:::scripts
        Docker["docker/Dockerfile"]:::env
        Setup["setup.py"]:::scripts
        CFG["setup.cfg"]:::scripts
        Req["requirements.txt"]:::scripts
        TrainOpts["options/train/EvDeblurVSR/"]:::config
        TestOpts["options/test/EvDeblurVSR/"]:::config
    end

    %% Data flow
    Datasets --> Sampler --> Transforms --> Loader --> EvArch
    Loader --> SPyNet
    Loader --> VGG
    EvArch --> BasicLoss
    EvArch --> GANLoss
    EvArch --> PSNR
    EvArch --> LPIPS

    %% Training control flow
    Train --> Loader
    Train --> EvArch
    Train --> BasicLoss
    Train --> LRSched
    Train --> BaseModel
    Test --> EvArch
    Test --> MetricUtil
    Test --> PSNR
    Test --> FID

    %% CUDA ops connections
    DCNPy --> DCN
    DCNSrc --> DCN
    FusedPy --> Fused
    FusedSrc --> Fused
    UpPy --> UpDown
    UpSrc --> UpDown
    DCN --> EvArch
    Fused --> EvArch
    UpDown --> EvArch

    %% Scripts and packaging
    Scripts --> Train
    Scripts --> Test
    TrainOpts --> Train
    TestOpts --> Test
    Docker --> Train
    Docker --> Test

    %% Click Events
    click Datasets "https://github.com/dachunkai/ev-deblurvsr/tree/main/datasets/"
    click Meta "https://github.com/dachunkai/ev-deblurvsr/tree/main/basicsr/data/meta_info/"
    click Sampler "https://github.com/dachunkai/ev-deblurvsr/blob/main/basicsr/data/data_sampler.py"
    click Transforms "https://github.com/dachunkai/ev-deblurvsr/blob/main/basicsr/data/transforms.py"
    click Loader "https://github.com/dachunkai/ev-deblurvsr/blob/main/basicsr/data/prefetch_dataloader.py"
    click EvArch "https://github.com/dachunkai/ev-deblurvsr/blob/main/basicsr/archs/evdeblurvsr_arch.py"
    click SPyNet "https://github.com/dachunkai/ev-deblurvsr/blob/main/basicsr/archs/spynet_arch.py"
    click VGG "https://github.com/dachunkai/ev-deblurvsr/blob/main/basicsr/archs/vgg_arch.py"
    click ArchUtil "https://github.com/dachunkai/ev-deblurvsr/blob/main/basicsr/archs/arch_util.py"
    click AttnUtil "https://github.com/dachunkai/ev-deblurvsr/blob/main/basicsr/archs/attn_util.py"
    click Registry "https://github.com/dachunkai/ev-deblurvsr/blob/main/basicsr/utils/registry.py"
    click Train "https://github.com/dachunkai/ev-deblurvsr/blob/main/basicsr/train.py"
    click Test "https://github.com/dachunkai/ev-deblurvsr/blob/main/basicsr/test.py"
    click BaseModel "https://github.com/dachunkai/ev-deblurvsr/blob/main/basicsr/models/base_model.py"
    click BlurModel "https://github.com/dachunkai/ev-deblurvsr/blob/main/basicsr/models/blurvsr_model.py"
    click Recurrent "https://github.com/dachunkai/ev-deblurvsr/blob/main/basicsr/models/video_recurrent_model.py"
    click SRUtil "https://github.com/dachunkai/ev-deblurvsr/blob/main/basicsr/models/sr_model.py"
    click LRSched "https://github.com/dachunkai/ev-deblurvsr/blob/main/basicsr/models/lr_scheduler.py"
    click BasicLoss "https://github.com/dachunkai/ev-deblurvsr/blob/main/basicsr/losses/basic_loss.py"
    click GANLoss "https://github.com/dachunkai/ev-deblurvsr/blob/main/basicsr/losses/gan_loss.py"
    click LossUtil "https://github.com/dachunkai/ev-deblurvsr/blob/main/basicsr/losses/loss_util.py"
    click PSNR "https://github.com/dachunkai/ev-deblurvsr/blob/main/basicsr/metrics/psnr_ssim.py"
    click LPIPS "https://github.com/dachunkai/ev-deblurvsr/blob/main/basicsr/metrics/lpips.py"
    click FID "https://github.com/dachunkai/ev-deblurvsr/blob/main/basicsr/metrics/fid.py"
    click NIQE "https://github.com/dachunkai/ev-deblurvsr/blob/main/basicsr/metrics/niqe.py"
    click MetricUtil "https://github.com/dachunkai/ev-deblurvsr/blob/main/basicsr/metrics/metric_util.py"
    click DCNPy "https://github.com/dachunkai/ev-deblurvsr/blob/main/basicsr/ops/dcn/deform_conv.py"
    click DCNSrc "https://github.com/dachunkai/ev-deblurvsr/tree/main/basicsr/ops/dcn/src/"
    click FusedPy "https://github.com/dachunkai/ev-deblurvsr/blob/main/basicsr/ops/fused_act/fused_act.py"
    click FusedSrc "https://github.com/dachunkai/ev-deblurvsr/tree/main/basicsr/ops/fused_act/src/"
    click UpPy "https://github.com/dachunkai/ev-deblurvsr/blob/main/basicsr/ops/upfirdn2d/upfirdn2d.py"
    click UpSrc "https://github.com/dachunkai/ev-deblurvsr/tree/main/basicsr/ops/upfirdn2d/src/"
    click Scripts "https://github.com/dachunkai/ev-deblurvsr/tree/main/scripts/"
    click DistTrain "https://github.com/dachunkai/ev-deblurvsr/blob/main/scripts/dist_train.sh"
    click DistTest "https://github.com/dachunkai/ev-deblurvsr/blob/main/scripts/dist_test.sh"
    click Docker "https://github.com/dachunkai/ev-deblurvsr/tree/main/docker/Dockerfile"
    click Setup "https://github.com/dachunkai/ev-deblurvsr/blob/main/setup.py"
    click CFG "https://github.com/dachunkai/ev-deblurvsr/blob/main/setup.cfg"
    click Req "https://github.com/dachunkai/ev-deblurvsr/blob/main/requirements.txt"
    click TrainOpts "https://github.com/dachunkai/ev-deblurvsr/tree/main/options/train/EvDeblurVSR/"
    click TestOpts "https://github.com/dachunkai/ev-deblurvsr/tree/main/options/test/EvDeblurVSR/"

    %% Styles
    classDef data fill:#f9f,stroke:#333,stroke-width:1px
    classDef model fill:#bbf,stroke:#333,stroke-width:1px
    classDef engine fill:#fea,stroke:#333,stroke-width:1px
    classDef loss fill:#fdd,stroke:#333,stroke-width:1px
    classDef metric fill:#dfd,stroke:#333,stroke-width:1px
    classDef ops fill:#ffd,stroke:#333,stroke-width:1px
    classDef scripts fill:#eef,stroke:#333,stroke-width:1px
    classDef config fill:#cec,stroke:#333,stroke-width:1px
    classDef env fill:#ddd,stroke:#333,stroke-width:1px
```
