How blaz-r/supersimplenet works
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/