lvface 0.1.0__py3-none-any.whl

lvface/__init__.py

@@ -0,0 +1,37 @@
+"""Modern face-embedding framework."""
+
+from . import metrics
+from .detect import FaceDetector, InsightFaceDetector
+from .embed import FaceEmbedder, LVFaceOnnxEmbedder
+from .errors import AlignmentError, NoFaceError
+from .hub import resolve_weights
+from .io import load_image
+from .recognizer import FaceRecognizer
+from .registry import DEFAULT_MODEL, MODELS, Model, resolve_model_path
+from .types import BBox, ComparisonResult, Embedding, Face, Match, MatchResult
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AlignmentError",
+    "BBox",
+    "ComparisonResult",
+    "DEFAULT_MODEL",
+    "Embedding",
+    "Face",
+    "FaceDetector",
+    "FaceEmbedder",
+    "FaceRecognizer",
+    "InsightFaceDetector",
+    "LVFaceOnnxEmbedder",
+    "MODELS",
+    "Match",
+    "MatchResult",
+    "Model",
+    "NoFaceError",
+    "__version__",
+    "load_image",
+    "metrics",
+    "resolve_model_path",
+    "resolve_weights",
+]

lvface/detect/__init__.py

@@ -0,0 +1,16 @@
+"""Face detection and alignment backends."""
+
+from lvface.errors import AlignmentError
+
+from .align import ARCFACE_DST, estimate_norm, norm_crop
+from .base import FaceDetector
+from .insightface import InsightFaceDetector
+
+__all__ = [
+    "ARCFACE_DST",
+    "AlignmentError",
+    "FaceDetector",
+    "InsightFaceDetector",
+    "estimate_norm",
+    "norm_crop",
+]

lvface/detect/align.py

