FaceDetectionSystem

Realistic face detection project with CLI + Web UI, multiple detectors, analytics, and output exports.

Features

• Two detector backends:
  • dnn (OpenCV SSD, higher accuracy, default)
  • haar (fast classic cascade)
• Real-time webcam detection
• Image detection with bounding boxes
• Video file detection and re-encoding with overlays
• Automatic output saving to outputs/
• Analytics report generation in JSON
• Web UI with detector selector and confidence tuning
• Webcam v2 capabilities:
  • Duplicate box suppression (IoU dedup)
  • Stable tracking IDs per face across frames
  • Jitter smoothing for cleaner boxes
  • Live metrics: active faces, unique people, FPS
  • Entry/exit event feed per track ID
  • Session controls: reset and JSON export from dashboard
  • Detection latency metric in milliseconds

Setup

1. Create and activate a virtual environment (recommended).
2. Install dependencies:

pip install -r requirements.txt

Usage

1) Webcam face detection (default DNN)

python app.py

Press q to quit.

2) Image face detection

python app.py --image "path/to/your/image.jpg"

3) Video face detection

python app.py --video "path/to/your/video.mp4"

4) Web UI (live webcam detection)

python web_app.py

Then open http://127.0.0.1:5000, click Start Webcam Detection, and allow camera permission. The browser sends frames to Flask for detection and draws boxes in real time. Each face gets a stable ID, and the dashboard shows live FPS and enter/exit events. Use Reset Session to clear tracking history. Use Export Session Report to save full analytics + events JSON under outputs/.

If DNN model download fails on your network, keep detector as haar in the web UI.

CLI options

• --detector {dnn,haar} (default: dnn)
• --confidence 0.6 (used for DNN)
• --camera-index 0 (webcam source)
• --save-output outputs/custom.mp4
• --report-json outputs/my_report.json

Examples:

python app.py --image "group_photo.jpg" --detector dnn --confidence 0.65 --save-output "outputs/group_detected.png"
python app.py --video "meeting.mp4" --detector haar --save-output "outputs/meeting_detected.mp4" --report-json "outputs/meeting_report.json"

Project structure

• app.py - CLI for webcam/image/video processing
• web_app.py - Flask UI for upload + inference
• detector_engine.py - reusable detection engine and analytics helpers
• outputs/ - generated media + JSON reports
• models/ - auto-downloaded DNN model files (first DNN run only)