facekey 0.0.1__py3-none-any.whl

facekey/__init__.py

@@ -0,0 +1,71 @@
+"""facekey - Face-ID-style unlock for your app.
+
+See the README for the security caveats and model licensing. Quick start::
+
+    from facekey import FaceLock
+
+    lock = FaceLock()
+    lock.run_enrollment(camera=0, on_prompt=print)
+    if lock.unlock(camera=0, timeout=5):
+        ...
+"""
+
+from __future__ import annotations
+
+from .core import FaceLock, __version__
+from .embedders import Embedder, get_embedder, register
+from .enrollment import EnrollmentSession
+from .errors import (
+    EnrollmentIncomplete,
+    FaceKeyError,
+    FaceKeyLicenseWarning,
+    LivenessCheckFailed,
+    LowQualityFrame,
+    ModelDownloadError,
+    MultipleFacesDetected,
+    NoFaceDetected,
+    NotEnrolled,
+    StoreFull,
+    WeakLivenessWarning,
+)
+from .liveness import HeuristicLiveness, LivenessChecker, NullLiveness
+from .matching import DEFAULT_THRESHOLD, cosine_similarity
+from .models import AuthResult, CaptureResult, FaceObservation, FaceTemplate, PoseBucket
+from .stores import FileStore, SQLiteStore, Store
+
+__all__ = [
+    "__version__",
+    "FaceLock",
+    "EnrollmentSession",
+    "AuthResult",
+    "CaptureResult",
+    "FaceObservation",
+    "FaceTemplate",
+    "PoseBucket",
+    "DEFAULT_THRESHOLD",
+    "cosine_similarity",
+    # embedders
+    "Embedder",
+    "get_embedder",
+    "register",
+    # liveness
+    "LivenessChecker",
+    "HeuristicLiveness",
+    "NullLiveness",
+    # stores
+    "Store",
+    "FileStore",
+    "SQLiteStore",
+    # errors / warnings
+    "FaceKeyError",
+    "NoFaceDetected",
+    "MultipleFacesDetected",
+    "LowQualityFrame",
+    "LivenessCheckFailed",
+    "NotEnrolled",
+    "EnrollmentIncomplete",
+    "StoreFull",
+    "ModelDownloadError",
+    "FaceKeyLicenseWarning",
+    "WeakLivenessWarning",
+]

facekey/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

facekey/_image.py