@@ -0,0 +1,196 @@
+"""Five-point ArcFace alignment without OpenCV."""
+
+from __future__ import annotations
+
+import numpy as np
+import numpy.typing as npt
+from PIL import Image
+
+from lvface.errors import AlignmentError
+
+ARCFACE_DST: npt.NDArray[np.float32] = np.array(
+    [
+        [38.2946, 51.6963],
+        [73.5318, 51.5014],
+        [56.0252, 71.7366],
+        [41.5493, 92.3655],
+        [70.7299, 92.2041],
+    ],
+    dtype=np.float32,
+)
+ARCFACE_DST.setflags(write=False)
+
+
+def _landmarks_array(kps: object) -> npt.NDArray[np.float64]:
+    """Validate five-point landmarks as a float64 array.
+
+    Args:
+        kps: Array-like landmark coordinates.
+
+    Returns:
+        A finite, nondegenerate array with shape ``(5, 2)``.
+    """
+    try:
+        landmarks = np.asarray(kps, dtype=np.float64)
+    except (TypeError, ValueError) as error:
+        raise AlignmentError("landmarks must be a numeric array with shape (5, 2)") from error
+
+    if landmarks.shape != (5, 2):
+        raise AlignmentError(f"need exactly 5 landmarks with shape (5, 2), got {landmarks.shape}")
+
+    if not np.isfinite(landmarks).all():
+        raise AlignmentError("landmarks must contain only finite coordinates")
+
+    if np.linalg.matrix_rank(landmarks - landmarks.mean(axis=0)) < 2:
+        raise AlignmentError("degenerate landmark geometry; cannot align")
+
+    return landmarks
+
+
+def _umeyama(
+    source: npt.NDArray[np.float64],
+    destination: npt.NDArray[np.float64],
+) -> npt.NDArray[np.float64] | None:
+    """Estimate a 2D similarity transform with Umeyama's method.
+
+    Args:
+        source: Source points with shape ``(N, 2)``.
+        destination: Destination points with shape ``(N, 2)``.
+
+    Returns:
+        A ``(2, 3)`` affine matrix, or ``None`` for degenerate points.
+    """
+    source_mean = source.mean(axis=0)
+    destination_mean = destination.mean(axis=0)
+    source_centered = source - source_mean
+    destination_centered = destination - destination_mean
+    source_variance = np.sum(source_centered**2) / source.shape[0]
+    if source_variance <= np.finfo(np.float64).eps:
+        return None
+
+    covariance = destination_centered.T @ source_centered / source.shape[0]
+    u, singular_values, vh = np.linalg.svd(covariance)
+    signs = np.ones(source.shape[1], dtype=np.float64)
+    if np.linalg.det(covariance) < 0:
+        signs[-1] = -1.0
+
+    rank = np.linalg.matrix_rank(covariance)
+    if rank == 0:
+        return None
+
+    if rank == source.shape[1] - 1:
+        if np.linalg.det(u) * np.linalg.det(vh) > 0:
+            rotation = u @ vh
+        else:
+            final_sign = signs[-1]
+            signs[-1] = -1.0
+            rotation = u @ np.diag(signs) @ vh
+            signs[-1] = final_sign
+    else:
+        rotation = u @ np.diag(signs) @ vh
+
+    scale = float(singular_values @ signs) / source_variance
+    matrix = np.empty((2, 3), dtype=np.float64)
+    matrix[:, :2] = scale * rotation
+    matrix[:, 2] = destination_mean - scale * rotation @ source_mean
+    return matrix
+
+
+def _invert_affine(matrix: npt.NDArray[np.floating]) -> npt.NDArray[np.float64]:
+    """Invert a two-dimensional affine transform.
+
+    Args:
+        matrix: Affine matrix with shape ``(2, 3)``.
+
+    Returns:
+        The inverse affine matrix.
+    """
+    linear = np.asarray(matrix[:, :2], dtype=np.float64)
+    translation = np.asarray(matrix[:, 2], dtype=np.float64)
+    try:
+        inverse_linear = np.linalg.inv(linear)
+    except np.linalg.LinAlgError as error:
+        raise AlignmentError("alignment transform is not invertible") from error
+
+    inverse = np.empty((2, 3), dtype=np.float64)
+    inverse[:, :2] = inverse_linear
+    with np.errstate(invalid="ignore"):
+        inverse[:, 2] = -inverse_linear @ translation
+
+    if not np.isfinite(inverse).all():
+        raise AlignmentError("alignment transform is not finite")
+
+    return inverse
+
+
+def estimate_norm(kps: object, size: int = 112) -> npt.NDArray[np.float32]:
+    """Estimate the transform from landmarks to the ArcFace template.
+
+    Args:
+        kps: Five facial landmarks with shape ``(5, 2)``.
+        size: Output crop size; LVFace supports only 112.
+
+    Returns:
+        A float32 affine matrix with shape ``(2, 3)``.
+    """
+    if size != 112:
+        raise AlignmentError("only size=112 is supported for LVFace alignment")
+
+    landmarks = _landmarks_array(kps)
+    matrix = _umeyama(landmarks, ARCFACE_DST.astype(np.float64))
+    if matrix is None or not np.isfinite(matrix).all():
+        raise AlignmentError("degenerate landmark geometry; cannot align")
+
+    return matrix.astype(np.float32)
+
+
+def _validate_image(image: object) -> npt.NDArray[np.uint8]:
+    """Validate an RGB uint8 image array.
+
+    Args:
+        image: Object expected to be a non-empty RGB image.
+
+    Returns:
+        The validated image without copying it.
+    """
+    if not isinstance(image, np.ndarray):
+        raise TypeError("image must be a NumPy array")
+
+    if image.ndim != 3 or image.shape[2] != 3 or image.shape[0] == 0 or image.shape[1] == 0:
+        raise ValueError(f"image must have non-zero shape (H, W, 3), got {image.shape}")
+
+    if image.dtype != np.uint8:
+        raise ValueError(f"image must have dtype uint8, got {image.dtype}")
+
+    return image
+
+
+def norm_crop(
+    image: np.ndarray,
+    kps: object,
+    size: int = 112,
+) -> npt.NDArray[np.uint8]:
+    """Align an RGB image to an ArcFace crop using Pillow.
+
+    Args:
+        image: Source RGB uint8 image.
+        kps: Five facial landmarks with shape ``(5, 2)``.
+        size: Output width and height; LVFace supports only 112.
+
+    Returns:
+        An owned aligned RGB uint8 crop.
+    """
+    source = _validate_image(image)
+    matrix = estimate_norm(kps, size)
+    inverse = _invert_affine(matrix)
+
+    # Pillow samples pixel centers, so shift the affine transform by half a pixel.
+    inverse[:, 2] += 0.5 - inverse[:, :2] @ np.full(2, 0.5)
+    coefficients = tuple(float(value) for value in inverse.reshape(-1))
+    aligned = Image.fromarray(source, mode="RGB").transform(
+        (size, size),
+        Image.Transform.AFFINE,
+        coefficients,
+        resample=Image.Resampling.BILINEAR,
+    )
+    return np.array(aligned, dtype=np.uint8, order="C", copy=True)

