# phatnguyen6635/glass architecture

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

- Interactive diagram: https://gitdiagram.com/phatnguyen6635/glass
- Repository: https://github.com/phatnguyen6635/glass

## Overview

##### Project Type and Purpose
- This is a machine-learning research codebase (full ML pipeline) implementing “GLASS,” a unified anomaly synthesis strategy for unsupervised industrial anomaly detection/localization in PyTorch.
- It provides data ingestion, synthetic anomaly generation (via gradient ascent), model training, evaluation, and optional ONNX export.

##### File Structure Analysis
- Top-level Python modules:
- main.py – orchestration entry point (parses args, kicks off training or testing)
- datasets/ – dataset loaders and Excel distributions for MVTec, VisA, MPDD, WFDD
- backbones.py – model backbone definitions (e.g., CNN variants)
- glass.py – core anomaly synthesis logic (gradient ascent procedure)
- model.py – wraps backbone + synthesis into full detection model
- loss.py – custom loss functions for anomaly localization
- metrics.py – performance calculators (I-AUROC, P-AUROC, etc.)
- perlin.py – utility for Perlin-noise augmentation
- onnx/ – scripts for converting PyTorch models to ONNX and running with ORT
- shell/ – bash scripts to launch experiments per dataset
- utils.py, common.py – shared utilities (logging, argument parsing, I/O)
- Configuration/build:
- requirements.txt – Python dependencies (PyTorch, numpy, etc.)
- scripts under shell/ parameterize datapaths, class lists, and hyperparameters.

##### Key README Insights
- Describes environment setup (conda + pip), data download/organization, experiment launch via shell scripts.

