Face tracker web demo

README.md

@@ -0,0 +1,61 @@
+---
+title: Face Tracker Demo
+emoji: 🎥
+colorFrom: blue
+colorTo: purple
+sdk: gradio
+sdk_version: "5.9.1"
+app_file: app.py
+python_version: "3.10"
+pinned: false
+---
+
+# Face Tracker Demo (web)
+
+Browser demo of the pipeline in `../app`: live webcam → InsightFace detection
+→ ArcFace embedding → ByteTrack → FAISS identity match → boxes/IDs drawn in
+your browser. Nothing is recorded or stored; state lives only in your tab for
+the session and is discarded on reload.
+
+This is **not** the NUC/production app - it's a lightweight, standalone copy
+tuned for a shared free CPU (smaller `buffalo_s` model pack, 320px detection,
+2 ONNX Runtime threads by default). See `../app/README.md` for the real
+RTSP/webcam app this demonstrates.
+
+## Deploying
+
+1. Create a new Space at https://huggingface.co/new-space with SDK "Gradio".
+2. Push the contents of this folder (not the whole repo) to the Space's git
+   remote:
+   ```bash
+   cd webdemo
+   git init
+   git remote add space https://huggingface.co/spaces/<your-username>/<space-name>
+   git add -A
+   git commit -m "Face tracker web demo"
+   git push space main
+   ```
+3. The Space builds automatically from `requirements.txt` and launches
+   `app.py`. First build takes a few minutes (downloads the `buffalo_s` model
+   pack on first request).
+
+## Local test before deploying
+
+```bash
+cd webdemo
+pip install -r requirements.txt
+python app.py
+```
+
+Opens at http://127.0.0.1:7860 - allow webcam access in the browser.
+
+## Tuning via environment variables
+
+Set these as Space secrets/variables, or env vars for local testing:
+
+| Variable | Default | Notes |
+|---|---|---|
+| `DET_SIZE` | `320` | detector input size |
+| `MODEL_NAME` | `buffalo_s` | or `buffalo_l` for more accuracy, slower |
+| `ONNX_THREADS` | `2` | match the Space's CPU tier core count |
+| `MATCH_THRESHOLD` | `0.38` | cosine similarity for matching a face to an existing ID |

app.py

