chore: add template layout and stage 1 face mesh demo

evaluation/evaluate.py

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

evaluation/metrics.py

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

models/attention_model/attention_classifier.py

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

models/attention_model/collect_features.py

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

models/attention_model/train_attention.py

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

models/attention_score_fusion/fusion.py

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

models/eye_behaviour/eye_attention_model.py

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

models/eye_behaviour/eye_crop.py

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

models/eye_behaviour/eye_scorer.py

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

models/face_mesh/__init__.py

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

models/face_mesh/face_mesh.py

@@ -0,0 +1,95 @@
+"""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

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

models/face_orientation_model/best_model.pt

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:18c1f2750c7274e72538b94afcc9f0243287a5b2eb8fcce6be6e4ae18ec59cb0
-size 15033

models/train_eye_cnn.py

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

requirements.txt

@@ -0,0 +1,4 @@
+# Stage 1: face mesh + test UI (no torch)
+mediapipe>=0.10.14
+opencv-python>=4.8.0
+numpy>=1.24.0

ui/README.md

@@ -1,3 +1,15 @@
 # ui
 
-Live demo and session view — structure up to the team.
+Live demo and session view.
+
+## Stage 1 (face mesh only)
+
+- **pipeline.py** — frame → 478 landmarks (no head pose / CNN).
+- **live_demo.py** — webcam + mesh overlay (tessellation, contours, eyes, irises).
+
+From repo root:
+```bash
+pip install -r requirements.txt
+python ui/live_demo.py
+```
+`q` = quit, `m` = cycle mesh mode (full / contours / off).

ui/live_demo.py

@@ -0,0 +1,181 @@
+# Stage 1 demo — webcam + face mesh overlay
+
+import argparse
+import os
+import sys
+import time
+
+import cv2
+import numpy as np
+from mediapipe.tasks.python.vision import FaceLandmarksConnections
+
+_PROJECT_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+if _PROJECT_ROOT not in sys.path:
+    sys.path.insert(0, _PROJECT_ROOT)
+
+from ui.pipeline import FaceMeshPipeline
+from models.face_mesh.face_mesh import FaceMeshDetector
+
+# Drawing
+FONT = cv2.FONT_HERSHEY_SIMPLEX
+CYAN = (255, 255, 0)
+GREEN = (0, 255, 0)
+MAGENTA = (255, 0, 255)
+ORANGE = (0, 165, 255)
+RED = (0, 0, 255)
+WHITE = (255, 255, 255)
+YELLOW = (0, 255, 255)
+LIGHT_GREEN = (144, 238, 144)
+
+_TESSELATION = [(c.start, c.end) for c in FaceLandmarksConnections.FACE_LANDMARKS_TESSELATION]
+_CONTOURS = [(c.start, c.end) for c in FaceLandmarksConnections.FACE_LANDMARKS_CONTOURS]
+_LEFT_EYEBROW = [70, 63, 105, 66, 107, 55, 65, 52, 53, 46]
+_RIGHT_EYEBROW = [300, 293, 334, 296, 336, 285, 295, 282, 283, 276]
+_NOSE_BRIDGE = [6, 197, 195, 5, 4, 1, 19, 94, 2]
+_LIPS_OUTER = [61, 146, 91, 181, 84, 17, 314, 405, 321, 375, 291, 409, 270, 269, 267, 0, 37, 39, 40, 185, 61]
+_LIPS_INNER = [78, 95, 88, 178, 87, 14, 317, 402, 318, 324, 308, 415, 310, 311, 312, 13, 82, 81, 80, 191, 78]
+_LEFT_EAR_POINTS = [33, 160, 158, 133, 153, 145]
+_RIGHT_EAR_POINTS = [362, 385, 387, 263, 373, 380]
+
+MESH_FULL = 0
+MESH_CONTOURS = 1
+MESH_OFF = 2
+_MESH_NAMES = ["FULL MESH", "CONTOURS", "MESH OFF"]
+
+
+def _lm_to_px(landmarks, idx, w, h):
+    return (int(landmarks[idx, 0] * w), int(landmarks[idx, 1] * h))
+
+
+def draw_tessellation(frame, landmarks, w, h):
+    overlay = frame.copy()
+    for conn in _TESSELATION:
+        pt1 = _lm_to_px(landmarks, conn[0], w, h)
+        pt2 = _lm_to_px(landmarks, conn[1], w, h)
+        cv2.line(overlay, pt1, pt2, (200, 200, 200), 1, cv2.LINE_AA)
+    cv2.addWeighted(overlay, 0.3, frame, 0.7, 0, frame)
+
+
+def draw_contours(frame, landmarks, w, h):
+    for conn in _CONTOURS:
+        pt1 = _lm_to_px(landmarks, conn[0], w, h)
+        pt2 = _lm_to_px(landmarks, conn[1], w, h)
+        cv2.line(frame, pt1, pt2, CYAN, 1, cv2.LINE_AA)
+    for indices in [_LEFT_EYEBROW, _RIGHT_EYEBROW]:
+        for i in range(len(indices) - 1):
+            pt1 = _lm_to_px(landmarks, indices[i], w, h)
+            pt2 = _lm_to_px(landmarks, indices[i + 1], w, h)
+            cv2.line(frame, pt1, pt2, LIGHT_GREEN, 2, cv2.LINE_AA)
+    for i in range(len(_NOSE_BRIDGE) - 1):
+        pt1 = _lm_to_px(landmarks, _NOSE_BRIDGE[i], w, h)
+        pt2 = _lm_to_px(landmarks, _NOSE_BRIDGE[i + 1], w, h)
+        cv2.line(frame, pt1, pt2, ORANGE, 1, cv2.LINE_AA)
+    for i in range(len(_LIPS_OUTER) - 1):
+        pt1 = _lm_to_px(landmarks, _LIPS_OUTER[i], w, h)
+        pt2 = _lm_to_px(landmarks, _LIPS_OUTER[i + 1], w, h)
+        cv2.line(frame, pt1, pt2, MAGENTA, 1, cv2.LINE_AA)
+    for i in range(len(_LIPS_INNER) - 1):
+        pt1 = _lm_to_px(landmarks, _LIPS_INNER[i], w, h)
+        pt2 = _lm_to_px(landmarks, _LIPS_INNER[i + 1], w, h)
+        cv2.line(frame, pt1, pt2, (200, 0, 200), 1, cv2.LINE_AA)
+
+
+def draw_eyes_and_irises(frame, landmarks, w, h):
+    left_pts = np.array(
+        [_lm_to_px(landmarks, i, w, h) for i in FaceMeshDetector.LEFT_EYE_INDICES],
+        dtype=np.int32,
+    )
+    cv2.polylines(frame, [left_pts], True, GREEN, 2, cv2.LINE_AA)
+    right_pts = np.array(
+        [_lm_to_px(landmarks, i, w, h) for i in FaceMeshDetector.RIGHT_EYE_INDICES],
+        dtype=np.int32,
+    )
+    cv2.polylines(frame, [right_pts], True, GREEN, 2, cv2.LINE_AA)
+    for indices in [_LEFT_EAR_POINTS, _RIGHT_EAR_POINTS]:
+        for idx in indices:
+            pt = _lm_to_px(landmarks, idx, w, h)
+            cv2.circle(frame, pt, 3, YELLOW, -1, cv2.LINE_AA)
+    for iris_indices, eye_inner, eye_outer in [
+        (FaceMeshDetector.LEFT_IRIS_INDICES, 133, 33),
+        (FaceMeshDetector.RIGHT_IRIS_INDICES, 362, 263),
+    ]:
+        iris_pts = np.array(
+            [_lm_to_px(landmarks, i, w, h) for i in iris_indices],
+            dtype=np.int32,
+        )
+        center = iris_pts[0]
+        if len(iris_pts) >= 5:
+            radii = [np.linalg.norm(iris_pts[j] - center) for j in range(1, 5)]
+            radius = max(int(np.mean(radii)), 2)
+            cv2.circle(frame, tuple(center), radius, MAGENTA, 2, cv2.LINE_AA)
+            cv2.circle(frame, tuple(center), 2, WHITE, -1, cv2.LINE_AA)
+        eye_center_x = (landmarks[eye_inner, 0] + landmarks[eye_outer, 0]) / 2.0
+        eye_center_y = (landmarks[eye_inner, 1] + landmarks[eye_outer, 1]) / 2.0
+        eye_center = (int(eye_center_x * w), int(eye_center_y * h))
+        dx = center[0] - eye_center[0]
+        dy = center[1] - eye_center[1]
+        gaze_end = (int(center[0] + dx * 3), int(center[1] + dy * 3))
+        cv2.line(frame, tuple(center), gaze_end, RED, 1, cv2.LINE_AA)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="FocusGuard — Face mesh (Stage 1)")
+    parser.add_argument("--camera", type=int, default=0, help="Camera index")
+    args = parser.parse_args()
+
+    print("[DEMO] Face mesh only (Stage 1)")
+    pipeline = FaceMeshPipeline()
+
+    cap = cv2.VideoCapture(args.camera)
+    if not cap.isOpened():
+        print("[DEMO] ERROR: Cannot open camera")
+        return
+
+    print("[DEMO] q = quit, m = cycle mesh mode (full / contours / off)")
+    prev_time = time.time()
+    fps = 0.0
+    mesh_mode = MESH_FULL
+
+    try:
+        while True:
+            ret, frame = cap.read()
+            if not ret:
+                break
+
+            result = pipeline.process_frame(frame)
+            now = time.time()
+            fps = 0.9 * fps + 0.1 * (1.0 / max(now - prev_time, 1e-6))
+            prev_time = now
+
+            h, w = frame.shape[:2]
+            if result["landmarks"] is not None:
+                lm = result["landmarks"]
+                if mesh_mode == MESH_FULL:
+                    draw_tessellation(frame, lm, w, h)
+                    draw_contours(frame, lm, w, h)
+                elif mesh_mode == MESH_CONTOURS:
+                    draw_contours(frame, lm, w, h)
+                draw_eyes_and_irises(frame, lm, w, h)
+
+            cv2.rectangle(frame, (0, 0), (w, 28), (0, 0, 0), -1)
+            cv2.putText(frame, f"{_MESH_NAMES[mesh_mode]}  FPS: {fps:.0f}", (10, 20), FONT, 0.5, (255, 255, 255), 1, cv2.LINE_AA)
+            cv2.putText(frame, "q:quit  m:mesh", (w - 140, 20), FONT, 0.4, (180, 180, 180), 1, cv2.LINE_AA)
+
+            cv2.imshow("FocusGuard", frame)
+
+            key = cv2.waitKey(1) & 0xFF
+            if key == ord("q"):
+                break
+            elif key == ord("m"):
+                mesh_mode = (mesh_mode + 1) % 3
+                print(f"[DEMO] Mesh: {_MESH_NAMES[mesh_mode]}")
+
+    finally:
+        cap.release()
+        cv2.destroyAllWindows()
+        pipeline.close()
+        print("[DEMO] Done")
+
+
+if __name__ == "__main__":
+    main()

ui/pipeline.py

@@ -0,0 +1,32 @@
+# Stage 1: face mesh only (no head pose / eye model / fusion)
+
+import os
+import sys
+
+import numpy as np
+
+_PROJECT_ROOT = 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
+
+
+class FaceMeshPipeline:
+    # frame -> face mesh -> 478 landmarks
+
+    def __init__(self):
+        self.detector = FaceMeshDetector()
+
+    def process_frame(self, bgr_frame: np.ndarray) -> dict:
+        landmarks = self.detector.process(bgr_frame)
+        return {"landmarks": landmarks}
+
+    def close(self):
+        self.detector.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()