YOLOv8 Face Detection

A real-time face detection application using YOLOv8 with support for both PyTorch (.pt) and ONNX (.onnx) models. Optimized for webcam streaming with high FPS performance.

Features

• Real-time Face Detection: Process webcam feed with optimized frame processing
• Multiple Model Support:
  • PyTorch models (.pt) with GPU acceleration
  • ONNX models (.onnx) for cross-platform compatibility
• Performance Optimizations:
  • Vectorized postprocessing with NumPy
  • Frame skipping for better FPS
  • Configurable input sizes
• Visual Feedback:
  • Live FPS counter
  • Bounding boxes with confidence scores
  • Green overlay for detected faces

Requirements

• Python 3.12+
• Webcam/Camera device
• Optional: CUDA-capable GPU for accelerated inference

Quick Start

Installation

Method 1: Using uv (Recommended - Faster & Cleaner)

uv is a fast Python package installer and resolver.

1. Install uv (if not already installed)

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

#manual
pip install uv

2. Clone the repository

git clone https://github.com/CodeFreak2186/face-detection-YOLOV8.git
cd face-detection-YOLOV8

3. Install dependencies

uv sync

4. Run the application

python main.py  

or

uv run main.py

---

Method 2: Manual Installation with venv and pip

1. Clone the repository

git clone https://github.com/CodeFreak2186/face-detection-YOLOV8.git
cd face-detection-YOLOV8

2. Create a virtual environment

# Windows
python -m venv venv
venv\Scripts\activate

# macOS/Linux
python3 -m venv venv
source venv/bin/activate

3. Install dependencies

pip install -r requirements.txt

4. Run the application

python main.py

---

Dependencies

• opencv-python>=4.13.0 - Computer vision and DNN operations
• numpy>=2.4.1 - Numerical operations and array processing
• torch>=2.9.1 - PyTorch for model inference
• ultralytics>=8.4.7 - YOLOv8 implementation
• torchaudio>=2.9.1 - Audio processing utilities
• torchvision>=0.24.1 - Vision utilities for PyTorch

Usage

Main Entry Point

The main.py is your entry point to the application. It provides an interactive menu to choose which detection method to use:

python main.py

You'll see an interactive menu:

Select which file to run:

1. Face Detection (Webcam)
2. Image Detection

Enter your choice (1 or 2):

Option 1: Runs the PyTorch model (src/pt-model.py) for real-time webcam detection
Option 2: Runs the ONNX model (src/onnx-model.py) for image detection

---

Running Scripts Directly

You can also run the detection scripts directly without the menu:

PyTorch Model (GPU/CPU)

For real-time webcam detection with GPU acceleration:

python src/pt-model.py

Features:

• Automatic GPU/CPU detection
• Full PyTorch inference pipeline
• Best performance with NVIDIA GPU
• Real-time FPS display

ONNX Model (CPU-optimized)

For CPU-based inference or image detection:

python src/onnx-model.py

Features:

• CPU-optimized inference
• Live face count display
• Optimized postprocessing
• No GPU required

Controls

• Press q to quit the application
• FPS is displayed in the top-left corner (blue text)
• Face count is shown below FPS (ONNX model only)
• Face detections show confidence scores with green bounding boxes

Configuration

PyTorch Model (src/pt-model.py)

MODEL_PATH = "model/pt-model.pt"               # Model file path
CONFIDENCE = 0.45                              # Detection confidence threshold
IMAGE_SIZE = 640                               # Input image size (640 or 320)
DEVICE = 0 if torch.cuda.is_available() else "cpu"  # Auto GPU/CPU

ONNX Model (src/onnx-model.py)

MODEL_PATH = "model/onnx-model.onnx"            # ONNX model path
INPUT_SIZE = 640                                # Must match model training size
CONF_THRESH = 0.4                               # Detection confidence threshold
NMS_THRESH = 0.45                               # Non-maximum suppression threshold

Performance Tuning

For higher FPS:

• Use smaller model: yolov8n instead of yolov8m
• Use PyTorch model with GPU (src/pt-model.py)
• Reduce IMAGE_SIZE to 320 in pt-model.py
• Webcam resolution is fixed at 640×480 for optimal performance

For better accuracy:

• Use larger model: yolov8l or yolov8x
• Keep IMAGE_SIZE at 640
• Lower CONF_THRESH to detect more faces (e.g., 0.3)
• Increase NMS_THRESH to reduce false positives

Project Structure

