# junlinhan/cwr architecture

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

## Overview

##### Project type and purpose
- This is a research‐oriented PyTorch project implementing “Contrastive UnderWater Restoration (CWR),” a deep learning pipeline for unpaired (and paired) underwater image restoration and related low‐level vision tasks (dehazing, deraining).
- It provides training and testing scripts, dataset loaders, model definitions (generator + contrastive losses), utilities (visualization, HTML logging), and an experiments entry point.

##### File structure
- Top-level scripts:
- train.py – launches the training loop
- test.py – runs inference and saves results
- experiments/__main__.py – alternative launcher for experiments
- Modules by responsibility:
- options/ – CLI argument parsing (base, train, test)
- data/ – abstract dataset classes and concrete unaligned/paired datasets
- datasets/ – local data storage (HICRD folder with train/test splits)
- models/ – model definitions (networks.py, spectralNormalization, PatchNCE, StyleGAN networks, base & template models)
- util/ – helpers for data loading, HTML generation, image pooling, logging, visualization via Visdom
- Configuration & environment: requirements.txt, environment.yml
- Checkpoints & results conventions: saved under ./checkpoints/<name> and ./results/<name>

##### README for additional insights
- Confirms architecture: unpaired image‐to‐image translation with contrastive loss (built upon CUT and CycleGAN codebases)
- Training uses Visdom server for real‐time loss curves and HTML pages for visual outputs
- External dependencies: PyTorch, torchvision, visdom, dominate, gputil

