How zhenqifu/usuir works
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)