🚗 Real Time Driver Drowsiness and Distraction Detection System

---

🚀 Installation

🔧 1. Installing Required Packages

# Clone the repository
git clone https://github.com/username/driver-drowsiness.git
cd driver-drowsiness

# Create a virtual environment (recommended)
python -m venv venv

# Activate the virtual environment
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

# Install required packages
pip install -r requirements.txt

🤖 2. Downloading the ETH-XGaze Model

The ETH-XGaze model is not included in the repository due to its large size. Follow these steps:

Option A: Official Model (Recommended)

1. Visit the ETH-XGaze official page
2. Download the model file (epoch_24_ckpt.pth.tar)
3. Place it in the models/ directory:

   mkdir -p models
   # Copy the downloaded file to the models directory
   cp /download/path/epoch_24_ckpt.pth.tar models/eth_xgaze_model.pth

Option B: ONNX Format (Fast Inference)

# Run the model conversion script
python scripts/convert_ethxgaze_model.py models/eth_xgaze_model.pth models/eth_xgaze_model.onnx --export_onnx

---

💻 Usage

🎮 1. Basic Usage

# Start the main application
python run.py

Usage Steps:

1. 🎥 Make sure your camera is connected
2. ▶️ Click the "Start" button
3. 👤 Keep your face in the camera's field of view
4. 📊 Monitor real-time metrics
5. ⏹️ End the analysis with "Stop"

📹 2. Video Analysis

# Video file analysis
python examples/analyze_video.py --input video.mp4 --output results/

# Batch video analysis
python scripts/batch_analyze.py --input_dir videos/ --output_dir results/

🎯 3. Gaze Zone Detection

# Gaze zone test
python tests/test_gaze_zone_detector.py --camera 0 --show_zones

# Gaze zone calibration
python scripts/calibrate_gaze_zones.py

Classification Performance Metrics

• Overall Accuracy: 93.23%
• Balanced Accuracy: 83.70%
• Macro-averaged Precision: 91.96%
• Macro-averaged Recall: 83.70%
• Macro-averaged F1-Score: 85.84%

Statistical Reliability Measures

• Cohen's Kappa: 0.9110 (Almost Perfect)
• Matthews Correlation Coefficient: 0.8549
• Krippendorff's Alpha: 0.9110

---

📊 Scientific Metrics

👁️ EAR (Eye Aspect Ratio)

• Formula: EAR = (|p2-p6| + |p3-p5|) / (2 * |p1-p4|)
• Threshold Value: 0.21 (eyes considered closed below this)
• Usage: Instant eye blink and closure detection

👄 MAR (Mouth Aspect Ratio)

• Formula: MAR = |p14-p18| / |p12-p16|
• Threshold Value: 0.65 (mouth considered open above this)
• Usage: Yawning detection

💤 PERCLOS

• Definition: Percentage of eye closure over a 60-second period
• Warning Threshold: 15%
• Critical Threshold: 20%

😴 KSS (Karolinska Sleepiness Scale)

Score	Status	Description
1-3	🟢 Normal	Fully awake state
4-5	🟡 Mild	Mild signs of fatigue
6-7	🟠 Warning	Beginning of attention deficit
8-9	🔴 Critical	Immediate intervention required

---

🔬 Advanced Features

🎭 3D Head Pose Visualization

• Real-time 3D Model: Real-time head pose visualization
• Pitch/Yaw/Roll: Three-axis rotation tracking
• Interactive Controls: User-controlled view settings

# 3D model usage example
from src.ui.head_pose_model import Head3DPanel

head_panel = Head3DPanel()
head_panel.update_pose(pitch=10, yaw=-5, roll=2)

📍 Gaze Zone Detection

EU regulation C(2023)4523 compliant 9 zones:

Zone ID	Zone Name	Area	Criticality
0	Road Center	Area 2	🔴 Critical
1	Driving Instruments	Area 2	🟡 Driving Related
2	Infotainment	Area 1	🟠 Non-Driving
3	Left Side	Area 2	🟡 Driving Related
4	Right Side	Area 2	🟡 Driving Related
5	Rear Mirror	Area 2	🔴 Critical

🧪 Testing and Evaluation

🔬 Scientific Evaluation

# Precision/Recall analysis
python scripts/scientific_evaluation.py \
  --ground_truth data/gt.json \
  --predictions data/pred.json \
  --output_dir evaluation_results/

Most Frequent Confusion Pairs:

• Zones 4↔5: 36 errors (2.32%)
• Zones 1↔2: 21 errors (1.35%)
• Zones 2↔4: 14 errors (0.90%)

Critical Zone Performance:

• Critical Zone Accuracy: 85.82%
• Safety Impact Score: 14.18%

CONCLUSIONS AND RECOMMENDATIONS

• Excellent classification performance achieved (>90% accuracy)
• Almost perfect inter-rater agreement demonstrated

---

🔬 Scientific References

• ETH-XGaze: Gaze estimation model (Paper)
• MediaPipe: Face mesh detection (Documentation)

---