Project Guide | Weld Defect Vision

Live Demo

• Open the public GitHub Pages demo
• Scope: credential-free, synthetic-data demo for industrial validation discovery and quality evaluators.

Industrial weld defect detection research sandbox using YOLOv8 fine-tuning. It demonstrates 5 defect labels: Crack, Porosity, Spatter, Undercut, and Overlap. The repository is a synthetic-data validation discovery surface, not evidence of plant-floor performance.

Technical review pack: `docs/architecture-pack.md`

System Overview

An industrial inspection AI workflow that sells value through validation discovery, data-suitability review, and operator-readable evidence.

Evaluation Path

• Start here: Read the model card and validation notes before checking detections.
• Local demo: Start the API with uvicorn api.main:app --host 0.0.0.0 --port 8000, then test /detect or /detect/visualize.
• Checks: Run pytest -v; keep human inspector review explicit when presenting outputs.

Architecture Notes

• Architecture guide summarizes the system scope, first files to inspect, runtime commands, and known boundaries.
• Quality notes lists the local checks, CI surface, and release expectations for this repository.
• Enterprise readiness notes outlines security, data, operations, integration, and handoff expectations.

Architecture

Input Image (640x640)
    │
    ▼
┌──────────────────────────┐
│  YOLOv8 Backbone (CSPNet) │  ← COCO pretrained weights
│  + FPN Neck               │
└──────────┬───────────────┘
           │ Multi-scale features
           ▼
┌──────────────────────────┐
│  Detection Head           │
│  3 scales: P3/P4/P5       │
│  Per anchor: bbox + cls   │
└──────────┬───────────────┘
           │
           ▼
    NMS → Detections
    [bbox, class, confidence]

Key Features

• YOLOv8 Fine-tuning: Transfer learning from COCO-pretrained weights for weld defect domain
• 5 Defect Classes: Crack, Porosity, Spatter, Undercut, Overlap
• Data Augmentation: Mosaic, MixUp, HSV jitter, flip (built into YOLO pipeline)
• Evaluation: mAP@50, mAP@50-95, per-class precision/recall charts
• Visualization: Bounding box overlay with class-specific colors and confidence scores
• Inference API: FastAPI endpoint for real-time detection + annotated image response
• Docker: GPU-enabled training and CPU/GPU serving containers

Project Structure

weld-defect-vision/
├── src/
│   ├── config.py        # Hyperparameters, class labels, colors
│   ├── dataset.py       # YOLO dataset prep, validation, synthetic data
│   ├── train.py         # YOLOv8 training pipeline
│   ├── evaluate.py      # mAP evaluation with per-class charts
│   ├── inference.py     # Detection wrapper (single/batch)
│   └── visualize.py     # Bounding box drawing, detection grid
├── api/
│   ├── main.py          # FastAPI detection server
│   └── schemas.py       # Request/response models
├── data/
│   └── weld_defect.yaml # YOLO dataset configuration
├── tests/
│   ├── test_dataset.py  # Dataset and label format tests
│   ├── test_train.py    # Config and training component tests
│   └── test_api.py      # API endpoint tests
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
└── requirements.txt

Setup

pip install -r requirements.txt

Prepare Dataset

## Option 2: Generate synthetic data for pipeline testing
python -m src.dataset --synthetic 200


## Validate dataset structure
python -m src.dataset data/weld_defect.yaml

Expected YOLO format:

data/
├── weld_defect.yaml
├── images/
│   ├── train/
│   ├── val/
│   └── test/
└── labels/          # class x_center y_center width height (normalized)
    ├── train/
    ├── val/
    └── test/

Train

python -m src.train

Outputs:

• checkpoints/best.pt — Best model weights
• runs/detect/weld_defect/ — Training curves, PR curves, confusion matrix

Evaluate

python -m src.evaluate checkpoints/best.pt

Outputs:

• outputs/evaluation_results.json — Full metrics (mAP, precision, recall per class)
• outputs/per_class_metrics.png — Per-class AP/P/R bar chart

Inference API

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


## Detect defects (JSON response)
curl -X POST http://localhost:8000/detect -F "file=@weld_image.jpg"


## Detect + visualize (annotated image response)
curl -X POST http://localhost:8000/detect/visualize -F "file=@weld_image.jpg" -o result.png

Docker

## Inference server
docker compose up api


## Training (GPU)
docker compose --profile training run train

Tests

pytest -v

Defect Classes

Tech Stack

Case Studies

See docs/case-studies/ for composite narratives. They are illustrative discovery material, not proof from a live site:

• Shipyard pipeline — 2-camera station integrated with PLC signals, Jetson Orin edge deployment, 90-day rollout with before/after metrics.
• Automotive body shop — line-of-sight inspection at 1 weld / 2s throughput, integration with Andon systems.

Both are composite narratives with fabricated but plausible numbers, written in the SE-delivery format.

Production Deployment

docs/production/ covers deployment considerations that would need site-specific validation before use:

Edge & Integration

• edge/jetson-orin/ — Jetson-specific Dockerfile, systemd unit, setup script, watchdog.
• serving/triton/ — Triton Inference Server model repository config for the weld_defect model.
• integrations/ — reference integrations for OPC-UA, MQTT, Kafka, REST webhook.

Model Governance

governance/ follows industry-standard artifacts:

• model-card.md — Google-style Model Card (intended use, training data, evaluation, limitations).
• data-sheet.md — Gebru-style Datasheet for Datasets.
• Ethics review — worker-monitoring implications, false-positive/negative cost framing.

Benchmarks

benchmarks/ contains reference benchmarks across devices and configurations. Sample results (see benchmarks/results/):

Regenerate with python benchmarks/latency_benchmark.py --devices cpu,gpu,jetson.

Related Projects

Cloud + AI Architecture

• Cloud + AI architecture blueprint
• Machine-readable architecture manifest
• Validation command: python3 scripts/validate_architecture_blueprint.py

Enterprise Productization

• Product operating model defines the product scope, trust boundary, operating checks, and service path for this repository.

System Architecture

• System architecture maps the runtime boundary, data/control flow, cloud or local deployment surface, and operating assumptions for this repository.

Service Architecture

• Service architecture defines the cloud resources, account information, cost controls, and production guardrails needed to turn this repo into a scoped service without publishing public financial assumptions.

Search And Service Surface

• Public entry: free static inspection demo and architecture page
• Paid boundary: private industrial validation discovery for data suitability, baseline evaluation, model-card drafting, and human-review acceptance criteria
• Canonical URL: https://weld-defect-vision.pages.dev/
• Lead capture: https://kim3310-doeon-kim-portfolio.pages.dev/?offer=weld-defect-vision&inquiry=industrial-validation-discovery#private-inquiry
• Resource route: https://kim3310-doeon-kim-portfolio.pages.dev/resources/weld-defect-vision/
• Commercial route: https://kim3310-doeon-kim-portfolio.pages.dev/?offer=weld-defect-vision#service-offers
• CTA: Request private industrial validation discovery through the central inquiry URL
• Machine-readable offer: docs/service-offer.json
• Search growth implementation: docs/search-growth-implementation.md
• Revenue architecture: docs/revenue-architecture.md