# pksvision/deep-wavenet-underwater-image-restoration architecture

> Architecture diagram of the GitHub repository pksvision/deep-wavenet-underwater-image-restoration, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pksvision/deep-wavenet-underwater-image-restoration
- Repository: https://github.com/pksvision/deep-wavenet-underwater-image-restoration

## Overview

##### Main components
a. External Datasets & Resources
- EUVP test/train folders
- UIEB & Challenging‐60
- UFO‐120 (2X/3X/4X)
- Sample degraded videos (underwater_video.mp4)
- resources/existing_soas_list_with_codes.txt
b. Configuration & Installation
- installation/requirements.txt
- options.py files in each task module
c. Core Modules (per task)
- uie_euvp/
- uie_uieb/
- super-resolution/2X, 3X, 4X
- uw_video_processing/
d. Shared Utilities
- utils/gen_seg_maps.py
- matlab_iqms/ and python_iqms/ for SSIM/PSNR/UIQM
- loss‐plotting & other misc scripts
e. DeepWaveNet Model Definition
- models.py in each module (network architecture with WaveNet blocks)
- vgg.py (for perceptual loss)
f. Experiment Engines
- train.py (orchestrates data loading, model, loss, optimizer, checkpointing)
- test.py (loads checkpoint, runs inference, saves outputs)
g. Outputs & Evaluation
- Checkpoints in ckpts/
- Enhanced / super‐resolved images in output directories
- Metrics (SSIM, PSNR, UIQM) computed via utils

##### Relationships & data flows
- External Datasets → Dataset.py → DataLoader
- DataLoader → train.py / test.py → Model (models.py + vgg.py)
- Model → Restored Images → save to disk
- After inference → utils/python_iqms or utils/matlab_iqms → Metrics output
- train.py saves checkpoints → test.py loads checkpoints
- uw_video_processing/test.py uses the same model APIs for frame‐by‐frame processing

##### Architectural patterns & design principles
- Modular separation by task (UIE vs. SR vs. Video)
- Reusable Dataset / Model / Options components across tasks
- Configuration‐driven experiments (options.py)
- Checkpointing for reproducibility
- Shared utility library for metrics and post‐processing

