# foxprint666/cnn-based-drowsiness-detection-with-advanced-preprocessing-and-speed-optimisation architecture

> Architecture diagram of the GitHub repository foxprint666/cnn-based-drowsiness-detection-with-advanced-preprocessing-and-speed-optimisation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/foxprint666/cnn-based-drowsiness-detection-with-advanced-preprocessing-and-speed-optimisation
- Repository: https://github.com/foxprint666/cnn-based-drowsiness-detection-with-advanced-preprocessing-and-speed-optimisation

## Overview

1. **What this repo is**
   - This is a **local, real-time driver drowsiness detection system**, not a web or service app.
   - The runtime path is a computer-vision pipeline that ingests camera frames, extracts face/eye/mouth features, runs a PyTorch classifier, and triggers alerts.

2. **Primary execution boundary**
   - `main.py` is the top-level orchestrator for the live system.
   - `config.py` centralizes camera settings and detection thresholds, so the runtime behavior is mostly controlled by configuration rather than hardcoded values.

3. **Core runtime pipeline**
   - The live system is split into four main modules under `pipeline/`:
     - `capture.py` for frame acquisition
     - `preprocessing.py` for face/landmark processing and feature extraction
     - `inference.py` for eye-state model execution
     - `alerting.py` for state evaluation and user notification
   - The architecture is staged, so each module owns one phase of the data flow.

4. **Frame acquisition subsystem**
   - `pipeline/capture.py` is the camera boundary.
   - It reads frames from a local device using OpenCV, likely driven by `CAMERA_ID`, `CAMERA_WIDTH`, and `CAMERA_HEIGHT`.
   - This is the only subsystem that touches the live video source.

5. **Preprocessing and feature extraction**
   - `pipeline/preprocessing.py` handles face detection and landmark-based measurements.
   - The repo uses **MediaPipe Face Landmarker** (`models/face_landmarker.task`) to get dense facial landmarks.
   - From those landmarks it derives the key safety signals described in the README: eye-region crops / eye aspect ratio, mouth aspect ratio for yawning, and head pose estimates using `cv2.solvePnP`.

6. **Model inference subsystem**
   - `pipeline/inference.py` loads and runs the PyTorch eye-state classifier.
   - The model artifact is `models/mobilenet_v2_eye_state.pth`, which implies a MobileNetV2-based binary or probabilistic eye-state model.
   - The README also indicates optional GPU acceleration via PyTorch AMP/autocast, so inference can run on CPU or CUDA depending on configuration.

7. **Alerting and decision logic**
   - `pipeline/alerting.py` is the policy boundary that turns raw signals into user-facing outcomes.
   - It combines the CNN eye-state probability with head-pose and yawning cues to decide between normal, distracted/yawning warning, and critical drowsiness alarm.
   - Audio alerting is part of this layer, using a lightweight local playback dependency rather than any external notification service.

8. **Data flow between modules**
   - The system is built as a **multi-threaded async pipeline** with queue handoffs between stages.
   - Frames move forward from capture → preprocessing → inference → alerting, while intermediate features can be forwarded separately to the alerting logic.
   - The important architectural property is that feature extraction and classification are decoupled, which helps real-time throughput and avoids blocking the camera thread.

9. **Model and artifact boundary**
   - The `models/` directory is the deployment bundle for runtime assets, not source code.
   - It contains both the MediaPipe task file and the trained PyTorch weights, so the repo packages the full runtime dependency set needed for inference.
   - This means the project has a clear split between **offline-trained artifacts** and **online detection code**.

10. **Training and evaluation subsystem**
   - The `train/` directory is a separate offline ML workflow:
     - `train/dataset.py` for dataset loading/preparation
     - `train/train.py` for training the eye-state model
     - `train/evaluate.py` for validation/testing
   - This is a distinct boundary from the live pipeline: training produces the `.pth` model consumed by `pipeline/inference.py`.

11. **Technology profile that matters to architecture**
   - The repo depends on **OpenCV** for camera/image handling, **MediaPipe** for facial landmarks, **PyTorch** for the classifier, **NumPy** for numeric processing, and **playsound** for alerts.
   - The system is therefore a **desktop CV + ML application** with local inference and no external backend or cloud dependency.

12. **How to draw it**
   - A correct architecture diagram should show:
     - a local camera feeding a capture stage,
     - preprocessing/feature extraction as the central transform,
     - a PyTorch inference stage for eye-state estimation,
     - a rule-based alerting stage combining multiple signals,
     - and a separate offline training path that produces the model artifact used at runtime.

