# rudrabarad/driver-drowsiness-detection architecture

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

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

## Overview

##### Project type and purpose
- This is an open-source computer-vision + deep-learning application for real-time driver drowsiness detection.
- It offers two pipelines:
- A custom CNN approach (folder: DDDS_CNN)
- A Transfer Learning approach (folder: Transfer_learning)
- Both capture live video, detect facial features, classify eye state, and trigger an alarm if drowsiness is detected.

##### File structure
Top level:
- DDDS_CNN/ – Python scripts for your custom CNN pipeline
– Dataset.txt – URLs for raw images
– haar cascade files/ – face & eye detectors (XMLs)
– model_training.py – trains custom CNN & saves model
– main_capture.py – live camera inference & alarm
- Transfer_learning/ – Jupyter notebook & helper scripts for TL pipeline
– get_dataset.txt – URLs for TL dataset
– data_prep.py & data_dist.py – preprocessing & train/test split
– Model_Training_TL.ipynb – trains TL model & saves it
– tl_capture.py – live camera inference & alarm
- alarm.wav – sound file used by both pipelines
- Research Article.docx, Video_Demonstration.mkv – documentation & demo
- README.md & LICENSE

##### Key insights from the README
- Lists required libraries (Keras, OpenCV, Pygame, NumPy, etc.)
- Describes training vs. inference steps for both approaches
- Shows performance metrics for each model
- Notes that model files are generated at training time

##### Components
a. Main components
1. Data Acquisition
– Dataset URLs (Dataset.txt / get_dataset.txt)
– Raw image folders (downloaded externally)
2. Data Preprocessing
– data_prep.py, data_dist.py (Transfer Learning)
– optional augmentation / resizing
3. Model Training
– model_training.py (Custom CNN)
– Model_Training_TL.ipynb (Transfer Learning)
– Output: saved .h5 (or similar) model file(s)
4. Inference / Runtime
– Video Capture module (OpenCV)
– Haar Cascade detectors (face, left eye, right eye)
– Model Inference (Keras -> open-vs-closed classification)
– Alarm module (Pygame + alarm.wav)
5. External Interfaces / Artifacts
– Research Article & Video Demo
– Logs / Metrics / Saved model versions

b. Relationships & Data Flow
- Data Acquisition → Data Preprocessing → Model Training → Saved Model
- Saved Model + Haar Cascades + Live Video Stream → Inference Engine
- Inference Engine → Decision Logic (open vs. closed eyes) → Alarm Module → Audio Output
- (Optional) Inference metrics → Log / Console

c. Architectural patterns & design principles
- Modularity: separate training vs. inference code paths
- Reusability: shared alarm.wav & Haar cascades
- Pipeline pattern: data → preprocess → train/infer → output
- Extensibility: ability to plug in new models (e.g., improved CNN or TL checkpoint)

d. Key technologies & libraries
- Python, OpenCV (cv2) for video and face detection
- Keras (TensorFlow backend) for model definition & inference
- Pygame for alarm sound playback
- Numpy / glob / tqdm / Matplotlib for data handling & visualization
- Jupyter Notebook for interactive TL training

## Diagram (Mermaid)

