# 050903/aifacedetectionproject architecture

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

- Interactive diagram: https://gitdiagram.com/050903/aifacedetectionproject
- Repository: https://github.com/050903/aifacedetectionproject

## Overview

##### Project type and purpose
- This is a stand-alone Python command-line & GUI tool (an “open-source tool”) for real-time drowsiness and yawn detection using a webcam.
- Its goal is to capture video frames, detect faces and facial landmarks, compute eye/mouth aspect ratios, and trigger visual/sound alerts and logging when thresholds are crossed.

a. Input Layer
– Webcam (video stream)
– Command-line arguments (thresholds, flags, model path, log file path)
b. Initialization
– Argument parser (argparse)
– Load Dlib pre-trained model (`shape_predictor_68_face_landmarks.dat`)
– Initialize OpenCV VideoCapture
– Initialize logging (optional file `drowsiness_log.txt`)
c. Frame Processing Pipeline
1. & Preprocess
- Grab frame → resize → convert to grayscale
2. Face Detection & Landmark Prediction
3. Metric Calculation
- EAR module (Eye Aspect Ratio)
- MAR module (Mouth Aspect Ratio)
- PERCLOS module (sliding‐window percentage of eye closure)
4. Alert Decision Logic
- Compare EAR/MAR/PERCLOS against thresholds
- Maintain counters (consecutive frames, yawns, PERCLOS window)
d. Output & Side Effects
1. Visualization
- Screen flash overlay on alert
2. Audible Alerts
- `winsound` thread (Windows only), toggled ON/OFF at runtime
3. Event Logging
- Write timestamped entries to log file when events occur (session start, drowsiness, yawn, alarm toggles)
4. Runtime Controls
- Hotkey handlers for ESC, r, +/–, f, a

- Command-line arguments → Initialization modules (feeds thresholds & flags)
- Webcam → Frame Preprocessing → Face Detection → Landmark Prediction → Metric Calculators → Alert Logic
- Alert Logic → Visualization, Sound, Logging
- Visualization & Sound → User (feedback loop)
- Hotkeys → Runtime controls → Alert Logic / Display / Logging

##### Architectural patterns & principles
- Modular pipeline: each stage is a separate responsibility (separation of concerns)
- Data flow orchestration: linear, frame-by-frame processing
- Event logging as a cross-cutting concern
- Runtime configurability via CLI & hotkeys

##### Technologies & libraries (annotate each component)
- Python 3.x (core)
- OpenCV (frame capture, display, GUI)
- Dlib (face detection, landmarks)
- NumPy/SciPy (calculations)
- argparse (configuration)
- winsound & threading (audio alerts)
- collections.deque (PERCLOS history)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Layer
    subgraph "Input Layer"
        CLI["Command-Line Arguments"]:::input
        Webcam["Webcam (Video Stream)"]:::input
        Model["Dlib Model File\n(shape_predictor_68_face_landmarks.dat)"]:::input
    end

    %% Initialization
    subgraph "Initialization"
        ArgParse["Argument Parser\n(argparse)"]:::processing
        LoadModel["Load Dlib Model"]:::processing
        InitCam["Initialize VideoCapture\n(OpenCV)"]:::processing
        InitLog["Initialize Logging\n(drowsiness_log.txt)"]:::processing
    end

    %% Frame Processing Pipeline
    subgraph "Frame Processing Pipeline"
        Preproc["Capture & Preprocess\n(resize, grayscale)"]:::processing
        Detect["Face Detection & Landmark Prediction"]:::processing
        subgraph "Detection Engines"
            EAR["Eye Aspect Ratio (EAR)"]:::processing
            MAR["Mouth Aspect Ratio (MAR)"]:::processing
            PERCLOS["PERCLOS Module"]:::processing
        end
        AlertLogic["Alert Decision Logic\n(counters & thresholds)"]:::decision
    end

    %% Output & Side Effects
    subgraph "Output & Side Effects"
        Viz["Visualization & GUI\n(OpenCV imshow, overlays)"]:::output
        Sound["Audible Alerts\n(winsound + threading)"]:::output
        Log["Event Logging\n(drowsiness_log.txt)"]:::output
        Controls["Runtime Controls\n(hotkeys)"]:::output
    end

    %% Data Flow
    CLI -->|feeds thresholds & flags| ArgParse
    Webcam --> InitCam
    Model --> LoadModel

    ArgParse --> Preproc
    InitCam --> Preproc
    LoadModel --> Detect
    InitLog --> Log

    Preproc --> Detect
    Detect --> EAR
    Detect --> MAR
    Detect --> PERCLOS
    EAR --> AlertLogic
    MAR --> AlertLogic
    PERCLOS --> AlertLogic

    AlertLogic --> Viz
    AlertLogic --> Sound
    AlertLogic --> Log
    Controls --> AlertLogic
    Controls --> Viz
    Controls --> Log

    Viz -->|feedback| User["User"]:::resource
    Sound -->|feedback| User

    %% Click Events
    click CLI "https://github.com/050903/aifacedetectionproject/blob/main/main.py"
    click Webcam "https://github.com/050903/aifacedetectionproject/blob/main/main.py"
    click Model "https://github.com/050903/aifacedetectionproject/blob/main/shape_predictor_68_face_landmarks.dat"
    click Preproc "https://github.com/050903/aifacedetectionproject/blob/main/main.py"
    click Detect "https://github.com/050903/aifacedetectionproject/blob/main/main.py"
    click EAR "https://github.com/050903/aifacedetectionproject/blob/main/main.py"
    click MAR "https://github.com/050903/aifacedetectionproject/blob/main/main.py"
    click PERCLOS "https://github.com/050903/aifacedetectionproject/blob/main/main.py"
    click AlertLogic "https://github.com/050903/aifacedetectionproject/blob/main/main.py"
    click Viz "https://github.com/050903/aifacedetectionproject/blob/main/main.py"
    click Sound "https://github.com/050903/aifacedetectionproject/blob/main/main.py"
    click Log "https://github.com/050903/aifacedetectionproject/blob/main/drowsiness_log.txt"
    click Resource "https://github.com/050903/aifacedetectionproject/blob/main/requirements.txt"
    click README "https://github.com/050903/aifacedetectionproject/blob/main/README.markdown"
    click LICENSE "https://github.com/050903/aifacedetectionproject/blob/main/LICENSE.txt"

    %% Styles
    classDef input fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef processing fill:#90EE90,stroke:#000,stroke-width:1px
    classDef decision fill:#FFD580,stroke:#000,stroke-width:1px
    classDef output fill:#FFB6C1,stroke:#000,stroke-width:1px
    classDef resource fill:#E0E0E0,stroke:#000,stroke-width:1px

    class User resource
```