##### Components
a. Main Components
1. Data Ingestion & Preparation
- Raw Dataset Folders (MVTec, VisA, MPDD, WFDD, DTD)
- Excel Distribution files
- Optional foreground masks
2. Data Augmentation & Synthesis
- Perlin noise generator (perlin.py)
- GLASS synthesis module (glass.py) performing gradient ascent
3. Model Definition
- Backbone networks (backbones.py)
- Detection head + anomaly scoring (model.py)
4. Training & Evaluation Pipeline
- main.py orchestrating train vs. test based on args
- loss computation (loss.py)
- metric computation (metrics.py)
5. Results & Export
- Checkpoint save/load
- ONNX conversion (onnx/pth2onnx.py)
- Inference with ONNX Runtime (onnx/ort.py)
- Figures output under figures/ and results/
6. Experiment Orchestration
- shell/*.sh scripts driving batch runs per dataset
b. Relationships & Interactions
- Data loaders feed raw images → augmentation/synthesis → model input
- Model outputs anomaly maps/scores → loss & metrics modules
- Training loop (in main.py) updates backbone + synthesis parameters
- Post-training: checkpoint → ONNX conversion → ORT inference → final metrics
- shell scripts wrap all components: set config → call main.py or onnx scripts
c. Architectural Patterns & Principles
- Modular separation: data, synthesis, model, training, evaluation, export
- Single entry-point CLI (main.py) with explicit mode flags (train/test/ckpt)
- Extensibility: adding a new dataset involves dropping loader in datasets/ + shell script
- Clear layering: low-level utilities (perlin, common) < core algorithm (glass) < training loop < orchestration scripts
d. Technologies & Libraries
- PyTorch (model, training), NumPy, OpenCV/PIL (image I/O in datasets),
- ONNX & ONNX Runtime for model export + inference
- Bash for running experiments

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layer 1: Data Source & Preprocessing
    subgraph "Layer 1: Data Source & Preprocessing"
        direction TB
        RawData["Raw Dataset Folders\n(MVTec, VisA, MPDD, WFDD, DTD)"]:::data
        ExcelFiles["Excel Distribution Files"]:::data
        DatasetPkg["Datasets Module"]:::data
        RawData --> DatasetPkg
        ExcelFiles --> DatasetPkg
    end

    %% Layer 2: Anomaly Synthesis & Augmentation
    subgraph "Layer 2: Anomaly Synthesis & Augmentation"
        direction TB
        Perlin["Perlin Noise Generator"]:::synthesis
        GLASS["GLASS Synthesis Module"]:::synthesis
        DatasetPkg --> Perlin
        Perlin --> GLASS
    end

    %% Layer 3: Model Architecture
    subgraph "Layer 3: Model Architecture"
        direction TB
        Backbones["CNN Backbones"]:::model
        ModelWrap["Detection Model (Backbone + Head)"]:::model
        GLASS --> ModelWrap
        Backbones --> ModelWrap
    end

    %% Layer 4: Training & Evaluation Engine
    subgraph "Layer 4: Training & Evaluation Engine"
        direction TB
        Main["main.py (Orchestrator)"]:::training
        Loss["Custom Loss Functions"]:::training
        Metrics["Metrics Calculator"]:::training
        ModelWrap --> Main
        Loss --> Main
        Metrics --> Main
    end

    %% Layer 5: Export & Inference (ONNX)
    subgraph "Layer 5: Export & Inference (ONNX)"
        direction TB
        Checkpoint["Model Checkpoint"]:::export
        Pth2ONNX["pth2onnx.py"]:::export
        ORT["ort.py"]:::export
        Figures["Figures/ Results/"]:::export
        Main --> Checkpoint
        Checkpoint --> Pth2ONNX
        Pth2ONNX --> ORT
        ORT --> Figures
    end

    %% Experiment Orchestrator
    subgraph "Experiment Orchestrator (shell scripts)"
        direction TB
        ShellMVTEC["run-mvtec.sh"]:::orchestrator
        ShellVISA["run-visa.sh"]:::orchestrator
        ShellMPDD["run-mpdd.sh"]:::orchestrator
        ShellWFDD["run-wfdd.sh"]:::orchestrator
        ShellCustom["run-custom.sh"]:::orchestrator
        ShellMadMan["run-mad-man.sh"]:::orchestrator
        ShellMadSys["run-mad-sys.sh"]:::orchestrator
        ShellMVTEC --> Main
        ShellVISA --> Main
        ShellMPDD --> Main
        ShellWFDD --> Main
        ShellCustom --> Main
        ShellMadMan --> Main
        ShellMadSys --> Main
    end

    %% Shared Utilities & Config
    subgraph "Shared Utilities & Configuration"
        direction TB
        Common["common.py"]:::utils
        Utils["utils.py"]:::utils
        Req["requirements.txt"]:::utils
        Readme["README.md"]:::utils
        License["LICENSE"]:::utils
        Common --> Main
        Utils --> Main
    end

    %% Click Events
    click DatasetPkg "https://github.com/phatnguyen6635/glass/tree/main/datasets/"
    click DatasetPkg "https://github.com/phatnguyen6635/glass/blob/main/datasets/__init__.py"
    click DatasetPkg "https://github.com/phatnguyen6635/glass/blob/main/datasets/mvtec.py"
    click DatasetPkg "https://github.com/phatnguyen6635/glass/blob/main/datasets/visa.py"
    click ExcelFiles "https://github.com/phatnguyen6635/glass/blob/main/datasets/excel/mpdd_distribution.xlsx"
    click ExcelFiles "https://github.com/phatnguyen6635/glass/blob/main/datasets/excel/mvtec_distribution.xlsx"
    click ExcelFiles "https://github.com/phatnguyen6635/glass/blob/main/datasets/excel/visa_distribution.xlsx"
    click ExcelFiles "https://github.com/phatnguyen6635/glass/blob/main/datasets/excel/wfdd_distribution.xlsx"
    click Perlin "https://github.com/phatnguyen6635/glass/blob/main/perlin.py"
    click GLASS "https://github.com/phatnguyen6635/glass/blob/main/glass.py"
    click Backbones "https://github.com/phatnguyen6635/glass/blob/main/backbones.py"
    click ModelWrap "https://github.com/phatnguyen6635/glass/blob/main/model.py"
    click Main "https://github.com/phatnguyen6635/glass/blob/main/main.py"
    click Loss "https://github.com/phatnguyen6635/glass/blob/main/loss.py"
    click Metrics "https://github.com/phatnguyen6635/glass/blob/main/metrics.py"
    click Pth2ONNX "https://github.com/phatnguyen6635/glass/blob/main/onnx/pth2onnx.py"
    click ORT "https://github.com/phatnguyen6635/glass/blob/main/onnx/ort.py"
    click Figures "https://github.com/phatnguyen6635/glass/tree/main/figures/"
    click ShellMVTEC "https://github.com/phatnguyen6635/glass/blob/main/shell/run-mvtec.sh"
    click ShellVISA "https://github.com/phatnguyen6635/glass/blob/main/shell/run-visa.sh"
    click ShellMPDD "https://github.com/phatnguyen6635/glass/blob/main/shell/run-mpdd.sh"
    click ShellWFDD "https://github.com/phatnguyen6635/glass/blob/main/shell/run-wfdd.sh"
    click ShellCustom "https://github.com/phatnguyen6635/glass/blob/main/shell/run-custom.sh"
    click ShellMadMan "https://github.com/phatnguyen6635/glass/blob/main/shell/run-mad-man.sh"
    click ShellMadSys "https://github.com/phatnguyen6635/glass/blob/main/shell/run-mad-sys.sh"
    click Common "https://github.com/phatnguyen6635/glass/blob/main/common.py"
    click Utils "https://github.com/phatnguyen6635/glass/blob/main/utils.py"
    click Req "https://github.com/phatnguyen6635/glass/blob/main/requirements.txt"
    click Readme "https://github.com/phatnguyen6635/glass/blob/main/README.md"
    click License "https://github.com/phatnguyen6635/glass/tree/main/LICENSE"

    %% Styles
    classDef data fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef synthesis fill:#D0FFD8,stroke:#28a745,color:#28a745
    classDef model fill:#FFF7D6,stroke:#dbab09,color:#dbab09
    classDef training fill:#E8F3FF,stroke:#005CC5,color:#005CC5
    classDef export fill:#FFEFE0,stroke:#d15704,color:#d15704
    classDef orchestrator fill:#F0D0E8,stroke:#6f42c1,color:#6f42c1
    classDef utils fill:#F2F2F2,stroke:#586069,color:#586069
```