@@ -0,0 +1,68 @@
+"""Frame coercion and quality gating shared by enrollment and auth."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Union
+
+import cv2
+import numpy as np
+
+from .errors import LowQualityFrame
+from .models import FaceObservation
+
+Frame = Union[np.ndarray, bytes, bytearray, memoryview]
+
+
+def to_bgr(frame: Frame) -> np.ndarray:
+    """Coerce a frame to an ``H x W x 3`` uint8 BGR array.
+
+    Accepts a decoded ndarray (BGR or grayscale) or encoded image bytes
+    (PNG/JPEG/...). Raises :class:`ValueError` if it cannot be interpreted.
+    """
+    if isinstance(frame, np.ndarray):
+        img = frame
+        if img.ndim == 2:
+            return cv2.cvtColor(img, cv2.COLOR_GRAY2BGR)
+        if img.ndim == 3 and img.shape[2] == 4:
+            return cv2.cvtColor(img, cv2.COLOR_BGRA2BGR)
+        if img.ndim == 3 and img.shape[2] == 3:
+            return np.ascontiguousarray(img)
+        raise ValueError(f"unsupported image array shape: {img.shape}")
+
+    if isinstance(frame, (bytes, bytearray, memoryview)):
+        buf = np.frombuffer(bytes(frame), dtype=np.uint8)
+        img = cv2.imdecode(buf, cv2.IMREAD_COLOR)
+        if img is None:
+            raise ValueError("could not decode image bytes")
+        return img
+
+    raise ValueError(f"unsupported frame type: {type(frame)!r}")
+
+
+@dataclass
+class QualityPolicy:
+    """Thresholds a detected face must clear to be usable."""
+
+    min_face_fraction: float = 0.06   # face bbox width / frame width
+    min_det_score: float = 0.60
+    min_sharpness: float = 40.0       # variance of Laplacian over the face crop
+
+    def check(self, bgr: np.ndarray, obs: FaceObservation) -> None:
+        """Raise :class:`LowQualityFrame` if ``obs`` is not good enough."""
+        frame_w = bgr.shape[1]
+        x1, y1, x2, y2 = (int(round(v)) for v in obs.bbox)
+        face_w = max(1, x2 - x1)
+
+        if face_w / frame_w < self.min_face_fraction:
+            raise LowQualityFrame("face too small in frame; move closer")
+
+        if obs.det_score < self.min_det_score:
+            raise LowQualityFrame(f"weak detection ({obs.det_score:.2f})")
+
+        crop = bgr[max(0, y1):max(1, y2), max(0, x1):max(1, x2)]
+        if crop.size:
+            gray = cv2.cvtColor(crop, cv2.COLOR_BGR2GRAY)
+            sharpness = float(cv2.Laplacian(gray, cv2.CV_64F).var())
+            if sharpness < self.min_sharpness:
+                raise LowQualityFrame(f"frame too blurry (sharpness {sharpness:.0f})")

facekey/camera.py

@@ -0,0 +1,117 @@
+"""Optional webcam helpers built on the frame-based API.
+
+Nothing else in facekey imports this module; it is only pulled in when you call
+``FaceLock.unlock()`` / ``FaceLock.run_enrollment()`` or use :class:`Camera`
+directly. ``cv2.VideoCapture`` is available in the base install
+(opencv-python-headless); ``pip install "facekey[camera]"`` additionally brings
+the highgui build if you want to show a preview window yourself.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Callable, Optional
+
+import cv2
+
+from .errors import FaceKeyError
+from .models import FaceTemplate, PoseBucket
+
+PROMPTS = {
+    PoseBucket.FRONTAL: "Look straight at the camera",
+    PoseBucket.LEFT: "Turn your head to your left",
+    PoseBucket.RIGHT: "Turn your head to your right",
+    PoseBucket.UP: "Tilt your head up",
+    PoseBucket.DOWN: "Tilt your head down",
+}
+
+
+class Camera:
+    """Context manager around a single ``cv2.VideoCapture`` device."""
+
+    def __init__(self, index: int = 0) -> None:
+        self.index = index
+        self._cap: "Optional[cv2.VideoCapture]" = None
+
+    def __enter__(self) -> "Camera":
+        self._cap = cv2.VideoCapture(self.index)
+        if not self._cap or not self._cap.isOpened():
+            raise FaceKeyError(f"could not open camera {self.index}")
+        return self
+
+    def __exit__(self, *exc) -> None:
+        if self._cap is not None:
+            self._cap.release()
+            self._cap = None
+
+    def read(self):
+        assert self._cap is not None, "use Camera as a context manager"
+        ok, frame = self._cap.read()
+        if not ok:
+            raise FaceKeyError("failed to read a frame from the camera")
+        return frame
+
+
+def capture_until_match(
+    lock,
+    *,
+    camera: int = 0,
+    timeout: float = 5.0,
+    enrollee: "Optional[str]" = None,
+    interval: float = 0.15,
+) -> bool:
+    """Poll the camera until :meth:`FaceLock.authenticate` grants or time runs out."""
+    deadline = time.monotonic() + timeout
+    with Camera(camera) as cam:
+        while time.monotonic() < deadline:
+            try:
+                if lock.authenticate(cam.read(), enrollee=enrollee).granted:
+                    return True
+            except FaceKeyError:
+                pass  # no face / multiple faces this frame; keep trying
+            time.sleep(interval)
+    return False
+
+
+def guided_enrollment(
+    lock,
+    *,
+    camera: int = 0,
+    label: str = "default",
+    on_prompt: "Optional[Callable[[str], None]]" = None,
+    attempts_per_pose: int = 60,
+    interval: float = 0.1,
+) -> FaceTemplate:
+    """Walk the user through every required pose, then commit and store.
+
+    ``on_prompt`` receives short instruction strings ("Turn your head to your
+    left", ...) so you can render them however you like.
+    """
+    say = on_prompt or (lambda _msg: None)
+    session = lock.enroll(label)
+
+    with Camera(camera) as cam:
+        last_prompt = None
+        while session.needs:
+            target = session.needs[0]
+            bucket = PoseBucket(target)
+            prompt = PROMPTS.get(bucket, f"Show pose: {target}")
+            if prompt != last_prompt:
+                say(prompt)
+                last_prompt = prompt
+
+            got_it = False
+            for _ in range(attempts_per_pose):
+                result = session.capture(cam.read())
+                if result.accepted and result.bucket == bucket:
+                    say(f"Got it ({target}).")
+                    got_it = True
+                    break
+                time.sleep(interval)
+            if not got_it:
+                say(f"Still need {target} - trying again.")
+
+    template = session.commit()
+    lock.store.put(template)
+    say("Enrollment complete.")
+    return template