face-yolo8/
├── main.py                          # Interactive menu launcher
├── src/
│   ├── pt-model.py                 # PyTorch-based face detection (webcam)
│   └── onnx-model.py               # ONNX-based face detection (images)
├── model/
│   ├── pt-model.pt                 # PyTorch model weights
│   └── onnx-model.onnx             # ONNX model weights
├── Dockerfile                       # Docker container configuration
├── docker-compose.yml               # Docker Compose orchestration
├── .dockerignore                    # Docker ignore patterns
├── requirements.txt                 # Dependencies for pip install
├── pyproject.toml                   # Project dependencies (uv)
├── uv.lock                          # Dependency lock file
├── README.md                        # This file
├── .gitignore                       # Git ignore rules
├── .python-version                  # Python version specification
└── dockerfile                       # Legacy dockerfile (empty)

Models

This project uses YOLOv8 Face Detection models trained by LinDevs:

• yolov8n-face: Nano (fastest, lowest accuracy)
• yolov8s-face: Small (balanced)
• yolov8m-face: Medium (recommended - good speed/accuracy balance)
• yolov8l-face: Large (highest accuracy, slower)
• yolov8x-face: Extra-large (best accuracy, slowest)

The medium model (yolov8m) is included as it provides optimal performance for real-time applications.

Model Download

Models are included in the model/ directory. If you need different variants, download from:

• Ultralytics YOLOv8
• Face Detection Models

Docker Support

Docker allows you to run the application in a containerized environment without installing dependencies on your host machine.

Note: The Dockerfile supports both pip (default) and uv installation methods. To use uv, edit the Dockerfile and uncomment the uv installation section.

Prerequisites

• Docker installed (Get Docker)
• Docker Compose (optional, for easier management)
• Webcam device

Choosing Installation Method in Docker

By default, Docker uses pip + requirements.txt. To use uv instead:

1. Open Dockerfile
2. Comment out the pip section (lines with COPY requirements.txt and pip install)
3. Uncomment the uv section (lines with uv installation)

Option 1: Using Docker Compose (Recommended)

1. Build and run with one command

docker-compose up --build

2. Stop the container

# Press Ctrl+C, then:
docker-compose down

Option 2: Using Docker CLI

Linux/macOS

1. Allow X11 forwarding for GUI display

xhost +local:docker

2. Build the Docker image

docker build -t yolov8-face-detection .

3. Run the container

docker run --rm -it \
  --device=/dev/video0:/dev/video0 \
  -e DISPLAY=$DISPLAY \
  -v /tmp/.X11-unix:/tmp/.X11-unix:rw \
  --privileged \
  yolov8-face-detection

4. Cleanup (optional)

xhost -local:docker

Windows

Docker GUI support on Windows requires additional setup:

1. Install VcXsrv or Xming (X11 server for Windows)

   • Download VcXsrv
   • Run XLaunch with "Disable access control" checked

2. Build the Docker image

docker build -t yolov8-face-detection .

3. Get your local IP address

ipconfig
# Look for your IPv4 Address (e.g., 192.168.1.100)

4. Run the container

docker run --rm -it `
  --device=/dev/video0:/dev/video0 `
  -e DISPLAY=YOUR_IP:0.0 `
  --privileged `
  yolov8-face-detection

Replace YOUR_IP with your actual local IP address.

Docker Configuration Details

Dockerfile features:

• Based on Python 3.12 slim image
• Installs OpenCV system dependencies
• Copies only necessary files
• Optimized layer caching

Docker Compose features:

• Automatic webcam device mapping
• X11 display forwarding
• Model directory volume mount
• Network host mode for better performance

Troubleshooting Docker

Cannot connect to X server:

• Linux/macOS: Run xhost +local:docker before starting container
• Windows: Ensure VcXsrv/Xming is running and accessible

Webcam not detected:

• Check device exists: ls /dev/video* (Linux/macOS)
• Try different device number (e.g., /dev/video1)
• Ensure --privileged flag is set

Permission denied for webcam:

# Linux: Add your user to video group
sudo usermod -aG video $USER
# Then logout and login again

Container exits immediately:

# Run in interactive mode to see errors
docker run --rm -it yolov8-face-detection /bin/bash

PyTorch (.pt) vs ONNX (.onnx) - Which to Use?

PyTorch Model (pt-model.py)

Advantages:

