# jzyustc/mbrs architecture

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

- Interactive diagram: https://gitdiagram.com/jzyustc/mbrs
- Repository: https://github.com/jzyustc/mbrs

## Overview

##### Project Type and Purpose
- This is a research‐oriented deep learning project (MBRS) focused on robust watermark embedding and extraction in images using PyTorch.
- It implements a mini‐batch strategy combining real and simulated JPEG compression during training to improve watermark robustness.

##### High‐Level Architecture Overview
The system can be broken down into three major layers:
A. Data & Configuration Layer
B. Core ML Pipeline (Network + Noise Simulation + Training/Test Loops)
C. Persistence & Results Layer

##### Main Components
1. Data & Configuration
- Datasets directory (ImageNet/COCO folders under `datasets/`)
- `utils/` modules:
- Dataloader.py – wraps PyTorch DataLoader for training/test sets
- load_train_setting.py / load_test_setting.py – parse JSON hyperparameters
- settings.py – default constants
- Configuration files:
- `train_settings.json`
- `test_settings.json`

2. Core ML Pipeline
a. Network Module (`network/`)
- Encoder classes (Encoder_MP.py, Encoder_MP_Decoder.py)
- Decoder.py – extracts watermark bits
- Discriminator.py – adversarial discriminator for image realism
- Network.py – orchestrates the end‐to‐end forward pass
- Blocks submodule (`network/blocks/`): reusable layers (ConvNet, ExpandNet, SENet)
b. Noise Simulation (`network/noise_layers/`)
- Combined, crop, gaussian_filter, jpeg, salt_pepper, etc.
- Injects distortion between encoder and decoder during training
c. Training & Testing Scripts
- `train.py`: loads settings, instantiates DataLoader, network, noise layers, optimizer, loss functions, and executes the training loop with early stopping, checkpoint saving.
- `test.py`: loads a saved model checkpoint, runs inference over test images, records BER & PSNR metrics.

3. Persistence & Results
- `results/`: hierarchical storage per experiment (e.g., `MBRS_256_m256/`), containing:
- models/ – saved checkpoints
- images/ – sample reconstructions
- train_log.txt, val_log.txt, test_*.log, *.json – performance logs and parameters

##### Relationships & Data Flow
1. Configuration files → JSON parser (`utils/load_*_setting.py`) → training/test parameters
2. Dataset directory → `utils/Dataloader.py` → minibatches of images & watermark bits
3. minibatch → Encoder → watermarked images
4. watermarked images → “real + simulated JPEG” noise layers → corrupted images
5. corrupted images → Decoder → recovered watermark bits
6. (During training) Encoder+Decoder outputs → loss functions (+ Discriminator) → backprop through Network
7. Every N epochs → checkpoint saved into `results/.../models/` → performance logged

##### Architectural Patterns & Design Principles
- Modular design:
- Separation of concerns between network layers (`network/blocks`), noise simulation (`network/noise_layers`), and orchestration (`network/Network.py`).
- Configurable pipeline: JSON‐driven hyperparameters allow reproducibility and multiple experiment configurations.
- Pluggable noise modules: easy to add new attacks by dropping new Python modules in `noise_layers/`.
- Clear logging and checkpointing for rapid iteration.

