remove old duplicate folders

data_preparation/explore_collected_data.ipynb

@@ -1,414 +0,0 @@
-{
-  "cells": [
-    {
-      "cell_type": "markdown",
-      "metadata": {},
-      "source": [
-        "# FocusGuard — Collected Data Explorer\n",
-        "Load `.npz` files from `collect_features.py` and inspect the data before training."
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "metadata": {},
-      "outputs": [
-        {
-          "ename": "FileNotFoundError",
-          "evalue": "No .npz files in /content/collected — run collect_features.py first",
-          "output_type": "error",
-          "traceback": [
-            "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
-            "\u001b[0;31mFileNotFoundError\u001b[0m                         Traceback (most recent call last)",
-            "\u001b[0;32m/tmp/ipython-input-251140757.py\u001b[0m in \u001b[0;36m<cell line: 0>\u001b[0;34m()\u001b[0m\n\u001b[1;32m      9\u001b[0m \u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m     10\u001b[0m \u001b[0;32mif\u001b[0m \u001b[0;32mnot\u001b[0m \u001b[0mnpz_files\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m---> 11\u001b[0;31m     \u001b[0;32mraise\u001b[0m \u001b[0mFileNotFoundError\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34mf\"No .npz files in {COLLECTED_DIR} — run collect_features.py first\"\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m\u001b[1;32m     12\u001b[0m \u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m     13\u001b[0m \u001b[0mNPZ_PATH\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0mnpz_files\u001b[0m\u001b[0;34m[\u001b[0m\u001b[0;34m-\u001b[0m\u001b[0;36m1\u001b[0m\u001b[0;34m]\u001b[0m  \u001b[0;31m# latest file\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n",
-            "\u001b[0;31mFileNotFoundError\u001b[0m: No .npz files in /content/collected — run collect_features.py first"
-          ]
-        }
-      ],
-      "source": [
-        "import numpy as np\n",
-        "import matplotlib.pyplot as plt\n",
-        "import os\n",
-        "import glob\n",
-        "\n",
-        "# auto-find the latest .npz in collected/, or set manually\n",
-        "COLLECTED_DIR = os.path.join(os.path.dirname(os.path.abspath(\"__file__\")), \"collected\")\n",
-        "npz_files = sorted(glob.glob(os.path.join(COLLECTED_DIR, \"*.npz\")))\n",
-        "\n",
-        "if not npz_files:\n",
-        "    raise FileNotFoundError(f\"No .npz files in {COLLECTED_DIR} — run collect_features.py first\")\n",
-        "\n",
-        "NPZ_PATH = npz_files[-1]  # latest file\n",
-        "print(f\"Using: {NPZ_PATH}\")\n",
-        "\n",
-        "data = np.load(NPZ_PATH, allow_pickle=True)\n",
-        "features = data['features']\n",
-        "labels = data['labels']\n",
-        "names = list(data['feature_names'])\n",
-        "\n",
-        "print(f\"Loaded: {NPZ_PATH}\")\n",
-        "print(f\"Samples: {len(labels)}\")\n",
-        "print(f\"Features: {features.shape[1]} -> {names}\")\n",
-        "print(f\"Labels: 0={int((labels==0).sum())}, 1={int((labels==1).sum())}\")"
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "metadata": {},
-      "source": [
-        "## 1. Basic Stats"
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "import pandas as pd\n",
-        "\n",
-        "df = pd.DataFrame(features, columns=names)\n",
-        "df['label'] = labels\n",
-        "\n",
-        "print(\"=\" * 60)\n",
-        "print(\"FEATURE STATISTICS\")\n",
-        "print(\"=\" * 60)\n",
-        "df.describe().round(4)"
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "# NaN check\n",
-        "nan_counts = df.isna().sum()\n",
-        "if nan_counts.sum() == 0:\n",
-        "    print(\"No NaN values found\")\n",
-        "else:\n",
-        "    print(\"NaN counts:\")\n",
-        "    print(nan_counts[nan_counts > 0])"
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "metadata": {},
-      "source": [
-        "## 2. Label Distribution"
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "n0 = int((labels == 0).sum())\n",
-        "n1 = int((labels == 1).sum())\n",
-        "total = len(labels)\n",
-        "\n",
-        "fig, axes = plt.subplots(1, 2, figsize=(10, 4))\n",
-        "\n",
-        "# bar chart\n",
-        "axes[0].bar(['Unfocused (0)', 'Focused (1)'], [n0, n1], color=['#EF476F', '#06D6A0'])\n",
-        "axes[0].set_ylabel('Samples')\n",
-        "axes[0].set_title('Label Distribution')\n",
-        "for i, v in enumerate([n0, n1]):\n",
-        "    axes[0].text(i, v + total*0.01, f'{v} ({v/total*100:.1f}%)', ha='center', fontsize=10)\n",
-        "\n",
-        "# label over time\n",
-        "axes[1].plot(labels, color='#00B4D8', linewidth=0.5)\n",
-        "axes[1].fill_between(range(len(labels)), labels, alpha=0.3, color='#06D6A0')\n",
-        "axes[1].set_xlabel('Frame')\n",
-        "axes[1].set_ylabel('Label')\n",
-        "axes[1].set_title('Label Over Time')\n",
-        "axes[1].set_yticks([0, 1])\n",
-        "axes[1].set_yticklabels(['Unfocused', 'Focused'])\n",
-        "\n",
-        "plt.tight_layout()\n",
-        "plt.show()\n",
-        "\n",
-        "# transitions\n",
-        "transitions = int(np.sum(np.diff(labels) != 0))\n",
-        "print(f\"Transitions: {transitions}\")\n",
-        "print(f\"Avg segment: {total/max(transitions,1):.0f} frames ({total/max(transitions,1)/30:.1f}s)\")\n",
-        "if transitions < 10:\n",
-        "    print(\"⚠️  Too few transitions — switch every 10-30s when re-recording\")"
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "metadata": {},
-      "source": [
-        "## 3. Feature Distributions (Focused vs Unfocused)"
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "n_features = features.shape[1]\n",
-        "cols = 3\n",
-        "rows = (n_features + cols - 1) // cols\n",
-        "\n",
-        "fig, axes = plt.subplots(rows, cols, figsize=(14, rows * 2.5))\n",
-        "axes = axes.flatten()\n",
-        "\n",
-        "for i in range(n_features):\n",
-        "    ax = axes[i]\n",
-        "    f0 = features[labels == 0, i]\n",
-        "    f1 = features[labels == 1, i]\n",
-        "    ax.hist(f0, bins=40, alpha=0.6, color='#EF476F', label='Unfocused', density=True)\n",
-        "    ax.hist(f1, bins=40, alpha=0.6, color='#06D6A0', label='Focused', density=True)\n",
-        "    ax.set_title(names[i], fontsize=10, fontweight='bold')\n",
-        "    ax.tick_params(labelsize=8)\n",
-        "    if i == 0:\n",
-        "        ax.legend(fontsize=8)\n",
-        "\n",
-        "# hide empty axes\n",
-        "for i in range(n_features, len(axes)):\n",
-        "    axes[i].set_visible(False)\n",
-        "\n",
-        "plt.suptitle('Feature Distributions by Label', fontsize=14, fontweight='bold', y=1.01)\n",
-        "plt.tight_layout()\n",
-        "plt.show()"
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "metadata": {},
-      "source": [
-        "## 4. Feature-Label Correlations"
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "correlations = [np.corrcoef(features[:, i], labels)[0, 1] for i in range(n_features)]\n",
-        "sort_idx = np.argsort(np.abs(correlations))[::-1]\n",
-        "\n",
-        "fig, ax = plt.subplots(figsize=(10, 5))\n",
-        "colors = ['#06D6A0' if c > 0 else '#EF476F' for c in [correlations[i] for i in sort_idx]]\n",
-        "bars = ax.barh([names[i] for i in sort_idx],\n",
-        "               [correlations[i] for i in sort_idx],\n",
-        "               color=colors)\n",
-        "ax.set_xlabel('Correlation with Label (focused=1)')\n",
-        "ax.set_title('Feature-Label Correlations (sorted by |r|)')\n",
-        "ax.axvline(0, color='gray', linewidth=0.5)\n",
-        "\n",
-        "for bar, idx in zip(bars, sort_idx):\n",
-        "    r = correlations[idx]\n",
-        "    ax.text(r + (0.01 if r >= 0 else -0.01), bar.get_y() + bar.get_height()/2,\n",
-        "            f'{r:.3f}', va='center', ha='left' if r >= 0 else 'right', fontsize=9)\n",
-        "\n",
-        "plt.tight_layout()\n",
-        "plt.show()\n",
-        "\n",
-        "print(\"\\nTop predictive features:\")\n",
-        "for i in sort_idx[:5]:\n",
-        "    print(f\"  {names[i]:<20} r = {correlations[i]:+.4f}\")"
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "metadata": {},
-      "source": [
-        "## 5. Feature Correlation Matrix"
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "corr_matrix = np.corrcoef(features.T)\n",
-        "\n",
-        "fig, ax = plt.subplots(figsize=(10, 8))\n",
-        "im = ax.imshow(corr_matrix, cmap='RdBu_r', vmin=-1, vmax=1)\n",
-        "ax.set_xticks(range(n_features))\n",
-        "ax.set_yticks(range(n_features))\n",
-        "ax.set_xticklabels(names, rotation=45, ha='right', fontsize=9)\n",
-        "ax.set_yticklabels(names, fontsize=9)\n",
-        "ax.set_title('Feature Correlation Matrix')\n",
-        "plt.colorbar(im, ax=ax, shrink=0.8)\n",
-        "\n",
-        "# annotate\n",
-        "for i in range(n_features):\n",
-        "    for j in range(n_features):\n",
-        "        val = corr_matrix[i, j]\n",
-        "        if abs(val) > 0.5 and i != j:\n",
-        "            ax.text(j, i, f'{val:.2f}', ha='center', va='center', fontsize=7,\n",
-        "                    color='white' if abs(val) > 0.7 else 'black')\n",
-        "\n",
-        "plt.tight_layout()\n",
-        "plt.show()"
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "metadata": {},
-      "source": [
-        "## 6. Features Over Time"
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "# Plot key features over time with label shading\n",
-        "key_features = ['s_face', 's_eye', 'ear_avg', 'yaw', 'pitch']\n",
-        "# filter to only features that exist in this file\n",
-        "key_features = [f for f in key_features if f in names]\n",
-        "\n",
-        "fig, axes = plt.subplots(len(key_features) + 1, 1, figsize=(14, (len(key_features)+1) * 1.8),\n",
-        "                         sharex=True)\n",
-        "\n",
-        "# label timeline\n",
-        "axes[0].fill_between(range(len(labels)), labels, alpha=0.4, color='#06D6A0', step='mid')\n",
-        "axes[0].set_ylabel('Label')\n",
-        "axes[0].set_yticks([0, 1])\n",
-        "axes[0].set_yticklabels(['Unfocused', 'Focused'], fontsize=9)\n",
-        "axes[0].set_title('Label + Key Features Over Time', fontsize=12, fontweight='bold')\n",
-        "\n",
-        "for i, feat in enumerate(key_features):\n",
-        "    idx = names.index(feat)\n",
-        "    ax = axes[i + 1]\n",
-        "    ax.plot(features[:, idx], linewidth=0.8, color='#00B4D8')\n",
-        "    # shade focused regions\n",
-        "    ax.fill_between(range(len(labels)), ax.get_ylim()[0], ax.get_ylim()[1],\n",
-        "                    where=labels == 1, alpha=0.1, color='green')\n",
-        "    ax.set_ylabel(feat, fontsize=9)\n",
-        "\n",
-        "axes[-1].set_xlabel('Frame')\n",
-        "plt.tight_layout()\n",
-        "plt.show()"
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "metadata": {},
-      "source": [
-        "## 7. Quality Summary"
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "duration_sec = len(labels) / 30.0\n",
-        "balance = n1 / max(total, 1)\n",
-        "\n",
-        "checks = {\n",
-        "    'Duration >= 2 min': duration_sec >= 120,\n",
-        "    'Samples >= 3000': total >= 3000,\n",
-        "    'Balance 30-70%': 0.3 <= balance <= 0.7,\n",
-        "    'Transitions >= 10': transitions >= 10,\n",
-        "    'No NaN values': int(np.isnan(features).sum()) == 0,\n",
-        "    'No constant features': all(features[:, i].std() > 0.001 for i in range(n_features)),\n",
-        "}\n",
-        "\n",
-        "print(\"DATA QUALITY CHECKLIST\")\n",
-        "print(\"=\" * 40)\n",
-        "for check, passed in checks.items():\n",
-        "    icon = '✅' if passed else '❌'\n",
-        "    print(f\"  {icon}  {check}\")\n",
-        "\n",
-        "passed = sum(checks.values())\n",
-        "print(f\"\\n  {passed}/{len(checks)} checks passed\")\n",
-        "if passed == len(checks):\n",
-        "    print(\"  Ready for training!\")\n",
-        "else:\n",
-        "    print(\"  Re-record or collect more data.\")"
-      ]
-    },
-    {
-      "cell_type": "markdown",
-      "metadata": {},
-      "source": [
-        "## 8. Merge Multiple Sessions (Optional)\n",
-        "Run this if you have multiple `.npz` files from different team members."
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "metadata": {},
-      "outputs": [],
-      "source": [
-        "COLLECTED_DIR = \"data_preparation/collected/\"\n",
-        "\n",
-        "all_features = []\n",
-        "all_labels = []\n",
-        "all_participants = []  # for participant-aware splitting\n",
-        "\n",
-        "npz_files = sorted([f for f in os.listdir(COLLECTED_DIR) if f.endswith('.npz')])\n",
-        "print(f\"Found {len(npz_files)} .npz files:\\n\")\n",
-        "\n",
-        "for i, fname in enumerate(npz_files):\n",
-        "    d = np.load(os.path.join(COLLECTED_DIR, fname), allow_pickle=True)\n",
-        "    f, l = d['features'], d['labels']\n",
-        "    n = len(l)\n",
-        "    n1 = int((l == 1).sum())\n",
-        "    trans = int(np.sum(np.diff(l) != 0))\n",
-        "    print(f\"  [{i}] {fname}\")\n",
-        "    print(f\"      {n} samples, {n1/n*100:.0f}% focused, {trans} transitions, {n/30:.0f}s\")\n",
-        "    \n",
-        "    all_features.append(f)\n",
-        "    all_labels.append(l)\n",
-        "    all_participants.append(np.full(n, i, dtype=np.int32))\n",
-        "\n",
-        "if len(all_features) > 0:\n",
-        "    merged_features = np.concatenate(all_features)\n",
-        "    merged_labels = np.concatenate(all_labels)\n",
-        "    merged_participants = np.concatenate(all_participants)\n",
-        "    \n",
-        "    print(f\"\\nMerged: {len(merged_labels)} total samples\")\n",
-        "    print(f\"  Focused: {int((merged_labels==1).sum())} ({(merged_labels==1).mean()*100:.1f}%)\")\n",
-        "    print(f\"  Unfocused: {int((merged_labels==0).sum())} ({(merged_labels==0).mean()*100:.1f}%)\")\n",
-        "    \n",
-        "    # Save merged\n",
-        "    out_path = os.path.join(COLLECTED_DIR, \"merged_all.npz\")\n",
-        "    np.savez(out_path,\n",
-        "             features=merged_features,\n",
-        "             labels=merged_labels,\n",
-        "             participants=merged_participants,\n",
-        "             feature_names=d['feature_names'])\n",
-        "    print(f\"  Saved -> {out_path}\")\n",
-        "else:\n",
-        "    print(\"No .npz files found\")"
-      ]
-    }
-  ],
-  "metadata": {
-    "kernelspec": {
-      "display_name": "venv",
-      "language": "python",
-      "name": "python3"
-    },
-    "language_info": {
-      "codemirror_mode": {
-        "name": "ipython",
-        "version": 3
-      },
-      "file_extension": ".py",
-      "mimetype": "text/x-python",
-      "name": "python",
-      "nbconvert_exporter": "python",
-      "pygments_lexer": "ipython3",
-      "version": "3.13.7"
-    }
-  },
-  "nbformat": 4,
-  "nbformat_minor": 4
-}

evaluation/evaluate.py

@@ -1 +0,0 @@
-# stub

evaluation/metrics.py

@@ -1 +0,0 @@
-# stub

models/attention_model/attention_classifier.py

@@ -1 +0,0 @@
-# stub

models/attention_model/collect_features.py

@@ -1,403 +0,0 @@
-# Collect labeled face mesh features from webcam for training
-#
-# Run the demo, press 1 = focused, 0 = not focused, p = pause, q = save & quit.
-# Each labeled frame saves 17 features (geometric + temporal) + label.
-# Expect 5-10 min per person. Switch focus/unfocus every 10-30 seconds.
-#
-# Usage:
-#   python models/attention_model/collect_features.py
-#   python models/attention_model/collect_features.py --name alice --duration 600
-
-import argparse
-import collections
-import math
-import os
-import sys
-import time
-
-import cv2
-import numpy as np
-
-_PROJECT_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
-if _PROJECT_ROOT not in sys.path:
-    sys.path.insert(0, _PROJECT_ROOT)
-
-from models.face_mesh.face_mesh import FaceMeshDetector
-from models.face_orientation.head_pose import HeadPoseEstimator
-from models.eye_behaviour.eye_scorer import EyeBehaviourScorer, compute_gaze_ratio, compute_mar
-
-FONT = cv2.FONT_HERSHEY_SIMPLEX
-GREEN = (0, 255, 0)
-RED = (0, 0, 255)
-WHITE = (255, 255, 255)
-YELLOW = (0, 255, 255)
-ORANGE = (0, 165, 255)
-GRAY = (120, 120, 120)
-
-# ---------------------------------------------------------------------------
-# 17 features: geometric (11) + derived (2) + temporal (4)
-# ---------------------------------------------------------------------------
-FEATURE_NAMES = [
-    # --- geometric (from landmarks each frame) ---
-    "ear_left",          # 0  Left Eye Aspect Ratio
-    "ear_right",         # 1  Right Eye Aspect Ratio
-    "ear_avg",           # 2  Mean EAR
-    "h_gaze",            # 3  Horizontal iris position
-    "v_gaze",            # 4  Vertical iris position
-    "mar",               # 5  Mouth Aspect Ratio
-    "yaw",               # 6  Head horizontal rotation (degrees)
-    "pitch",             # 7  Head vertical tilt (degrees)
-    "roll",              # 8  Head lateral tilt (degrees)
-    "s_face",            # 9  Cosine-decay head pose score [0,1]
-    "s_eye",             # 10 Geometric eye score [0,1]
-    # --- derived ---
-    "gaze_offset",       # 11 Distance from gaze centre: sqrt((h-0.5)^2 + (v-0.5)^2)
-    "head_deviation",    # 12 sqrt(yaw^2 + pitch^2)
-    # --- temporal (rolling window) ---
-    "perclos",           # 13 % eye closure over last 60 frames
-    "blink_rate",        # 14 Blinks per minute (30s window)
-    "closure_duration",  # 15 Current sustained eye closure (seconds)
-    "yawn_duration",     # 16 Current sustained yawn (seconds)
-]
-
-NUM_FEATURES = len(FEATURE_NAMES)
-assert NUM_FEATURES == 17
-
-
-# ---------------------------------------------------------------------------
-# Temporal tracker — keeps rolling history for PERCLOS, blink rate, etc.
-# ---------------------------------------------------------------------------
-class TemporalTracker:
-    """Track temporal signals across frames."""
-
-    EAR_BLINK_THRESH = 0.21       # EAR below this = eyes closed
-    MAR_YAWN_THRESH = 0.04        # MAR above this = yawning
-    PERCLOS_WINDOW = 60           # frames for PERCLOS
-    BLINK_WINDOW_SEC = 30.0       # seconds for blink rate
-
-    def __init__(self):
-        self.ear_history = collections.deque(maxlen=self.PERCLOS_WINDOW)
-        self.blink_timestamps = collections.deque()  # list of blink end times
-        self._eyes_closed = False
-        self._closure_start = None     # time when eyes first closed
-        self._yawn_start = None        # time when yawn started
-
-    def update(self, ear_avg, mar, now=None):
-        """Call once per frame. Returns (perclos, blink_rate, closure_dur, yawn_dur)."""
-        if now is None:
-            now = time.time()
-
-        # --- PERCLOS ---
-        closed = ear_avg < self.EAR_BLINK_THRESH
-        self.ear_history.append(1.0 if closed else 0.0)
-        perclos = sum(self.ear_history) / len(self.ear_history) if self.ear_history else 0.0
-
-        # --- Blink detection (closed -> open transition) ---
-        if self._eyes_closed and not closed:
-            # blink just ended
-            self.blink_timestamps.append(now)
-        self._eyes_closed = closed
-
-        # prune old blinks
-        cutoff = now - self.BLINK_WINDOW_SEC
-        while self.blink_timestamps and self.blink_timestamps[0] < cutoff:
-            self.blink_timestamps.popleft()
-        blink_rate = len(self.blink_timestamps) * (60.0 / self.BLINK_WINDOW_SEC)
-
-        # --- Closure duration ---
-        if closed:
-            if self._closure_start is None:
-                self._closure_start = now
-            closure_dur = now - self._closure_start
-        else:
-            self._closure_start = None
-            closure_dur = 0.0
-
-        # --- Yawn duration ---
-        yawning = mar > self.MAR_YAWN_THRESH
-        if yawning:
-            if self._yawn_start is None:
-                self._yawn_start = now
-            yawn_dur = now - self._yawn_start
-        else:
-            self._yawn_start = None
-            yawn_dur = 0.0
-
-        return perclos, blink_rate, closure_dur, yawn_dur
-
-
-# ---------------------------------------------------------------------------
-# Feature extraction (one frame -> 17-dim vector)
-# ---------------------------------------------------------------------------
-def extract_features(landmarks, w, h, head_pose, eye_scorer, temporal):
-    """Extract 17 features from one frame's landmarks."""
-    from models.eye_behaviour.eye_scorer import _LEFT_EYE_EAR, _RIGHT_EYE_EAR, compute_ear
-
-    # --- geometric ---
-    ear_left = compute_ear(landmarks, _LEFT_EYE_EAR)
-    ear_right = compute_ear(landmarks, _RIGHT_EYE_EAR)
-    ear_avg = (ear_left + ear_right) / 2.0
-    h_gaze, v_gaze = compute_gaze_ratio(landmarks)
-    mar = compute_mar(landmarks)
-
-    angles = head_pose.estimate(landmarks, w, h)
-    yaw = angles[0] if angles else 0.0
-    pitch = angles[1] if angles else 0.0
-    roll = angles[2] if angles else 0.0
-
-    s_face = head_pose.score(landmarks, w, h)
-    s_eye = eye_scorer.score(landmarks)
-
-    # --- derived ---
-    gaze_offset = math.sqrt((h_gaze - 0.5) ** 2 + (v_gaze - 0.5) ** 2)
-    head_deviation = math.sqrt(yaw ** 2 + pitch ** 2)
-
-    # --- temporal ---
-    perclos, blink_rate, closure_dur, yawn_dur = temporal.update(ear_avg, mar)
-
-    return np.array([
-        ear_left, ear_right, ear_avg,
-        h_gaze, v_gaze,
-        mar,
-        yaw, pitch, roll,
-        s_face, s_eye,
-        gaze_offset,
-        head_deviation,
-        perclos, blink_rate, closure_dur, yawn_dur,
-    ], dtype=np.float32)
-
-
-# ---------------------------------------------------------------------------
-# Quality checks — run at save time
-# ---------------------------------------------------------------------------
-def quality_report(labels):
-    """Print warnings about data quality issues."""
-    n = len(labels)
-    n1 = int((labels == 1).sum())
-    n0 = n - n1
-    transitions = int(np.sum(np.diff(labels) != 0))
-    duration_sec = n / 30.0  # approximate at 30fps
-
-    warnings = []
-
-    print(f"\n{'='*50}")
-    print(f"  DATA QUALITY REPORT")
-    print(f"{'='*50}")
-    print(f"  Total samples : {n}")
-    print(f"  Focused       : {n1} ({n1/max(n,1)*100:.1f}%)")
-    print(f"  Unfocused     : {n0} ({n0/max(n,1)*100:.1f}%)")
-    print(f"  Duration      : {duration_sec:.0f}s ({duration_sec/60:.1f} min)")
-    print(f"  Transitions   : {transitions}")
-    if transitions > 0:
-        print(f"  Avg segment   : {n/transitions:.0f} frames ({n/transitions/30:.1f}s)")
-
-    # checks
-    if duration_sec < 120:
-        warnings.append(f"TOO SHORT: {duration_sec:.0f}s — aim for 5-10 minutes (300-600s)")
-
-    if n < 3000:
-        warnings.append(f"LOW SAMPLE COUNT: {n} frames — aim for 9000+ (5 min at 30fps)")
-
-    balance = n1 / max(n, 1)
-    if balance < 0.3 or balance > 0.7:
-        warnings.append(f"IMBALANCED: {balance:.0%} focused — aim for 35-65% focused")
-
-    if transitions < 10:
-        warnings.append(f"TOO FEW TRANSITIONS: {transitions} — switch every 10-30s, aim for 20+")
-
-    if transitions == 1:
-        warnings.append("SINGLE BLOCK: you recorded one unfocused + one focused block — "
-                         "model will learn temporal position, not focus patterns")
-
-    if warnings:
-        print(f"\n  ⚠️  WARNINGS ({len(warnings)}):")
-        for w in warnings:
-            print(f"    • {w}")
-        print(f"\n  Consider re-recording this session.")
-    else:
-        print(f"\n  ✅ All checks passed!")
-
-    print(f"{'='*50}\n")
-    return len(warnings) == 0
-
-
-# ---------------------------------------------------------------------------
-# Main
-# ---------------------------------------------------------------------------
-def main():
-    parser = argparse.ArgumentParser(description="Collect labeled attention data from webcam")
-    parser.add_argument("--name", type=str, default="session",
-                        help="Your name or session ID")
-    parser.add_argument("--camera", type=int, default=0,
-                        help="Camera index")
-    parser.add_argument("--duration", type=int, default=600,
-                        help="Max recording time (seconds, default 10 min)")
-    parser.add_argument("--output-dir", type=str,
-                        default=os.path.join(_PROJECT_ROOT, "data_preparation", "collected"),
-                        help="Where to save .npz files")
-    args = parser.parse_args()
-
-    os.makedirs(args.output_dir, exist_ok=True)
-
-    detector = FaceMeshDetector()
-    head_pose = HeadPoseEstimator()
-    eye_scorer = EyeBehaviourScorer()
-    temporal = TemporalTracker()
-
-    cap = cv2.VideoCapture(args.camera)
-    if not cap.isOpened():
-        print("[COLLECT] ERROR: can't open camera")
-        return
-
-    print("[COLLECT] Data Collection Tool")
-    print(f"[COLLECT] Session: {args.name}, max {args.duration}s")
-    print(f"[COLLECT] Features per frame: {NUM_FEATURES}")
-    print("[COLLECT] Controls:")
-    print("  1 = FOCUSED       (looking at screen normally)")
-    print("  0 = NOT FOCUSED   (phone, away, eyes closed, yawning)")
-    print("  p = pause")
-    print("  q = save & quit")
-    print()
-    print("[COLLECT] TIPS for good data:")
-    print("  • Switch between 1 and 0 every 10-30 seconds")
-    print("  • Aim for 20+ transitions total")
-    print("  • Act out varied scenarios: reading, phone, talking, drowsy")
-    print("  • Record at least 5 minutes")
-    print()
-
-    features_list = []
-    labels_list = []
-    label = None        # None = paused
-    transitions = 0     # count label switches
-    prev_label = None
-    status = "PAUSED -- press 1 (focused) or 0 (not focused)"
-    t_start = time.time()
-    prev_time = time.time()
-    fps = 0.0
-
-    try:
-        while True:
-            elapsed = time.time() - t_start
-            if elapsed > args.duration:
-                print(f"[COLLECT] Time limit ({args.duration}s)")
-                break
-
-            ret, frame = cap.read()
-            if not ret:
-                break
-
-            h, w = frame.shape[:2]
-            landmarks = detector.process(frame)
-            face_ok = landmarks is not None
-
-            # record if labeling + face visible
-            if face_ok and label is not None:
-                vec = extract_features(landmarks, w, h, head_pose, eye_scorer, temporal)
-                features_list.append(vec)
-                labels_list.append(label)
-
-                # count transitions
-                if prev_label is not None and label != prev_label:
-                    transitions += 1
-                prev_label = label
-
-            now = time.time()
-            fps = 0.9 * fps + 0.1 * (1.0 / max(now - prev_time, 1e-6))
-            prev_time = now
-
-            # --- draw UI ---
-            n = len(labels_list)
-            n1 = sum(1 for x in labels_list if x == 1)
-            n0 = n - n1
-            remaining = max(0, args.duration - elapsed)
-
-            # top bar
-            bar_color = GREEN if label == 1 else (RED if label == 0 else (80, 80, 80))
-            cv2.rectangle(frame, (0, 0), (w, 70), (0, 0, 0), -1)
-            cv2.putText(frame, status, (10, 22), FONT, 0.55, bar_color, 2, cv2.LINE_AA)
-            cv2.putText(frame, f"Samples: {n}  (F:{n1}  U:{n0})  Switches: {transitions}",
-                        (10, 48), FONT, 0.42, WHITE, 1, cv2.LINE_AA)
-            cv2.putText(frame, f"FPS:{fps:.0f}", (w - 80, 22), FONT, 0.45, WHITE, 1, cv2.LINE_AA)
-            cv2.putText(frame, f"{int(remaining)}s left", (w - 80, 48), FONT, 0.42, YELLOW, 1, cv2.LINE_AA)
-
-            # balance bar
-            if n > 0:
-                bar_w = min(w - 20, 300)
-                bar_x = w - bar_w - 10
-                bar_y = 58
-                frac = n1 / n
-                cv2.rectangle(frame, (bar_x, bar_y), (bar_x + bar_w, bar_y + 8), (40, 40, 40), -1)
-                cv2.rectangle(frame, (bar_x, bar_y), (bar_x + int(bar_w * frac), bar_y + 8), GREEN, -1)
-                cv2.putText(frame, f"{frac:.0%}F", (bar_x + bar_w + 4, bar_y + 8),
-                            FONT, 0.3, GRAY, 1, cv2.LINE_AA)
-
-            if not face_ok:
-                cv2.putText(frame, "NO FACE", (w // 2 - 60, h // 2), FONT, 0.7, RED, 2, cv2.LINE_AA)
-
-            # red dot = recording
-            if label is not None and face_ok:
-                cv2.circle(frame, (w - 20, 80), 8, RED, -1)
-
-            # live warnings
-            warn_y = h - 35
-            if n > 100 and transitions < 3:
-                cv2.putText(frame, "! Switch more often (aim for 20+ transitions)",
-                            (10, warn_y), FONT, 0.38, ORANGE, 1, cv2.LINE_AA)
-                warn_y -= 18
-            if elapsed > 30 and n > 0:
-                bal = n1 / n
-                if bal < 0.25 or bal > 0.75:
-                    cv2.putText(frame, f"! Imbalanced ({bal:.0%} focused) - record more of the other",
-                                (10, warn_y), FONT, 0.38, ORANGE, 1, cv2.LINE_AA)
-                    warn_y -= 18
-
-            cv2.putText(frame, "1:focused  0:unfocused  p:pause  q:save+quit",
-                        (10, h - 10), FONT, 0.38, GRAY, 1, cv2.LINE_AA)
-
-            cv2.imshow("FocusGuard -- Data Collection", frame)
-
-            key = cv2.waitKey(1) & 0xFF
-            if key == ord("1"):
-                label = 1
-                status = "Recording: FOCUSED"
-                print(f"[COLLECT] -> FOCUSED (n={n}, transitions={transitions})")
-            elif key == ord("0"):
-                label = 0
-                status = "Recording: NOT FOCUSED"
-                print(f"[COLLECT] -> NOT FOCUSED (n={n}, transitions={transitions})")
-            elif key == ord("p"):
-                label = None
-                status = "PAUSED"
-                print(f"[COLLECT] paused (n={n})")
-            elif key == ord("q"):
-                break
-
-    finally:
-        cap.release()
-        cv2.destroyAllWindows()
-        detector.close()
-
-        if len(features_list) > 0:
-            feats = np.stack(features_list)
-            labs = np.array(labels_list, dtype=np.int64)
-
-            ts = time.strftime("%Y%m%d_%H%M%S")
-            fname = f"{args.name}_{ts}.npz"
-            fpath = os.path.join(args.output_dir, fname)
-            np.savez(fpath,
-                     features=feats,
-                     labels=labs,
-                     feature_names=np.array(FEATURE_NAMES))
-
-            print(f"\n[COLLECT] Saved {len(labs)} samples -> {fpath}")
-            print(f"  Shape: {feats.shape}  ({NUM_FEATURES} features)")
-
-            quality_report(labs)
-        else:
-            print("\n[COLLECT] No data collected")
-
-        print("[COLLECT] Done")
-
-
-if __name__ == "__main__":
-    main()

models/attention_model/train_attention.py

@@ -1 +0,0 @@
-# stub

models/attention_score_fusion/fusion.py

@@ -1 +0,0 @@
-# stub

models/eye_behaviour/eye_attention_model.py

@@ -1,48 +0,0 @@
-# MobileNetV2 eye attention classifier (attentive vs inattentive)
-
-import torch
-import torch.nn as nn
-import torchvision.models as models
-
-
-class EyeAttentionModel(nn.Module):
-    def __init__(
-        self,
-        pretrained: bool = True,
-        dropout1: float = 0.3,
-        dropout2: float = 0.2,
-    ):
-        super().__init__()
-
-        weights = models.MobileNet_V2_Weights.DEFAULT if pretrained else None
-        backbone = models.mobilenet_v2(weights=weights)
-
-        self.features = backbone.features
-        self.pool = nn.AdaptiveAvgPool2d(1)
-        self.classifier = nn.Sequential(
-            nn.Dropout(dropout1),
-            nn.Linear(1280, 256),
-            nn.ReLU(),
-            nn.Dropout(dropout2),
-            nn.Linear(256, 2),
-        )
-
-    def forward(self, x: torch.Tensor) -> torch.Tensor:
-        x = self.features(x)
-        x = self.pool(x).flatten(1)
-        return self.classifier(x)
-
-    def predict_score(self, x: torch.Tensor) -> torch.Tensor:
-        logits = self.forward(x)
-        probs = torch.softmax(logits, dim=1)
-        return probs[:, 1]
-
-    def freeze_backbone(self):
-        for param in self.features.parameters():
-            param.requires_grad = False
-
-    def unfreeze_last_blocks(self, n: int = 4):
-        total_blocks = len(self.features)
-        for i in range(max(0, total_blocks - n), total_blocks):
-            for param in self.features[i].parameters():
-                param.requires_grad = True

models/eye_behaviour/eye_classifier.py

@@ -1,149 +0,0 @@
-# Swappable eye classifier: geometric only, MobileNetV2 (96x96), or YOLO open/closed (224x224)
-
-from __future__ import annotations
-
-from abc import ABC, abstractmethod
-
-import cv2
-import numpy as np
-
-
-class EyeClassifier(ABC):
-    @property
-    @abstractmethod
-    def name(self) -> str:
-        pass
-
-    @abstractmethod
-    def predict_score(self, crops_bgr: list[np.ndarray]) -> float:
-        # crops_bgr: [left_crop, right_crop] BGR; returns score in [0,1], 1 = attentive (open)
-        pass
-
-
-class GeometricOnlyClassifier(EyeClassifier):
-    @property
-    def name(self) -> str:
-        return "geometric"
-
-    def predict_score(self, crops_bgr: list[np.ndarray]) -> float:
-        return 1.0
-
-
-class MobileNetV2Classifier(EyeClassifier):
-    # 96x96 crops, ImageNet norm
-    def __init__(self, checkpoint_path: str, device: str = "cpu"):
-        import torch
-
-        from models.eye_behaviour.eye_attention_model import EyeAttentionModel
-        from models.eye_behaviour.eye_crop import crop_to_tensor, CROP_SIZE
-
-        self._crop_to_tensor = crop_to_tensor
-        self._crop_size = CROP_SIZE
-        self._device = torch.device(device)
-
-        self._model = EyeAttentionModel(pretrained=False).to(self._device)
-        self._model.load_state_dict(
-            torch.load(checkpoint_path, map_location=self._device, weights_only=True)
-        )
-        self._model.eval()
-
-    @property
-    def name(self) -> str:
-        return "mobilenet"
-
-    def predict_score(self, crops_bgr: list[np.ndarray]) -> float:
-        import torch
-
-        if not crops_bgr:
-            return 1.0
-        tensors = []
-        for crop in crops_bgr:
-            resized = cv2.resize(crop, (self._crop_size, self._crop_size), interpolation=cv2.INTER_AREA)
-            tensors.append(self._crop_to_tensor(resized))
-        batch = torch.stack(tensors).to(self._device)
-        with torch.no_grad():
-            scores = self._model.predict_score(batch)
-        return scores.mean().item()
-
-
-class YOLOv11Classifier(EyeClassifier):
-    # YOLO open/closed; resizes to 224x224 internally
-    def __init__(self, checkpoint_path: str, device: str = "cpu"):
-        from ultralytics import YOLO
-
-        self._model = YOLO(checkpoint_path)
-        self._device = device
-
-        names = self._model.names
-        self._attentive_idx = None
-        for idx, cls_name in names.items():
-            if cls_name in ("open", "attentive"):
-                self._attentive_idx = idx
-                break
-        if self._attentive_idx is None:
-            self._attentive_idx = max(names.keys())
-        print(f"[YOLO] Classes: {names}, attentive_idx={self._attentive_idx}")
-
-    @property
-    def name(self) -> str:
-        return "yolo"
-
-    def predict_score(self, crops_bgr: list[np.ndarray]) -> float:
-        if not crops_bgr:
-            return 1.0
-        results = self._model.predict(crops_bgr, device=self._device, verbose=False)
-        scores = [float(r.probs.data[self._attentive_idx]) for r in results]
-        return sum(scores) / len(scores) if scores else 1.0
-
-
-def _is_yolo_checkpoint(path: str) -> bool:
-    try:
-        import torch
-
-        data = torch.load(path, map_location="cpu", weights_only=False)
-        if isinstance(data, dict):
-            model_obj = data.get("model")
-            if model_obj is not None and "Model" in type(model_obj).__name__:
-                return True
-            if "train_args" in data and "model" in data:
-                return True
-    except Exception:
-        pass
-    return False
-
-
-def load_eye_classifier(
-    path: str | None = None,
-    backend: str = "auto",
-    device: str = "cpu",
-) -> EyeClassifier:
-    if path is None or backend == "geometric":
-        return GeometricOnlyClassifier()
-
-    if backend == "yolo":
-        try:
-            return YOLOv11Classifier(path, device=device)
-        except ImportError:
-            print("[CLASSIFIER] ultralytics required. pip install ultralytics")
-            raise
-
-    if backend == "mobilenet":
-        return MobileNetV2Classifier(path, device=device)
-
-    if _is_yolo_checkpoint(path):
-        try:
-            return YOLOv11Classifier(path, device=device)
-        except ImportError:
-            print("[CLASSIFIER] YOLO checkpoint needs ultralytics. pip install ultralytics")
-            raise
-    try:
-        return MobileNetV2Classifier(path, device=device)
-    except Exception as exc:
-        err = str(exc)
-        if "Weights only load failed" in err and "ultralytics" in err:
-            try:
-                return YOLOv11Classifier(path, device=device)
-            except ImportError:
-                print("[CLASSIFIER] pip install ultralytics for this checkpoint")
-                raise
-        raise

models/eye_behaviour/eye_crop.py

@@ -1,70 +0,0 @@
-# Eye region extraction from Face Mesh landmarks
-
-import cv2
-import numpy as np
-
-LEFT_EYE_CONTOUR = [33, 7, 163, 144, 145, 153, 154, 155, 133, 173, 157, 158, 159, 160, 161, 246]
-RIGHT_EYE_CONTOUR = [362, 382, 381, 380, 374, 373, 390, 249, 263, 466, 388, 387, 386, 385, 384, 398]
-
-IMAGENET_MEAN = (0.485, 0.456, 0.406)
-IMAGENET_STD = (0.229, 0.224, 0.225)
-
-CROP_SIZE = 96
-
-
-def _bbox_from_landmarks(
-    landmarks: np.ndarray,
-    indices: list[int],
-    frame_w: int,
-    frame_h: int,
-    expand: float = 0.4,
-) -> tuple[int, int, int, int]:
-    pts = landmarks[indices, :2]
-    px = pts[:, 0] * frame_w
-    py = pts[:, 1] * frame_h
-
-    x_min, x_max = px.min(), px.max()
-    y_min, y_max = py.min(), py.max()
-    w = x_max - x_min
-    h = y_max - y_min
-    cx = (x_min + x_max) / 2
-    cy = (y_min + y_max) / 2
-
-    size = max(w, h) * (1 + expand)
-    half = size / 2
-
-    x1 = int(max(cx - half, 0))
-    y1 = int(max(cy - half, 0))
-    x2 = int(min(cx + half, frame_w))
-    y2 = int(min(cy + half, frame_h))
-
-    return x1, y1, x2, y2
-
-
-def extract_eye_crops(
-    frame: np.ndarray,
-    landmarks: np.ndarray,
-    expand: float = 0.4,
-    crop_size: int = CROP_SIZE,
-) -> tuple[np.ndarray, np.ndarray, tuple, tuple]:
-    h, w = frame.shape[:2]
-
-    left_bbox = _bbox_from_landmarks(landmarks, LEFT_EYE_CONTOUR, w, h, expand)
-    right_bbox = _bbox_from_landmarks(landmarks, RIGHT_EYE_CONTOUR, w, h, expand)
-
-    left_crop = frame[left_bbox[1] : left_bbox[3], left_bbox[0] : left_bbox[2]]
-    right_crop = frame[right_bbox[1] : right_bbox[3], right_bbox[0] : right_bbox[2]]
-
-    left_crop = cv2.resize(left_crop, (crop_size, crop_size), interpolation=cv2.INTER_AREA)
-    right_crop = cv2.resize(right_crop, (crop_size, crop_size), interpolation=cv2.INTER_AREA)
-
-    return left_crop, right_crop, left_bbox, right_bbox
-
-
-def crop_to_tensor(crop_bgr: np.ndarray):
-    import torch
-
-    rgb = cv2.cvtColor(crop_bgr, cv2.COLOR_BGR2RGB).astype(np.float32) / 255.0
-    for c in range(3):
-        rgb[:, :, c] = (rgb[:, :, c] - IMAGENET_MEAN[c]) / IMAGENET_STD[c]
-    return torch.from_numpy(rgb.transpose(2, 0, 1))

models/eye_behaviour/eye_scorer.py

@@ -1,167 +0,0 @@
-# EAR + gaze from landmarks -> S_eye (no model)
-
-import math
-
-import numpy as np
-
-_LEFT_EYE_EAR = [33, 160, 158, 133, 153, 145]
-_RIGHT_EYE_EAR = [362, 385, 387, 263, 373, 380]
-
-_LEFT_IRIS_CENTER = 468
-_RIGHT_IRIS_CENTER = 473
-
-_LEFT_EYE_INNER = 133
-_LEFT_EYE_OUTER = 33
-_RIGHT_EYE_INNER = 362
-_RIGHT_EYE_OUTER = 263
-
-_LEFT_EYE_TOP = 159
-_LEFT_EYE_BOTTOM = 145
-_RIGHT_EYE_TOP = 386
-_RIGHT_EYE_BOTTOM = 374
-
-# Mouth (MAR) — inner lip landmarks
-_MOUTH_TOP = 13
-_MOUTH_BOTTOM = 14
-_MOUTH_LEFT = 78
-_MOUTH_RIGHT = 308
-_MOUTH_UPPER_1 = 82
-_MOUTH_UPPER_2 = 312
-_MOUTH_LOWER_1 = 87
-_MOUTH_LOWER_2 = 317
-
-MAR_YAWN_THRESHOLD = 0.55  # MAR above this = mouth open (e.g. yawning / sleepy)
-
-
-def _distance(p1: np.ndarray, p2: np.ndarray) -> float:
-    return float(np.linalg.norm(p1 - p2))
-
-
-def compute_ear(landmarks: np.ndarray, eye_indices: list[int]) -> float:
-    p1 = landmarks[eye_indices[0], :2]
-    p2 = landmarks[eye_indices[1], :2]
-    p3 = landmarks[eye_indices[2], :2]
-    p4 = landmarks[eye_indices[3], :2]
-    p5 = landmarks[eye_indices[4], :2]
-    p6 = landmarks[eye_indices[5], :2]
-
-    vertical1 = _distance(p2, p6)
-    vertical2 = _distance(p3, p5)
-    horizontal = _distance(p1, p4)
-
-    if horizontal < 1e-6:
-        return 0.0
-
-    return (vertical1 + vertical2) / (2.0 * horizontal)
-
-
-def compute_avg_ear(landmarks: np.ndarray) -> float:
-    left_ear = compute_ear(landmarks, _LEFT_EYE_EAR)
-    right_ear = compute_ear(landmarks, _RIGHT_EYE_EAR)
-    return (left_ear + right_ear) / 2.0
-
-
-def compute_gaze_ratio(landmarks: np.ndarray) -> tuple[float, float]:
-    left_iris = landmarks[_LEFT_IRIS_CENTER, :2]
-    left_inner = landmarks[_LEFT_EYE_INNER, :2]
-    left_outer = landmarks[_LEFT_EYE_OUTER, :2]
-    left_top = landmarks[_LEFT_EYE_TOP, :2]
-    left_bottom = landmarks[_LEFT_EYE_BOTTOM, :2]
-
-    right_iris = landmarks[_RIGHT_IRIS_CENTER, :2]
-    right_inner = landmarks[_RIGHT_EYE_INNER, :2]
-    right_outer = landmarks[_RIGHT_EYE_OUTER, :2]
-    right_top = landmarks[_RIGHT_EYE_TOP, :2]
-    right_bottom = landmarks[_RIGHT_EYE_BOTTOM, :2]
-
-    left_h_total = _distance(left_inner, left_outer)
-    right_h_total = _distance(right_inner, right_outer)
-
-    if left_h_total < 1e-6 or right_h_total < 1e-6:
-        return 0.5, 0.5
-
-    left_h_ratio = _distance(left_outer, left_iris) / left_h_total
-    right_h_ratio = _distance(right_outer, right_iris) / right_h_total
-    h_ratio = (left_h_ratio + right_h_ratio) / 2.0
-
-    left_v_total = _distance(left_top, left_bottom)
-    right_v_total = _distance(right_top, right_bottom)
-
-    if left_v_total < 1e-6 or right_v_total < 1e-6:
-        return h_ratio, 0.5
-
-    left_v_ratio = _distance(left_top, left_iris) / left_v_total
-    right_v_ratio = _distance(right_top, right_iris) / right_v_total
-    v_ratio = (left_v_ratio + right_v_ratio) / 2.0
-
-    return float(np.clip(h_ratio, 0, 1)), float(np.clip(v_ratio, 0, 1))
-
-
-def compute_mar(landmarks: np.ndarray) -> float:
-    # Mouth aspect ratio: high = mouth open (yawning / sleepy)
-    top = landmarks[_MOUTH_TOP, :2]
-    bottom = landmarks[_MOUTH_BOTTOM, :2]
-    left = landmarks[_MOUTH_LEFT, :2]
-    right = landmarks[_MOUTH_RIGHT, :2]
-    upper1 = landmarks[_MOUTH_UPPER_1, :2]
-    lower1 = landmarks[_MOUTH_LOWER_1, :2]
-    upper2 = landmarks[_MOUTH_UPPER_2, :2]
-    lower2 = landmarks[_MOUTH_LOWER_2, :2]
-
-    horizontal = _distance(left, right)
-    if horizontal < 1e-6:
-        return 0.0
-    v1 = _distance(upper1, lower1)
-    v2 = _distance(top, bottom)
-    v3 = _distance(upper2, lower2)
-    return (v1 + v2 + v3) / (2.0 * horizontal)
-
-
-class EyeBehaviourScorer:
-    def __init__(
-        self,
-        ear_open: float = 0.30,
-        ear_closed: float = 0.16,
-        gaze_max_offset: float = 0.28,
-    ):
-        self.ear_open = ear_open
-        self.ear_closed = ear_closed
-        self.gaze_max_offset = gaze_max_offset
-
-    def _ear_score(self, ear: float) -> float:
-        if ear >= self.ear_open:
-            return 1.0
-        if ear <= self.ear_closed:
-            return 0.0
-        return (ear - self.ear_closed) / (self.ear_open - self.ear_closed)
-
-    def _gaze_score(self, h_ratio: float, v_ratio: float) -> float:
-        h_offset = abs(h_ratio - 0.5)
-        v_offset = abs(v_ratio - 0.5)
-        offset = math.sqrt(h_offset**2 + v_offset**2)
-        t = min(offset / self.gaze_max_offset, 1.0)
-        return 0.5 * (1.0 + math.cos(math.pi * t))
-
-    def score(self, landmarks: np.ndarray) -> float:
-        ear = compute_avg_ear(landmarks)
-        ear_s = self._ear_score(ear)
-        if ear_s < 0.3:
-            return ear_s
-        h_ratio, v_ratio = compute_gaze_ratio(landmarks)
-        gaze_s = self._gaze_score(h_ratio, v_ratio)
-        return ear_s * gaze_s
-
-    def detailed_score(self, landmarks: np.ndarray) -> dict:
-        ear = compute_avg_ear(landmarks)
-        ear_s = self._ear_score(ear)
-        h_ratio, v_ratio = compute_gaze_ratio(landmarks)
-        gaze_s = self._gaze_score(h_ratio, v_ratio)
-        s_eye = ear_s if ear_s < 0.3 else ear_s * gaze_s
-        return {
-            "ear": round(ear, 4),
-            "ear_score": round(ear_s, 4),
-            "h_gaze": round(h_ratio, 4),
-            "v_gaze": round(v_ratio, 4),
-            "gaze_score": round(gaze_s, 4),
-            "s_eye": round(s_eye, 4),
-        }

models/face_mesh/__init__.py

@@ -1 +0,0 @@
-# face mesh (stage 1)

models/face_mesh/face_mesh.py

@@ -1,95 +0,0 @@
-"""MediaPipe FaceLandmarker — 478 landmarks (incl. iris)."""
-
-import os
-from pathlib import Path
-from urllib.request import urlretrieve
-
-import cv2
-import numpy as np
-import mediapipe as mp
-from mediapipe.tasks.python.vision import FaceLandmarkerOptions, FaceLandmarker, RunningMode
-from mediapipe.tasks import python as mp_tasks
-
-_MODEL_URL = (
-    "https://storage.googleapis.com/mediapipe-models/face_landmarker/"
-    "face_landmarker/float16/latest/face_landmarker.task"
-)
-
-
-def _ensure_model() -> str:
-    cache_dir = Path(os.environ.get(
-        "FOCUSGUARD_CACHE_DIR",
-        Path.home() / ".cache" / "focusguard",
-    ))
-    model_path = cache_dir / "face_landmarker.task"
-    if model_path.exists():
-        return str(model_path)
-    cache_dir.mkdir(parents=True, exist_ok=True)
-    print(f"[FACE_MESH] Downloading model to {model_path}...")
-    urlretrieve(_MODEL_URL, model_path)
-    print("[FACE_MESH] Download complete.")
-    return str(model_path)
-
-
-class FaceMeshDetector:
-
-    # indices for eyes/iris (for downstream)
-    LEFT_EYE_INDICES = [33, 7, 163, 144, 145, 153, 154, 155, 133, 173, 157, 158, 159, 160, 161, 246]
-    RIGHT_EYE_INDICES = [362, 382, 381, 380, 374, 373, 390, 249, 263, 466, 388, 387, 386, 385, 384, 398]
-    LEFT_IRIS_INDICES = [468, 469, 470, 471, 472]
-    RIGHT_IRIS_INDICES = [473, 474, 475, 476, 477]
-
-    def __init__(
-        self,
-        max_num_faces: int = 1,
-        min_detection_confidence: float = 0.5,
-        min_tracking_confidence: float = 0.5,
-    ):
-        model_path = _ensure_model()
-        options = FaceLandmarkerOptions(
-            base_options=mp_tasks.BaseOptions(model_asset_path=model_path),
-            num_faces=max_num_faces,
-            min_face_detection_confidence=min_detection_confidence,
-            min_face_presence_confidence=min_detection_confidence,
-            min_tracking_confidence=min_tracking_confidence,
-            running_mode=RunningMode.VIDEO,
-        )
-        self._landmarker = FaceLandmarker.create_from_options(options)
-        self._frame_ts = 0  # ms, for video API
-
-    def process(self, bgr_frame: np.ndarray) -> np.ndarray | None:
-        # BGR in -> (478,3) norm x,y,z or None
-        rgb = cv2.cvtColor(bgr_frame, cv2.COLOR_BGR2RGB)
-        mp_image = mp.Image(image_format=mp.ImageFormat.SRGB, data=rgb)
-        self._frame_ts += 33  # ~30fps
-        result = self._landmarker.detect_for_video(mp_image, self._frame_ts)
-
-        if not result.face_landmarks:
-            return None
-
-        face = result.face_landmarks[0]
-        return np.array([(lm.x, lm.y, lm.z) for lm in face], dtype=np.float32)
-
-    def get_pixel_landmarks(self, landmarks: np.ndarray, frame_w: int, frame_h: int) -> np.ndarray:
-        # norm -> pixel (x,y)
-        pixel = np.zeros((landmarks.shape[0], 2), dtype=np.int32)
-        pixel[:, 0] = (landmarks[:, 0] * frame_w).astype(np.int32)
-        pixel[:, 1] = (landmarks[:, 1] * frame_h).astype(np.int32)
-        return pixel
-
-    def get_3d_landmarks(self, landmarks: np.ndarray, frame_w: int, frame_h: int) -> np.ndarray:
-        # norm -> pixel-scale x,y,z (z scaled by width)
-        pts = np.zeros_like(landmarks)
-        pts[:, 0] = landmarks[:, 0] * frame_w
-        pts[:, 1] = landmarks[:, 1] * frame_h
-        pts[:, 2] = landmarks[:, 2] * frame_w
-        return pts
-
-    def close(self):
-        self._landmarker.close()
-
-    def __enter__(self):
-        return self
-
-    def __exit__(self, *args):
-        self.close()

models/face_orientation/head_pose.py

@@ -1,114 +0,0 @@
-# Head pose from 6 Face Mesh landmarks (solvePnP) -> yaw/pitch/roll, S_face
-
-import math
-
-import cv2
-import numpy as np
-
-_LANDMARK_INDICES = [1, 152, 33, 263, 61, 291]
-
-_MODEL_POINTS = np.array(
-    [
-        [0.0, 0.0, 0.0],
-        [0.0, -330.0, -65.0],
-        [-225.0, 170.0, -135.0],
-        [225.0, 170.0, -135.0],
-        [-150.0, -150.0, -125.0],
-        [150.0, -150.0, -125.0],
-    ],
-    dtype=np.float64,
-)
-
-
-class HeadPoseEstimator:
-    def __init__(self, max_angle: float = 30.0, roll_weight: float = 0.5):
-        self.max_angle = max_angle
-        self.roll_weight = roll_weight
-        self._camera_matrix = None
-        self._frame_size = None
-        self._dist_coeffs = np.zeros((4, 1), dtype=np.float64)
-
-    def _get_camera_matrix(self, frame_w: int, frame_h: int) -> np.ndarray:
-        if self._camera_matrix is not None and self._frame_size == (frame_w, frame_h):
-            return self._camera_matrix
-        focal_length = float(frame_w)
-        cx, cy = frame_w / 2.0, frame_h / 2.0
-        self._camera_matrix = np.array(
-            [[focal_length, 0, cx], [0, focal_length, cy], [0, 0, 1]],
-            dtype=np.float64,
-        )
-        self._frame_size = (frame_w, frame_h)
-        return self._camera_matrix
-
-    def _solve(self, landmarks: np.ndarray, frame_w: int, frame_h: int):
-        image_points = np.array(
-            [
-                [landmarks[i, 0] * frame_w, landmarks[i, 1] * frame_h]
-                for i in _LANDMARK_INDICES
-            ],
-            dtype=np.float64,
-        )
-        camera_matrix = self._get_camera_matrix(frame_w, frame_h)
-        success, rvec, tvec = cv2.solvePnP(
-            _MODEL_POINTS,
-            image_points,
-            camera_matrix,
-            self._dist_coeffs,
-            flags=cv2.SOLVEPNP_ITERATIVE,
-        )
-        return success, rvec, tvec, image_points
-
-    def estimate(
-        self, landmarks: np.ndarray, frame_w: int, frame_h: int
-    ) -> tuple[float, float, float] | None:
-        success, rvec, tvec, _ = self._solve(landmarks, frame_w, frame_h)
-        if not success:
-            return None
-
-        rmat, _ = cv2.Rodrigues(rvec)
-        nose_dir = rmat @ np.array([0.0, 0.0, 1.0])
-        face_up = rmat @ np.array([0.0, 1.0, 0.0])
-
-        yaw = math.degrees(math.atan2(nose_dir[0], -nose_dir[2]))
-        pitch = math.degrees(math.asin(np.clip(-nose_dir[1], -1.0, 1.0)))
-        roll = math.degrees(math.atan2(face_up[0], -face_up[1]))
-
-        return (yaw, pitch, roll)
-
-    def score(self, landmarks: np.ndarray, frame_w: int, frame_h: int) -> float:
-        angles = self.estimate(landmarks, frame_w, frame_h)
-        if angles is None:
-            return 0.0
-
-        yaw, pitch, roll = angles
-        deviation = math.sqrt(yaw**2 + pitch**2 + (self.roll_weight * roll) ** 2)
-        t = min(deviation / self.max_angle, 1.0)
-        return 0.5 * (1.0 + math.cos(math.pi * t))
-
-    def draw_axes(
-        self,
-        frame: np.ndarray,
-        landmarks: np.ndarray,
-        axis_length: float = 50.0,
-    ) -> np.ndarray:
-        h, w = frame.shape[:2]
-        success, rvec, tvec, image_points = self._solve(landmarks, w, h)
-        if not success:
-            return frame
-
-        camera_matrix = self._get_camera_matrix(w, h)
-        nose = tuple(image_points[0].astype(int))
-
-        axes_3d = np.float64(
-            [[axis_length, 0, 0], [0, axis_length, 0], [0, 0, axis_length]]
-        )
-        projected, _ = cv2.projectPoints(
-            axes_3d, rvec, tvec, camera_matrix, self._dist_coeffs
-        )
-
-        colors = [(0, 0, 255), (0, 255, 0), (255, 0, 0)]
-        for i, color in enumerate(colors):
-            pt = tuple(projected[i].ravel().astype(int))
-            cv2.line(frame, nose, pt, color, 2)
-
-        return frame

models/train.py

@@ -1,186 +0,0 @@
-# Run from repo root: python -m models.train (or cd models && python train.py)
-
-import json
-import os
-import random
-
-import numpy as np as np
-import torch
-import torch.nn as nn
-import torch.optim as optim
-
-from prepare_dataset import get_dataloaders
-
-CFG = {
-    "model_name": "face_orientation",  # "face_orientation" or "eye_behaviour"
-    "epochs": 30,
-    "batch_size": 32,
-    "lr": 1e-3,
-    "seed": 42,
-    "split_ratios": (0.7, 0.15, 0.15),
-    "checkpoints_dir": {
-        "face_orientation": os.path.join(os.path.dirname(__file__), "face_orientation_model"),
-        "eye_behaviour": os.path.join(os.path.dirname(__file__), "eye_behaviour_model"),
-    },
-    "logs_dir": os.path.join(os.path.dirname(__file__), "..", "evaluation", "logs"),
-}
-
-
-def set_seed(seed: int):
-    random.seed(seed)
-    np.random.seed(seed)
-    torch.manual_seed(seed)
-    if torch.cuda.is_available():
-        torch.cuda.manual_seed_all(seed)
-
-
-class BaseModel(nn.Module):
-    def __init__(self, num_features: int, num_classes: int):
-        super().__init__()
-        self.network = nn.Sequential(
-            nn.Linear(num_features, 64),
-            nn.ReLU(),
-            nn.Linear(64, 32),
-            nn.ReLU(),
-            nn.Linear(32, num_classes),
-        )
-
-    def forward(self, x):
-        return self.network(x)
-
-    def training_step(self, loader, optimizer, criterion, device):
-        self.train()
-        total_loss = 0.0
-        correct = 0
-        total = 0
-
-        for features, labels in loader:
-            features, labels = features.to(device), labels.to(device)
-
-            optimizer.zero_grad()
-            outputs = self(features)
-            loss = criterion(outputs, labels)
-            loss.backward()
-            optimizer.step()
-
-            total_loss += loss.item() * features.size(0)
-            correct += (outputs.argmax(dim=1) == labels).sum().item()
-            total += features.size(0)
-
-        return total_loss / total, correct / total
-
-    @torch.no_grad()
-    def validation_step(self, loader, criterion, device):
-        self.eval()
-        total_loss = 0.0
-        correct = 0
-        total = 0
-
-        for features, labels in loader:
-            features, labels = features.to(device), labels.to(device)
-            outputs = self(features)
-            loss = criterion(outputs, labels)
-
-            total_loss += loss.item() * features.size(0)
-            correct += (outputs.argmax(dim=1) == labels).sum().item()
-            total += features.size(0)
-
-        return total_loss / total, correct / total
-
-    @torch.no_grad()
-    def test_step(self, loader, criterion, device):
-        self.eval()
-        total_loss = 0.0
-        correct = 0
-        total = 0
-
-        for features, labels in loader:
-            features, labels = features.to(device), labels.to(device)
-            outputs = self(features)
-            loss = criterion(outputs, labels)
-
-            total_loss += loss.item() * features.size(0)
-            correct += (outputs.argmax(dim=1) == labels).sum().item()
-            total += features.size(0)
-
-        return total_loss / total, correct / total
-
-
-def main():
-    set_seed(CFG["seed"])
-
-    device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
-    print(f"[TRAIN] Device: {device}")
-    print(f"[TRAIN] Model: {CFG['model_name']}")
-
-    train_loader, val_loader, test_loader, num_features, num_classes = get_dataloaders(
-        model_name=CFG["model_name"],
-        batch_size=CFG["batch_size"],
-        split_ratios=CFG["split_ratios"],
-        seed=CFG["seed"],
-    )
-
-    model = BaseModel(num_features, num_classes).to(device)
-    criterion = nn.CrossEntropyLoss()
-    optimizer = optim.Adam(model.parameters(), lr=CFG["lr"])
-
-    print(f"[TRAIN] Parameters: {sum(p.numel() for p in model.parameters()):,}")
-
-    ckpt_dir = CFG["checkpoints_dir"][CFG["model_name"]]
-    os.makedirs(ckpt_dir, exist_ok=True)
-    best_ckpt_path = os.path.join(ckpt_dir, "best_model.pt")
-
-    history = {
-        "model_name": CFG["model_name"],
-        "epochs": [],
-        "train_loss": [],
-        "train_acc": [],
-        "val_loss": [],
-        "val_acc": [],
-    }
-
-    best_val_acc = 0.0
-
-    print(f"\n{'Epoch':>6} | {'Train Loss':>10} | {'Train Acc':>9} | {'Val Loss':>10} | {'Val Acc':>9}")
-    print("-" * 60)
-
-    for epoch in range(1, CFG["epochs"] + 1):
-        train_loss, train_acc = model.training_step(train_loader, optimizer, criterion, device)
-        val_loss, val_acc = model.validation_step(val_loader, criterion, device)
-
-        history["epochs"].append(epoch)
-        history["train_loss"].append(round(train_loss, 4))
-        history["train_acc"].append(round(train_acc, 4))
-        history["val_loss"].append(round(val_loss, 4))
-        history["val_acc"].append(round(val_acc, 4))
-
-        marker = ""
-        if val_acc > best_val_acc:
-            best_val_acc = val_acc
-            torch.save(model.state_dict(), best_ckpt_path)
-            marker = " *"
-
-        print(f"{epoch:>6} | {train_loss:>10.4f} | {train_acc:>8.2%} | {val_loss:>10.4f} | {val_acc:>8.2%}{marker}")
-
-    print(f"\nBest validation accuracy: {best_val_acc:.2%}")
-    print(f"Checkpoint saved to: {best_ckpt_path}")
-
-    model.load_state_dict(torch.load(best_ckpt_path, weights_only=True))
-    test_loss, test_acc = model.test_step(test_loader, criterion, device)
-    print(f"\n[TEST] Loss: {test_loss:.4f} | Accuracy: {test_acc:.2%}")
-
-    history["test_loss"] = round(test_loss, 4)
-    history["test_acc"] = round(test_acc, 4)
-
-    logs_dir = CFG["logs_dir"]
-    os.makedirs(logs_dir, exist_ok=True)
-    log_path = os.path.join(logs_dir, f"{CFG['model_name']}_training_log.json")
-
-    with open(log_path, "w") as f:
-        json.dump(history, f, indent=2)
-
-    print(f"[LOG] Training history saved to: {log_path}")
-
-
-if __name__ == "__main__":
-    main()

models/train_eye_cnn.py

@@ -1 +0,0 @@
-# stub