# zhenqifu/usuir architecture

> Architecture diagram of the GitHub repository zhenqifu/usuir, 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/zhenqifu/usuir
- Repository: https://github.com/zhenqifu/usuir

## Overview

##### Project Type and Purpose
- Type: Machine-Learning research codebase (PyTorch) for underwater image restoration.
- Purpose: Train an unsupervised deep network to restore underwater images and then evaluate restoration quality using UCIQE & UIQM metrics (implemented in MATLAB).

##### File Structure
Top-level scripts:
– main.py → training entry point
– eval.py → evaluation entry point
– data.py, dataset.py → data-loading & preprocessing
– measure.py → Python wrapper/invocation for computing quality metrics
– utils.py → helpers (I/O, logging, image saving)
Core modules:
– net/
- net.py → defines the neural network architecture
- losses.py → custom loss functions
- ITA.py → additional algorithmic components
– final_weight/ → stores pretrained model checkpoints (.pth)
MATLAB metrics:
– UCIQE/…/*.m
– UIQM/…/*.m
Resources:
– img/ → sample figures
– README.md → instructions, dependencies (Python 3.7, PyTorch 1.7.1, Ubuntu 16.04, NVIDIA GPU)

##### README Insights
- Describes required environment (Ubuntu, Python, PyTorch, GPU).
- Two main flows:
– Training: prepare dataset (via dataset.py), then run main.py
– Testing/Evaluation: load checkpoints, run eval.py

##### Core Components & Their Relationships
a. Data Ingestion Layer
- Raw images directory → dataset.py / data.py
- Preprocessing steps (resizing, normalizing)
b. Model Layer
- net/net.py (CNN architecture)
- net/losses.py + net/ITA.py (loss computation & auxiliary modules)
c. Training Controller
- main.py orchestrates epochs:
– fetch batches → forward pass → compute loss → backprop → update weights → checkpoint to final_weight/
d. Evaluation Controller
- eval.py loads a .pth checkpoint → runs forward pass on test images → saves restored images
e. Metrics Modules
- measure.py calls MATLAB scripts (UCIQE/, UIQM/) or computes metrics in Python
- Outputs quantitative scores
f. Utilities Layer
- utils.py for logging, config management, image I/O

##### Architectural Patterns & Design Principles
- Modular pipeline: Clear separation between data, model, training, evaluation, and metrics.
- Checkpointing: Persistent storage of model weights for reproducibility.
- External dependency integration: MATLAB for specialized image-quality metrics.
- Reusability: data/dataset module can be swapped for other datasets; net module can serve as a plug-and-play backbone.

##### Essential Elements
– Clear, concise labels on each component
– Callouts for configuration points (e.g., dataset path in main.py, model path in eval.py)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data & I/O"
        DataStore["Raw Images"]:::data
        ImgSample["Sample Figures<br/>(img/)"]:::data
        DataLoader["Data Loader<br/>(data.py, dataset.py)"]:::data
    end

    subgraph "Core ML Components"
        Model["Model<br/>(PyTorch 1.7.1)<br/>(net/net.py)"]:::ml
        LossComp["Loss Functions<br/>(net/losses.py)"]:::ml
        AuxComp["Auxiliary Modules<br/>(net/ITA.py)"]:::ml
        Trainer["Training Controller<br/>(main.py)"]:::ml
    end

    subgraph "Checkpoint Store"
        Checkpoint["Model Checkpoints<br/>(final_weight/)"]:::data
    end

    subgraph "Evaluation & Metrics"
        Evaluator["Evaluation Controller<br/>(eval.py)"]:::eval
        MetricsWrapper["Metrics Wrapper<br/>(measure.py)"]:::eval
        subgraph "MATLAB Metrics Engine"
            UE["UCIQE Scripts"]:::ext
            UI["UIQM Scripts"]:::ext
        end
        Scores["Quality Scores"]:::eval
    end

    subgraph "Utilities"
        Utils["Utilities<br/>(utils.py)"]:::data
    end

    ExtGPU["GPU"]:::ext
    Docs["Documentation<br/>(README.md)"]:::data

    DataStore --> DataLoader
    ImgSample --> DataLoader

    DataLoader --> Model
    Model --> LossComp
    LossComp --> AuxComp

    Trainer -->|fetch batches| DataLoader
    Trainer -->|train loop| Model
    Trainer -->|save checkpoint| Checkpoint
    Model --> ExtGPU
    Trainer --> Utils

    Checkpoint --> Evaluator
    DataLoader --> Evaluator
    Evaluator -->|infer| Model
    Evaluator --> ExtGPU

    Evaluator --> MetricsWrapper
    MetricsWrapper --> UE
    MetricsWrapper --> UI
    UE --> Scores
    UI --> Scores

    DataLoader --> Utils
    Evaluator --> Utils
    MetricsWrapper --> Utils

    Docs --> Trainer
    Docs --> Evaluator

    classDef data fill:#D0E6F6,stroke:#333,stroke-width:1px
    classDef ml fill:#C6E2C3,stroke:#333,stroke-width:1px
    classDef eval fill:#FDD8B2,stroke:#333,stroke-width:1px
    classDef ext fill:#E0E0E0,stroke:#333,stroke-width:1px

    click DataLoader "https://github.com/zhenqifu/usuir/blob/main/data.py"
    click DataLoader "https://github.com/zhenqifu/usuir/blob/main/dataset.py"
    click Model "https://github.com/zhenqifu/usuir/blob/main/net/net.py"
    click LossComp "https://github.com/zhenqifu/usuir/blob/main/net/losses.py"
    click AuxComp "https://github.com/zhenqifu/usuir/blob/main/net/ITA.py"
    click Trainer "https://github.com/zhenqifu/usuir/blob/main/main.py"
    click Checkpoint "https://github.com/zhenqifu/usuir/tree/main/final_weight/"
    click Evaluator "https://github.com/zhenqifu/usuir/blob/main/eval.py"
    click MetricsWrapper "https://github.com/zhenqifu/usuir/blob/main/measure.py"
    click UE "https://github.com/zhenqifu/usuir/blob/main/UCIQE/UCIQE.m"
    click UE "https://github.com/zhenqifu/usuir/blob/main/UCIQE/mian.m"
    click UE "https://github.com/zhenqifu/usuir/blob/main/UCIQE/rgb2lab_n.m"
    click UI "https://github.com/zhenqifu/usuir/blob/main/UIQM/UIQM.m"
    click UI "https://github.com/zhenqifu/usuir/blob/main/UIQM/UICM.m"
    click UI "https://github.com/zhenqifu/usuir/blob/main/UIQM/UIConM.m"
    click UI "https://github.com/zhenqifu/usuir/blob/main/UIQM/UISM.m"
    click UI "https://github.com/zhenqifu/usuir/blob/main/UIQM/mian.m"
    click Utils "https://github.com/zhenqifu/usuir/blob/main/utils.py"
    click ImgSample "https://github.com/zhenqifu/usuir/tree/main/img/"
    click Docs "https://github.com/zhenqifu/usuir/blob/main/README.md"
```
