# blaz-r/supersimplenet architecture

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

- Interactive diagram: https://gitdiagram.com/blaz-r/supersimplenet
- Repository: https://github.com/blaz-r/supersimplenet

## Overview

##### Project type and purpose
- SuperSimpleNet is a research-oriented machine-learning framework for unified surface-defect detection (both supervised and unsupervised).
- It provides data-preparation scripts, datamodules, model definition, training, evaluation, and performance benchmarking.

##### File structure
- Top-level folders:
- common/         → shared utilities (losses, noise, visualizer, results writer)
- datamodules/    → data-loading abstractions (base classes, dataset plugins, setup scripts)
- model/          → network code (feature_extractor.py, supersimplenet.py)
- perf/           → performance benchmark code
- paper_results/  → static JSON/CSV with published results
- Scripts at root:
- train.py, eval.py, perf/perf_main.py
- Slurm wrappers for train/eval/perf
- Config and dependencies in requirements.txt; optional wandb logging.

##### Main components
a. Data Preparation & Storage
- External raw data sources (MVTec, VisA, KSDD2, SensumSODF)
- datamodules/setup scripts → download, extract, organize into standardized folder tree
- Final `datasets/` directory
b. Datamodules Layer
- Base datamodule and dataset classes (datamodules/base/)
- Dataset-specific implementations (ksdd2.py, mvtec.py, visa.py, sensum.py)
- Exposes train/val/test PyTorch DataLoaders
c. Model Definition
- common utilities: loss functions, perlin noise augmentation, visualizer, results writer
- model/feature_extractor.py → backbone network
- model/supersimplenet.py → head for defect classification/localization
d. Training Pipeline
- train.py orchestrates:
- Instantiates chosen datamodule
- Instantiates network, loss, optimizer, scheduler (config in train.py)
- (Optional) wandb logger
- Training loop → writes weights to `./weights/<run_id>/…`
- Results logged via common/results_writer.py
e. Evaluation Pipeline
- eval.py loads checkpoint, datamodule, runs inference, computes metrics
- Outputs: AUC, pixel-level scores, JSON/CSV (written to paper_results/ or local results/)
f. Performance Benchmark
- perf/perf_main.py runs inference benchmarks (throughput, latency, memory, flops)
- Outputs performance metrics, slurm wrapper available

##### Relationships and interactions
- Data Preparation → datasets/
↓
- Datamodules (read datasets/)
↓
- Training (datamodule → model → results_writer → weights/)
↓
- Evaluation (weights/ + datamodule → eval metrics → outputs/)
↓
- perf_main (model weights + synthetic or real data → performance measures)
- common/ utilities used by both training and evaluation

##### Architectural patterns and design principles
- Modular separation: data-prep, data-loading, model, training, evaluation, perf
- Single-responsibility: each script or module has a focused role
- Plug-and-play datamodules: new datasets integrate by subclassing base classes
- CLI-driven workflows: train.py, eval.py, perf_main.py + Slurm wrappers
- Optional external logging (wandb) decoupled behind config flag

