🔍 YOLOv12 Human Face Detection Web Application

A professional, real-time face detection system built with YOLOv12 INT8 ONNX Runtime and Flask. This project leverages the latest Attention Mechanism features of YOLOv12 combined with Static INT8 Quantization to detect faces in images, videos, and live webcam streams with state-of-the-art accuracy, ultra-low latency, and zero-PyTorch architecture footprint.

View the demo using this link.

✨ Features

📷 Image & Video Detection

• Upload and detect faces in images (JPG, PNG) and videos (MP4, AVI, MOV).
• Attention-based detection for small, distant, or occluded faces.
• Interactive bounding boxes with cropped face previews.
• Download annotated results and face statistics.
• Privacy mode for images is here to blur faces in the output.

📹 Live Webcam

• Real-time detection directly from your browser.
• Side-by-side video feed and detection results.
• Live statistics (FPS, face count, duration).

📊 Feedback & Analytics

• Built-in MySQL database integration (via Aiven) to collect user ratings and feedback securely.
• Ready for admin dashboard visualization.

🤖 Pure INT8 ONNX Runtime Models

All models are statically quantized to INT8, achieving over ~70% reduction in file size while maintaining state-of-the-art accuracy:

• YOLOv12 Nano - Super Fast (~3.6 MB), best for CPU/Webcam.
• YOLOv12 Small - Balanced speed & accuracy (~10.1 MB).
• YOLOv12 Medium - High precision (~20.7 MB).
• YOLOv12 Large - State-of-the-art accuracy (~27.7 MB).

---

System Business Flow

graph TD
    %% Define Nodes
    User((User))
    UI[Web UI / Frontend]
    ModelSelection{Select YOLOv12 Model}
    InputSelect{Select Data Source}
    
    %% Data Sources
    Upload[Upload Image/Video]
    Webcam[Live Webcam Stream]
    
    %% Backend & API
    API_Detect[/API: /api/detect-image & video/]
    FlaskBackend[Flask Backend Server]
    YOLO_Engine[YOLOv12 INT8 ONNX Inference Engine]
    
    %% Results & Post-processing
    Results[Extract Bounding Box, Confidence, Count]
    Display[Display Results & Stats on UI]
    
    %% Actions & Telemetry
    Action_Download[Download Annotated Files]
    Action_Feedback[Submit Rating & Feedback]
    API_Download[/API: /api/download/]
    API_Feedback[/API: /api/feedback/]
    DB[(Aiven MySQL Database)]

    %% Edges (Flow)
    User --> UI
    UI --> ModelSelection
    ModelSelection -->|Nano / Small / Medium / Large| InputSelect
    
    InputSelect -->|Static File| Upload
    InputSelect -->|Real-time| Webcam
    
    Upload --> API_Detect
    API_Detect --> FlaskBackend
    FlaskBackend --> |Save temporary file to UPLOAD_FOLDER| YOLO_Engine
    
    Webcam --> |Send continuous frames| YOLO_Engine
    
    YOLO_Engine --> Results
    Results --> Display
    
    Display --> Action_Download
    Display --> Action_Feedback
    
    Action_Download --> API_Download
    Action_Feedback --> API_Feedback
    
    API_Feedback --> |Securely store telemetry| DB

Loading

---

Business Logic Detailed Explanation

1. Initialization & Configuration

• User Interaction: The user accesses the Web UI (hosted locally or via Hugging Face Spaces).
• Model Selection: The system prompts the user to select a YOLOv12 model variant (Nano, Small, Medium, or Large). This allows the user to balance between blazing-fast inference speeds (ideal for webcams) and maximum precision (ideal for high-resolution static images).

2. Data Input Stage The system routes the user through one of two primary data pipelines:

• Batch Processing (Static Files): The user uploads image (JPG, PNG) or video (MP4, AVI, MOV) files. The frontend packages the payload and sends a POST request to the respective /api/detect-image or /api/detect-video endpoints.
• Real-Time Stream: The user grants browser camera permissions. The frontend captures the live video feed and continuously pushes frames to the processing engine.

3. Core AI Inference

