# baaotraan0407/drowsiness-detection architecture

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

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

## Overview

This repository is a real-time webcam driver-drowsiness detector, with a separate script for training eye-state and yawn CNNs. The user workflow captures video, detects a face, classifies eye and mouth regions, combines temporal signals into a drowsiness score, and presents visual and audio alerts. README documents model/device selection, ROI fallback, scoring, hysteresis, recovery, and optional CSV logging. The main implementation is partly sampled, so documented relationships are cited to README where appropriate.

Main entry points: [`main.py`](https://github.com/baaotraan0407/drowsiness-detection/blob/main/main.py) (Webcam application), [`Train.py`](https://github.com/baaotraan0407/drowsiness-detection/blob/main/Train.py) (CNN trainer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Detection runtime"]
  node_app["Webcam application<br/>[main.py]"]
  node_detector["Face detector<br/>[main.py]"]
  node_roi["Eye/mouth ROIs<br/>[main.py]"]
  node_eye["Eye classifier<br/>[main.py]"]
  node_mouth["Mouth classifier<br/>[main.py]"]
end

subgraph group_analysis["Drowsiness analysis"]
  node_temporal["Mouth temporal features<br/>[main.py]"]
  node_perclos["PERCLOS and closure<br/>[main.py]"]
  node_score["Drowsiness score<br/>[main.py]"]
  node_alert["Alert and recovery<br/>[main.py]"]
end

subgraph group_training["Model training"]
  node_trainer["CNN trainer<br/>[Train.py]"]
  node_datasets[("Training datasets")]
  node_cnnmodels["Trained CNNs"]
end

subgraph group_integrations["Models and output"]
  node_visual["Visual alert<br/>[main.py]"]
  node_audio["Audio beep<br/>[main.py]"]
  node_csv["CSV logging<br/>[main.py]"]
  node_models["Pretrained models"]
end

node_driver(("Driver"))
node_webcam(("Webcam frames"))

node_driver -->|"provides video"| node_webcam
node_webcam -->|"streams frames"| node_app
node_app -->|"processes frames"| node_detector
node_detector -->|"provides face"| node_roi
node_roi -->|"classifies eyes"| node_eye
node_roi -->|"classifies mouth"| node_mouth
node_mouth -->|"feeds MAR history"| node_temporal
node_eye -->|"updates closure"| node_perclos
node_temporal -->|"informs yawn signal"| node_score
node_perclos -->|"supplies eye signals"| node_score
node_score -->|"drives state"| node_alert
node_app -->|"renders alert"| node_visual
node_alert -->|"triggers beep"| node_audio
node_app -->|"writes metrics"| node_csv
node_app -.->|"loads models"| node_models
node_datasets -->|"supplies images"| node_trainer
node_trainer -->|"trains and saves"| node_cnnmodels
node_cnnmodels -.->|"provides eye weights"| node_eye
node_cnnmodels -.->|"provides mouth weights"| node_mouth

click node_app "https://github.com/baaotraan0407/drowsiness-detection/blob/main/main.py"
click node_detector "https://github.com/baaotraan0407/drowsiness-detection/blob/main/main.py"
click node_roi "https://github.com/baaotraan0407/drowsiness-detection/blob/main/main.py"
click node_eye "https://github.com/baaotraan0407/drowsiness-detection/blob/main/main.py"
click node_mouth "https://github.com/baaotraan0407/drowsiness-detection/blob/main/main.py"
click node_temporal "https://github.com/baaotraan0407/drowsiness-detection/blob/main/main.py"
click node_perclos "https://github.com/baaotraan0407/drowsiness-detection/blob/main/main.py"
click node_score "https://github.com/baaotraan0407/drowsiness-detection/blob/main/main.py"
click node_alert "https://github.com/baaotraan0407/drowsiness-detection/blob/main/main.py"
click node_visual "https://github.com/baaotraan0407/drowsiness-detection/blob/main/main.py"
click node_audio "https://github.com/baaotraan0407/drowsiness-detection/blob/main/main.py"
click node_csv "https://github.com/baaotraan0407/drowsiness-detection/blob/main/main.py"
click node_trainer "https://github.com/baaotraan0407/drowsiness-detection/blob/main/Train.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_detector,node_roi,node_eye,node_mouth toneBlue
class node_temporal,node_perclos,node_score,node_alert toneAmber
class node_trainer,node_datasets,node_cnnmodels toneMint
class node_visual,node_audio,node_csv,node_models toneRose
class node_driver,node_webcam toneIndigo
```

## Components

### Detection runtime

- [Webcam application](https://github.com/baaotraan0407/drowsiness-detection/blob/main/main.py): `main.py`
- [Face detector](https://github.com/baaotraan0407/drowsiness-detection/blob/main/main.py): `main.py`
- [Eye/mouth ROIs](https://github.com/baaotraan0407/drowsiness-detection/blob/main/main.py): `main.py`
- [Eye classifier](https://github.com/baaotraan0407/drowsiness-detection/blob/main/main.py): `main.py`
- [Mouth classifier](https://github.com/baaotraan0407/drowsiness-detection/blob/main/main.py): `main.py`

### Drowsiness analysis

- [Mouth temporal features](https://github.com/baaotraan0407/drowsiness-detection/blob/main/main.py): `main.py`
- [PERCLOS and closure](https://github.com/baaotraan0407/drowsiness-detection/blob/main/main.py): `main.py`
- [Drowsiness score](https://github.com/baaotraan0407/drowsiness-detection/blob/main/main.py): `main.py`
- [Alert and recovery](https://github.com/baaotraan0407/drowsiness-detection/blob/main/main.py): `main.py`

### Model training

- [CNN trainer](https://github.com/baaotraan0407/drowsiness-detection/blob/main/Train.py): `Train.py`
- **Training datasets**
- **Trained CNNs**

### Models and output

- [Visual alert](https://github.com/baaotraan0407/drowsiness-detection/blob/main/main.py): `main.py`
- [Audio beep](https://github.com/baaotraan0407/drowsiness-detection/blob/main/main.py): `main.py`
- [CSV logging](https://github.com/baaotraan0407/drowsiness-detection/blob/main/main.py): `main.py`
- **Pretrained models**

### Other components

- **Driver**
- **Webcam frames**

## Connections

- Driver → Webcam frames: provides video (evidence: `README.md`)
- Webcam frames → Webcam application: streams frames (evidence: `main.py`)
- Webcam application → Face detector: processes frames (evidence: `README.md`)
- Face detector → Eye/mouth ROIs: provides face (evidence: `README.md`)
- Eye/mouth ROIs → Eye classifier: classifies eyes (evidence: `README.md`)
- Eye/mouth ROIs → Mouth classifier: classifies mouth (evidence: `README.md`)
- Mouth classifier → Mouth temporal features: feeds MAR history (evidence: `README.md`)
- Eye classifier → PERCLOS and closure: updates closure (evidence: `README.md`)
- Mouth temporal features → Drowsiness score: informs yawn signal (evidence: `README.md`)
- PERCLOS and closure → Drowsiness score: supplies eye signals (evidence: `README.md`)
- Drowsiness score → Alert and recovery: drives state (evidence: `README.md`)
- Webcam application → Visual alert: renders alert (evidence: `README.md`)
- Alert and recovery → Audio beep: triggers beep (evidence: `main.py`)
- Webcam application → CSV logging: writes metrics (evidence: `main.py`)
- Webcam application → Pretrained models: loads models
- Training datasets → CNN trainer: supplies images (evidence: `Train.py`)
- CNN trainer → Trained CNNs: trains and saves (evidence: `Train.py`)
- Trained CNNs → Eye classifier: provides eye weights
- Trained CNNs → Mouth classifier: provides mouth weights
