training/README.md

Steel ROI Gate Training

This project now supports a steel-surface detector in front of defect segmentation.

Why detector and not plain classifier?

1. A classifier can say steel or non_steel, but it cannot give the bounding box you asked for.
2. A detector can localize the steel region, crop that ROI, and send only that region into the defect segmentation model.
3. This is the right architecture for mixed live-camera scenes with people, tools, and background clutter.

What the scripts do

prepare_surface_gate_dataset.py

• downloads steel-positive sources automatically
• downloads non-steel backgrounds automatically
• creates a YOLO detector dataset
• generates synthetic composites so the detector learns actual steel bounding boxes
• writes dataset.yaml

train_surface_gate_detector.py

• finetunes a small YOLO detector quickly
• copies the best checkpoint into models/steel_surface_detector.pt
• makes the web app use that model automatically after restart

Automatic data sources

Positive steel sources:

• NEU mirror on Hugging Face
• local test_images/
• optional Severstal mirror on Hugging Face

Automatic non-steel/background source:

• torchvision datasets downloaded automatically
• default quick path: CIFAR10
• optional stronger but heavier path: STL10

This avoids making you manually collect a non-steel dataset.

Recommended quick workflow

1. Install training extras:

cd "/Users/ravindranadhm/Documents/Projects/steel-surface-inspection copy"
venv/bin/python -m pip install -r training/requirements.txt

2. Build the detector dataset:

cd "/Users/ravindranadhm/Documents/Projects/steel-surface-inspection copy"
venv/bin/python training/prepare_surface_gate_dataset.py

This default mode is the fastest path because it avoids the larger Severstal archive and uses CIFAR10 as an automatic non-steel source.

If you want stronger natural-scene negatives later:

venv/bin/python training/prepare_surface_gate_dataset.py --negative-source stl10

If you want a stronger detector after the first run, rebuild with Severstal included:

venv/bin/python training/prepare_surface_gate_dataset.py --include-severstal

3. Train the lightweight detector:

cd "/Users/ravindranadhm/Documents/Projects/steel-surface-inspection copy"
venv/bin/python training/train_surface_gate_detector.py

4. Restart the app:

cd "/Users/ravindranadhm/Documents/Projects/steel-surface-inspection copy"
venv/bin/uvicorn api.main:app --host 127.0.0.1 --port 8000

Fast settings

If you want the quickest useful first model:

• model=yolo11n.pt
• epochs=18
• imgsz=512
• batch=16
• dataset build without --include-severstal

If you have only CPU and want to finish faster:

venv/bin/python training/train_surface_gate_detector.py --epochs 12 --imgsz 416 --batch 8

If you want a stronger detector later

• increase --max-severstal
• increase --max-negatives
• raise --composite-multiplier
• train 25-40 epochs instead of 12-18

Runtime config after training

The app will automatically use:

• models/steel_surface_detector.pt

Relevant env keys are already supported:

• SURFACE_DETECTOR_PATH
• SURFACE_DETECTOR_CLASS_NAME
• SURFACE_DETECTOR_CONFIDENCE
• SURFACE_DETECTOR_MIN_AREA_RATIO
• SURFACE_DETECTOR_EXPAND_RATIO
• SURFACE_DETECTOR_IMAGE_SIZE

Important expectation

The first fast model is meant to be a practical gate, not a perfect production vision model.

The improvement loop should be:

1. train the quick detector
2. deploy it
3. save false accepts / false rejects from live camera
4. add those hard examples back into training
5. retrain

That is the fastest route to a reliable factory-facing steel ROI gate.