```mermaid
graph TB
    %% Training Phase
    subgraph "Training Phase"
        direction LR
        subgraph "Custom CNN" 
            direction TB
            DA_CNN[(Dataset URLs)]:::cnn
            Download_CNN["Download Images"]:::cnn
            DA_CNN-->Download_CNN
            CNN_Trainer["model_training.py"]:::cnn
            Download_CNN-->CNN_Trainer
            CNN_Trainer-->CNN_Model[(CNN Model File)]:::storage
        end
        subgraph "Transfer Learning"
            direction TB
            DA_TL[(Dataset URLs)]:::tl
            Download_TL["Download Images"]:::tl
            DA_TL-->Download_TL
            Data_Prep["data_prep.py"]:::tl
            Download_TL-->Data_Prep
            Data_Dist["data_dist.py"]:::tl
            Data_Prep-->Data_Dist
            TL_Notebook[/Model_Training_TL.ipynb/]:::notebook
            Data_Dist-->TL_Notebook
            TL_Notebook-->TL_Model[(TL Model File)]:::storage
        end
    end

    %% Inference Phase
    subgraph "Inference Phase" 
        direction TB
        Live["Live Video Stream"]:::shared
        subgraph "Haar Cascades"
            direction TB
            HaarFace["haarcascade_frontalface_alt.xml"]:::shared
            HaarLeft["haarcascade_lefteye_2splits.xml"]:::shared
            HaarRight["haarcascade_righteye_2splits.xml"]:::shared
        end
        Live-->HaarFace
        Live-->HaarLeft
        Live-->HaarRight

        HaarFace-->CNN_Capture["main_capture.py"]:::shared
        HaarLeft-->CNN_Capture
        HaarRight-->CNN_Capture
        HaarFace-->TL_Capture["tl_capture.py"]:::shared
        HaarLeft-->TL_Capture
        HaarRight-->TL_Capture

        CNN_Capture-->AlarmPlayer["Alarm Player"]:::shared
        TL_Capture-->AlarmPlayer

        subgraph "Alarm Module"
            direction TB
            AlarmCNNFile["alarm.wav (CNN)"]:::shared
            AlarmTLFile["alarm.wav (TL)"]:::shared
        end
        AlarmCNNFile-->AlarmPlayer
        AlarmTLFile-->AlarmPlayer
        AlarmPlayer-->Audio["Audio Output"]:::shared
    end

    %% External Artifacts
    subgraph "External Artifacts"
        direction TB
        README["README.md"]:::external
        LICENSE["LICENSE"]:::external
        Article["Research Article.docx"]:::external
        Video["Video_Demonstration.mkv"]:::external
    end

    %% Connections to external
    README---CNN_Trainer
    README---TL_Notebook
    LICENSE---CNN_Trainer
    Article---Video

    %% Click Events
    click DA_CNN "https://github.com/rudrabarad/driver-drowsiness-detection/blob/main/DDDS_CNN/Dataset.txt"
    click DA_TL "https://github.com/rudrabarad/driver-drowsiness-detection/blob/main/Transfer_learning/get_dataset.txt"
    click Data_Prep "https://github.com/rudrabarad/driver-drowsiness-detection/blob/main/Transfer_learning/data_prep.py"
    click Data_Dist "https://github.com/rudrabarad/driver-drowsiness-detection/blob/main/Transfer_learning/data_dist.py"
    click CNN_Trainer "https://github.com/rudrabarad/driver-drowsiness-detection/blob/main/DDDS_CNN/model_training.py"
    click TL_Notebook "https://github.com/rudrabarad/driver-drowsiness-detection/blob/main/Transfer_learning/Model_Training_TL.ipynb"
    click CNN_Capture "https://github.com/rudrabarad/driver-drowsiness-detection/blob/main/DDDS_CNN/main_capture.py"
    click TL_Capture "https://github.com/rudrabarad/driver-drowsiness-detection/blob/main/Transfer_learning/tl_capture.py"
    click HaarFace "https://github.com/rudrabarad/driver-drowsiness-detection/blob/main/DDDS_CNN/haar cascade files/haarcascade_frontalface_alt.xml"
    click HaarLeft "https://github.com/rudrabarad/driver-drowsiness-detection/blob/main/DDDS_CNN/haar cascade files/haarcascade_lefteye_2splits.xml"
    click HaarRight "https://github.com/rudrabarad/driver-drowsiness-detection/blob/main/DDDS_CNN/haar cascade files/haarcascade_righteye_2splits.xml"
    click AlarmCNNFile "https://github.com/rudrabarad/driver-drowsiness-detection/blob/main/DDDS_CNN/alarm.wav"
    click AlarmTLFile "https://github.com/rudrabarad/driver-drowsiness-detection/blob/main/Transfer_learning/alarm.wav"

    %% Styles
    classDef cnn fill:#ADD8E6,stroke:#000
    classDef tl fill:#90EE90,stroke:#000
    classDef shared fill:#D3D3D3,stroke:#000
    classDef storage fill:#FFF0F5,stroke:#000,stroke-dasharray: 5 5
    classDef notebook fill:#E6E6FA,stroke:#000,stroke-dasharray: 2 2
    classDef external fill:#FFFACD,stroke:#000,stroke-dasharray: 2 2
```
