MaskGuard-AI

Real-time face mask detection using TensorFlow/Keras, OpenCV, and Flask.

---

What This Project Does

MaskGuard-AI detects faces from webcam/video frames and classifies each face as:

• Mask
• No Mask

It includes:

• model training (train_model.py)
• model evaluation (evaluate_model.py)
• webcam detection (detect_mask_video.py)
• single image detection (detect_mask_image.py)
• Flask API + browser UI (api_server.py + web/index.html)

UI Screenshots

Main UI Views

Home	Model Evaluation

Objectives	Live Detection (Mask)

Live Detection (No Mask)

Quick Start

cd MaskGuard-AI
python -m venv .venv

Activate venv:

• Windows: .venv\Scripts\activate
• macOS/Linux: source .venv/bin/activate

Install dependencies:

pip install -r requirements.txt

Dataset Setup

Create and fill these folders:

dataset/
|- with_mask/
|- without_mask/

Supported formats: .jpg, .jpeg, .png, .bmp, .webp

Train Model

python train_model.py

Expected output:

• model/mask_detector.h5

Run the Project

Option A: Full UI + Backend (recommended)

python api_server.py

Then open:

• http://127.0.0.1:5000/

In UI, click Start camera & API.

Option B: Direct webcam detection (no browser)

python detect_mask_video.py

Press q to quit.

Option C: Single image detection

python detect_mask_image.py path\to\image.jpg

API Endpoint

POST /api/predict

• Request: multipart/form-data with field image
• Response: JSON containing faces[] with box coordinates, label, and confidence

Evaluate Model

python evaluate_model.py

Troubleshooting

• Model load error: run python train_model.py again to regenerate model/mask_detector.h5
• UI not detecting: make sure server is running with python api_server.py
• Camera not opening: allow camera permission and try different camera index in OpenCV script if needed
• Do not open UI with file://: always use Flask URL (http://127.0.0.1:5000/)

Project Structure

MaskGuard-AI/
|- assets/
|  |- maskguard-banner.png
|  |- ui-home.png
|  |- ui-model-eval.png
|  |- ui-objectives.png
|  |- ui-live-mask.png
|  |- ui-live-no-mask.png
|- dataset/
|- model/
|- haarcascades/
|- web/
|  |- index.html
|- api_server.py
|- inference_backend.py
|- train_model.py
|- evaluate_model.py
|- detect_mask_video.py
|- detect_mask_image.py
|- requirements.txt

License

MIT - see LICENSE.