Spaces:

FocusGuard
/

final

Sleeping

+{
+  "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
+}

models/attention_model/collect_features.py CHANGED Viewed

	@@ -1 +1,403 @@
1	- # ~~stub~~

+# 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()