DissTraqt - Real-Time Distraction Detection System

DissTraqt is an enterprise AI-powered attention and distraction monitoring system combining Ultralytics YOLO tracking, MediaPipe 3D solvePnP Face Mesh with Perspective Compensation, and an interactive Flask Web Monitoring Console.

---

Key Features

• Multi-Person Tracking & Phone Proximity: YOLO object tracking (class 0 person, class 67 phone) with spatial heuristics and ByteTrack tracking.
• MediaPipe 3D solvePnP Face Analysis:
  • 3D Perspective Head Pose: OpenCV solvePnP with vertical/horizontal perspective offset compensation ($\text{pitch}{\text{adjusted}} = \text{pitch}{\text{raw}} - \text{offset}$) so upright subjects are not misclassified as head down.
  • Head-Crop Fallback Detection: Automatically crops, rescales, and maps small/distant faces in wide-angle classroom scenes back to global coordinate space.
  • Iris Gaze Tracking: Measures horizontal and vertical eye gaze angle displacement.
• Live Stream Preview: Integrated dashboard live video preview with connection state indicators.
• Dynamic Sensitivity Control: Live slider adjustments in the web dashboard sync seamlessly to active detectors without restarting.
• Enterprise Web Console: Modern glassmorphic interface, SVG iconography, timeline feeds, screenshot capture, and JSON report generation.

---

Directory Structure

Al_DissTraqt/
├── src/
│   └── disstraqt/
│       ├── __init__.py                 # Package version and metadata
│       ├── config.py                   # Centralized configuration dataclass & persistence
│       ├── core/                       # Computer vision pipeline
│       │   ├── __init__.py
│       │   ├── detector.py             # DistractionDetectorCore & attention state
│       │   ├── face_mesh.py            # MediaPipe 3D solvePnP & head-crop engine
│       │   └── yolo_tracker.py         # YOLO object tracking & proximity matching
│       ├── web/                        # Web dashboard backend
│       │   ├── __init__.py
│       │   ├── app.py                  # Flask application factory (create_app)
│       │   ├── routes.py               # REST API & dashboard routes
│       │   ├── state.py                # Thread-safe monitoring state & report generation
│       │   ├── static/
│       │   │   ├── css/
│       │   │   │   └── dashboard.css   # Modern glassmorphic styling (zero emojis)
│       │   │   └── js/
│       │   │       └── dashboard.js    # Telemetry polling & live stream client
│       │   └── templates/
│       │       └── dashboard.html      # Responsive HTML5 dashboard with SVG icons
│       └── utils/
│           ├── __init__.py
│           └── visualization.py        # Frame annotation & telemetry overlays
│
├── scripts/                            # Operational entrypoints
│   ├── run_dashboard.py                # Web console server launcher
│   └── run_detector.py                 # Live detection worker launcher
│
├── tests/                              # Automated test suite
│   ├── test_api.py                     # REST API unit tests
│   ├── test_config.py                  # Configuration serialization tests
│   └── test_tracker.py                 # Geometry & proximity tests
│
├── assets/                             # Video and asset files
│   └── classroom.mp4                   # Sample classroom footage
│
├── dashboard_data/                     # Runtime artifacts
│   ├── config.json                     # Dynamic settings state
│   ├── reports/                        # Exported JSON reports
│   └── screenshots/                    # Violation screenshots & live feed frames
│
├── pyproject.toml                      # Standard package build definition
└── requirements.txt                    # Project dependencies

---

Quickstart Guide

1. Environment Setup

# Create and activate virtual environment
python -m venv .venv
.\.venv\Scripts\Activate.ps1

# Install requirements
pip install -r requirements.txt
pip install -e .

2. Run Automated Tests

pytest tests

3. Launch Web Dashboard (Terminal 1)

python scripts/run_dashboard.py

(Console runs on http://localhost:5000)

4. Launch Detector Worker (Terminal 2)

python scripts/run_detector.py

---

Detection Thresholds & Live Customization

Detection parameters can be tuned dynamically via the Web UI (http://localhost:5000):

Parameter	Default	Description
Phone Threshold	1.0s	Seconds phone must remain near person to trigger violation
Gaze Away Threshold	1.0s	Seconds gaze must deviate before triggering violation
Head Down Threshold	1.2s	Seconds head must tilt down or turn before triggering violation
Gaze Angle Threshold	20.0°	Iris angular sensitivity offset in degrees
Head Pitch Threshold	22.0°	Head tilt-down pitch threshold (perspective compensated)
Head Yaw Threshold	25.0°	Head side-turn yaw threshold
YOLO Confidence	0.25	Confidence score cutoff for object detection
Grace Period	1.0s	Temporary flicker forgiveness buffer before timer reset

---

REST API Specification

• GET /api/summary: Active subjects count, connection status, violation totals, and live view path.
• GET /api/statistics: Aggregate statistics, average risk index, and highest-distraction subject.
• GET /api/violations: Chronological violation log with timestamp and duration.
• GET /api/config: Current detection sensitivity parameters.
• POST /api/config: Update sensitivity parameters dynamically.
• POST /api/update-state: Detector worker heartbeat and compressed live preview frame transmission.
• POST /api/test/add-violation: Log new violation event with optional base64 frame capture.
• POST /api/report/export: Generate and write JSON audit report to disk.
• POST /api/reset: Reset active session tracking.
• GET /health: Health status and service telemetry.