# yuhangzhoucjy/wformer architecture

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

- Interactive diagram: https://gitdiagram.com/yuhangzhoucjy/wformer
- Repository: https://github.com/yuhangzhoucjy/wformer

## Overview

##### Project type and purpose
- Project type: Deep‑learning research codebase with training and inference pipelines.
- Purpose: Embed and extract watermarks in images robustly under various noise/distortion layers using a transformer‑based architecture and adversarial training (generator vs. discriminator).

##### File structure
- Top‑level scripts:
- train.py / train_settings.json → orchestrates training.
- test.py, test_noise.py / test_settings.json → run inference/robustness evaluation.
- Core module: transformer_watermarking/
- encoder.py, decoder.py, encoder_decoder.py → watermark embedding & extraction logic.
- Discriminator.py → adversarial discriminator network.
- Network.py → overall model wrapper.
- Noise.py & noise_layers/ → various simulated attacks (JPEG, crop, brightness, etc.).
- blocks/ → building blocks (ConvNet, ExpandNet, SENet) used in encoder/decoder.
- Utilities: utils/ (Dataloader, settings loaders, save_images).
- Results folder: stores trained model checkpoints and output images.

##### README insights
- Confirms transformer‑based watermarking approach.
- Emphasis on robustness against multiple noise/distortion pipelines.

##### Main components
a. Data Ingestion & Preprocessing
– Raw images in → Dataloader (WFormer/utils/Dataloader.py).
– Settings loaded (train/test JSON).
b. Watermark Embedding (Generator)
– Encoder module: takes cover image + secret bits → embedded image.
– Fusion block (transformer layers + Conv/SENet/ExpandNet blocks).
c. Noise Simulation Pipeline
– Composed of multiple noise_layers (JPEG, crop, Gaussian, etc.).
– Applied to embedded image to simulate attacks.
d. Watermark Extraction (Decoder)
– Decoder module: recovers secret bits from attacked image.
e. Discriminator (Adversarial)
– Takes embedded image (or attacked image?) → distinguishes real vs. watermarked.
– Provides adversarial loss to generator.
f. Training Orchestration (train.py)
– Iterates: encode→noise→decode & discriminate → compute losses → backprop.
– Uses settings from train_settings.json.
g. Inference/Evaluation (test.py, test_noise.py)
– Runs encode + noise layers + decode.
– Saves images & metrics via utils/save_images.
h. Storage
– Model checkpoints (.pth in results/.../models).
– Output images in results/.../images.

##### Relationships & data flow
- Data loader → Generator (encoder) → Embedded image.
- Embedded image → Noise pipeline → Noised image.
- Noised image → Decoder → Recovered watermark.
- Embedded image (or noised) → Discriminator → Real vs. fake score.
- Losses from decoder & discriminator → back to Generator.
- Scripts (train.py/test.py) orchestrate flows and leverage utils.

##### Architectural patterns & design principles
- Modular separation: encoder, decoder, discriminator, noise layers.
- Plugin‑style noise modules for extensibility.
- Adversarial training loop (GAN‑like).
- Config‑driven via JSON settings.
- Clear separation of training vs. inference scripts.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Utilities"
        DL["Data Loader"]:::data
        SLT["Settings Loader (Train)"]:::utils
        SLTest["Settings Loader (Test)"]:::utils
        Save["Image Saving Utility"]:::utils
    end

    subgraph "Training Script: train.py"
        TrainScript["train.py"]:::script
    end

    subgraph "Training Pipeline"
        DL -->|provides images| Encoder["Encoder (Generator)"]:::gen
        SLT -->|provides settings| TrainScript
        TrainScript -->|calls encoder| Encoder
        Encoder -->|embedded image| Noise["Noise Pipeline"]:::noise
        Noise -->|noised image| Decoder["Decoder"]:::gen
        Encoder -->|embedded image| Discriminator["Discriminator"]:::adv
        Decoder -->|recovered watermark| TrainScript
        Discriminator -->|real/fake score| TrainScript
        TrainScript -->|compute losses & backprop| Encoder
        TrainScript -->|save checkpoint| Checkpoints["Checkpoint Store"]:::store
    end

    subgraph "Inference/Evaluation"
        DL -->|provides images| EncoderInf["Encoder"]:::gen
        SLTest -->|provides settings| TestScript["test.py / test_nosie.py"]:::script
        TestScript -->|calls encoder| EncoderInf
        EncoderInf -->|embedded image| NoiseInf["Noise Pipeline"]:::noise
        NoiseInf -->|noised image| DecoderInf["Decoder"]:::gen
        DecoderInf -->|recovered watermark| Save
        TestScript -->|save results| Save
        Save -->|images & metrics| Results["Output Store"]:::store
    end

    subgraph "Results Storage"
        Checkpoints
        Results
    end

    %% Click Events
    click DL "https://github.com/yuhangzhoucjy/wformer/blob/master/WFormer/utils/Dataloader.py"
    click SLT "https://github.com/yuhangzhoucjy/wformer/blob/master/WFormer/utils/load_train_setting.py"
    click SLTest "https://github.com/yuhangzhoucjy/wformer/blob/master/WFormer/utils/load_test_setting.py"
    click Save "https://github.com/yuhangzhoucjy/wformer/blob/master/WFormer/utils/save_images.py"
    click Encoder "https://github.com/yuhangzhoucjy/wformer/blob/master/WFormer/transformer_watermarking/encoder.py"
    click Noise "https://github.com/yuhangzhoucjy/wformer/blob/master/WFormer/transformer_watermarking/Noise.py"
    click Decoder "https://github.com/yuhangzhoucjy/wformer/blob/master/WFormer/transformer_watermarking/decoder.py"
    click Discriminator "https://github.com/yuhangzhoucjy/wformer/blob/master/WFormer/transformer_watermarking/Discriminator.py"
    click TrainScript "https://github.com/yuhangzhoucjy/wformer/blob/master/WFormer/train.py"
    click TestScript "https://github.com/yuhangzhoucjy/wformer/blob/master/WFormer/test.py"
    click Checkpoints "https://github.com/yuhangzhoucjy/wformer/tree/master/WFormer/results"
    click Results "https://github.com/yuhangzhoucjy/wformer/tree/master/WFormer/results"

    classDef data fill:#ADD8E6,stroke:#000
    classDef gen fill:#90EE90,stroke:#000
    classDef noise fill:#FFA500,stroke:#000
    classDef adv fill:#FF6347,stroke:#000
    classDef utils fill:#D3D3D3,stroke:#000
    classDef script fill:#E0FFFF,stroke:#000
    classDef store fill:#F5F5DC,stroke:#000
```