facekey/cli.py

@@ -0,0 +1,111 @@
+"""``facekey`` command-line interface.
+
+    facekey download-models        pre-fetch the embedder model pack
+    facekey enroll [--label L]     guided enrollment via the webcam
+    facekey test                   try one unlock and print the result
+    facekey list                   show enrolled labels
+    facekey remove --label L       delete a template
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+
+def _add_common(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--store", default=None, help="path to the template store (default: user data dir)")
+    p.add_argument("--camera", type=int, default=0, help="camera index (default: 0)")
+    p.add_argument("--no-liveness", action="store_true", help="disable the passive liveness check")
+
+
+def _build_lock(args):
+    from .core import FaceLock
+
+    return FaceLock(store=args.store, liveness=not args.no_liveness)
+
+
+def cmd_download_models(args) -> int:
+    from .embedders import get_embedder
+
+    emb = get_embedder("buffalo_l" if not getattr(args, "model", None) else args.model)
+    print(f"Preparing embedder {emb.name!r} (first run downloads ~300 MB)...")
+    emb.detect(_black_frame())
+    print("Model pack ready.")
+    return 0
+
+
+def cmd_enroll(args) -> int:
+    lock = _build_lock(args)
+    print(f"Enrolling {args.label!r}. Follow the prompts.")
+    lock.run_enrollment(camera=args.camera, label=args.label, on_prompt=print)
+    return 0
+
+
+def cmd_test(args) -> int:
+    lock = _build_lock(args)
+    if not lock.is_enrolled():
+        print("Nothing enrolled yet. Run `facekey enroll` first.", file=sys.stderr)
+        return 2
+    granted = lock.unlock(camera=args.camera, timeout=args.timeout)
+    print("ACCESS GRANTED" if granted else "ACCESS DENIED")
+    return 0 if granted else 1
+
+
+def cmd_list(args) -> int:
+    lock = _build_lock(args)
+    labels = lock.enrolled()
+    print("\n".join(labels) if labels else "(nothing enrolled)")
+    return 0
+
+
+def cmd_remove(args) -> int:
+    lock = _build_lock(args)
+    print("removed" if lock.remove(args.label) else "no such label")
+    return 0
+
+
+def _black_frame():
+    import numpy as np
+
+    return np.zeros((320, 320, 3), dtype=np.uint8)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="facekey", description=__doc__,
+                                     formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("download-models", help="pre-fetch the embedder model pack")
+    p.add_argument("--model", default="buffalo_l")
+    p.set_defaults(func=cmd_download_models)
+
+    p = sub.add_parser("enroll", help="guided webcam enrollment")
+    _add_common(p)
+    p.add_argument("--label", default="default")
+    p.set_defaults(func=cmd_enroll)
+
+    p = sub.add_parser("test", help="attempt one unlock")
+    _add_common(p)
+    p.add_argument("--timeout", type=float, default=5.0)
+    p.set_defaults(func=cmd_test)
+
+    p = sub.add_parser("list", help="show enrolled labels")
+    _add_common(p)
+    p.set_defaults(func=cmd_list)
+
+    p = sub.add_parser("remove", help="delete a template")
+    _add_common(p)
+    p.add_argument("--label", required=True)
+    p.set_defaults(func=cmd_remove)
+
+    return parser
+
+
+def main(argv: "list[str] | None" = None) -> int:
+    args = build_parser().parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

facekey/core.py

@@ -0,0 +1,198 @@
+"""``FaceLock`` — the top-level entry point."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+from ._image import Frame, QualityPolicy, to_bgr
+from .embedders import Embedder, get_embedder
+from .enrollment import EnrollmentSession
+from .errors import (
+    MultipleFacesDetected,
+    NoFaceDetected,
+    NotEnrolled,
+    StoreFull,
+)
+from .liveness import DEFAULT_LIVENESS_THRESHOLD, LivenessChecker, make_liveness
+from .matching import DEFAULT_THRESHOLD, decide, identify, match_template
+from .models import AuthResult, FaceObservation
+from .stores import FileStore, Store
+
+__version__ = "0.0.1"
+
+
+class FaceLock:
+    """Enroll a face, then authenticate camera frames against it.
+
+    Parameters
+    ----------
+    store:
+        ``None`` for a JSON store under the per-user data dir, a path for a
+        :class:`~facekey.stores.FileStore` there, or any :class:`Store`.
+    threshold:
+        Cosine-similarity cut-off for a match (higher = stricter).
+    liveness:
+        ``True`` (default) runs passive anti-spoofing; ``False`` skips it.
+    model:
+        Embedder name passed to :func:`~facekey.embedders.get_embedder` unless
+        an explicit ``embedder`` is given.
+    max_enrollees:
+        Upper bound on stored templates. ``1`` today; raise for a shared device.
+    gpu:
+        ``True`` or a device index to run the embedder on GPU.
+    """
+
+    def __init__(
+        self,
+        store: "Store | str | Path | None" = None,
+        *,
+        threshold: float = DEFAULT_THRESHOLD,
+        liveness: bool = True,
+        model: str = "buffalo_l",
+        max_enrollees: int = 1,
+        gpu: "bool | int" = False,
+        embedder: "Optional[Embedder]" = None,
+        liveness_checker: "Optional[LivenessChecker]" = None,
+        liveness_threshold: float = DEFAULT_LIVENESS_THRESHOLD,
+        quality: "Optional[QualityPolicy]" = None,
+    ) -> None:
+        if isinstance(store, (str, Path)):
+            self.store: Store = FileStore(store)
+        elif store is None:
+            self.store = FileStore()
+        else:
+            self.store = store
+
+        self.threshold = threshold
+        self.max_enrollees = max_enrollees
+        self.quality = quality or QualityPolicy()
+        self.liveness_threshold = liveness_threshold
+
+        self._embedder = embedder or get_embedder(model, gpu=gpu)
+        self._liveness = liveness_checker or make_liveness(liveness, threshold=liveness_threshold)
+
+    # -- enrollment ------------------------------------------------------
+    def enroll(self, label: str = "default") -> EnrollmentSession:
+        existing = set(self.store.list())
+        if label not in existing and len(existing) >= self.max_enrollees:
+            raise StoreFull(
+                f"max_enrollees={self.max_enrollees} reached ({sorted(existing)})"
+            )
+        return EnrollmentSession(
+            label=label,
+            embedder=self._embedder,
+            liveness=self._liveness,
+            model_name=self._embedder.name,
+            quality=self.quality,
+            liveness_threshold=self.liveness_threshold,
+            version=__version__,
+        )
+
+    def enrolled(self) -> "list[str]":
+        return self.store.list()
+
+    def is_enrolled(self, label: "Optional[str]" = None) -> bool:
+        labels = self.store.list()
+        return bool(labels) if label is None else label in labels
+
+    def remove(self, label: str = "default") -> bool:
+        return self.store.delete(label)
+
+    def commit(self, session: EnrollmentSession, *, allow_partial: bool = False) -> None:
+        """Persist a completed :class:`EnrollmentSession`. ``session.commit()``
+        builds the template; this stores it and enforces ``max_enrollees``."""
+        template = session.commit(allow_partial=allow_partial)
+        existing = set(self.store.list())
+        if template.label not in existing and len(existing) >= self.max_enrollees:
+            raise StoreFull(f"max_enrollees={self.max_enrollees} reached")
+        self.store.put(template)
+
+    # -- authentication -----------------------------------------------
+    def authenticate(self, frame: Frame, enrollee: "Optional[str]" = None) -> AuthResult:
+        """1:1 verification. If ``enrollee`` is omitted, the sole enrolled label
+        is used (raising :class:`NotEnrolled` when there is not exactly one)."""
+        labels = self.store.list()
+        if not labels:
+            raise NotEnrolled("no faces enrolled")
+        if enrollee is None:
+            if len(labels) != 1:
+                raise NotEnrolled(
+                    f"{len(labels)} faces enrolled; pass enrollee= to pick one"
+                )
+            enrollee = labels[0]
+
+        template = self.store.get(enrollee)
+        if template is None:
+            raise NotEnrolled(f"no template for {enrollee!r}")
+
+        obs, liveness_state, live_reason = self._observe(frame)
+        if obs is None:
+            return AuthResult(False, 0.0, liveness_state, enrollee, live_reason)
+
+        score = match_template(obs.embedding, template)
+        granted = liveness_state != "failed" and decide(score, self.threshold)
+        reason = "match" if granted else ("liveness failed" if liveness_state == "failed"
+                                          else f"below threshold ({score:.3f} < {self.threshold})")
+        return AuthResult(granted, score, liveness_state, enrollee, reason)
+
+    def identify(self, frame: Frame) -> AuthResult:
+        """1:N — compare against every enrolled template, return the best."""
+        labels = self.store.list()
+        if not labels:
+            raise NotEnrolled("no faces enrolled")
+
+        obs, liveness_state, live_reason = self._observe(frame)
+        if obs is None:
+            return AuthResult(False, 0.0, liveness_state, None, live_reason)
+
+        templates = [t for t in (self.store.get(x) for x in labels) if t is not None]
+        label, score = identify(obs.embedding, templates)
+        granted = liveness_state != "failed" and decide(score, self.threshold)
+        reason = (
+            f"matched {label!r}" if granted
+            else ("liveness failed" if liveness_state == "failed"
+                  else f"best {score:.3f} < {self.threshold}")
+        )
+        return AuthResult(granted, score, liveness_state, label if granted else None, reason)
+
+    # -- camera helpers (thin; require a working cv2.VideoCapture) --------
+    def unlock(self, camera: int = 0, timeout: float = 5.0, *, enrollee: "Optional[str]" = None,
+               interval: float = 0.15) -> bool:
+        from .camera import capture_until_match
+
+        return capture_until_match(
+            self, camera=camera, timeout=timeout, enrollee=enrollee, interval=interval
+        )
+
+    def run_enrollment(self, camera: int = 0, *, label: str = "default", on_prompt=None,
+                       attempts_per_pose: int = 60):
+        from .camera import guided_enrollment
+
+        return guided_enrollment(
+            self, camera=camera, label=label, on_prompt=on_prompt,
+            attempts_per_pose=attempts_per_pose,
+        )
+
+    # -- internals -----------------------------------------------------
+    def _observe(self, frame: Frame) -> "tuple[Optional[FaceObservation], str, str]":
+        """Detect exactly one face and run liveness.
+
+        Returns ``(observation | None, liveness_state, reason)`` where
+        ``liveness_state`` is ``"passed"``, ``"failed"`` or ``"skipped"``.
+        """
+        bgr = to_bgr(frame)
+        faces = self._embedder.detect(bgr)
+        if not faces:
+            raise NoFaceDetected("no face in frame")
+        if len(faces) > 1:
+            raise MultipleFacesDetected(f"{len(faces)} faces in frame")
+
+        obs = faces[0]
+        if not self._liveness.enabled:
+            return obs, "skipped", "liveness disabled"
+        live = self._liveness.score(bgr, obs)
+        obs.liveness_score = live
+        if live < self.liveness_threshold:
+            return None, "failed", f"liveness {live:.2f} < {self.liveness_threshold}"
+        return obs, "passed", "ok"

