# zzh-tech/estrnn architecture

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

- Interactive diagram: https://gitdiagram.com/zzh-tech/estrnn
- Repository: https://github.com/zzh-tech/estrnn

## Overview

##### Project Type and Purpose
- This is a research‐grade machine‐learning codebase for video deblurring using an Efficient Spatio‐Temporal Recurrent Neural Network (ESTRNN) and associated dataset (BSD, GOPRO, REDS).
- It provides:
- Data loading and preprocessing for synthetic and real‐world deblurring datasets
- Model definitions for multiple RNN‐based architectures
- Training scripts (single‐GPU, data‐parallel, distributed) with configurable hyperparameters
- Inference scripts to apply trained checkpoints to blurry videos
- Utilities for logging, metrics, and parameter management

##### High‐Level Components (
a. CLI / Orchestration Layer
- main.py (entry point for training & testing)
- inference.py (entry point for standalone video inference)
b. Data Layer
- data/ (dataset classes and utilities)
- External storage: LMDB, raw image folders, Google Drive or local dataset root
c. Model Layer
- model/ (network architectures: ESTRNN.py, STRCNN.py, SRN.py, etc.; attention, arches, model.py)
d. Training Engine
- train/
- dp.py (single‐machine data‐parallel)
- ddp.py (multi‐GPU distributed)
- trainer.py (training loop orchestration)
- loss.py, optimizer.py, metrics.py, utils.py
e. Inference Engine
- inference.py
- Loading checkpoints, reading frames from src, writing results to dst
f. Configuration and Parameters
- para/parameter.py (default hyperparameters, dataset configs)
g. Utilities
- utils/logger.py (logging, tensorboard sync)