lvface/detect/base.py

@@ -0,0 +1,71 @@
+"""Shared face detector and aligner adapter."""
+
+from abc import ABC, abstractmethod
+
+import numpy as np
+
+from lvface.types import Face
+
+from .align import norm_crop
+
+
+class FaceDetector(ABC):
+    """Base class for pluggable face detection and alignment backends."""
+
+    @abstractmethod
+    def load(self) -> None:
+        """Lazily initialize the detection backend."""
+
+    @abstractmethod
+    def detect(self, image: np.ndarray) -> list[Face]:
+        """Detect faces and five-point landmarks in an RGB image.
+
+        Args:
+            image: Source RGB uint8 image.
+
+        Returns:
+            Detected faces in backend order.
+        """
+
+    def align(self, image: np.ndarray, kps: np.ndarray, size: int = 112) -> np.ndarray:
+        """Align five landmarks to the canonical ArcFace template.
+
+        Args:
+            image: Source RGB uint8 image.
+            kps: Five facial landmarks with shape ``(5, 2)``.
+            size: Output crop size.
+
+        Returns:
+            The aligned RGB crop.
+        """
+        return norm_crop(image, kps, size)
+
+    def crop(self, image: np.ndarray) -> list[np.ndarray]:
+        """Detect and align every face that has landmarks.
+
+        Args:
+            image: Source RGB uint8 image.
+
+        Returns:
+            Aligned crops for faces with five-point landmarks.
+        """
+        self.load()
+        return [self.align(image, face.kps) for face in self.detect(image) if face.kps is not None]
+
+    def detect_and_align(self, image: np.ndarray) -> list[Face]:
+        """Detect faces and attach crops when landmarks are available.
+
+        Args:
+            image: Source RGB uint8 image.
+
+        Returns:
+            Detected faces, with aligned crops where possible.
+        """
+        self.load()
+        faces = self.detect(image)
+
+        for face in faces:
+            if face.kps is not None:
+                face.aligned = self.align(image, face.kps)
+
+        return faces

lvface/detect/insightface.py