• Request Handling: The Flask Backend receives the data. For uploads, it temporarily stores the files in the UPLOAD_FOLDER (validating against the MAX_FILE_SIZE limit).
• YOLOv12 Processing: The YOLOv12 ONNX Inference Engine is triggered. Utilizing its advanced Attention Mechanisms, it scans the input to detect human faces, calculating exact bounding box coordinates and assigning a Confidence Score based on the pre-configured threshold (default: 0.32).

4. Post-Processing & Response

• Data Aggregation: The raw model outputs are synthesized into a structured JSON response (containing face count, coordinates, and inference duration) and returned to the client.
• Visualization: The Web UI dynamically renders interactive bounding boxes over the media and updates real-time statistics (such as FPS and total faces detected).

5. User Actions & Telemetry

• Retrieval: Users can interact with the /api/download/<filename> endpoint to securely download their processed, annotated files.
• Feedback Loop: To drive future improvements, users can submit ratings and comments. The frontend calls the /api/feedback endpoint, which securely inserts the telemetry data into the Aiven MySQL Database for future analytics.

---

🚀 Quick Start

Prerequisites

• Python 3.14+
• Git

Installation

1. Clone the repository:

git clone [https://github.com/RevDra/human-face-detection.git](https://github.com/RevDra/human-face-detection.git)
cd human-face-detection

2. Install dependencies:

pip install -r requirements.txt

3. Environment Setup (Required): Copy the template environment file and add your secure credentials.

cp .env.example .env

Open .env in a text editor and update the DB_URL with your MySQL connection string.

4. Run the web server:

Linux/Mac

./config/deploy.sh start

Windows

config\deploy.bat start

5. Open in browser: Navigate to https://localhost:7860

📁 Project Structure

Human_face_detection/
├── .github/                         # CI/CD & Automation
│   ├── ISSUE_TEMPLATE/              # Community Forms
│   │   ├── bug_report.md            # Bug report template
│   │   ├── config.yml               # Discussions link config
│   │   └── feature_request.md       # Feature request template
│   ├── workflows/
│   │   ├── docker-publish.yml       # Auto-build Docker Image
|   |   ├── release.yml             # Automated Semantic Release CI/CD
│   │   └── lint.yml                 # Quality Check (Black + Flake8 + isort + Mypy)
│   ├── dependabot.yml               # Automated Dependency Updates
│   └── FUNDING.yml                  # Sponsor settings
│
├── assets/                          # Project Images & Screenshots
│   └── demo_ui.png                  # Interface preview for README
│
├── config/                          # Configuration & Deployment scripts
│   ├── Dockerfile                   # Docker image config
│   ├── docker-compose.yml           # Docker Compose setup
│   ├── deploy.sh                    # Linux deployment script
│   ├── deploy.bat                   # Windows deployment script
│   └── DEPLOYMENT_GUIDE.md          # Detailed deployment guide
│
├── models/                          # YOLOv12 ONNX Models
│   ├── yolov12n-face-int8.onnx           # Nano model
│   ├── yolov12s-face-int8.onnx           # Small model
│   ├── yolov12m-face-int8.onnx           # Medium model
│   ├── MODELS.md                    # Download instructions for Med/Large models
│   └── training/                    # Source code & benchmarks (Loss, PR curves, etc.)
│
├── src/                             # Source Code (Zero-PyTorch ONNX Runtime)
│   ├── web_app.py                   # Flask web server
│   └── face_detection_yolov12.py    # YOLOv12 detection engine (OpenCV + ONNX)
│
├── web/                             # Frontend Assets
│   └── templates/
│       └── index.html               # Web UI
│
├── .flake8                          # Flake8 Configuration
├── .dockerignore                    # Docker Ignore
├── .gitignore                       # Git Ignore
├── .gitattributes                   # Normalized code (LF)
├── pyproject.toml                   # Black + Mypy + isort Configuration
├── CODE_OF_CONDUCT.md               # Community guidelines
├── CONTRIBUTING.md                  # Contribution guidelines
├── LICENSE                          # AGPL v3 License
├── README.md                        # Main documentation
├── SECURITY.md                      # Security policy
├── .env.example                     # Template for environment variables (DB credentials)
└── requirements.txt                 # Python dependencies

🐳 Docker Support (Recommended)

You can run the application instantly without needing to install Python or manually install dependencies.

Prerequisites: Docker Desktop installed.

1. Clone the repository:

git clone [https://github.com/RevDra/human-face-detection.git](https://github.com/RevDra/human-face-detection.git)
cd human-face-detection

2. Run with Docker Compose:

# Build and run with Docker Compose (from project root)
docker-compose -f config/docker-compose.yml up --build

# Or build manually
docker build -t yolov12-face-detection -f config/Dockerfile .
docker run -p 7860:7860 -v $(pwd)/data:/app/data yolov12-face-detection

3. Access the App: Open http://localhost:7860 in your browser.

🔧 API Endpoints

Method	Endpoint	Description
GET	/	Web interface
POST	/api/detect-image	Detect faces in uploaded image
POST	/api/detect-video	Detect faces in uploaded video
GET	/api/models	List available models
POST	/api/feedback	Submit user rating and comments to database
GET	/api/health	Health check
GET	/api/download/<filename>	Download processed files

💻 Usage

Via Web Interface

1. Select a detection model
2. Upload an image/video or start webcam
3. Wait for processing
4. View results and download if needed

Via API (Python Example)

import requests

# Detect faces in image
with open('image.jpg', 'rb') as f:
    files = {'file': f}
    data = {'model': 'yolov12l-face.onnx'}
    response = requests.post('http://localhost:7860/api/detect-image', 
                            files=files, data=data)
    result = response.json()
    
print(f"Detected {result['detections']['count']} faces")

📊 Detection Details

Confidence Threshold

Default: 0.32 (32%)

• Higher threshold = fewer false positives but may miss faces
• Lower threshold = more detections but more false positives

Output Includes

• Bounding box coordinates (x1, y1, x2, y2)
• Confidence score (0-100%)
• Face dimensions (width × height)
• Face position on image

⚙️ Configuration

Edit web_app.py to modify:

• MAX_FILE_SIZE - Maximum upload size (default: 500MB)
• UPLOAD_FOLDER - Temporary file location
• PORT - Application port (default: 7860)

📝 Notes

Model Files Required

Model files are required in the models/ directory:

• yolov12n-face-int8.onnx ✅ Included
• yolov12s-face-int8.onnx ✅ Included
• yolov12m-face-int8.onnx ✅ Included
• yolov12l-face-int8.onnx 📥 Download, then use the pipeline in models/ to help you transform ONNX FP32 to INT8

See models/MODELS.md for detailed download instructions.

Performance Tips

1. Use YOLOv12 Nano for webcam to achieve high FPS.
2. Use YOLOv12 Large for high-resolution static images.
3. If running on Hugging Face Spaces (CPU), stick to Nano or Small models.

Browser Compatibility

• Chrome/Edge: ✅ Full support
• Firefox: ✅ Full support
• Safari: ✅ Full support
• IE: ❌ Not supported

🐛 Troubleshooting

Models Not Found

FileNotFoundError: Model not found: models/yolov12m-face.onnx

Solution: Download missing models from models/MODELS.md. Only nano and small models are included by default.

Camera Permission Denied

Solution: Grant camera permission in browser settings. If deploying on a remote server, you must use HTTPS for the webcam to work.

Out of Memory

Solution: Use a smaller model (Nano) or reduce video resolution

Slow Detection

Solution:

• Use YOLOv12 Nano
• Reduce input resolution
• Check CPU/GPU usage

📚 References

• Model Setup Guide - Download and setup instructions
• YOLOv12-Face Repository - Source of the models/weights.
• Ultralytics YOLOv12 - YOLOv12 documentation.
• Flask Documentation
• OpenCV Documentation

🙏 Acknowledgements & Licenses

This project uses the following open-source components:

1. YOLOv12 by Ultralytics:

• License: AGPL-3.0
• Source: https://github.com/ultralytics/ultralytics

2. Face Detection Weights inspired by YapaLab:

• License: GPL-3.0
• Source: https://github.com/YapaLab/yolo-face

Project License: This entire project is licensed under the AGPL-3.0 to comply with the licensing terms of the YOLO ecosystem.

💬 Support & Q&A

---

Last Updated: October 29, 2026 | Status: ✅ Production Ready