README_API.md

Industrial Defect Detection API

A unified service providing both FastAPI endpoints (for production) and Gradio UI (for testing/demo).

Overview

This service allows multiple MonitaQC vision engines to perform defect detection inference using ONNX models without requiring local GPU resources.

Features

• FastAPI Endpoints: RESTful API compatible with MonitaQC's YOLO inference format
• Gradio UI: Web interface for visual testing and demonstration
• Multiple Models: Support for 8 different defect detection models
• CPU-based: Runs on ONNX Runtime (no GPU required)
• Cloud-ready: Can be deployed to HuggingFace Spaces or any cloud platform

Deployment Options

Option 1: HuggingFace Spaces (Recommended for Cloud)

Deploy to HuggingFace Spaces to make the API publicly accessible:

1. Create a new Space on HuggingFace:

   # Visit https://huggingface.co/new-space
   # Choose: Gradio SDK
   # Set to Public or Private
   

2. Push your code:

   git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
   cd YOUR_SPACE_NAME
   cp /path/to/api.py app.py
   cp /path/to/requirements*.txt .
   git add .
   git commit -m "Add Industrial Defect Detection API"
   git push
   

3. Your API will be available at:

   • Gradio UI: https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/gradio
   • API Docs: https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/docs
   • API Endpoint: https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/v1/object-detection/detect

Option 2: Local Docker Deployment

Run locally with Docker:

# Build the image
docker build -t defect-detection-api .

# Run the container
docker run -p 8000:8000 \
  -e HUGGINGFACE_TOKEN=your_token_here \
  -e DEFAULT_MODEL=data-matrix \
  defect-detection-api

Access:

• Gradio UI: http://localhost:8000/gradio
• API Docs: http://localhost:8000/docs
• API Endpoint: http://localhost:8000/v1/object-detection/detect

Option 3: Direct Python

Run directly with Python:

# Install dependencies
pip install -r requirements.txt -r requirements-api.txt

# Run the service
python api.py

API Usage

For MonitaQC Vision Engines

Update your MonitaQC infrastructure configuration to use this API instead of local YOLO:

1. Open MonitaQC status page: http://localhost:5050/status
2. Go to "Infrastructure Configuration"
3. Update YOLO URL to:
   • HuggingFace Spaces: https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/v1/object-detection/data-matrix/detect
   • Local: http://localhost:8000/v1/object-detection/data-matrix/detect
4. Click "Set URL"

API Endpoints

1. Detect with Default Model

POST /v1/object-detection/detect
Content-Type: multipart/form-data

Parameters:
  - image: file (required)
  - model: string (optional, default: data-matrix)
  - confidence: float (optional, default: 0.25)

Example:
curl -X POST "http://localhost:8000/v1/object-detection/detect" \
  -F "image=@test.jpg" \
  -F "model=data-matrix" \
  -F "confidence=0.25"

2. Detect with Specific Model

POST /v1/object-detection/{model_name}/detect
Content-Type: multipart/form-data

Parameters:
  - image: file (required)
  - confidence: float (optional, default: 0.25)

Example:
curl -X POST "http://localhost:8000/v1/object-detection/data-matrix/detect" \
  -F "image=@test.jpg" \
  -F "confidence=0.25"

Response Format

[
  {
    "bbox": [x1, y1, x2, y2],
    "confidence": 0.85,
    "class_id": 0,
    "x1": 100.0,
    "y1": 150.0,
    "x2": 200.0,
    "y2": 250.0
  }
]

Available Models

Model Key	Model Name	Use Case
data-matrix	Data Matrix	Data Matrix code defect detection
dental-implant	Dental Implant	Dental implant defect detection
ball-pen	Ball Pen	Ball pen defect detection
knit-up	Knit Up	Knit fabric (up side) defect detection
knit-back	Knit Back	Knit fabric (back side) defect detection
jean-up	Jean Up	Jean fabric (up side) defect detection
jean-back	Jean Back	Jean fabric (back side) defect detection
tire-cord	Tire Cord	Tire cord defect detection

Architecture

┌─────────────────────────────────────┐
│   HuggingFace Spaces (Cloud)        │
│                                     │
│  ┌──────────────────────────────┐  │
│  │  FastAPI + Gradio Service    │  │
│  │                              │  │
│  │  - ONNX Runtime (CPU)        │  │
│  │  - 8 Defect Detection Models │  │
│  │  - REST API Endpoints        │  │
│  │  - Gradio Web UI             │  │
│  └──────────────────────────────┘  │
└─────────────────────────────────────┘
           ▲
           │ HTTPS API Calls
           │
┌──────────┴──────────────────────────┐
│  MonitaQC Vision Engines (Multiple) │
│                                     │
│  ┌────────────┐  ┌────────────┐    │
│  │ Engine 1   │  │ Engine 2   │    │
│  │ (Factory A)│  │ (Factory B)│    │
│  └────────────┘  └────────────┘    │
└─────────────────────────────────────┘

Benefits Over Local YOLO

Aspect	Local YOLO	HuggingFace API
GPU Required	Yes	No (CPU-based)
Setup Complexity	High (GPU drivers, CUDA, etc.)	Low (just API URL)
Model Updates	Manual	Automatic
Multiple Factories	Each needs GPU	All share one API
Cost	GPU hardware per site	Cloud hosting only
Maintenance	Per-site updates	Centralized

Environment Variables

• HUGGINGFACE_TOKEN: Your HuggingFace token (for private models)
• DEFAULT_MODEL: Default model to use (default: data-matrix)
• HOST: Server host (default: 0.0.0.0)
• PORT: Server port (default: 8000)

Testing

1. Via Gradio UI: Navigate to /gradio and upload test images
2. Via API: Use curl or Python requests to test endpoints
3. Via Swagger: Navigate to /docs for interactive API documentation

License

Same as the original HuggingFace models.

Support

For issues or questions:

• API Issues: Check /health endpoint
• Model Issues: Check available models at /models
• Integration Help: See MonitaQC documentation