1. CLI Layer
- train.py / test.py / experiments
- Options Parser (options/base_options.py, train_options.py, test_options.py)
2. Data Layer
- Dataset Factory (data/__init__.py)
- Dataset Classes (unaligned_dataset, single_dataset, image_folder, etc.)
- Local Storage (datasets/HICRD/*)
- DataLoader (PyTorch DataLoader via util/get_data.py)
3. Model Layer
- Network Architectures (models/networks.py, stylegan_networks.py)
- Contrastive Modules (models/patchnce.py, spectralNormalization.py)
- Model Orchestration (models/base_model.py, template_model.py, cwr_model.py)
4. Training Engine
- Training Loop (train.py)
- Loss Computation (contrastive, adversarial, cycle, identity etc.)
- Optimizers & Schedulers
- Checkpoint Manager (saving under ./checkpoints)
5. Testing/Inference Engine
- Inference Loop (test.py)
- Image Pre/post‐processing (util/util.py, util/image_pool.py)
- Result Export (HTML pages via util/html.py)
6. Visualization & Logging
- Visdom Server (util/visualizer.py)
- HTML Logger (util/html.py)
7. External Systems
- Local Filesystem (datasets, checkpoints, results)
- Visdom Server (http://localhost:8097)

b. Relationships and interactions
- CLI scripts → parse options → instantiate Data Layer & Model Layer
- Data Layer → yields batches → Training Engine / Testing Engine
- Training Engine ↔ Model Layer (forward/backward passes)
- Training Engine → loss/output → Visualization & Logging
- Training Engine → checkpoint saving to filesystem
- Testing Engine → model.load() → inference → HTML export

c. Architectural patterns & design principles
- Modular separation of concerns: options, data, models, utils
- Factory pattern for dataset instantiation
- Template Method / Inheritance for Model classes (base_model → cwr_model, template_model)
- Pipeline pattern: data → model → loss → optimizer → log → checkpoint

d. Key technologies/frameworks
- PyTorch & torchvision for model and DataLoader
- Visdom + dominate for real‐time and static visualization
- Conda / pip for environment reproducibility
- Based on pytorch-CycleGAN-and-pix2pix and CUT implementations

##### Final Advice
- Essential modules (options, data classes, model classes, utils).
- Data flow and dependency direction clearly.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        CLI_Train["train.py"]:::code
        CLI_Test["test.py"]:::code
        CLI_Exp["experiments/__main__.py"]:::code
    end

    %% Options Parser
    subgraph "Options Parser"
        Opt_Base["base_options.py"]:::code
        Opt_Train["train_options.py"]:::code
        Opt_Test["test_options.py"]:::code
    end

    %% Data Layer
    subgraph "Data Layer"
        Data_Init["data/__init__.py"]:::code
        Data_Base["data/base_dataset.py"]:::code
        Data_Template["data/template_dataset.py"]:::code
        Data_Unaligned["data/unaligned_dataset.py"]:::code
        Data_SingleImg["data/singleimage_dataset.py"]:::code
        Data_Single["data/single_dataset.py"]:::code
        Data_Folder["data/image_folder.py"]:::code
    end

    %% Local Storage
    Files_DS["datasets/HICRD/*"]:::ext

    %% DataLoader Utility
    Get_Data["util/get_data.py"]:::code

    %% Model Layer
    subgraph "Model Layer"
        Mod_Nets["models/networks.py"]:::code
        Mod_SG["models/stylegan_networks.py"]:::code
        Mod_PatchNCE["models/patchnce.py"]:::code
        Mod_SpecNorm["models/spectralNormalization.py"]:::code
        Mod_BaseModel["models/base_model.py"]:::code
        Mod_TemplateModel["models/template_model.py"]:::code
        Mod_CWR["models/cwr_model.py"]:::code
    end

    %% Training Engine
    Train_Engine["Training Engine"]:::code

    %% Testing/Inference Engine
    Test_Engine["Testing Engine"]:::code

    %% Visualization & Logging
    subgraph "Visualization & Logging"
        Viz_Visdom["util/visualizer.py"]:::code
        Viz_HTML["util/html.py"]:::code
        Viz_Pool["util/image_pool.py"]:::code
        Viz_Util["util/util.py"]:::code
    end

    %% Experiments Framework
    Exp_Framework["Experiments Framework"]:::code

    %% Environment & Dependencies
    Env_Req["requirements.txt"]:::code
    Env_Conda["environment.yml"]:::code
    Env_Readme["README.md"]:::code
    Env_License["LICENSE"]:::code

    %% External Systems
    FS["Local Filesystem"]:::ext
    VS["Visdom Server"]:::ext

    %% Connections
    CLI_Train -->|uses| Opt_Base
    CLI_Train -->|uses| Opt_Train
    CLI_Train -->|launches| Train_Engine
    CLI_Test -->|uses| Opt_Base
    CLI_Test -->|uses| Opt_Test
    CLI_Test -->|launches| Test_Engine
    CLI_Exp -->|launches| Exp_Framework

    Train_Engine -->|loads options| Opt_Train
    Train_Engine -->|fetches data| Get_Data
    Get_Data -->|calls| Data_Init
    Data_Init -->|instantiates| Data_Unaligned
    Data_Init -->|instantiates| Data_SingleImg
    Data_Init -->|instantiates| Data_Single
    Data_Init -->|instantiates| Data_Folder
    Data_Folder -->|reads| Files_DS
    Train_Engine -->|uses| Mod_CWR
    Mod_CWR -->|inherits| Mod_BaseModel
    Mod_CWR -->|inherits| Mod_TemplateModel
    Mod_CWR -->|uses| Mod_Nets
    Mod_CWR -->|uses| Mod_SG
    Mod_CWR -->|uses| Mod_PatchNCE
    Mod_CWR -->|uses| Mod_SpecNorm
    Train_Engine -->|logs| Viz_Visdom
    Train_Engine -->|saves| FS
    Train_Engine -->|saves checkpoint| FS

    Test_Engine -->|loads options| Opt_Test
    Test_Engine -->|fetches data| Get_Data
    Test_Engine -->|inference| Mod_CWR
    Test_Engine -->|exports| Viz_HTML
    Test_Engine -->|uses util| Viz_Util
    Test_Engine -->|uses pool| Viz_Pool
    Test_Engine -->|saves results| FS

    %% Visualization & Logging flows
    Viz_Visdom -->|push plots| VS
    Viz_HTML -->|writes reports| FS

    %% Experiments Framework
    Exp_Framework -->|parses options| Opt_Base

    %% Environment & Dependencies
    Env_Req -->|defines| FS
    Env_Conda -->|defines| FS
    Env_Readme -->|documents| FS
    Env_License -->|governs| FS

    %% Class Definitions
    classDef code fill:#BBDEFB,stroke:#2196F3,color:#0D47A1
    classDef ext fill:#C8E6C9,stroke:#388E3C,color:#1B5E20

    %% Click Events
    click CLI_Train "https://github.com/junlinhan/cwr/blob/main/train.py"
    click CLI_Test "https://github.com/junlinhan/cwr/blob/main/test.py"
    click CLI_Exp "https://github.com/junlinhan/cwr/blob/main/experiments/__main__.py"
    click Opt_Base "https://github.com/junlinhan/cwr/blob/main/options/base_options.py"
    click Opt_Train "https://github.com/junlinhan/cwr/blob/main/options/train_options.py"
    click Opt_Test "https://github.com/junlinhan/cwr/blob/main/options/test_options.py"
    click Data_Init "https://github.com/junlinhan/cwr/blob/main/data/__init__.py"
    click Data_Base "https://github.com/junlinhan/cwr/blob/main/data/base_dataset.py"
    click Data_Template "https://github.com/junlinhan/cwr/blob/main/data/template_dataset.py"
    click Data_Unaligned "https://github.com/junlinhan/cwr/blob/main/data/unaligned_dataset.py"
    click Data_SingleImg "https://github.com/junlinhan/cwr/blob/main/data/singleimage_dataset.py"
    click Data_Single "https://github.com/junlinhan/cwr/blob/main/data/single_dataset.py"
    click Data_Folder "https://github.com/junlinhan/cwr/blob/main/data/image_folder.py"
    click Get_Data "https://github.com/junlinhan/cwr/blob/main/util/get_data.py"
    click Mod_Nets "https://github.com/junlinhan/cwr/blob/main/models/networks.py"
    click Mod_SG "https://github.com/junlinhan/cwr/blob/main/models/stylegan_networks.py"
    click Mod_PatchNCE "https://github.com/junlinhan/cwr/blob/main/models/patchnce.py"
    click Mod_SpecNorm "https://github.com/junlinhan/cwr/blob/main/models/spectralNormalization.py"
    click Mod_BaseModel "https://github.com/junlinhan/cwr/blob/main/models/base_model.py"
    click Mod_TemplateModel "https://github.com/junlinhan/cwr/blob/main/models/template_model.py"
    click Mod_CWR "https://github.com/junlinhan/cwr/blob/main/models/cwr_model.py"
    click Exp_Framework "https://github.com/junlinhan/cwr/blob/main/experiments/__main__.py"
    click Env_Req "https://github.com/junlinhan/cwr/blob/main/requirements.txt"
    click Env_Conda "https://github.com/junlinhan/cwr/blob/main/environment.yml"
    click Env_Readme "https://github.com/junlinhan/cwr/blob/main/README.md"
    click Env_License "https://github.com/junlinhan/cwr/tree/main/LICENSE"
```
