Steel Surface Defect Detection with YOLOv8

An open source YOLOv8 project for steel surface defect detection, training, validation, inference, and GUI demos.

English | 简体中文

---

Overview

This repository is a learning-oriented steel surface defect detection project built on YOLOv8. It targets NEU-DET style steel defect datasets and provides a practical workflow for model training, validation, image inference, video inference, and a desktop GUI demo.

It is designed for students, computer vision beginners, and industrial vision learners who want a real, runnable, and maintainable open source project rather than an unmaintained collection of scripts.

Datasets, training outputs, and model weights are not included in this repository. Prepare them locally by following docs/dataset.md.

Start Here

python -m pip install -r requirements.txt
python predict.py --model /path/to/trusted-best.pt --source /path/to/image.jpg --device cpu

The rendered result is saved under runs/detect/. Bring a trusted local weight and an image you are allowed to process; the repository intentionally does not bundle either. See the sample inference guide for CPU, Apple Silicon MPS, and NVIDIA CUDA examples.

Current Status

• Current version: v0.1.3.
• CI runs focused Ruff checks, unit tests, CLI smoke tests, a synthetic CPU training/validation integration test, repository hygiene, and Python compilation on Python 3.10.
• The same health checks run automatically every Monday and can be started manually from GitHub Actions.
• Documentation exists for macOS, dataset preparation, model cards, sample inference, troubleshooting, support, security, and the roadmap.
• Datasets and model weights are not included in the repository; users should prepare them locally.
• The GUI checks local model, dataset, image, folder, and video paths before launching work.
• Apple Silicon MPS has been checked with PyTorch 2.5.1, a tensor operation, and one temporary image inference run.
• Planned v0.2.0 work focuses on reproducible training presets, broader device checks, and clearer experiment outputs.
• A fresh 50-epoch YOLOv8s/NEU-DET reproduction is recorded transparently in the experiment log. Historical metrics are not presented as verified because the original checkpoint and result files were lost during a device migration.

Reproduced Baseline

The v0.1.3 Apple Silicon run trained YOLOv8s for 50 epochs on a local 1,440 / 360 image split. Independent CPU validation of its local best.pt produced:

Precision	Recall	mAP50	mAP50-95	mAP75
0.719	0.721	0.7637	0.4455	0.4530

These values describe one public-dataset-style split, not factory performance. The crazing class was the weakest at 0.1861 mAP50-95. See the experiment log and model card for per-class results, environment details, limitations, and the local weight checksum. The dataset and weight are not committed or released.

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

Reproduction setup: YOLOv8s, 50 epochs, 640 px input, batch size 16, Apple M5 with MPS training, followed by independent CPU validation on 360 validation images containing 822 labeled defect instances.

Features

Feature	Description
Single-image inference	Load one image and visualize detected defect boxes.
Batch inference	Process an image folder and generate summary reports.
Video inference	Run defect detection on video files or camera streams.
Model training	Train YOLOv8 models from the command line or GUI.
Model validation	Evaluate trained weights and inspect mAP metrics.
GUI demo	Use a ttkbootstrap desktop interface for common workflows.
Device selection	Choose CPU, Apple Silicon MPS, or NVIDIA CUDA for CLI prediction.

Documentation

• macOS and Apple Silicon guide
• Sample inference with local files
• Dataset preparation
• Model card template
• YOLOv8s baseline experiment log
• YOLOv8s v0.1.3 model card
• Troubleshooting
• Roadmap
• Contributing guide
• Code of conduct
• Support
• Security policy

Screenshots

Single-image inference

Batch inference

Video inference

Training

Validation

Project Structure

steel-defect-detection/
├── ui.py                  # Desktop GUI built with ttkbootstrap
├── train.py               # YOLOv8 training entrypoint
├── predict.py             # Image and batch prediction entrypoint
├── val.py                 # Validation entrypoint
├── video_predict.py       # Video inference helper
├── translate.py           # VOC XML to YOLO TXT conversion utility
├── path_validation.py     # Dependency-light GUI path checks
├── dataset.yaml           # Dataset configuration
├── requirements.txt       # Python dependencies
├── requirements-dev.txt   # Focused lint and test dependencies
├── docs/                  # Project setup and maintenance docs
├── .github/               # CI, Dependabot, and issue templates
├── datasets/              # Local datasets, ignored by git
├── runs/                  # Local training/inference outputs, ignored by git
└── weights/ or *.pt        # Local model weights, ignored by git