##### Key technologies & frameworks
- Python 3.x
- PyTorch (deep learning)
- torchvision, numpy, scipy, opencv
- Jupyter (DeepWaveNet_demo.ipynb)
- Optional: MATLAB for IQM computations
- Deployment mention: Heroku web‐app (256×256 demo)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Datasets & Resources
    subgraph "External Datasets & Resources"
        direction TB
        EUVP_test["EUVP test/train"]:::data
        UIEB_clean_test["UIEB clean_test"]:::data
        UIEB_hazy_test["UIEB hazy_test"]:::data
        UFO_2X["UFO-120 (2X)"]:::data
        UFO_3X["UFO-120 (3X)"]:::data
        UFO_4X["UFO-120 (4X)"]:::data
        degraded_video["Sample degraded videos"]:::data
        existing_soas["existing_soas_list_with_codes.txt"]:::data
    end

    %% Common Utilities & Config
    subgraph "Common Utilities & Config"
        direction TB
        requirements["requirements.txt"]:::code
        super2x_opts["super-resolution 2X options.py"]:::code
        super3x_opts["super-resolution 3X options.py"]:::code
        super4x_opts["super-resolution 4X options.py"]:::code
        euvp_opts["uie_euvp options.py"]:::code
        uieb_opts["uie_uieb options.py"]:::code
        gen_seg["gen_seg_maps.py"]:::code
        matlab_iqms["matlab_iqms/"]:::code
        python_iqms["python_iqms/"]:::code
    end

    %% Core Modules
    subgraph "Core Modules"
        direction TB
        subgraph "Underwater Image Enhancement"
            direction TB
            uie_euvp["uie_euvp/"]:::code
            uie_uieb["uie_uieb/"]:::code
        end
        subgraph "Super-Resolution"
            direction TB
            sr2x["super-resolution/2X/"]:::code
            sr3x["super-resolution/3X/"]:::code
            sr4x["super-resolution/4X/"]:::code
        end
        uw_video["uw_video_processing/"]:::code
    end

    %% Experiment Engines
    subgraph "Experiment Engines"
        direction TB
        train["train.py"]:::core
        test["test.py"]:::core
        demo["DeepWaveNet_demo.ipynb"]:::core
    end

    %% Outputs & Evaluation
    subgraph "Outputs & Evaluation"
        direction TB
        ckpts["ckpts/"]:::data
        results["results/ & enhanced_video.avi"]:::data
        metrics["SSIM/PSNR/UIQM Modules"]:::core
    end

    %% Frameworks
    subgraph "Frameworks"
        direction TB
        pytorch["PyTorch"]:::external
        opencv["OpenCV"]:::external
        matlab["MATLAB"]:::external
        jupyter["Jupyter"]:::external
    end

    %% Data Flow
    EUVP_test -->|feeds| uie_euvp
    UIEB_clean_test -->|feeds| uie_uieb
    UIEB_hazy_test -->|feeds| uie_uieb
    UFO_2X -->|feeds| sr2x
    UFO_3X -->|feeds| sr3x
    UFO_4X -->|feeds| sr4x
    degraded_video -->|feeds| uw_video
    uie_euvp -->|uses options| euvp_opts
    uie_uieb -->|uses options| uieb_opts
    sr2x -->|uses options| super2x_opts
    sr3x -->|uses options| super3x_opts
    sr4x -->|uses options| super4x_opts
    subgraph UtilFlow
        requirements
        gen_seg
        matlab_iqms
        python_iqms
    end
    UtilFlow --> uie_euvp
    UtilFlow --> uie_uieb
    UtilFlow --> sr2x
    UtilFlow --> sr3x
    UtilFlow --> sr4x
    UtilFlow --> uw_video

    uie_euvp -->|model| train
    uie_uieb -->|model| train
    sr2x -->|model| train
    sr3x -->|model| train
    sr4x -->|model| train
    uw_video -->|model| train

    train --> test
    test --> results
    test --> metrics
    train --> ckpts
    test --> ckpts
    demo --> train
    demo --> test

    pytorch --> train
    opencv --> test
    matlab --> metrics
    jupyter --> demo

    %% Click Events
    click existing_soas "https://github.com/pksvision/deep-wavenet-underwater-image-restoration/blob/main/resources/existing_soas_list_with_codes.txt"
    click degraded_video "https://github.com/pksvision/deep-wavenet-underwater-image-restoration/blob/main/uw_video_processing/degraded_video.mp4"
    click UIEB_clean_test "https://github.com/pksvision/deep-wavenet-underwater-image-restoration/tree/main/uie_uieb/clean_test"
    click UIEB_hazy_test "https://github.com/pksvision/deep-wavenet-underwater-image-restoration/tree/main/uie_uieb/hazy_test"
    click requirements "https://github.com/pksvision/deep-wavenet-underwater-image-restoration/blob/main/installation/requirements.txt"
    click super2x_opts "https://github.com/pksvision/deep-wavenet-underwater-image-restoration/blob/main/super-resolution/2X/options.py"
    click super3x_opts "https://github.com/pksvision/deep-wavenet-underwater-image-restoration/blob/main/super-resolution/3X/options.py"
    click super4x_opts "https://github.com/pksvision/deep-wavenet-underwater-image-restoration/blob/main/super-resolution/4X/options.py"
    click euvp_opts "https://github.com/pksvision/deep-wavenet-underwater-image-restoration/blob/main/uie_euvp/options.py"
    click uieb_opts "https://github.com/pksvision/deep-wavenet-underwater-image-restoration/blob/main/uie_uieb/options.py"
    click uie_euvp "https://github.com/pksvision/deep-wavenet-underwater-image-restoration/tree/main/uie_euvp/"
    click uie_uieb "https://github.com/pksvision/deep-wavenet-underwater-image-restoration/tree/main/uie_uieb/"
    click sr2x "https://github.com/pksvision/deep-wavenet-underwater-image-restoration/tree/main/super-resolution/2X/"
    click sr3x "https://github.com/pksvision/deep-wavenet-underwater-image-restoration/tree/main/super-resolution/3X/"
    click sr4x "https://github.com/pksvision/deep-wavenet-underwater-image-restoration/tree/main/super-resolution/4X/"
    click uw_video "https://github.com/pksvision/deep-wavenet-underwater-image-restoration/tree/main/uw_video_processing/"
    click gen_seg "https://github.com/pksvision/deep-wavenet-underwater-image-restoration/blob/main/utils/gen_seg_maps.py"
    click matlab_iqms "https://github.com/pksvision/deep-wavenet-underwater-image-restoration/tree/main/utils/matlab_iqms/"
    click python_iqms "https://github.com/pksvision/deep-wavenet-underwater-image-restoration/tree/main/utils/python_iqms/"

    %% Styles
    classDef data fill:#87CEFA,stroke:#333,stroke-width:1px
    classDef code fill:#8FBC8F,stroke:#333,stroke-width:1px
    classDef core fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
