A high-performance, real-time face mask detector built with OpenCV YuNet, MobileNetV2, and a threaded, batch-inference architecture.
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
┌─────────────────────────────────────────────────────────┐
│ 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
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)
- Python 3.8 – 3.11 (TensorFlow 2.x does not yet support Python 3.12+)
- A working webcam
# 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.pypython 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).
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 |
| 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. |
See CONTRIBUTING.md for guidelines on submitting pull requests, reporting bugs, and code style.
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.