@@ -0,0 +1,191 @@
+"""InsightFace detection and reference alignment backend."""
+
+from __future__ import annotations
+
+import threading
+import warnings
+from typing import Any
+
+import numpy as np
+
+from lvface.embed.onnx import Device, _resolve_providers
+from lvface.types import BBox, Face
+
+from .align import _validate_image, estimate_norm
+from .base import FaceDetector
+
+_LICENSE_WARNING = (
+    "InsightFace bundled model packs are licensed for non-commercial research use only. "
+    "Use a detector with appropriately licensed weights or pre-aligned crops for other uses."
+)
+_license_warning_lock = threading.Lock()
+_license_warning_emitted = False
+
+
+def _warn_about_model_license() -> None:
+    """Emit the InsightFace model-license warning once per process."""
+    global _license_warning_emitted
+    if _license_warning_emitted:
+        return
+    with _license_warning_lock:
+        if _license_warning_emitted:
+            return
+        warnings.warn(_LICENSE_WARNING, UserWarning, stacklevel=3)
+        _license_warning_emitted = True
+
+
+def _import_insightface() -> tuple[type[Any], Any]:
+    """Import optional InsightFace detection components.
+
+    Returns:
+        The ``FaceAnalysis`` class and face-alignment module.
+    """
+    try:
+        from insightface.app import FaceAnalysis
+        from insightface.utils import face_align
+    except ModuleNotFoundError as error:
+        if error.name == "insightface":
+            raise ImportError(
+                'InsightFace detection requires `pip install "lvface[detect]"`'
+            ) from error
+        raise
+    return FaceAnalysis, face_align
+
+
+class InsightFaceDetector(FaceDetector):
+    """Face detector using InsightFace detection landmarks."""
+
+    def __init__(
+        self,
+        name: str = "buffalo_l",
+        *,
+        device: Device = "auto",
+        det_size: tuple[int, int] = (640, 640),
+        min_score: float = 0.5,
+    ) -> None:
+        """Configure the InsightFace detector.
+
+        Args:
+            name: InsightFace model-pack name.
+            device: Preferred inference device.
+            det_size: Detection input width and height.
+            min_score: Minimum confidence retained as a face.
+        """
+        if not name:
+            raise ValueError("name must not be empty")
+
+        if (
+            len(det_size) != 2
+            or any(isinstance(value, bool) or not isinstance(value, int) for value in det_size)
+            or any(value <= 0 for value in det_size)
+        ):
+            raise ValueError("det_size must contain two positive integers")
+
+        if not np.isfinite(min_score) or not 0.0 <= min_score <= 1.0:
+            raise ValueError("min_score must be finite and between 0 and 1")
+
+        self.name = name
+        self.device = device
+        self.det_size = det_size
+        self.min_score = float(min_score)
+        self.app: Any | None = None
+        self._face_align: Any | None = None
+        self._load_lock = threading.Lock()
+
+    def load(self) -> None:
+        """Initialize the requested InsightFace detection pack once."""
+        if self.app is not None:
+            return
+        with self._load_lock:
+            if self.app is not None:
+                return
+
+            providers = _resolve_providers(self.device)
+            face_analysis, face_align = _import_insightface()
+            _warn_about_model_license()
+            app = face_analysis(
+                name=self.name,
+                allowed_modules=["detection"],
+                providers=providers,
+            )
+            ctx_id = 0 if providers[0] == "CUDAExecutionProvider" else -1
+            app.prepare(ctx_id=ctx_id, det_size=self.det_size)
+            self._face_align = face_align
+            self.app = app
+
+    def detect(self, image: np.ndarray) -> list[Face]:
+        """Detect faces with InsightFace.
+
+        Args:
+            image: Source RGB uint8 image.
+
+        Returns:
+            Faces meeting the configured confidence threshold.
+        """
+        source = _validate_image(image)
+        self.load()
+        if self.app is None:
+            raise RuntimeError("detector failed to initialize")
+
+        bgr = np.ascontiguousarray(source[:, :, ::-1])
+        detected = self.app.get(bgr)
+        faces: list[Face] = []
+
+        for detected_face in detected:
+            score = float(detected_face.det_score)
+            if not np.isfinite(score) or score < self.min_score:
+                continue
+
+            coordinates = np.asarray(detected_face.bbox, dtype=np.float64)
+            if coordinates.shape != (4,) or not np.isfinite(coordinates).all():
+                raise ValueError("InsightFace returned an invalid bounding box")
+
+            landmarks = getattr(detected_face, "kps", None)
+            if landmarks is not None:
+                landmarks = np.asarray(landmarks, dtype=np.float32)
+                if landmarks.shape != (5, 2) or not np.isfinite(landmarks).all():
+                    raise ValueError("InsightFace returned invalid five-point landmarks")
+
+            faces.append(
+                Face(
+                    bbox=BBox(
+                        float(coordinates[0]),
+                        float(coordinates[1]),
+                        float(coordinates[2]),
+                        float(coordinates[3]),
+                        score,
+                    ),
+                    kps=landmarks,
+                    aligned=None,
+                    embedding=None,
+                    face_index=len(faces),
+                )
+            )
+        return faces
+
+    def align(self, image: np.ndarray, kps: np.ndarray, size: int = 112) -> np.ndarray:
+        """Align an RGB image with InsightFace's reference warp.
+
+        Args:
+            image: Source RGB uint8 image.
+            kps: Five facial landmarks with shape ``(5, 2)``.
+            size: Output crop size.
+
+        Returns:
+            An aligned RGB uint8 crop.
+        """
+        source = _validate_image(image)
+        estimate_norm(kps, size)
+        self.load()
+        if self._face_align is None:
+            raise RuntimeError("detector failed to initialize")
+
+        aligned = np.asarray(self._face_align.norm_crop(source, landmark=kps, image_size=size))
+        result = _validate_image(aligned)
+        expected_shape = (size, size, 3)
+
+        if result.shape != expected_shape:
+            raise ValueError(
+                f"InsightFace alignment returned shape {result.shape}, expected {expected_shape}"
+            )
+        return result

lvface/embed/__init__.py

@@ -0,0 +1,6 @@
+"""Face embedding backends."""
+
+from .base import FaceEmbedder
+from .onnx import LVFaceOnnxEmbedder
+
+__all__ = ["FaceEmbedder", "LVFaceOnnxEmbedder"]

lvface/embed/base.py