@@ -0,0 +1,104 @@
+"""Browser-based live demo: face detection + tracking + per-session persistent ID.
+
+Deploy target: Hugging Face Spaces (Gradio SDK, Python 3.10, free CPU Basic).
+This is a demo of the pipeline in ../app, not the NUC/production app itself -
+no RTSP, no SQLite, nothing saved. Each visitor gets their own tracker and
+FAISS gallery for the lifetime of their browser tab (held in gr.State);
+nothing is stored server-side or shared between visitors.
+"""
+import os
+from typing import Dict, List, Optional, Tuple
+
+import numpy as np
+import gradio as gr
+import supervision as sv
+
+from face_engine import FaceEngine
+from identity_store import IdentityStore
+
+DET_SIZE = int(os.environ.get("DET_SIZE", "320"))
+MODEL_NAME = os.environ.get("MODEL_NAME", "buffalo_s")
+ONNX_THREADS = int(os.environ.get("ONNX_THREADS", "2"))
+MATCH_THRESHOLD = float(os.environ.get("MATCH_THRESHOLD", "0.38"))
+
+box_annotator = sv.BoxAnnotator()
+label_annotator = sv.LabelAnnotator()
+
+# One shared FaceEngine process-wide (loading the ONNX models per visitor
+# would be far too slow); it holds no per-visitor state, so this is safe.
+face_engine = FaceEngine(
+    det_size=(DET_SIZE, DET_SIZE),
+    ctx_id=-1,
+    model_name=MODEL_NAME,
+    num_threads=ONNX_THREADS,
+)
+
+SessionState = Tuple[sv.ByteTrack, IdentityStore, Dict[int, int]]
+
+
+def build_detections(faces: list) -> sv.Detections:
+    if not faces:
+        return sv.Detections.empty()
+
+    xyxy = np.array([face.bbox for face in faces], dtype=np.float32)
+    confidence = np.array([face.det_score for face in faces], dtype=np.float32)
+    embeddings = np.array([face.normed_embedding for face in faces], dtype=np.float32)
+    class_id = np.zeros(len(faces), dtype=int)
+
+    return sv.Detections(
+        xyxy=xyxy,
+        confidence=confidence,
+        class_id=class_id,
+        data={"embedding": embeddings},
+    )
+
+
+def process_frame(
+    frame_rgb: Optional[np.ndarray], state: Optional[SessionState]
+) -> Tuple[Optional[np.ndarray], SessionState]:
+    if state is None:
+        state = (sv.ByteTrack(), IdentityStore(embedding_dim=512, match_threshold=MATCH_THRESHOLD), {})
+    tracker, identity_store, track_to_person = state
+
+    if frame_rgb is None:
+        return None, state
+
+    # gradio's numpy Image type is RGB; our pipeline (InsightFace, supervision) expects BGR.
+    frame_bgr = frame_rgb[:, :, ::-1]
+
+    faces = face_engine.detect(frame_bgr)
+    detections = build_detections(faces)
+    detections = tracker.update_with_detections(detections)
+
+    labels: List[str] = []
+    embeddings = detections.data.get("embedding") if detections.data else None
+    for i in range(len(detections)):
+        track_id = int(detections.tracker_id[i])
+        if embeddings is not None:
+            person_id = identity_store.match_or_register(embeddings[i])
+            track_to_person[track_id] = person_id
+        person_id = track_to_person.get(track_id, track_id)
+        labels.append(f"ID {person_id}")
+
+    annotated_bgr = box_annotator.annotate(scene=frame_bgr.copy(), detections=detections)
+    annotated_bgr = label_annotator.annotate(scene=annotated_bgr, detections=detections, labels=labels)
+
+    return annotated_bgr[:, :, ::-1], (tracker, identity_store, track_to_person)
+
+
+with gr.Blocks(title="Face Tracker Demo") as demo:
+    gr.Markdown(
+        "# Real-time multi-person face identification & tracking\n"
+        "Allow webcam access below. Each detected face gets a box and a "
+        "persistent `ID n` for as long as this tab stays open. Nothing is "
+        "recorded, stored, or sent anywhere beyond this page - it all resets "
+        "when you reload."
+    )
+    state = gr.State(None)
+    with gr.Row():
+        webcam = gr.Image(sources=["webcam"], streaming=True, label="Your webcam", mirror_webcam=True)
+        output = gr.Image(label="Detected + tracked", streaming=True)
+    webcam.stream(fn=process_frame, inputs=[webcam, state], outputs=[output, state])
+
+if __name__ == "__main__":
+    demo.queue().launch()

face_engine.py

