Train, validate and run a YOLOv8 steel surface defect detector from a desktop GUI or the command line.
This is a learning-oriented project for the six NEU-DET steel surface defect classes. It covers the whole loop: convert VOC annotations, train, validate, detect on images, folders and video, and inspect the results in a desktop app. Datasets and weights are not bundled. You prepare them locally (docs/dataset.md).
- Desktop app with a sidebar workspace, dark and light themes, and a CPU / Apple MPS / CUDA device picker on every page. It runs on Windows, macOS and Linux, with a one-click setup and launcher for Windows.
- Single image: switch between the original and the annotated image. Every detection is listed with its confidence and area.
- Batch: per-folder statistics, class and confidence charts, and a per-image table. Double-click a row to open its result image.
- Video and camera: live inference that drops stale frames, with FPS and per-frame defect counts.
- Training: each run writes to its own directory and draws live mAP and loss
curves from
results.csv. A run can be stopped from the app. - Validation: overall precision, recall and mAP, plus per-class results
parsed from
val.py. - CLI scripts for every step, tested in CI (Ruff, unit tests, CLI smoke tests, and a synthetic CPU train and validate run) on Linux and Windows.
git clone https://github.com/YfengJ/steel-defect-detection.git
cd steel-defect-detection
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txtOn Windows you can instead run scripts\windows\setup.bat (add cuda for an
NVIDIA GPU) and then double-click start_gui.bat. See
docs/windows.md.
Launch the GUI:
python ui.pyOr detect on one image from the command line:
python predict.py --model /path/to/trusted-best.pt --source /path/to/image.jpg --device cpuResults go to runs/detect/<name>/. Only load weights you trust: PyTorch
checkpoints can contain serialized Python objects. Platform guides:
Windows and macOS. For a dataset-free first run, see
docs/sample_inference.md.
| Batch detection | Video detection |
|---|---|
![]() |
![]() |
| Training | Validation |
![]() |
![]() |
The light theme is one click away in the sidebar:
The screenshots use the v0.1.3 YOLOv8s baseline weight described below. The
images come from the NEU-DET validation split. The training page shows the
results.csv of that baseline run.
YOLOv8s, 50 epochs, 640 px, batch 16. It was trained on Apple M5 (MPS) with a local 1,440 / 360 image split, then validated separately on CPU against 822 labeled defect instances:
| Precision | Recall | mAP50 | mAP50-95 | mAP75 |
|---|---|---|---|---|
| 0.719 | 0.721 | 0.7637 | 0.4455 | 0.4530 |
| Class | Precision | Recall | mAP50 | mAP50-95 |
|---|---|---|---|---|
crazing |
0.625 | 0.383 | 0.472 | 0.1861 |
inclusion |
0.716 | 0.767 | 0.816 | 0.4821 |
patches |
0.741 | 0.891 | 0.904 | 0.6045 |
pitted_surface |
0.825 | 0.788 | 0.847 | 0.5253 |
rolled-in_scale |
0.611 | 0.567 | 0.630 | 0.2883 |
scratches |
0.795 | 0.928 | 0.913 | 0.5864 |
These numbers describe one public-dataset split, not factory performance. Details, limitations and the weight checksum are in the experiment log and the model card. The weight itself is not published.
python train.py --model yolov8n.pt --data dataset.yaml --epochs 50 --batch 16 --device cpu
python train.py --model yolov8n.pt --data dataset.yaml --epochs 50 --batch 8 --device mps
python train.py --model yolov8n.pt --data dataset.yaml --epochs 50 --batch 16 --device 0| Option | Default | Notes |
|---|---|---|
--imgsz |
640 |
Training image size |
--workers |
2 |
Set to 0 if Windows multiprocessing fails |
--project / --name |
runs/detect / train_result |
An existing run directory is never reused; the run becomes train_result2, train_result3, … |
--exist-ok |
off | Reuse the directory on purpose. This overwrites the old weights and appends to the old results.csv |
The final weight path is printed when training ends.
python val.py --model runs/detect/train_result/weights/best.pt --data dataset.yaml
python val.py --model best.pt --data dataset.yaml --split test --device cpuval.py prints precision, recall, mAP50, mAP50-95 and mAP75, and the
per-class results. It also prints one METRICS_JSON {...} line for tools such as
the GUI.
python predict.py --model best.pt --source path/to/image.jpg --conf 0.25 --device cpu
python predict.py --model best.pt --source path/to/folder/ --name my_batchAnnotated images and YOLO labels with confidences are saved under
runs/detect/<name>/.
python video_predict.py best.pt path/to/video.mp4 --output output.mp4 --conf 0.25
python video_predict.py best.pt 0 # camera index 0Use the NEU Surface Defect Database or any dataset with the same class mapping:
datasets/NEU-DET/
├── images/{train,val,test}/
├── labels/{train,val,test}/
└── annotations/ # optional VOC XML
YOLO labels use class_id x_center y_center width height, normalized to
0.0–1.0. To convert VOC XML annotations, run:
python translate.pyThis writes labels/<split>/ for every existing images/<split> directory.
dataset.yaml resolves its path relative to the YAML file itself. See
docs/dataset.md for the full guide.
| ID | Class | Meaning |
|---|---|---|
| 0 | crazing |
Fine crack-like surface patterns |
| 1 | inclusion |
Non-metallic inclusions |
| 2 | patches |
Irregular surface patches |
| 3 | pitted_surface |
Pitting or corrosion-like marks |
| 4 | rolled-in_scale |
Oxide scale rolled into the surface |
| 5 | scratches |
Linear scratches |
steel-defect-detection/
├── ui.py # Desktop GUI (ttkbootstrap)
├── gui_logic.py # Display-free GUI helpers: label parsing, batch stats, metrics
├── train.py # Training CLI
├── val.py # Validation CLI
├── predict.py # Image / folder prediction CLI
├── video_predict.py # Video and camera inference CLI
├── translate.py # VOC XML → YOLO TXT conversion
├── path_validation.py # Local path and dataset YAML checks
├── cli_support.py # Shared CLI helpers (UTF-8 console output)
├── dataset.yaml # Default dataset configuration
├── start_gui.bat # Windows GUI launcher (no console window)
├── scripts/windows/ # Windows one-click setup
├── requirements*.txt # Runtime and contributor dependencies
├── tests/ # Unit, GUI-callback, CLI and training smoke tests
├── docs/ # Setup, dataset, experiment and maintenance docs
└── ultralytics/ # Vendored Ultralytics 8.0.182
datasets/, runs/, weights/ and *.pt files are git-ignored.
- The vendored Ultralytics 8.0.182 keeps the original runtime reproducible.
ultralytics/, most ofdocs/and the genericexamples/come from the Ultralytics project under AGPL-3.0. Changes to that core are deliberately conservative. - PyTorch < 2.6. The newer
torch.loaddefault breaks this checkpoint loader. - NumPy < 2.4. The vendored metrics code still calls
numpy.trapz. - ttkbootstrap 1.10+ and 2.x both work. The GUI registers its own themes.
- Windows · macOS and Apple Silicon · Sample inference · Dataset preparation · Troubleshooting
- Baseline experiment log · v0.1.3 model card · Model card template
- GUI smoke checklist · Roadmap · Release notes
- Contributing · Code of conduct · Support · Security
Bug reports, reproduction notes and focused pull requests are welcome. Share a tested environment or result in the reproduction reports discussion. If the project helps your study, a star supports continued maintenance. Please do not use star exchanges.
AGPL-3.0. YOLOv8 is provided by Ultralytics under its upstream license.