@@ -0,0 +1,126 @@
+"""Shared face-embedding adapter."""
+
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+
+import numpy as np
+import numpy.typing as npt
+
+from lvface.types import Embedding
+
+
+class FaceEmbedder(ABC):
+    """Base class for face-embedding backends."""
+
+    input_size: tuple[int, int] = (112, 112)
+    embedding_dim: int = 512
+    _fixed_batch_size: int | None = None
+
+    @abstractmethod
+    def load(self) -> None:
+        """Lazily initialize the embedding backend."""
+
+    @abstractmethod
+    def _forward(self, batch: npt.NDArray[np.float32]) -> npt.NDArray[np.floating]:
+        """Run inference for a normalized NCHW batch.
+
+        Args:
+            batch: Preprocessed float32 images with shape ``(N, C, H, W)``.
+
+        Returns:
+            Raw embedding vectors with shape ``(N, embedding_dim)``.
+        """
+
+    def preprocess(self, crop: np.ndarray) -> npt.NDArray[np.float32]:
+        """Convert an aligned RGB crop to a normalized CHW tensor.
+
+        Args:
+            crop: RGB uint8 crop matching ``input_size``.
+
+        Returns:
+            A contiguous normalized float32 CHW tensor.
+        """
+        expected_shape = (*self.input_size, 3)
+        if not isinstance(crop, np.ndarray):
+            raise TypeError("crop must be a NumPy array")
+
+        if crop.shape != expected_shape:
+            raise ValueError(f"crop must have shape {expected_shape}, got {crop.shape}")
+
+        if crop.dtype != np.uint8:
+            raise ValueError(f"crop must have dtype uint8, got {crop.dtype}")
+
+        chw = np.transpose(crop, (2, 0, 1))
+        normalized = ((chw / 255.0) - 0.5) / 0.5
+        return np.ascontiguousarray(normalized, dtype=np.float32)
+
+    def embed(self, crop: np.ndarray, *, normalize: bool = True) -> Embedding:
+        """Embed one aligned RGB crop.
+
+        Args:
+            crop: RGB uint8 crop matching ``input_size``.
+            normalize: Whether to L2-normalize the embedding.
+
+        Returns:
+            The generated face embedding.
+        """
+        return self.embed_batch([crop], normalize=normalize, batch_size=1)[0]
+
+    def embed_batch(
+        self,
+        crops: Sequence[np.ndarray],
+        *,
+        normalize: bool = True,
+        batch_size: int = 32,
+    ) -> list[Embedding]:
+        """Embed aligned crops while respecting the backend batch contract.
+
+        Args:
+            crops: Aligned RGB uint8 crops.
+            normalize: Whether to L2-normalize each embedding.
+            batch_size: Maximum batch size for dynamic-batch backends.
+
+        Returns:
+            Embeddings in the same order as ``crops``.
+        """
+        if batch_size <= 0:
+            raise ValueError("batch_size must be greater than zero")
+
+        crop_list = list(crops)
+        if not crop_list:
+            return []
+
+        tensors = [self.preprocess(crop) for crop in crop_list]
+        self.load()
+        required_batch = self._fixed_batch_size
+        chunk_size = batch_size if required_batch is None else required_batch
+        vectors: list[npt.NDArray[np.floating]] = []
+
+        for start in range(0, len(tensors), chunk_size):
+            chunk = tensors[start : start + chunk_size]
+            real_size = len(chunk)
+
+            # Some exported models only accept one fixed batch size.
+            if required_batch is not None and real_size < required_batch:
+                chunk.extend([chunk[-1]] * (required_batch - real_size))
+
+            batch = np.stack(chunk)
+            output = np.asarray(self._forward(batch))
+            if output.ndim != 2 or output.shape != (len(chunk), self.embedding_dim):
+                raise ValueError(
+                    "backend returned invalid embedding shape "
+                    f"{output.shape}; expected {(len(chunk), self.embedding_dim)}"
+                )
+
+            if not np.issubdtype(output.dtype, np.floating):
+                raise ValueError(f"backend returned non-floating embeddings: {output.dtype}")
+
+            if not np.isfinite(output).all():
+                raise ValueError("backend returned an embedding containing NaN/Inf")
+
+            vectors.extend(output[:real_size])
+
+        embeddings = [Embedding(vector) for vector in vectors]
+        if normalize:
+            return [embedding.normalize() for embedding in embeddings]
+        return embeddings