##### Technologies & Frameworks to Highlight
- PyTorch for model definition, training loops, autograd
- Kornia for differentiable image processing (when applicable)
- NumPy, Pillow, SciPy for data manipulation
- Python standard libs for JSON, logging, file I/O

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data & Configuration Layer"
        cfgTrain["train_settings.json"]:::data
        cfgTest["test_settings.json"]:::data
        loadTrain["load_train_setting.py"]:::data
        loadTest["load_test_setting.py"]:::data
        defaults["settings.py"]:::data
        Datasets["datasets/ (ImageNet/COCO)"]:::data
        DataLoader["Dataloader.py"]:::data
    end

    subgraph "Core ML Pipeline"
        subgraph "Network Module"
            Net["Network.py"]:::core
            EncoderMP["Encoder_MP.py"]:::core
            EncDec["Encoder_MP_Decoder.py"]:::core
            Decoder["Decoder.py"]:::core
            Discrim["Discriminator.py"]:::core
            subgraph "Blocks"
                ConvNet["ConvNet.py"]:::core
                ExpandNet["ExpandNet.py"]:::core
                SENet["SENet.py"]:::core
            end
        end
        NoiseEntry["Noise.py"]:::core
        subgraph "Noise Simulation Layers"
            Combined["combined.py"]:::core
            Crop["crop.py"]:::core
            GaussFilt["gaussian_filter.py"]:::core
            GaussNoise["gaussian_noise.py"]:::core
            Identity["identity.py"]:::core
            JPEG["jpeg.py"]:::core
            Middle["middle_filter.py"]:::core
            SaltPepper["salt_pepper_noise.py"]:::core
        end
        TrainScript["train.py"]:::script
        TestScript["test.py"]:::script
    end

    subgraph "Persistence & Results"
        Results["results/MBRS_256_m256"]:::storage
        Models["models/"]:::storage
        Images["images/"]:::storage
        TrainLog["train_log.txt"]:::storage
        ValLog["val_log.txt"]:::storage
        TestLog["test_JpegTest..._log.txt"]:::storage
        TestParams["test_JpegTest..._params.json"]:::storage
    end

    %% Relationships
    cfgTrain -->|parses| loadTrain
    cfgTest -->|parses| loadTest
    defaults -->|provides constants| TrainScript
    defaults -->|provides constants| TestScript
    loadTrain -->|settings| TrainScript
    loadTest -->|settings| TestScript
    Datasets -->|images| DataLoader
    DataLoader -->|mini-batch images+bits| TrainScript
    DataLoader -->|mini-batch images+bits| TestScript

    TrainScript -->|instantiates| Net
    TrainScript -->|uses| NoiseEntry
    TrainScript -->|runs loop| Net
    Net -->|calls| EncoderMP
    Net -->|calls| EncDec
    EncDec -->|extracts| Decoder
    Net -->|adversarial loss| Discrim
    NoiseEntry -->|injects| Combined
    Combined -->|flows through| Crop
    Crop --> GaussFilt --> GaussNoise --> Identity --> JPEG --> Middle --> SaltPepper
    SaltPepper -->|corrupted images| Decoder
    Decoder -->|recovered bits| Net
    Net -->|loss gradients| TrainScript
    TrainScript -->|saves checkpoint| Models
    TrainScript -->|writes logs| TrainLog
    TrainScript -->|writes logs| ValLog

    TestScript -->|loads checkpoint| Models
    TestScript -->|runs inference| Net
    TestScript -->|writes images| Images
    TestScript -->|writes logs| TestLog
    TestScript -->|writes params| TestParams

    %% Click Events
    click DataLoader "https://github.com/jzyustc/mbrs/blob/main/utils/Dataloader.py"
    click loadTrain "https://github.com/jzyustc/mbrs/blob/main/utils/load_train_setting.py"
    click loadTest "https://github.com/jzyustc/mbrs/blob/main/utils/load_test_setting.py"
    click defaults "https://github.com/jzyustc/mbrs/blob/main/utils/settings.py"
    click cfgTrain "https://github.com/jzyustc/mbrs/blob/main/train_settings.json"
    click cfgTest "https://github.com/jzyustc/mbrs/blob/main/test_settings.json"
    click EncoderMP "https://github.com/jzyustc/mbrs/blob/main/network/Encoder_MP.py"
    click EncDec "https://github.com/jzyustc/mbrs/blob/main/network/Encoder_MP_Decoder.py"
    click Decoder "https://github.com/jzyustc/mbrs/blob/main/network/Decoder.py"
    click Discrim "https://github.com/jzyustc/mbrs/blob/main/network/Discriminator.py"
    click Net "https://github.com/jzyustc/mbrs/blob/main/network/Network.py"
    click ConvNet "https://github.com/jzyustc/mbrs/blob/main/network/blocks/ConvNet.py"
    click ExpandNet "https://github.com/jzyustc/mbrs/blob/main/network/blocks/ExpandNet.py"
    click SENet "https://github.com/jzyustc/mbrs/blob/main/network/blocks/SENet.py"
    click NoiseEntry "https://github.com/jzyustc/mbrs/blob/main/network/Noise.py"
    click Combined "https://github.com/jzyustc/mbrs/blob/main/network/noise_layers/combined.py"
    click Crop "https://github.com/jzyustc/mbrs/blob/main/network/noise_layers/crop.py"
    click GaussFilt "https://github.com/jzyustc/mbrs/blob/main/network/noise_layers/gaussian_filter.py"
    click GaussNoise "https://github.com/jzyustc/mbrs/blob/main/network/noise_layers/gaussian_noise.py"
    click Identity "https://github.com/jzyustc/mbrs/blob/main/network/noise_layers/identity.py"
    click JPEG "https://github.com/jzyustc/mbrs/blob/main/network/noise_layers/jpeg.py"
    click Middle "https://github.com/jzyustc/mbrs/blob/main/network/noise_layers/middle_filter.py"
    click SaltPepper "https://github.com/jzyustc/mbrs/blob/main/network/noise_layers/salt_pepper_noise.py"
    click TrainScript "https://github.com/jzyustc/mbrs/blob/main/train.py"
    click TestScript "https://github.com/jzyustc/mbrs/blob/main/test.py"
    click Results "https://github.com/jzyustc/mbrs/tree/main/results/MBRS_256_m256"
    click Models "https://github.com/jzyustc/mbrs/tree/main/results/MBRS_256_m256/models"
    click Images "https://github.com/jzyustc/mbrs/tree/main/results/MBRS_256_m256/images"
    click TrainLog "https://github.com/jzyustc/mbrs/blob/main/results/MBRS_256_m256/train_log.txt"
    click ValLog "https://github.com/jzyustc/mbrs/blob/main/results/MBRS_256_m256/val_log.txt"
    click TestLog "https://github.com/jzyustc/mbrs/blob/main/results/MBRS_256_m256/test_JpegTest(50)_s1_log.txt"
    click TestParams "https://github.com/jzyustc/mbrs/blob/main/results/MBRS_256_m256/test_JpegTest(50)_s1_params.json"

    %% Styles
    classDef data fill:#e0f7fa,stroke:#006064,color:#004d40
    classDef core fill:#bbdefb,stroke:#0d47a1,color:#0d47a1
    classDef script fill:#ffe0b2,stroke:#e65100,color:#bf360c
    classDef storage fill:#eeeeee,stroke:#424242,color:#212121
```
