GazeMetric is a real-time engagement analytics project for webcam and recorded video sessions.

Under the hood, it uses MediaPipe face landmarks, OpenCV-based head pose estimation, gaze-direction heuristics, and calibration-aware thresholds to classify attention behavior frame by frame. The system also computes a composite engagement score, tracks signal quality/confidence, and exports full session reports.

Core capabilities:

• head direction estimation (left, right, up, down, straight)
• gaze direction estimation (forward, left, right, up, down)
• engagement labeling and smoothed score (0-100)
• quality/confidence checks with runtime warnings
• run artifacts for analysis (timeline.csv, timeline.json, summary.json, summary.pdf)

1. Detect facial landmarks on each frame.
2. Estimate head pose angles from landmark geometry.
3. Compute gaze offsets and classify gaze direction.
4. Combine gaze + head pose into engagement labels and scores.
5. Track quality signals (visibility, lighting, landmark stability).
6. Save per-frame timeline data and end-of-run summary reports.

• Python 3.10 or newer
• A webcam (for live mode) or a video file (for recorded mode)

1. Open PowerShell in the project folder.

2. Create a virtual environment:

   python -m venv .venv

3. Activate it:

   .\.venv\Scripts\Activate.ps1

4. Install dependencies:

   pip install -r requirements.txt

If your machine complains about text encoding while installing, run:

Get-Content requirements.txt -Encoding Unicode | Set-Content requirements_utf8.txt -Encoding utf8
pip install -r requirements_utf8.txt

.\.venv\Scripts\python.exe engagement_analysis_live.py

Put your video in the Video folder (or use any full path), then run:

.\.venv\Scripts\python.exe engagement_analysis_recorded.py --input "Video\your_video.mp4"

Webcam:

.\.venv\Scripts\python.exe engagement_analysis_full.py

Video:

.\.venv\Scripts\python.exe engagement_analysis_full.py --source video --input "Video\your_video.mp4"

Skip calibration:

.\.venv\Scripts\python.exe engagement_analysis_full.py --skip-calibration

Save annotated output video:

.\.venv\Scripts\python.exe engagement_analysis_full.py --source video --input "Video\your_video.mp4" --output-video "runs\annotated.mp4"

Choose report base folder:

.\.venv\Scripts\python.exe engagement_analysis_full.py --source video --input "Video\your_video.mp4" --timeline-dir "runs\my_runs"

After each run, the project saves:

• timeline.csv
• timeline.json
• summary.json
• summary.pdf

Each run now gets its own session folder, so old results are kept.

Example:

• runs/my_runs/session_20260414_101500/
• runs/my_runs/session_20260414_102030/

• engagement_analysis_live.py: easiest way to run webcam mode
• engagement_analysis_recorded.py: easiest way to run a saved video
• engagement_analysis_full.py: main script with all options

• Press Q in the video window to stop and save reports.

• You can place multiple videos in Video and choose one with the --input path.
• File names can be anything.

This project uses the MIT License. See LICENSE for details.