Maintained Scope And Upstream

This repository vendors Ultralytics 8.0.182 so the original project remains reproducible without silently changing its YOLO runtime. The vendored ultralytics/, much of docs/, and generic examples/ originate from the Ultralytics project under AGPL-3.0.

Project-specific maintenance focuses on:

• train.py, val.py, predict.py, and video_predict.py;
• the ttkbootstrap desktop workflow in ui.py;
• dataset conversion and path validation;
• CPU, CUDA, and Apple Silicon MPS setup and compatibility;
• focused tests, CI, release documentation, and contributor support.

Changes to the vendored YOLO core are intentionally conservative. A future move to a pinned external package is tracked as a compatibility project rather than being presented as original model architecture work.

Defect Classes

The default configuration follows the six common NEU-DET steel surface defect classes:

ID	Class	Meaning
0	crazing	Fine crack-like surface patterns
1	inclusion	Non-metallic inclusion defects
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 scratch defects

Quick Start

1. Requirements

• Python 3.10 recommended
• CPU, Apple Silicon MPS, or NVIDIA CUDA
• Windows, Linux, or macOS

macOS users should start with docs/macos.md.

2. Install

git clone https://github.com/YfengJ/steel-defect-detection.git
cd steel-defect-detection

python -m venv venv

# Windows
venv\Scripts\activate

# Linux/macOS
source venv/bin/activate

python -m pip install --upgrade pip
python -m pip install -r requirements.txt

Prepare these files locally:

• Dataset: see docs/dataset.md
• Weights: download a YOLOv8 pretrained weight such as yolov8n.pt, or use your own trained best.pt

For a dataset-free first run with your own local image and trusted weight, use docs/sample_inference.md.

3. Launch the GUI

python ui.py

The GUI includes tabs for image prediction, batch prediction, video inference, training, and validation.

Command-line Usage

Train

# CPU
python train.py --model yolov8n.pt --data dataset.yaml --epochs 50 --batch 16 --device cpu

# Apple Silicon MPS
python train.py --model yolov8n.pt --data dataset.yaml --epochs 50 --batch 8 --device mps

# NVIDIA CUDA
python train.py --model yolov8n.pt --data dataset.yaml --epochs 50 --batch 16 --device cuda

Validate

python val.py --model runs/detect/train_result/weights/best.pt --data dataset.yaml

Predict

python predict.py \
  --model runs/detect/train_result/weights/best.pt \
  --source path/to/image.jpg \
  --device cpu

Dataset Preparation

This project can use the NEU Surface Defect Database or another dataset with the same class mapping.

Expected local layout:

datasets/NEU-DET/
├── images/
│   ├── train/
│   ├── val/
│   └── test/
├── labels/
│   ├── train/
│   ├── val/
│   └── test/
└── annotations/

YOLO label files should use:

class_id x_center y_center width height

All coordinates must be normalized to 0.0 to 1.0.

If your annotations are VOC XML files, place them under datasets/NEU-DET/annotations/ and run:

python translate.py

Model Weights

Model weights are intentionally excluded from git. Keep large artifacts locally, in cloud storage, or in GitHub Releases.

Only load weights from sources you trust. PyTorch checkpoints may contain serialized Python objects.

Common local choices:

Weight	Use case
yolov8n.pt	Fastest baseline for CPU or small experiments
yolov8s.pt	Better speed/accuracy balance
yolov8m.pt	Medium experiments when hardware allows
best.pt	Your trained defect detector

Dependency Updates

Dependabot is enabled for Python dependencies and GitHub Actions. Large dependency jumps are reviewed conservatively because PyTorch, OpenCV, NumPy, and Ultralytics compatibility can be sensitive across platforms. This repository vendors Ultralytics 8.0.182; PyTorch is capped below 2.6 because newer torch.load defaults are incompatible with that checkpoint loader. NumPy is capped below 2.4 because this vendored runtime still calls numpy.trapz.

Release Notes

See RELEASE_NOTES.md for v0.1.3 changes, known limitations, and next plans.

Community

Real bug reports, reproduction notes, and focused pull requests are welcome. Share a tested environment or result in the reproduction reports discussion. If this project helps your study or research, consider starring the repository to support continued maintenance. Please do not use star exchanges or other artificial promotion.

License

This project is licensed under the AGPL-3.0 License.

YOLOv8 is provided by Ultralytics and follows its upstream license terms.