Skip to content

surface-defect-detection

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

surface-defect-detection

README.md

Confidence-Aware Visual Inspection

A practical computer-vision service for classifying six steel-surface defect types from the NEU dataset. The project combines model development with the operational work required to expose, run and troubleshoot an inference service.

Why this project matters

The repository demonstrates more than model training. It shows how I approach a technical system from an operations perspective:

  • reproducible configuration and seeded experiments
  • structured evaluation using macro F1, balanced accuracy and per-class metrics
  • documented API endpoints for health checks and predictions
  • request IDs and inference-time reporting for traceability
  • Docker packaging for a consistent runtime
  • clear setup, usage and troubleshooting documentation

Technology

Python 3.10+ · PyTorch · FastAPI · Docker · scikit-learn · OpenCV · Git

Defect classes

  1. Crazing
  2. Inclusion
  3. Patches
  4. Pitted surface
  5. Rolled-in scale
  6. Scratches

Repository map

surface-defect-detection/
├── configs/                 # reproducible training configuration
├── src/training/            # datasets, models, training and evaluation
├── src/api/app.py           # traceable FastAPI inference endpoint
├── api/                     # alternative API implementation
├── scripts/                 # training, evaluation and inference entry points
├── docs/                    # architecture, metrics and workflow notes
├── tests/                   # test modules
├── Dockerfile
└── docker-compose.yml

The repository retains earlier implementations and working notes to show the development history. The current consolidated training code is under src/training/; the API implementation with request IDs and inference timing is src/api/app.py.

Quick start

Local setup

git clone https://github.com/isaacyanney/Isaac-Yanney.git
cd Isaac-Yanney/surface-defect-detection
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

On Windows, activate the environment with .venv\Scripts\activate.

The NEU dataset and a trained checkpoint are required for training or prediction. Model checkpoints are intentionally not stored in the repository.

Train

python run.py train --config configs/baseline_config.yaml

Evaluate

python run.py eval --config configs/baseline_config.yaml --checkpoint models/resnet18_best.pth

Start an API implementation

uvicorn api.main:app --host 0.0.0.0 --port 8000

Interactive documentation is available at http://localhost:8000/docs. The service can start without a checkpoint, but prediction requests require a compatible trained model.

API overview

Endpoint Purpose
GET /health Service and model readiness
POST /predict Classify one uploaded image
POST /predict_batch Classify a small image batch
GET /classes Return supported defect classes

The consolidated API under src/api/app.py adds a UUID request_id and measured inference_ms to each successful prediction.

Current status

  • Training, evaluation and API modules are implemented.
  • Docker and Compose definitions are included.
  • Configuration and metric-selection logic are documented.
  • A trained checkpoint is required to reproduce predictions.
  • Performance figures are not claimed here until a clean, reproducible evaluation run is committed.

This status is intentionally explicit so that implemented functionality, required artifacts and future validation work are easy to distinguish.

Next improvements

  • consolidate the two API implementations into one supported entry point
  • add lightweight automated API tests that do not require a full checkpoint
  • pin a reproducible dependency set
  • publish a verified evaluation report and confusion matrix
  • add CI for formatting and test execution

Operational lessons

This project reinforced the same principles that matter in IT support and technical operations: make system state visible, document dependencies, reproduce the environment, isolate failures and give users a clear path to resolution.

Author

Isaac Lovelace Yanney
IT Support & Technical Operations · AI Engineering
LinkedIn · Portfolio