facekey/embedders/__init__.py

@@ -0,0 +1,54 @@
+"""Pluggable face-embedding backends.
+
+An embedder turns a BGR frame into zero or more :class:`FaceObservation`s
+(bounding box, 5 keypoints, detection score, and an L2-normalized embedding).
+Swap the default by passing ``embedder=`` to :class:`facekey.FaceLock` or by
+registering a factory here.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Protocol, runtime_checkable
+
+import numpy as np
+
+from ..models import FaceObservation
+
+
+@runtime_checkable
+class Embedder(Protocol):
+    """The interface every recognition backend must satisfy."""
+
+    #: Short identifier stored on templates so a mismatch can be detected later.
+    name: str
+
+    def detect(self, bgr: np.ndarray) -> "list[FaceObservation]":
+        """Return all faces in ``bgr``, best detection first."""
+        ...
+
+
+_REGISTRY: "dict[str, Callable[..., Embedder]]" = {}
+
+
+def register(key: str, factory: "Callable[..., Embedder]") -> None:
+    _REGISTRY[key] = factory
+
+
+def get_embedder(model: str = "buffalo_l", **kwargs) -> Embedder:
+    """Build a registered embedder by name.
+
+    ``buffalo_l`` and ``buffalo_s`` map to the InsightFace backend. Any other
+    name must have been :func:`register`-ed first.
+    """
+    if model in _REGISTRY:
+        return _REGISTRY[model](**kwargs)
+    if model.startswith("buffalo_"):
+        from .insightface import InsightFaceEmbedder
+
+        return InsightFaceEmbedder(model=model, **kwargs)
+    raise KeyError(
+        f"unknown embedder {model!r}; register it via facekey.embedders.register()"
+    )
+
+
+__all__ = ["Embedder", "get_embedder", "register"]