Installation | Model Zoo | Reporting Issues

Introduction

QuantumFlake is a modular framework for automated detection and layer classification of 2D-material flakes in microscope images. It provides a one-command pipeline covering the end-to-end workflow:

detect → crop → classify → visualize

The main branch works with PyTorch 2.5+ and Python 3.12+.

Major features

• Multi-backend detection — Plug-and-play support for YOLO, DETR, ViTDet, OpenVINO-YOLO (CPU), and MaskTerial (Mask2Former).
• Detailed Reports — Unified JSON sidecars and visualization overlays across detectors.
• Layer Classification — Lightweight ResNet-based layer classifier (e.g., 1-layer, 5plus-layer).
• Extras — Optional color calibration, patch-based inference for large images, progress bars, and reproducible configs.

Related Research Showcase

Extras from our lab you can explore independently of the core framework.

• φ-Adapt — physics-informed domain adaptation.
• CLIFF — continual learning for incremental flake features.

Installation

Please refer to Installation for setup instructions (CUDA/CPU options, pinned deps).

Overview of Model Zoo

Architectures

Object Detection	Classification	Utilities
YOLO (Ultralytics) DETR (HF) ViTDet (Detectron2) OpenVINO-YOLO (CPU) MaskTerial (Mask2Former)	ResNet Layer Classifier	Color Calibration Patch-based Inference Configuration System

Weights

Organize weights in a weights/ folder:

• weights/uark_detector_v3.pt — YOLO detector
• weights/flake_monolayer_classifier.pth — classifier
• weights/maskterial/{config.yaml, maskterial.pth} — MaskTerial (optional)

Pipeline

1. Detect flakes with the selected backend
2. Crop detections to flake chips
3. Classify crops (e.g., 1-layer, 5+ layers)
4. Save visualizations and JSON sidecars

Example JSON record:

{
  "bbox": [x1, y1, x2, y2],
  "det_conf": 0.8731,
  "cls": "1-layer",
  "cls_conf": 0.9123
}

Overlays are saved as vis_<image>.png, and per-image detections as <image_stem>.json inside output_dir.

Configuration

See docs/guide/config.md for instructions with adjusting the configurations.

Training (Overview)

Detector (YOLO)

Dataset YAML:

train: /path/to/detector_dataset/images/train
val: /path/to/detector_dataset/images/val
nc: 1
names: ["flake"]

Train:

python -m quantumflake.cli train detector   --data /path/to/dataset.yaml   --epochs 100   --imgsz 640   --device 0

DETR and YOLO training details & tips live in their respective docs:

• YOLO — docs/models/yolo.md
• DETR — docs/models/detr.md

Classifier (ImageFolder)

Folder structure:

my_dataset/
├── 1-layer/
│   ├── flake_01.png
│   └── ...
└── 5plus-layer/
    └── ...

Train:

python -m quantumflake.cli train classifier   --data my_dataset   --epochs 25   --device cuda:0   --save-dir runs/classify   --num-materials 2   --material-dim 64

Project Structure

quantumflake/
│
├─ quantumflake/
│  ├─ __init__.py
│  ├─ cli.py
│  ├─ pipeline.py
│  ├─ cfg/
│  │   └─ default.yaml
│  ├─ models/
│  │   └─ detector.py
│  ├─ trainers/
│  │   ├─ detect.py
│  │   └─ classify.py
│  └─ utils/
│      ├─ io.py
│      ├─ data.py
│      ├─ vis.py
│      ├─ vitdet_bootstrap.py
│      ├─ maskterial_bootstrap.py
│      └─ m2f_bootstrap.py
│
├─ weights/
│   ├─ uark_detector_v3.pt
│   ├─ flake_monolayer_classifier.pth
│   └─ maskterial/
│       ├─ config.yaml
│       └─ maskterial.pth
└─ README.md

Contributors

Name	Affiliation
Xuan-Bac Nguyen	University of Arkansas
Sankalp Pandey	University of Arkansas
Tim Faltermeier	Montana State University
Dr. Hugh Churchill	University of Arkansas
Dr. Nicholas Borys	Montana State University
Dr. Khoa Luu	University of Arkansas

License

This project is released under the MIT License.