##### Detail level
- Folder as a component group (common, datamodules, model, scripts)
- Call out key files inside model/ (feature_extractor, supersimplenet) and datamodules/

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Data Sources
    subgraph "External Data Sources" 
        direction TB
        Data1["Cloud: MVTec"]:::external
        Data2["Cloud: VisA"]:::external
        Data3["Cloud: KSDD2"]:::external
        Data4["Cloud: SensumSODF"]:::external
    end

    %% Data Preparation
    subgraph "Data Preparation Scripts" 
        direction TB
        Prep1["prepare_ksdd2.py"]:::data
        Prep2["prepare_mvtec.py"]:::data
        Prep3["prepare_visa.py"]:::data
    end
    click Prep1 "https://github.com/blaz-r/supersimplenet/blob/main/datamodules/setup/prepare_ksdd2.py"
    click Prep2 "https://github.com/blaz-r/supersimplenet/blob/main/datamodules/setup/prepare_mvtec.py"
    click Prep3 "https://github.com/blaz-r/supersimplenet/blob/main/datamodules/setup/prepare_visa.py"

    %% Dataset Storage
    Datasets["datasets/"]:::storage

    %% Datamodules Layer
    subgraph "Datamodules Layer"
        direction TB
        BaseDM["datamodule.py"]:::module
        BaseDS["dataset.py"]:::module
        KS["ksdd2.py"]:::module
        MV["mvtec.py"]:::module
        VI["visa.py"]:::module
        SE["sensum.py"]:::module
    end
    click BaseDM "https://github.com/blaz-r/supersimplenet/blob/main/datamodules/base/datamodule.py"
    click BaseDS "https://github.com/blaz-r/supersimplenet/blob/main/datamodules/base/dataset.py"
    click KS "https://github.com/blaz-r/supersimplenet/blob/main/datamodules/ksdd2.py"
    click MV "https://github.com/blaz-r/supersimplenet/blob/main/datamodules/mvtec.py"
    click VI "https://github.com/blaz-r/supersimplenet/blob/main/datamodules/visa.py"
    click SE "https://github.com/blaz-r/supersimplenet/blob/main/datamodules/sensum.py"

    %% Common Utilities
    subgraph "Common Utilities"
        direction TB
        Loss["loss.py"]:::util
        Noise["perlin_noise.py"]:::util
        Viz["visualizer.py"]:::util
        Writer["results_writer.py"]:::util
    end
    click Loss "https://github.com/blaz-r/supersimplenet/blob/main/common/loss.py"
    click Noise "https://github.com/blaz-r/supersimplenet/blob/main/common/perlin_noise.py"
    click Viz "https://github.com/blaz-r/supersimplenet/blob/main/common/visualizer.py"
    click Writer "https://github.com/blaz-r/supersimplenet/blob/main/common/results_writer.py"

    %% Model Definition
    subgraph "Model Definition"
        direction TB
        FE["feature_extractor.py"]:::model
        SSN["supersimplenet.py"]:::model
    end
    click FE "https://github.com/blaz-r/supersimplenet/blob/main/model/feature_extractor.py"
    click SSN "https://github.com/blaz-r/supersimplenet/blob/main/model/supersimplenet.py"

    %% Scripts
    subgraph "CLI Scripts"
        direction TB
        Train["train.py"]:::script
        Eval["eval.py"]:::script
        Perf["perf_main.py"]:::script
    end
    click Train "https://github.com/blaz-r/supersimplenet/blob/main/train.py"
    click Eval "https://github.com/blaz-r/supersimplenet/blob/main/eval.py"
    click Perf "https://github.com/blaz-r/supersimplenet/blob/main/perf/perf_main.py"

    %% Result Storage
    Weights["weights/"]:::storage
    subgraph "Published Results"
        direction TB
        PR1["icpr/perf_v100s.csv"]:::storage
        PR2["icpr/results_avg_std.json"]:::storage
        PR3["jims/perf_v100s.csv"]:::storage
        PR4["jims/results_avg_std.json"]:::storage
    end
    click PR1 "https://github.com/blaz-r/supersimplenet/blob/main/paper_results/icpr/perf_v100s.csv"
    click PR2 "https://github.com/blaz-r/supersimplenet/blob/main/paper_results/icpr/results_avg_std.json"
    click PR3 "https://github.com/blaz-r/supersimplenet/blob/main/paper_results/jims/perf_v100s.csv"
    click PR4 "https://github.com/blaz-r/supersimplenet/blob/main/paper_results/jims/results_avg_std.json"

    %% Flow Connections
    Data1 --> Prep2
    Data2 --> Prep2
    Data3 --> Prep1
    Data4 --> Prep3

    Prep1 --> Datasets
    Prep2 --> Datasets
    Prep3 --> Datasets

    Datasets --> BaseDM
    Datasets --> BaseDS
    BaseDM --> KS
    BaseDM --> MV
    BaseDM --> VI
    BaseDM --> SE
    KS -->|PyTorch DataLoader| Train
    MV -->|PyTorch DataLoader| Train
    VI -->|PyTorch DataLoader| Train
    SE -->|PyTorch DataLoader| Train

    Writer --> Train
    Loss --> Train
    Noise --> Train
    Viz --> Train

    FE --> Train
    SSN --> Train

    Train --> Weights
    Train -.->|Optional wandb| Wandb["Wandb Logger"]:::ext

    Weights --> Eval
    Datasets --> Eval
    SSN --> Eval
    BaseDM --> Eval
    Eval -->|AUC & Scores| PR1
    Eval -->|AUC & Scores| PR2
    Eval -->|AUC & Scores| PR3
    Eval -->|AUC & Scores| PR4

    Weights --> Perf
    FE --> Perf
    SSN --> Perf
    Datasets --> Perf
    Perf -->|Throughput, Latency, Memory, FLOPs| PR1
    Perf -->|Throughput, Latency, Memory, FLOPs| PR3

    %% Styles
    classDef external fill:#D0E6FF,stroke:#0284C7,color:#024E76;
    classDef data fill:#E6F4FF,stroke:#0284C7,color:#024E76;
    classDef storage fill:#F3F4F6,stroke:#6B7280,color:#374151,stroke-dasharray: 5 5;
    classDef module fill:#EFF6EE,stroke:#15803D,color:#14532D;
    classDef util fill:#FEF9C3,stroke:#D97706,color:#92400E;
    classDef model fill:#D1FAE5,stroke:#059669,color:#065F46;
    classDef script fill:#FFEDD5,stroke:#EA580C,color:#7C2D12;
    classDef ext fill:#E0E7FF,stroke:#4338CA,color:#312E81;
```