Main entry points: [`pipeline/preprocessing.py`](https://github.com/foxprint666/cnn-based-drowsiness-detection-with-advanced-preprocessing-and-speed-optimisation/blob/main/pipeline/preprocessing.py) (Preprocess), [`pipeline/inference.py`](https://github.com/foxprint666/cnn-based-drowsiness-detection-with-advanced-preprocessing-and-speed-optimisation/blob/main/pipeline/inference.py) (Eye inference), [`train/train.py`](https://github.com/foxprint666/cnn-based-drowsiness-detection-with-advanced-preprocessing-and-speed-optimisation/blob/main/train/train.py) (Training), [`main.py`](https://github.com/foxprint666/cnn-based-drowsiness-detection-with-advanced-preprocessing-and-speed-optimisation/blob/main/main.py) (Main loop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Live detection"]
  node_main["Main loop<br/>orchestrator<br/>[main.py]"]
  node_config["Config<br/>settings<br/>[config.py]"]
  node_capture["Frame capture<br/>camera input<br/>[capture.py]"]
  node_preprocessing["Preprocess<br/>vision features<br/>[preprocessing.py]"]
  node_inference["Eye inference<br/>pytorch runtime<br/>[inference.py]"]
  node_alerting["Alert policy<br/>decision logic<br/>[alerting.py]"]
  node_camera(("Camera device<br/>local source"))
end

subgraph group_artifacts["Model assets"]
  node_mediapipe["Face landmarker<br/>feature extractor"]
  node_eye_model["Eye model<br/>trained weights"]
end

subgraph group_training["Offline training"]
  node_dataset["Dataset prep<br/>data pipeline<br/>[dataset.py]"]
  node_train_script["Training<br/>[train.py]"]
  node_evaluate["Evaluation<br/>ml validation<br/>[evaluate.py]"]
end

node_main -->|"reads settings"| node_config
node_main -->|"starts pipeline"| node_capture
node_camera -->|"video frames"| node_capture
node_capture -->|"frames"| node_preprocessing
node_preprocessing -->|"landmarks"| node_mediapipe
node_preprocessing -->|"eye crops"| node_inference
node_preprocessing -->|"pose/yawn cues"| node_alerting
node_inference -->|"eye state"| node_alerting
node_alerting -->|"status"| node_main
node_inference -->|"loads weights"| node_eye_model
node_train_script -->|"produces"| node_eye_model
node_dataset -->|"training data"| node_train_script
node_train_script -->|"validated by"| node_evaluate

click node_main "https://github.com/foxprint666/cnn-based-drowsiness-detection-with-advanced-preprocessing-and-speed-optimisation/blob/main/main.py"
click node_config "https://github.com/foxprint666/cnn-based-drowsiness-detection-with-advanced-preprocessing-and-speed-optimisation/blob/main/config.py"
click node_capture "https://github.com/foxprint666/cnn-based-drowsiness-detection-with-advanced-preprocessing-and-speed-optimisation/blob/main/pipeline/capture.py"
click node_preprocessing "https://github.com/foxprint666/cnn-based-drowsiness-detection-with-advanced-preprocessing-and-speed-optimisation/blob/main/pipeline/preprocessing.py"
click node_inference "https://github.com/foxprint666/cnn-based-drowsiness-detection-with-advanced-preprocessing-and-speed-optimisation/blob/main/pipeline/inference.py"
click node_alerting "https://github.com/foxprint666/cnn-based-drowsiness-detection-with-advanced-preprocessing-and-speed-optimisation/blob/main/pipeline/alerting.py"
click node_mediapipe "https://github.com/foxprint666/cnn-based-drowsiness-detection-with-advanced-preprocessing-and-speed-optimisation/blob/main/models/face_landmarker.task"
click node_eye_model "https://github.com/foxprint666/cnn-based-drowsiness-detection-with-advanced-preprocessing-and-speed-optimisation/blob/main/models/mobilenet_v2_eye_state.pth"
click node_dataset "https://github.com/foxprint666/cnn-based-drowsiness-detection-with-advanced-preprocessing-and-speed-optimisation/blob/main/train/dataset.py"
click node_train_script "https://github.com/foxprint666/cnn-based-drowsiness-detection-with-advanced-preprocessing-and-speed-optimisation/blob/main/train/train.py"
click node_evaluate "https://github.com/foxprint666/cnn-based-drowsiness-detection-with-advanced-preprocessing-and-speed-optimisation/blob/main/train/evaluate.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_main,node_config,node_capture,node_preprocessing,node_inference,node_alerting,node_camera toneBlue
class node_mediapipe,node_eye_model toneAmber
class node_dataset,node_train_script,node_evaluate toneMint
```

## Components

### Live detection

Real-time camera-to-alert pipeline

- [Main loop](https://github.com/foxprint666/cnn-based-drowsiness-detection-with-advanced-preprocessing-and-speed-optimisation/blob/main/main.py): orchestrator · Top-level runtime entrypoint coordinating the live pipeline. · `main.py`
- [Config](https://github.com/foxprint666/cnn-based-drowsiness-detection-with-advanced-preprocessing-and-speed-optimisation/blob/main/config.py): settings · Centralized camera and detection thresholds. · `config.py`
- [Frame capture](https://github.com/foxprint666/cnn-based-drowsiness-detection-with-advanced-preprocessing-and-speed-optimisation/blob/main/pipeline/capture.py): camera input · Reads frames from the local camera device. · `pipeline/capture.py`
- [Preprocess](https://github.com/foxprint666/cnn-based-drowsiness-detection-with-advanced-preprocessing-and-speed-optimisation/blob/main/pipeline/preprocessing.py): vision features · Runs face/landmark processing and derives eye, mouth, and pose signals. · `pipeline/preprocessing.py`
- [Eye inference](https://github.com/foxprint666/cnn-based-drowsiness-detection-with-advanced-preprocessing-and-speed-optimisation/blob/main/pipeline/inference.py): pytorch runtime · Loads and executes the eye-state classifier. · `pipeline/inference.py`
- [Alert policy](https://github.com/foxprint666/cnn-based-drowsiness-detection-with-advanced-preprocessing-and-speed-optimisation/blob/main/pipeline/alerting.py): decision logic · Combines model output and behavioral cues to trigger warnings or alarms. · `pipeline/alerting.py`
- **Camera device**: local source · Live video source consumed by the capture stage.

### Model assets

Packaged runtime artifacts used by the detector

- [Face landmarker](https://github.com/foxprint666/cnn-based-drowsiness-detection-with-advanced-preprocessing-and-speed-optimisation/blob/main/models/face_landmarker.task): feature extractor · Dense facial landmark model used for geometric measurements. · `models/face_landmarker.task`
- [Eye model](https://github.com/foxprint666/cnn-based-drowsiness-detection-with-advanced-preprocessing-and-speed-optimisation/blob/main/models/mobilenet_v2_eye_state.pth): trained weights · PyTorch MobileNetV2 eye-state classifier artifact. · `models/mobilenet_v2_eye_state.pth`

### Offline training

Separate ML workflow that produces the runtime model

- [Dataset prep](https://github.com/foxprint666/cnn-based-drowsiness-detection-with-advanced-preprocessing-and-speed-optimisation/blob/main/train/dataset.py): data pipeline · Loads and prepares training data for the eye-state model. · `train/dataset.py`
- [Training](https://github.com/foxprint666/cnn-based-drowsiness-detection-with-advanced-preprocessing-and-speed-optimisation/blob/main/train/train.py): ml training · Trains the classifier that becomes the runtime model artifact. · `train/train.py`
- [Evaluation](https://github.com/foxprint666/cnn-based-drowsiness-detection-with-advanced-preprocessing-and-speed-optimisation/blob/main/train/evaluate.py): ml validation · Validates and tests the trained model. · `train/evaluate.py`

## Connections

- Main loop → Config: reads settings · Runtime behavior is driven by centralized configuration.
- Main loop → Frame capture: starts pipeline · Main loop launches the live capture stage.
- Camera device → Frame capture: video frames · Capture reads frames from the local device.
- Frame capture → Preprocess: frames · Raw frames flow into feature extraction.
- Preprocess → Face landmarker: landmarks · Preprocessing relies on packaged face-landmarker assets.
- Preprocess → Eye inference: eye crops · Derived eye-region features are passed to the classifier.
- Preprocess → Alert policy: pose/yawn cues · Behavioral signals are forwarded for decision making.
- Eye inference → Alert policy: eye state · Classifier output contributes to alert decisions.
- Alert policy → Main loop: status · Alerting returns the current driver state to the orchestrator.
- Eye inference → Eye model: loads weights · Inference consumes the trained PyTorch artifact.
- Training → Eye model: produces · Training emits the deployed model weights.
- Dataset prep → Training: training data · Prepared datasets feed the training stage.
- Training → Evaluation: validated by · Trained models are assessed by evaluation.
