🎭 Face Mask Detection System

A high-performance, real-time face mask detector built with OpenCV YuNet, MobileNetV2, and a threaded, batch-inference architecture.

---

✨ Overview

This system detects in real time whether people in a live webcam feed are wearing a face mask. It processes every frame through a two-stage AI pipeline — fast face localisation followed by mask classification — and overlays results directly on the camera feed with a clean, minimalist UI.

Key highlights:

• 🚀 Threaded capture — camera I/O runs in a dedicated daemon thread, eliminating blocking waits
• ⚡ Batch inference — all faces in a frame are classified in a single GPU/CPU call
• 🎯 Dual-resolution pipeline — full-res for display, downscaled for fast AI inference
• 🖼️ Resolution-independent UI — scales cleanly from 720p to 4K

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                      main.py (Orchestrator)              │
└────────┬─────────────────┬──────────────────┬───────────┘
         │                 │                  │
┌────────▼──────┐  ┌───────▼──────┐  ┌───────▼──────────┐
│  camera.py    │  │ detector.py  │  │     ui.py         │
│               │  │              │  │                   │
│ ThreadedCamera│  │ YuNetFace    │  │ UIManager         │
│ (daemon I/O)  │  │ Detector     │  │ - Pill labels     │
│               │  │              │  │ - Rounded boxes   │
│ → Frame Queue │  │ MaskDetector │  │ - HUD dashboard   │
└───────────────┘  │ (batch CNN)  │  └───────────────────┘
                   └──────┬───────┘
                          │
                   ┌──────▼───────┐
                   │  utils.py    │
                   │ (Compat.     │
                   │  Model Load) │
                   └──────────────┘
                          │
                   ┌──────▼───────┐
                   │  config.py   │
                   │ (All tunable │
                   │  constants)  │
                   └──────────────┘

Data flow per frame:

Camera → Flip (mirror) → Downscale → YuNet detect → Crop ROIs →
  → MobileNetV2 batch predict → Map coords back → Draw UI → Display

---

📂 Project Structure

Face-Mask-Detection-Python/
├── main.py              # Application entry point & main loop
├── setup_env.py         # One-click model download script
├── requirements.txt     # Python dependencies
├── models/              # AI model weights (downloaded by setup_env.py)
│   ├── face_detection_yunet_2023mar.onnx
│   └── mask_detector.h5
└── src/
    ├── __init__.py
    ├── config.py        # All tunable constants (single source of truth)
    ├── camera.py        # ThreadedCamera — non-blocking frame capture
    ├── detector.py      # YuNetFaceDetector + MaskDetector (batch CNN)
    ├── ui.py            # UIManager — rendering engine
    └── utils.py         # Robust Keras model loader (compat. patches)

---

🛠️ Installation

Prerequisites

• Python 3.8 – 3.11 (TensorFlow 2.x does not yet support Python 3.12+)
• A working webcam

Steps

# 1. Clone the repository
git clone https://github.com/rebeeh/Face-Mask-Detection-Python.git
cd Face-Mask-Detection-Python

# 2. (Recommended) Create a virtual environment
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

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

# 4. Download AI models (one-time, ~11 MB total)
python setup_env.py

---

▶️ Usage

python main.py

Key	Action
Q or ESC	Quit the application
Close window	Quit the application

The HUD (top-centre) shows live FPS, Mask count, and Alert count (faces without masks).

---

⚙️ Configuration

All tunable parameters live in src/config.py — no edits needed in main.py.

Constant	Default	Description
CAMERA_INDEX	0	Webcam device index
CAMERA_WIDTH	1280	Capture width (pixels)
CAMERA_HEIGHT	720	Capture height (pixels)
INFERENCE_WIDTH	640	AI inference frame width (lower = faster)
YUNET_SCORE_THRESHOLD	0.6	YuNet face detection confidence cutoff
CONFIDENCE_THRESHOLD	0.5	Mask classification decision boundary
MIN_FACE_SIZE_PX	10	Minimum face box size to process (filters noise)
BATCH_SIZE	32	Mask classifier batch size

---

🔧 Troubleshooting

Symptom	Fix
"Failed to open camera source"	Another application is using the webcam, or CAMERA_INDEX is wrong. Try CAMERA_INDEX = 1.
"TensorFlow is not installed"	Run pip install tensorflow (Windows/Linux) or pip install tensorflow-macos (Apple Silicon).
"Mask model not found"	Run python setup_env.py to download model files.
Low FPS	Lower INFERENCE_WIDTH in config.py (e.g., 320), or reduce CAMERA_WIDTH/CAMERA_HEIGHT.
"YuNet model not found"	Run python setup_env.py. If the download fails, check internet access.
Mask model loads with warnings	Normal — utils.py applies backward-compatibility patches transparently.

---

🤝 Contributing

See CONTRIBUTING.md for guidelines on submitting pull requests, reporting bugs, and code style.

---

📄 License

This project is licensed under the MIT License — see LICENSE for details.

---

Face detection powered by OpenCV YuNet. Mask classifier architecture from chandrikadeb7/Face-Mask-Detection.