# zhenglisec/blind-watermark-for-dnn architecture

> Architecture diagram of the GitHub repository zhenglisec/blind-watermark-for-dnn, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zhenglisec/blind-watermark-for-dnn
- Repository: https://github.com/zhenglisec/blind-watermark-for-dnn

## Overview

##### Project type and purpose
- This is an open-source machine-learning research framework for embedding and verifying a blind watermark in deep neural networks (DNNs).
- It uses PyTorch (Python 3.7) to train a pair of networks (a HidingUNet and a Discriminator) alongside a host model (LeNet / VGG / ResNet variants / etc.) on MNIST or CIFAR-10.

##### File structure
- Top-level:
- main.py – orchestrates training and evaluation
- utils.py – common helper functions (argument parsing, logging, checkpointing)
- data/ – raw datasets and watermark logo
- models/ – definitions of all network architectures (Host models, HidingUNet, Discriminator)
- results/ – per-model subfolders containing generated images, trained checkpoints, and run scripts
- Patterns:
- Modular model definitions in models/ for easy swapping of architectures
- Clear separation between data ingestion (data/), model code (models/), orchestration (main.py), and outputs (results/)

##### README for insights
- Framework supports two datasets (mnist, cifar10)
- Hosts a set of pre-defined network backbones
- Contains instructions on setting hyperparameters, seeds, and where outputs land

##### Main components and their interactions
a. Data Ingestion
– Dataset Loader: MNIST or CIFAR-10 reader (auto-downloads to data/)
– Logo Loader: samples a watermark image (mnist sample or data/IEEE/logo)
b. Host Model
– One of the classification networks (LeNet1/3/5, VGG11/13/16/19, ResNet18/34/101, PreActResNet18/34, GoogLeNet, DPN26, MobileNetV2)
c. Embedding Network (HidingUNet)
– Takes host model’s feature maps (or input image) + logo → produces a watermarked image
d. Discriminator
– Attempts to extract/recover the embedded logo from the watermarked image
e. Training Orchestrator (main.py)
– Initializes models, optimizers, and losses
– In each training loop:
- Forward pass: host model + HidingUNet + Discriminator
- Compute classification loss (host task), reconstruction loss (logo), adversarial loss
- Backpropagate and update HidingUNet & Discriminator (and sometimes host)
– Checkpoints final watermarked host model and networks into results/
f. Utilities
– Argument parser, logging, checkpoint save/load, visualization utilities (utils.py)

##### Architectural patterns and design principles
- Pipeline pattern: Data → Preprocessing → Embedding → Discrimination → Loss → Update
- Modular model registry: models are interchangeable, easy to extend with new backbones
- Separation of concerns:
- Data & configuration (main/data/)
- Model code (models/)
- Experiment orchestration (main.py + utils.py)
- Results & artifacts (results/)

##### Detailed element checklist
- Version note (PyTorch, Python)
- Directory mapping (e.g., show that model definitions live in models/, outputs in results/)
- Interaction notes (e.g., “HidingUNet consumes feature maps from Host Model”)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Data Sources"
        DL["Data Loader"]:::data
        LL["Logo Loader"]:::data
    end

    subgraph "Model Components"
        subgraph "Host Models" 
            LM["LeNet variants"]:::model
            VG["VGG variants"]:::model
            RN["ResNet variants"]:::model
            PA["PreActResNet variants"]:::model
            GN["GoogLeNet"]:::model
            DP["DPN26"]:::model
            MB["MobileNetV2"]:::model
        end
        HUN["HidingUNet"]:::model
        DIS["Discriminator"]:::model
    end

    TO["Training Orchestrator"]:::orchestrator
    UT["Utilities"]:::utils
    RS["Results Storage"]:::storage
    TECH["Python 3.7, PyTorch 1.2.0"]:::tech

    %% Data flow
    DL -->|"images"| LM
    DL -->|"images"| VG
    DL -->|"images"| RN
    DL -->|"images"| PA
    DL -->|"images"| GN
    DL -->|"images"| DP
    DL -->|"images"| MB
    LL -->|"logo"| HUN
    LM -->|"feature maps"| HUN
    VG -->|"feature maps"| HUN
    RN -->|"feature maps"| HUN
    PA -->|"feature maps"| HUN
    GN -->|"feature maps"| HUN
    DP -->|"feature maps"| HUN
    MB -->|"feature maps"| HUN
    HUN -->|"watermarked image"| DIS

    %% Orchestration and feedback
    DIS -->|"recovered logo"| TO
    HUN -->|"losses"| TO
    LM -->|"classification loss"| TO
    VG -->|"classification loss"| TO
    RN -->|"classification loss"| TO
    PA -->|"classification loss"| TO
    GN -->|"classification loss"| TO
    DP -->|"classification loss"| TO
    MB -->|"classification loss"| TO
    TO -->|"checkpoints & artifacts"| RS

    %% Utilities usage
    UT --> TO

    %% Legend or tech note
    TECH

    %% Click events
    click DL "https://github.com/zhenglisec/blind-watermark-for-dnn/tree/master/data/"
    click LL "https://github.com/zhenglisec/blind-watermark-for-dnn/tree/master/data/IEEE/logo"
    click LM "https://github.com/zhenglisec/blind-watermark-for-dnn/blob/master/models/LeNet.py"
    click VG "https://github.com/zhenglisec/blind-watermark-for-dnn/blob/master/models/vgg.py"
    click RN "https://github.com/zhenglisec/blind-watermark-for-dnn/blob/master/models/resnet.py"
    click PA "https://github.com/zhenglisec/blind-watermark-for-dnn/blob/master/models/preact_resnet.py"
    click GN "https://github.com/zhenglisec/blind-watermark-for-dnn/blob/master/models/googlenet.py"
    click DP "https://github.com/zhenglisec/blind-watermark-for-dnn/blob/master/models/dpn.py"
    click MB "https://github.com/zhenglisec/blind-watermark-for-dnn/blob/master/models/mobilenetv2.py"
    click HUN "https://github.com/zhenglisec/blind-watermark-for-dnn/blob/master/models/HidingUNet.py"
    click DIS "https://github.com/zhenglisec/blind-watermark-for-dnn/blob/master/models/Discriminator.py"
    click TO "https://github.com/zhenglisec/blind-watermark-for-dnn/blob/master/main.py"
    click UT "https://github.com/zhenglisec/blind-watermark-for-dnn/blob/master/utils.py"
    click RS "https://github.com/zhenglisec/blind-watermark-for-dnn/tree/master/results/"

    classDef data fill:#ade8f4,stroke:#000;
    classDef model fill:#caffbf,stroke:#000;
    classDef orchestrator fill:#ffadad,stroke:#000;
    classDef utils fill:#e0e0e0,stroke:#000;
    classDef storage fill:#fdffb6,stroke:#000;
    classDef tech fill:#ffffff,stroke:none,italic;
```
