# dilatuanaucar/drowsiness-detection architecture

> Architecture diagram of the GitHub repository dilatuanaucar/drowsiness-detection, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dilatuanaucar/drowsiness-detection
- Repository: https://github.com/dilatuanaucar/drowsiness-detection

## Overview

##### Project Type and Purpose
- This is a standalone Python computer-vision application for real-time drowsiness detection. It uses OpenCV to capture frames from a webcam, Haar cascades to locate faces and eyes, and a pre-trained Keras CNN to classify eye state. When eyes remain closed beyond a threshold, it triggers an audio alert.

##### Key Components (to appear
a. Input Layer
- Webcam (live video feed)
b. Preprocessing & Detection
- Frame Grabber (OpenCV VideoCapture)
- Face Detector (haar cascade: haarcascade_frontalface_alt.xml)
- Eye Detectors (haar cascade: lefteye & righteye .xml)
- ROI Extractor & Preprocessor (crop, grayscale, resize)
c. Classification Engine
- CNN Model Loader (loads models/cnnCat2.h5 via model.py)
- Inference Module (Keras/TensorFlow calls to classify “Open” vs “Closed”)
d. Logic & Scoring
- Score Calculator (maintains drowsiness score, increments when “Closed”)
- Threshold Checker (evaluates when score > limit)
e. Alert System
- Audio Player (plays alarm.wav when drowsiness detected)
f. File System Dependencies
- haar cascade .xml files (stored under “haar cascade files”)
- Model file (models/cnnCat2.h5)
- Python scripts (model.py for training, drowsiness detection.py as main)

##### Relationships and Data Flow
Webcam → Frame Grabber → Face Detector → Eye Detectors → ROI Extractor → Classification Engine → Logic & Scoring → Alert System
- That Detection modules share data with Preprocessor and feed into the CNN.

##### Architectural Patterns & Design Principles
- Pipeline pattern: each stage performs one responsibility (capture → detect → classify → alert).
- Separation of concerns:
- model.py handles model creation/training
- drowsiness detection.py orchestrates capture, inference, scoring, alert
- Local storage of static assets (cascades + .h5 model) vs. runtime modules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Pipeline stages
    Webcam["Webcam\n(live video feed)"]:::io
    FrameGrabber["Frame Grabber\n(OpenCV VideoCapture)"]:::cv
    FaceDetector["Face Detector\n(Haar Cascade)"]:::cv
    EyeDetectors["Eye Detectors\n(Haar Cascades)"]:::cv
    ROIPreprocessor["ROI Extractor & Preprocessor\n(crop, grayscale, resize)"]:::cv
    CNNModelLoader["CNN Model Loader"]:::ml
    InferenceModule["Inference Module\n(Keras/TensorFlow)"]:::ml
    ScoreCalculator["Score Calculator & Threshold Checker\n(score threshold=15)"]:::proc
    AlertSystem["Alert System\n(Audio Player)"]:::alert

    %% Data stores
    cascadeFiles["Cascade Files\n(.xml assets)"]:::datastore
    modelFile["Model File\ncnnCat2.h5"]:::datastore

    %% Flow arrows
    Webcam -->|"video frame"| FrameGrabber
    FrameGrabber -->|"frame"| FaceDetector
    FaceDetector -->|"face ROI"| EyeDetectors
    EyeDetectors -->|"eye regions"| ROIPreprocessor
    ROIPreprocessor -->|"cropped eye image (24×24 px)"| InferenceModule
    CNNModelLoader -->|"model instance"| InferenceModule
    InferenceModule -->|"state (Open/Closed)"| ScoreCalculator
    ScoreCalculator -->|"drowsiness alert"| AlertSystem

    %% Dotted load arrows
    cascadeFiles -.->|"load cascade"| FaceDetector
    cascadeFiles -.->|"load cascade"| EyeDetectors
    modelFile    -.->|"load model"| CNNModelLoader

    %% Click events
    click Webcam "https://github.com/dilatuanaucar/drowsiness-detection/blob/main/Drowsiness detection/drowsiness detection.py"
    click FrameGrabber "https://github.com/dilatuanaucar/drowsiness-detection/blob/main/Drowsiness detection/drowsiness detection.py"
    click FaceDetector "https://github.com/dilatuanaucar/drowsiness-detection/blob/main/Drowsiness detection/haar cascade files/haarcascade_frontalface_alt.xml"
    click EyeDetectors "https://github.com/dilatuanaucar/drowsiness-detection/blob/main/Drowsiness detection/haar cascade files/haarcascade_lefteye_2splits.xml"
    click EyeDetectors "https://github.com/dilatuanaucar/drowsiness-detection/blob/main/Drowsiness detection/haar cascade files/haarcascade_righteye_2splits.xml"
    click ROIPreprocessor "https://github.com/dilatuanaucar/drowsiness-detection/blob/main/Drowsiness detection/drowsiness detection.py"
    click CNNModelLoader "https://github.com/dilatuanaucar/drowsiness-detection/blob/main/Drowsiness detection/model.py"
    click modelFile "https://github.com/dilatuanaucar/drowsiness-detection/blob/main/Drowsiness detection/models/cnnCat2.h5"
    click InferenceModule "https://github.com/dilatuanaucar/drowsiness-detection/blob/main/Drowsiness detection/drowsiness detection.py"
    click ScoreCalculator "https://github.com/dilatuanaucar/drowsiness-detection/blob/main/Drowsiness detection/drowsiness detection.py"
    click AlertSystem "https://github.com/dilatuanaucar/drowsiness-detection/blob/main/Drowsiness detection/alarm.wav"

    %% Styling
    classDef io fill:#9f6,stroke:#333,stroke-width:1px
    classDef cv fill:#6cf,stroke:#333,stroke-width:1px
    classDef ml fill:#f90,stroke:#333,stroke-width:1px
    classDef proc fill:#bfd,stroke:#333,stroke-width:1px
    classDef alert fill:#f66,stroke:#333,stroke-width:1px
    classDef datastore fill:#fff,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5,shape:cylinder
```