• GPU Acceleration: Full CUDA support for 3-5x faster inference on NVIDIA GPUs
• Flexibility: Easy to modify, fine-tune, or retrain models
• Rich Ecosystem: Access to PyTorch's extensive tools and libraries
• Better Performance: Native PyTorch inference is optimized for both CPU and GPU
• Dynamic Graphs: Better for research and experimentation

Best For:

• Systems with NVIDIA GPU (RTX series, GTX series)
• Development and training environments
• When you need maximum performance
• Real-time applications requiring high FPS

Requirements:

• PyTorch (~2GB installation)
• Ultralytics library
• Optional: CUDA toolkit for GPU support

---

ONNX Model (onnx-model.py)

Advantages:

• Cross-Platform: Works on any platform without PyTorch dependencies
• Lightweight: Only requires OpenCV and NumPy (smaller deployment)
• Portable: Model can run on edge devices, mobile, web (via ONNX.js)
• Framework Independent: No need for PyTorch after export
• Faster Deployment: Smaller package size for production

Best For:

• CPU-only systems or non-NVIDIA GPUs
• Production deployment with minimal dependencies
• Edge devices (Raspberry Pi, Jetson Nano)
• Cross-platform applications
• When storage/memory is limited

Requirements:

• OpenCV with DNN module
• NumPy

---

Quick Comparison

Feature	PyTorch (.pt)	ONNX (.onnx)
GPU Support	Yes (CUDA)	Limited (OpenCV DNN)
Installation Size	~2-3 GB	~50 MB
FPS (GPU)	30-60	N/A
FPS (CPU)	8-12	5-10
Dependencies	PyTorch, Ultralytics	OpenCV, NumPy
Deployment	Development-focused	Production-ready
Flexibility	High (trainable)	Low (inference only)
Platform Support	Limited	Universal

Recommendation

• Have an NVIDIA GPU? Use pt-model.py for best performance
• CPU only or need portability? Use onnx-model.py for compatibility
• Development/Research? Use pt-model.py for flexibility
• Production deployment? Use onnx-model.py for simplicity

---

Performance Benchmarks

Configuration	FPS (CPU)	FPS (GPU)
pt-model.py (PyTorch, 640px)	~8-12	~30-60
onnx-model.py (ONNX, 640px)	~5-10	N/A

Results may vary based on hardware specifications

Note: The PyTorch model automatically detects and uses GPU if available. ONNX model is CPU-only but provides consistent cross-platform performance.

Troubleshooting

Low FPS Issues

Problem: FPS is below 5

• Solution 1: Use GPU acceleration with pt-model.py
• Solution 2: Switch to yolov8n (nano) model for faster inference
• Solution 3: Reduce IMAGE_SIZE to 320 in configuration
• Solution 4: Close other resource-intensive applications

CUDA/GPU Errors

Problem: CUDA errors or GPU not detected

• Solution: Use onnx-model.py (CPU-only)
• Alternative: Check PyTorch CUDA installation: python -c "import torch; print(torch.cuda.is_available())"
• Note: pt-model.py automatically falls back to CPU if GPU is unavailable

Model Not Found

Problem: FileNotFoundError for model files

• Solution: Ensure models are in model/ directory
• Check: Verify paths in MODEL_PATH configuration

Import Errors

Problem: Module not found errors

• Solution: Reinstall dependencies: uv sync or pip install -r requirements.txt
• Check: Ensure Python 3.12+ is installed

Use Cases

• Security Systems: Real-time face detection for surveillance
• Attendance Systems: Automated face recognition
• Photography: Auto-focus on faces
• Access Control: Face-based authentication
• Research: Computer vision and deep learning experiments

Technical Details

Architecture

1. Input: Webcam frame (BGR format)
2. Preprocessing:
   • Resize to 640×640
   • Normalize to [0, 1]
   • Convert to blob format
3. Inference: YOLOv8 forward pass
4. Postprocessing:
   • Filter by confidence threshold
   • Apply Non-Maximum Suppression (NMS)
   • Draw bounding boxes
5. Output: Annotated frame with detections

Optimization Techniques

• Vectorized Operations: NumPy arrays instead of Python loops
• Frame Skipping: Process every Nth frame, reuse last detections
• Webcam Resolution: Limited to 640×480 for faster capture
• NMS: Removes duplicate detections efficiently

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is open-source and available under the MIT License.

Acknowledgments

• Ultralytics - YOLOv8 implementation
• LinDevs - Face detection model training
• OpenCV community for computer vision tools

Contact

For questions or support, please open an issue in the repository.

---

Star this repository if you find it helpful!