Drowsiness Detection System

Welcome to the technical documentation for the Drowsiness Detection System. This project is a safety-focused application that uses state-of-the-art Artificial Intelligence to prevent accidents by monitoring driver or operator fatigue in real-time.

🚀 System at a Glance

At its core, the system acts as a “digital guardian” that constantly watches the user’s eyes through a webcam and calculates the probability of drowsiness based on biological patterns (like blinking vs. nodding off).

High-Level System Flow

graph TD
    A[Webcam Feed] -->|Raw Video Frames| B[YOLOv11 Classifier]
    B -->|Open/Closed Prediction| C[Temporal Analysis Engine]
    C -->|Closed Ratio / Streak| D{Drowsiness Detected?}
    D -->|No| A
    D -->|Yes| E[Multi-Modal Alert System]
    E -->|Desktop Notification| F[User]
    E -->|Audio Alarm| F
    E -->|Visual Warning| F
    F -->|User Wakes Up| A

🧠 How it Works: The Core Logic

The system avoids the common mistake of reacting to a single “closed eye” frame (which is just a blink). Instead, it uses Temporal Analysis.

It looks at a window of time (e.g., the last 15 frames). If the eyes are closed for too long (the Ratio) or closed in a continuous streak (the Consecutive Count), the system knows this isn’t a blink—it’s drowsiness.

🗺️ Documentation Map

To help you navigate this project, we’ve broken the documentation down by functional layers:

1. The AI Brain (Models & Training)

Understand how the AI was taught to see eyes.

• architecture: The “Black Box” explained—how YOLOv11 works.
• dataset: The MRL Eye Dataset and how data was organized.
• model-training: The step-by-step training pipeline.

2. The Execution Engine (Inference)

How the code turns pixels into alerts.

• detection-system: The real-time monitoring loop and state logic.
• alert-mechanism: How the alarms are triggered and managed.

3. The Control Panel (Configuration)

How to customize the system for your needs.

• environment: Getting the system running on your machine.
• hyperparameters: Tuning the sensitivity for the perfect balance.