@@ -0,0 +1,50 @@
+"""Thin wrapper around InsightFace's FaceAnalysis (RetinaFace detector + ArcFace embedder).
+
+Intentionally duplicated from ../app/face_engine.py: this folder is a separate,
+self-contained deployable (Hugging Face Spaces web demo) with its own
+requirements.txt (headless OpenCV, no GUI deps) and its own tuning defaults for
+a shared/free CPU, independent of the NUC/local app in ../app.
+"""
+from typing import List, Optional, Tuple
+
+import numpy as np
+import onnxruntime
+from insightface.app import FaceAnalysis
+from insightface.app.common import Face
+
+# We only ever read .bbox, .det_score, .normed_embedding, so the landmark_3d_68,
+# landmark_2d_106 and genderage models are pure overhead: excluding them via
+# allowed_modules skips loading AND running 3 extra ONNX forward passes per face.
+_REQUIRED_MODULES = ["detection", "recognition"]
+
+
+class FaceEngine:
+    """Detects faces and produces L2-normalized 512-d ArcFace embeddings."""
+
+    def __init__(
+        self,
+        det_size: Tuple[int, int] = (320, 320),
+        ctx_id: int = -1,
+        model_name: str = "buffalo_s",
+        num_threads: Optional[int] = None,
+    ) -> None:
+        # ctx_id=-1 -> CPUExecutionProvider only; ctx_id>=0 -> CUDAExecutionProvider device id.
+        providers = ["CPUExecutionProvider"] if ctx_id < 0 else ["CUDAExecutionProvider", "CPUExecutionProvider"]
+
+        sess_options = None
+        if num_threads is not None and num_threads > 0:
+            sess_options = onnxruntime.SessionOptions()
+            sess_options.intra_op_num_threads = num_threads
+            sess_options.inter_op_num_threads = 1
+
+        self.app = FaceAnalysis(
+            name=model_name,
+            providers=providers,
+            allowed_modules=_REQUIRED_MODULES,
+            sess_options=sess_options,
+        )
+        self.app.prepare(ctx_id=ctx_id, det_size=det_size)
+
+    def detect(self, frame_bgr: np.ndarray) -> List[Face]:
+        """Returns InsightFace Face objects with .bbox, .det_score, .normed_embedding (512-d, L2-normed)."""
+        return self.app.get(frame_bgr)

identity_store.py

@@ -0,0 +1,45 @@
+"""In-memory FAISS gallery assigning persistent person IDs to face embeddings.
+
+Duplicated from ../app/identity_store.py for this standalone web demo deployable
+(see face_engine.py for why). Here, one instance lives per browser session
+(held in gr.State), not per process - nothing persists between visitors.
+"""
+from typing import List
+
+import faiss
+import numpy as np
+
+
+class IdentityStore:
+    """Cosine-similarity gallery over L2-normalized ArcFace embeddings.
+
+    Uses FAISS IndexFlatIP (inner product), which equals cosine similarity
+    when all stored and query vectors are L2-normalized.
+    """
+
+    def __init__(self, embedding_dim: int = 512, match_threshold: float = 0.38) -> None:
+        self.embedding_dim = embedding_dim
+        self.match_threshold = match_threshold
+        self.index = faiss.IndexFlatIP(embedding_dim)
+        self._next_person_id = 1
+        self.person_ids: List[int] = []
+
+    def match_or_register(self, normed_embedding: np.ndarray) -> int:
+        """Finds the closest known identity; registers a new one if none is close enough."""
+        query = normed_embedding.astype(np.float32).reshape(1, -1)
+
+        if self.index.ntotal > 0:
+            similarities, indices = self.index.search(query, 1)
+            best_similarity = float(similarities[0, 0])
+            best_index = int(indices[0, 0])
+            if best_similarity >= self.match_threshold:
+                return self.person_ids[best_index]
+
+        person_id = self._next_person_id
+        self._next_person_id += 1
+        self.index.add(query)
+        self.person_ids.append(person_id)
+        return person_id
+
+    def __len__(self) -> int:
+        return self.index.ntotal

requirements.txt

@@ -0,0 +1,17 @@
+# Standalone deployable for Hugging Face Spaces (Python 3.10, CPU Basic).
+# Headless OpenCV (no GUI bindings/libGL needed) - do NOT use opencv-python
+# here, it will fail to import on the Space's headless Linux container.
+numpy==1.26.4
+opencv-python-headless==4.10.0.84
+onnxruntime==1.17.3
+insightface==0.7.3
+faiss-cpu==1.7.4
+supervision==0.24.0
+gradio==5.9.1
+# Pinned: pydantic>=2.11 changed how it emits JSON schema for open/Any-typed
+# values (e.g. our gr.State tuple) to `additionalProperties: true` (a bool).
+# gradio_client's schema walker doesn't handle that and crashes on every page
+# load ("TypeError: argument of type 'bool' is not iterable"). insightface's
+# albumentations dependency requires pydantic>=2.9.2, so stay on the 2.10.x
+# line - the last one before the regression - rather than going lower.
+pydantic==2.10.6