##### Relationships & Data Flow
- CLI → Configuration
- Parse flags (dataset root, model type, learning rate, batch size, trainer_mode)
- Configuration → Data Layer
- Instantiate dataset (BSD, GOPRO, REDS) via data/*.py
- Data Layer → Training Engine
- DataLoader yields batches to trainer
- Training Engine ↔ Model Layer
- Forward pass, compute loss, backprop, optimizer step
- Training Engine → Utilities
- Log losses/metrics to console and tensorboard
- Training Engine → Storage
- Save checkpoints to ./checkpoints/
- Inference Engine → Model Layer
- Load checkpoint, run forward pass on video frames
- Inference Engine → Storage
- Write deblurred frames/video to dst

##### Key Architectural Patterns & Principles
- Modular separation: data ingestion, model definition, training logic, inference logic, configuration
- Pluggable architectures: arches.py to select network topology at runtime
- Data‐parallel & Distributed training support (dp.py, ddp.py)
- Clear parameterization: central parameter module for experiment reproducibility

##### Technologies & Frameworks to Annotate
- Python 3.6+
- PyTorch 1.6+ (nn.Module, DataLoader, DistributedDataParallel)
- LMDB (dataset storage)
- OpenCV, scikit‐image (image I/O & processing)
- thop (model complexity profiling)
- tqdm (progress bars)
- tensorboard (visualization)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Orchestration Layer
    subgraph "CLI Orchestration"
        CLI_main[/main.py/]:::orchestration
        CLI_inf[/inference.py/]:::orchestration
    end

    %% Configuration
    subgraph "Configuration & Parameters"
        PARAM[pará/parameter.py]:::orchestration
    end

    %% Data Layer
    subgraph "Data Layer"
        DATA_mod["data/data.py"]:::data
        BSD["data/BSD.py"]:::data
        GPRO["data/gopro_ds_lmdb.py"]:::data
        REDS["data/reds_lmdb.py"]:::data
        DUTIL["data/utils.py"]:::data
        extStorage[(LMDB, Raw Images)]:::external
    end

    %% Model Layer
    subgraph "Model Layer"
        ARCHES["model/arches.py"]:::model
        ATT["model/attention.py"]:::model
        ESTRNN["model/ESTRNN.py"]:::model
        ESTRNN_RAW["model/ESTRNN-RAW.py"]:::model
        STRCNN["model/STRCNN.py"]:::model
        SRN["model/SRN.py"]:::model
        IFIRNN["model/IFIRNN.py"]:::model
        DBN["model/DBN.py"]:::model
        MOD["model/model.py"]:::model
    end

    %% Training Engine
    subgraph "Training Engine"
        Trainer["train/trainer.py"]:::training
        DP["train/dp.py"]:::training
        DDP["train/ddp.py"]:::training
        Loss["train/loss.py"]:::training
        Opt["train/optimizer.py"]:::training
        Metrics["train/metrics.py"]:::training
        TUtil["train/utils.py"]:::training
    end

    %% Inference Engine
    subgraph "Inference Engine"
        Infer["inference.py"]:::training
    end

    %% Utilities
    subgraph Utilities
        LOG["utils/logger.py"]:::utility
    end

    %% Storage
    Checkpoint[(Checkpoints Storage)]:::external
    VideoSrc[(Video Source)]:::external
    VideoOut[(Output Video Storage)]:::external

    %% Connections
    CLI_main -->|flags| PARAM
    CLI_inf -->|flags| PARAM
    CLI_main -->|mode=train| Trainer
    CLI_main -->|mode=infer| Infer
    CLI_inf --> Infer

    PARAM -->|config| DATA_mod
    PARAM -->|config| Trainer
    PARAM -->|config| Infer

    DATA_mod -->|batches| Trainer
    extStorage -->|source| DATA_mod

    Trainer -->|forward pass| ARCHES
    Trainer -->|attention| ATT
    Trainer -->|forward| ESTRNN
    Trainer -->|compute loss| Loss
    Loss -->|gradient| Opt
    Opt -->|update| ARCHES
    Trainer -->|record| Metrics
    Trainer -->|log metrics| LOG
    Trainer -->|save checkpoint| Checkpoint

    DP --> Trainer
    DDP --> Trainer

    Infer -->|load model| ESTRNN
    Infer -->|select arch| ARCHES
    VideoSrc -->|frames| Infer
    Checkpoint -->|checkpoint| Infer
    Infer -->|deblurred frames| VideoOut

    %% Click Events
    click CLI_main "https://github.com/zzh-tech/estrnn/blob/master/main.py"
    click CLI_inf "https://github.com/zzh-tech/estrnn/blob/master/inference.py"
    click PARAM "https://github.com/zzh-tech/estrnn/blob/master/para/parameter.py"
    click DATA_mod "https://github.com/zzh-tech/estrnn/blob/master/data/data.py"
    click BSD "https://github.com/zzh-tech/estrnn/blob/master/data/BSD.py"
    click GPRO "https://github.com/zzh-tech/estrnn/blob/master/data/gopro_ds_lmdb.py"
    click REDS "https://github.com/zzh-tech/estrnn/blob/master/data/reds_lmdb.py"
    click DUTIL "https://github.com/zzh-tech/estrnn/blob/master/data/utils.py"
    click ARCHES "https://github.com/zzh-tech/estrnn/blob/master/model/arches.py"
    click ATT "https://github.com/zzh-tech/estrnn/blob/master/model/attention.py"
    click ESTRNN "https://github.com/zzh-tech/estrnn/blob/master/model/ESTRNN.py"
    click ESTRNN_RAW "https://github.com/zzh-tech/estrnn/blob/master/model/ESTRNN-RAW.py"
    click STRCNN "https://github.com/zzh-tech/estrnn/blob/master/model/STRCNN.py"
    click SRN "https://github.com/zzh-tech/estrnn/blob/master/model/SRN.py"
    click IFIRNN "https://github.com/zzh-tech/estrnn/blob/master/model/IFIRNN.py"
    click DBN "https://github.com/zzh-tech/estrnn/blob/master/model/DBN.py"
    click MOD "https://github.com/zzh-tech/estrnn/blob/master/model/model.py"
    click Trainer "https://github.com/zzh-tech/estrnn/blob/master/train/trainer.py"
    click DP "https://github.com/zzh-tech/estrnn/blob/master/train/dp.py"
    click DDP "https://github.com/zzh-tech/estrnn/blob/master/train/ddp.py"
    click Loss "https://github.com/zzh-tech/estrnn/blob/master/train/loss.py"
    click Opt "https://github.com/zzh-tech/estrnn/blob/master/train/optimizer.py"
    click Metrics "https://github.com/zzh-tech/estrnn/blob/master/train/metrics.py"
    click TUtil "https://github.com/zzh-tech/estrnn/blob/master/train/utils.py"
    click LOG "https://github.com/zzh-tech/estrnn/blob/master/utils/logger.py"

    %% Styles
    classDef orchestration fill:#c7f9cc,stroke:#2d6a4f,color:#1b4332
    classDef data fill:#caf0f8,stroke:#0077b6,color:#03045e
    classDef model fill:#ade8f4,stroke:#0096c7,color:#023e8a
    classDef training fill:#90e0ef,stroke:#00b4d8,color:#0077b6
    classDef external fill:#ffd6a5,stroke:#ee9b00,color:#9b2c2c
    classDef utility fill:#e0e0e0,stroke:#6c757d,color:#343a40
```
