models/README.md

models/

Feature extraction modules and model training scripts.

1. Feature Extraction

Root-level modules form the real-time inference pipeline:

Module	Input	Output
face_mesh.py	BGR frame	478 MediaPipe landmarks
head_pose.py	Landmarks, frame size	yaw, pitch, roll, face/eye score, gaze offset, head deviation
eye_scorer.py	Landmarks	EAR (left/right/avg), gaze ratio (h/v), MAR
eye_crop.py	Landmarks, frame	Cropped eye region images
eye_classifier.py	Eye crops or landmarks	Eye open/closed prediction (geometric fallback)
collect_features.py	BGR frame	17-d feature vector + temporal features (PERCLOS, blink rate, etc.)

2. Training Scripts

Folder	Model	Command
mlp/	PyTorch MLP (64→32, 2-class)	python -m models.mlp.train
xgboost/	XGBoost (600 trees, depth 8)	python -m models.xgboost.train

mlp/

• train.py — training loop with early stopping, ClearML opt-in
• sweep.py — hyperparameter search (Optuna: lr, batch_size)
• eval_accuracy.py — load checkpoint and print test metrics
• Saves to checkpoints/mlp_best.pt

xgboost/

• train.py — training with eval-set logging
• sweep.py / sweep_local.py — hyperparameter search (Optuna + ClearML)
• eval_accuracy.py — load checkpoint and print test metrics
• Saves to checkpoints/xgboost_face_orientation_best.json

3. Data Loading

All training scripts import from data_preparation.prepare_dataset:

from data_preparation.prepare_dataset import get_numpy_splits   # XGBoost
from data_preparation.prepare_dataset import get_dataloaders     # MLP (PyTorch)

4. Results

Model	Test Accuracy	F1	ROC-AUC
XGBoost	95.87%	0.959	0.991
MLP	92.92%	0.929	0.971