How joysjohney/driver-drowsiness-detection works
This is a local, offline-capable, full-stack monolith (single Flask app + static frontend) that performs real-time driver drowsiness detection from a webcam feed using MediaPipe Face Mesh + OpenCV, computes EAR/MAR, derives a drowsiness score, and triggers audio/visual alerts plus a dashboard (Chart.js timeline, stats, admin/user pages).
• The real-time video processing loop (camera → CV pipeline → score/alerts)
• The UI dashboard (live feed + metrics + timeline)
• The Flask server roles: serving pages/static assets, exposing endpoints, orchestrating detector, auth, and persistence
• The local persistence (SQLite DB files)
• Any separation of concerns inside backend utils (eye tracking, yawn detection, alert manager)
From the tree:
Backend (Python/Flask)
• backend/app.py
Likely the Flask entrypoint: routes for pages/APIs, camera capture, streaming frames, sending metrics to frontend.
• backend/drowsiness_detector.py
Core detection engine coordinating face mesh, EAR/MAR, scoring, state machine (Normal/Warning/Alert).
• backend/utils/eye_tracker.py
Computes Eye Aspect Ratio + blink/closure tracking thresholds.
• backend/utils/yawn_detector.py
Computes Mouth Aspect Ratio + yawn detection.
• backend/utils/alert_manager.py
Alert policy (cooldown, escalation) and “when to alert”.
• backend/auth.py
Authentication/authorization logic for login/register/admin flows.
• backend/database.py + backend/users.db + backend/driver_data.db
SQLite persistence. Likely users table + driver sessions/events/timeline data.
Frontend (static HTML/CSS/JS)
• Multiple HTML pages: login.html, register.html, driver.html, admin.html, etc.
This implies role-based views (driver vs admin) and account/profile management.
• frontend/js/main.js
Likely:
• Requests live metrics / video stream
• Updates DOM stats
• Triggers audio (assets/alert-sound.wav) + red flash
• frontend/js/chart-config.js
Chart.js timeline configuration, rolling window plotting.
• frontend/css/style.css
Presentation only, but still include as “Static assets”.
Browser (Driver Dashboard / Admin UI)
• HTML pages + JS + Chart.js
• Plays audio, shows alerts, renders chart
Flask Backend (app.py)
• Serves static frontend + routes
• API endpoints for metrics/auth
• Possibly an MJPEG/streaming endpoint for live video
Drowsiness Detection Module (drowsiness_detector.py + utils)
• Face landmark detection (MediaPipe)
• EAR/MAR computations (SciPy/NumPy)
• State + score + alert level
Local Camera Device (Webcam)
• Video frames to backend (likely via OpenCV VideoCapture)
SQLite Databases
• users.db (auth/account data)
• driver_data.db (events, timeline, alerts, sessions)
• Browser ⇄ Flask: HTTP for pages + JSON APIs (metrics, login, register, admin actions)
• Flask → Webcam: frame capture
• Webcam frames → Detector: per-frame processing
• Detector → Flask: metrics (EAR/MAR, blink/yawn counts, score, status)
• Flask → Browser: stream + metrics (polling/WebSocket/Server-Sent Events—label based on what app.py does)
• Flask/Auth ↔ users.db: credential verification, user CRUD
• Flask/Detector ↔ driver_data.db: event logging / history / timeline retrieval
Inside “Backend” show modules and dependencies:
• app.py depends on:
• auth.py (login/register/session)
• database.py (DB connections/queries)
• drowsiness_detector.py (start/stop detection, get metrics)
• drowsiness_detector.py depends on:
• utils/eye_tracker.py
• utils/yawn_detector.py
• utils/alert_manager.py
• MediaPipe + OpenCV + NumPy/SciPy
• database.py manages:
• users.db
• driver_data.db
For each frame
• MediaPipe Face Mesh → 468 landmarks
• eye_tracker computes EAR + closure duration/blink rate
• yawn_detector computes MAR + yawn events
• drowsiness_detector computes score (0–100) + level (Normal/Warning/Alert)
• alert_manager applies cooldown/escalation rules
Backend pushes to frontend
• Live feed (overlay landmarks) and/or processed frame
• JSON metrics for UI + Chart.js timeline
Frontend triggers
• Visual alert (flash/status badge)
• Audio alert (wav)
Backend optionally persists
• Alert events, timestamps, session summaries → driver_data.db
• A “loop” annotation on the detector pipeline (“per frame @ ~15 FPS”).
Architectural patterns/principles to highlight (specific to this project)
• Modular CV pipeline: eye tracking, yawn detection, alert policy separated under backend/utils/
• Local-first / offline: no cloud services; dependencies are on-device libraries + local SQLite
• State machine / threshold-based scoring: Normal/Warning/Alert levels + cooldown (alert_manager)
Device layer: Webcam
Examples:
• “HTTP GET /login.html”
• “HTTP POST /api/login (username/password)”
• “MJPEG stream /video_feed” or “/api/metrics (JSON: ear, mar, score, status)”
• “SQL: insert alert event”
“Don’t overthink it” but be very detailed
Concretely, for this repo, “separating into as many components as possible” means:
• Split backend into app.py, auth.py, database.py, drowsiness_detector.py, and each utils/* module
• Split frontend into Pages, JS runtime (main.js), Chart config, and Assets
• Split data into the two DB files (not a single generic “DB”)
• Whether metrics are delivered via polling, SSE, WebSockets, or frame-embedded metadata