face-engine 3.0.0__tar.gz → 3.1.0__tar.gz

{face_engine-3.0.0/face_engine.egg-info → face_engine-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: face-engine
-Version: 3.0.0
+Version: 3.1.0
 Summary: Face Recognition Engine
 Author-email: Daniyar Kussainov <ohw0sseug@gmail.com>
 License-Expression: Apache-2.0
@@ -68,23 +68,25 @@ FaceEngine is supported only on Python 3.11 and above.
 Models
 ------
 
-FaceEngine is built on top of three model interfaces ``Detector``, ``Embedder``
-and ``Estimator`` (see `models`_), and leans on user provided implementations
-of these models.
+FaceEngine is built on top of four model interfaces ``Detector``, ``Embedder``,
+``Estimator`` and ``Antispoof`` (see `models`_), and leans on user provided
+implementations of these models.
 
 The default backend is `insightface`_ (the ``[insightface]`` extra), with
 these bundled model implementations:
 
-======================= ========== ============ ===========================
+======================= ========== ============ ==========================
 name                    role       model pack   notes
-======================= ========== ============ ===========================
+======================= ========== ============ ==========================
 ``scrfd``               detector   buffalo_l    default; deprecated alias
                                                 ``retina_face``
 ``arcface``             embedder   buffalo_l    default, 512-d
 ``scrfd_antelopev2``    detector   antelopev2   opt-in
 ``arcface_antelopev2``  embedder   antelopev2   strongest insightface
                                                 embedder, 512-d
-======================= ========== ============ ===========================
+``minifasnet``          antispoof  --           passive anti-spoofing,
+                                                opt-in
+======================= ========== ============ ==========================
 
 .. note::
    The ``[insightface]`` extra installs the CPU build of onnxruntime.
@@ -111,6 +113,24 @@ To work with your own custom models you have to implement required
 `models`_ and import it. FaceEngine models are used to register all inheriting
 imported subclasses (subclass registration `PEP 487`_).
 
+Face anti-spoofing
+------------------
+
+Since 3.1 the engine has an opt-in liveness (presentation attack detection)
+step powered by the ``Antispoof`` model interface:
+
+.. code-block:: python
+
+    >>> engine = FaceEngine(antispoof="minifasnet")
+    >>> engine.check_liveness('bubbles1.jpg')
+    array([0.971], dtype=float32)
+
+The bundled ``minifasnet`` model is an ensemble of the two released
+`Silent-Face-Anti-Spoofing`_ MiniFASNet models (requires ``onnxruntime``,
+already present with the ``[insightface]`` extra). It is effective against
+printed photos and basic screen replays; it is **not** a certified
+(ISO/IEC 30107-3) liveness solution.
+
 Model weights licensing
 -----------------------
 
@@ -120,6 +140,9 @@ come with their own terms:
 * insightface model packs (``buffalo_l``, ``antelopev2``) are available for
   **non-commercial research purposes only** (see `insightface`_).
 * dlib model files have their own terms, see `dlib-models`_.
+* ``minifasnet`` model weights are **Apache-2.0** (usable commercially) —
+  ONNX exports of the `Silent-Face-Anti-Spoofing`_ checkpoints, reproducible
+  with ``extra/export_minifasnet.py``.
 
 Breaking changes in 3.0
 -----------------------
@@ -139,6 +162,7 @@ For more information read the full `documentation`_.
 
 .. _models: https://github.com/guesswh0/face_engine/blob/master/face_engine/models/__init__.py
 .. _insightface: https://github.com/deepinsight/insightface
+.. _Silent-Face-Anti-Spoofing: https://github.com/minivision-ai/Silent-Face-Anti-Spoofing
 .. _dlib python api: http://dlib.net/python/index.html
 .. _files: https://github.com/davisking/dlib-models
 .. _dlib-models: https://github.com/davisking/dlib-models

{face_engine-3.0.0 → face_engine-3.1.0}/README.rst

@@ -29,23 +29,25 @@ FaceEngine is supported only on Python 3.11 and above.
 Models
 ------
 
-FaceEngine is built on top of three model interfaces ``Detector``, ``Embedder``
-and ``Estimator`` (see `models`_), and leans on user provided implementations
-of these models.
+FaceEngine is built on top of four model interfaces ``Detector``, ``Embedder``,
+``Estimator`` and ``Antispoof`` (see `models`_), and leans on user provided
+implementations of these models.
 
 The default backend is `insightface`_ (the ``[insightface]`` extra), with
 these bundled model implementations:
 
-======================= ========== ============ ===========================
+======================= ========== ============ ==========================
 name                    role       model pack   notes
-======================= ========== ============ ===========================
+======================= ========== ============ ==========================
 ``scrfd``               detector   buffalo_l    default; deprecated alias
                                                 ``retina_face``
 ``arcface``             embedder   buffalo_l    default, 512-d
 ``scrfd_antelopev2``    detector   antelopev2   opt-in
 ``arcface_antelopev2``  embedder   antelopev2   strongest insightface
                                                 embedder, 512-d
-======================= ========== ============ ===========================
+``minifasnet``          antispoof  --           passive anti-spoofing,
+                                                opt-in
+======================= ========== ============ ==========================
 
 .. note::
    The ``[insightface]`` extra installs the CPU build of onnxruntime.
@@ -72,6 +74,24 @@ To work with your own custom models you have to implement required
 `models`_ and import it. FaceEngine models are used to register all inheriting
 imported subclasses (subclass registration `PEP 487`_).
 
+Face anti-spoofing
+------------------
+
+Since 3.1 the engine has an opt-in liveness (presentation attack detection)
+step powered by the ``Antispoof`` model interface:
+
+.. code-block:: python
+
+    >>> engine = FaceEngine(antispoof="minifasnet")
+    >>> engine.check_liveness('bubbles1.jpg')
+    array([0.971], dtype=float32)
+
+The bundled ``minifasnet`` model is an ensemble of the two released
+`Silent-Face-Anti-Spoofing`_ MiniFASNet models (requires ``onnxruntime``,
+already present with the ``[insightface]`` extra). It is effective against
+printed photos and basic screen replays; it is **not** a certified
+(ISO/IEC 30107-3) liveness solution.
+
 Model weights licensing
 -----------------------
 
@@ -81,6 +101,9 @@ come with their own terms:
 * insightface model packs (``buffalo_l``, ``antelopev2``) are available for
   **non-commercial research purposes only** (see `insightface`_).
 * dlib model files have their own terms, see `dlib-models`_.
+* ``minifasnet`` model weights are **Apache-2.0** (usable commercially) —
+  ONNX exports of the `Silent-Face-Anti-Spoofing`_ checkpoints, reproducible
+  with ``extra/export_minifasnet.py``.
 
 Breaking changes in 3.0
 -----------------------
@@ -100,6 +123,7 @@ For more information read the full `documentation`_.
 
 .. _models: https://github.com/guesswh0/face_engine/blob/master/face_engine/models/__init__.py
 .. _insightface: https://github.com/deepinsight/insightface
+.. _Silent-Face-Anti-Spoofing: https://github.com/minivision-ai/Silent-Face-Anti-Spoofing
 .. _dlib python api: http://dlib.net/python/index.html
 .. _files: https://github.com/davisking/dlib-models
 .. _dlib-models: https://github.com/davisking/dlib-models

{face_engine-3.0.0 → face_engine-3.1.0}/face_engine/__init__.py

@@ -3,7 +3,7 @@ Face Recognition Engine
 """
 
 __all__ = ["logger", "RESOURCES", "FaceEngine", "_models", "load_engine"]
-__version__ = "3.0.0"
+__version__ = "3.1.0"
 __author__ = "Daniyar Kussainov"
 __license__ = "Apache License, Version 2.0"
 __copyright__ = "Copyright 2019-2026 Daniyar Kussainov"

{face_engine-3.0.0 → face_engine-3.1.0}/face_engine/core.py

@@ -17,6 +17,8 @@ from .tools import imread
 _DETECTOR_DEFAULTS = ("scrfd", "hog")
 _EMBEDDER_DEFAULTS = ("arcface", "resnet")
 _ESTIMATOR_DEFAULTS = ("basic",)
+# antispoof is opt-in: the default is the abstract no-op model
+_ANTISPOOF_DEFAULTS = ()
 
 
 def _resolve(name: Optional[str], defaults: Tuple[str, ...], kind: str) -> str:
@@ -84,6 +86,8 @@ def load_engine(filename: str) -> "FaceEngine":
         detector=data.get("detector"),
         embedder=data.get("embedder"),
         estimator=data.get("estimator"),
+        # absent in files saved by face-engine < 3.1
+        antispoof=data.get("antispoof"),
     )
     engine.n_classes = data.get("n_classes", 0)
     engine.n_samples = data.get("n_samples", 0)
@@ -107,6 +111,7 @@ class FaceEngine:
         * detector (str) -- face detector model to use
         * embedder (str) -- face embedder model to use
         * estimator (str) -- face estimator model to use
+        * antispoof (str) -- face anti-spoofing model to use (opt-in)
     """
 
     def __init__(self, **kwargs: Any) -> None:
@@ -116,6 +121,8 @@ class FaceEngine:
         self.detector = kwargs.get("detector")
         self.embedder = kwargs.get("embedder")
         self.estimator = kwargs.get("estimator")
+        # opt-in anti-spoofing model, abstract no-op by default
+        self.antispoof = kwargs.get("antispoof")
         # keep last fitted number of classes and samples
         self.n_classes = 0
         self.n_samples = 0
@@ -191,6 +198,28 @@ class FaceEngine:
         Estimator = _models.get(_resolve(name, _ESTIMATOR_DEFAULTS, "estimator"))
         self._estimator = Estimator()
 
+    @property
+    def antispoof(self) -> str:
+        """
+        :return: antispoof model name
+        :rtype: str
+        """
+
+        return self._antispoof.name
+
+    @antispoof.setter
+    def antispoof(self, name: Optional[str]) -> None:
+        """Face anti-spoofing model to use:
+            - 'minifasnet': MiniFASNet passive anti-spoofing ensemble
+            - by default the abstract no-op model is used
+
+        :param name: antispoof model name
+        :type name: str
+        """
+
+        Antispoof = _models.get(_resolve(name, _ANTISPOOF_DEFAULTS, "antispoof"))
+        self._antispoof = Antispoof()
+
     def save(self, filename: str) -> None:
         """Save engine object state to the file as JSON.
 
@@ -205,12 +234,19 @@ class FaceEngine:
         if self.n_samples > 0:
             self._estimator.save(os.path.dirname(filename))
 
-        # everything beyond the model trio and counters goes to "extra"
+        # everything beyond the models and counters goes to "extra"
         extra = {
             key: value
             for key, value in self.__dict__.items()
             if key
-            not in ("_detector", "_embedder", "_estimator", "n_classes", "n_samples")
+            not in (
+                "_detector",
+                "_embedder",
+                "_estimator",
+                "_antispoof",
+                "n_classes",
+                "n_samples",
+            )
         }
         data = {
             "format": "face-engine",
@@ -219,6 +255,7 @@ class FaceEngine:
             "detector": self.detector,
             "embedder": self.embedder,
             "estimator": self.estimator,
+            "antispoof": self.antispoof,
             "n_classes": self.n_classes,
             "n_samples": self.n_samples,
         }
@@ -405,6 +442,40 @@ class FaceEngine:
             bbs = bbs / ([width, height] * 2)
         return bbs, extra
 
+    def check_liveness(
+        self,
+        image: Union[str, bytes, os.PathLike, np.ndarray],
+        bounding_boxes: Optional[np.ndarray] = None,
+    ) -> np.ndarray:
+        """Predict live-face probabilities for faces in the image.
+
+        Antispoof's :meth:`~face_engine.models.Antispoof.predict`
+        wrapping method. When ``bounding_boxes`` is not given, faces are
+        located with :meth:`.find_faces` first.
+
+        .. note::
+            The default abstract antispoof model raises
+            ``NotImplementedError`` — set :attr:`antispoof` first
+            (e.g. ``engine.antispoof = "minifasnet"``).
+
+        :param image: RGB image content or image file uri.
+        :type image: Union[str, bytes, file, os.PathLike, numpy.ndarray]
+
+        :param bounding_boxes: face bounding boxes, found when omitted
+        :type bounding_boxes: numpy.ndarray
+
+        :returns: live-face probabilities in [0, 1] with shape (n_faces,)
+        :rtype: numpy.ndarray
+
+        :raises: FaceNotFoundError
+        """
+
+        if not hasattr(image, "shape"):
+            image = imread(image)
+        if bounding_boxes is None:
+            bounding_boxes, _ = self.find_faces(image)
+        return self._antispoof.predict(image, bounding_boxes)
+
     def compute_embeddings(
         self, image: np.ndarray, bounding_boxes: np.ndarray, **kwargs: Any
     ) -> np.ndarray:

{face_engine-3.0.0 → face_engine-3.1.0}/face_engine/fetching.py

@@ -27,6 +27,9 @@ KNOWN_HASHES = {
     # insightface model packs (v0.7 github release assets)
     "buffalo_l.zip": "80ffe37d8a5940d59a7384c201a2a38d4741f2f3c51eef46ebb28218a7b0ca2f",  # noqa: E501
     "antelopev2.zip": "8e182f14fc6e80b3bfa375b33eb6cff7ee05d8ef7633e738d1c89021dcf0c5c5",  # noqa: E501
+    # minifasnet anti-spoofing onnx exports, see extra/export_minifasnet.py
+    "2.7_80x80_MiniFASNetV2.onnx": "3052e9d1d97270f5d9f197bed4f039cae23b8c14d6282e879ca3a63073792a97",  # noqa: E501
+    "4_0_0_80x80_MiniFASNetV1SE.onnx": "2348be428f787149bf28dca49f802bd7ab9280ff3333475f76df1aafd2dada4f",  # noqa: E501
     # test assets (https://github.com/guesswh0/storage)
     "test.zip": "7e967899f1a106908798d750f81d3a966422300b479757b600eaf3ea4d96723b",
     "train.zip": "d61d21d6b0198df9b2f045de784924984177042a595a1a5fd42c3771b2b24b15",

{face_engine-3.0.0 → face_engine-3.1.0}/face_engine/models/__init__.py

@@ -2,7 +2,7 @@
 FaceEngine models API.
 """
 
-__all__ = ["Detector", "Embedder", "Estimator", "_models"]
+__all__ = ["Detector", "Embedder", "Estimator", "Antispoof", "_models"]
 
 from face_engine.tools import import_package
 
@@ -88,6 +88,29 @@ class Embedder(Model):
         raise NotImplementedError()
 
 
+class Antispoof(Model):
+    """Face anti-spoofing (presentation attack detection) model base class.
+
+    Estimates whether the faces in the image belong to live persons or
+    to presentation attacks (printed photos, screen replays, masks).
+    """
+
+    def predict(self, image, bounding_boxes):
+        """Predict live-face probabilities for given bounding boxes.
+
+        :param image: RGB image with shape (rows, cols, 3)
+        :type image: numpy.ndarray
+
+        :param bounding_boxes: bounding boxes with shape (n_faces, 4)
+        :type bounding_boxes: numpy.ndarray
+
+        :returns: live-face probabilities in [0, 1] with shape (n_faces,)
+        :rtype: numpy.ndarray
+        """
+
+        raise NotImplementedError()
+
+
 class Estimator(Model):
     """Estimator model base class. Used to make predictions for face
     embedding vectors.

face_engine-3.1.0/face_engine/models/_onnx.py

@@ -0,0 +1,19 @@
+"""Shared helpers for onnxruntime backed models.
+
+Underscore-prefixed so ``import_package`` skips it: importing it must stay
+an explicit choice of modules that already require onnxruntime.
+"""
+
+import onnxruntime
+
+
+def _providers():
+    """Cuda when available, cpu otherwise.
+
+    Insightface requests CUDAExecutionProvider unconditionally, making
+    onnxruntime warn on every non-CUDA machine.
+    """
+    available = onnxruntime.get_available_providers()
+    return [
+        p for p in ("CUDAExecutionProvider", "CPUExecutionProvider") if p in available
+    ]

{face_engine-3.0.0 → face_engine-3.1.0}/face_engine/models/insightface_models.py

@@ -2,7 +2,6 @@ import os
 import warnings
 
 import numpy as np
-import onnxruntime
 from insightface.model_zoo import model_zoo
 from insightface.utils import face_align
 
@@ -10,6 +9,7 @@ from face_engine import RESOURCES
 from face_engine.exceptions import FaceNotFoundError
 from face_engine.fetching import fetch_file
 from face_engine.models import Detector, Embedder
+from face_engine.models._onnx import _providers
 
 # model packs from the insightface v0.7 release assets
 # (storage.insightface.ai is no longer available);
@@ -17,18 +17,6 @@ from face_engine.models import Detector, Embedder
 _PACK_URL = "https://github.com/deepinsight/insightface/releases/download/v0.7/{}.zip"
 
 
-def _providers():
-    """Cuda when available, cpu otherwise.
-
-    Insightface requests CUDAExecutionProvider unconditionally, making
-    onnxruntime warn on every non-CUDA machine.
-    """
-    available = onnxruntime.get_available_providers()
-    return [
-        p for p in ("CUDAExecutionProvider", "CPUExecutionProvider") if p in available
-    ]
-
-
 def _fetch_pack(pack, filename):
     """Fetch insightface model pack and return path to the model file."""
     extract_dir = os.path.join(RESOURCES, "models", pack)

face_engine-3.1.0/face_engine/models/minifasnet.py

@@ -0,0 +1,127 @@
+import os
+
+import numpy as np
+import onnxruntime
+
+from face_engine import RESOURCES
+from face_engine.fetching import fetch_file
+from face_engine.models import Antispoof
+from face_engine.models._onnx import _providers
+
+# apache-2.0 onnx exports, see extra/export_minifasnet.py
+_ASSET_URL = "https://github.com/guesswh0/face_engine/releases/download/v3.0.0/{}"
+
+
+def _softmax(logits):
+    exp = np.exp(logits - logits.max(axis=1, keepdims=True))
+    return exp / exp.sum(axis=1, keepdims=True)
+
+
+def _resize_bilinear(image, out_h, out_w):
+    """cv2.resize(INTER_LINEAR) equivalent, to avoid an opencv dependency."""
+    in_h, in_w = image.shape[:2]
+    ys = (np.arange(out_h) + 0.5) * in_h / out_h - 0.5
+    xs = (np.arange(out_w) + 0.5) * in_w / out_w - 0.5
+    y0 = np.floor(ys).astype(int)
+    x0 = np.floor(xs).astype(int)
+    wy = (ys - y0)[:, None, None]
+    wx = (xs - x0)[None, :, None]
+    y0c, y1c = np.clip(y0, 0, in_h - 1), np.clip(y0 + 1, 0, in_h - 1)
+    x0c, x1c = np.clip(x0, 0, in_w - 1), np.clip(x0 + 1, 0, in_w - 1)
+    # gather the sampled rows first, cast only the gathered data
+    top_rows = image[y0c].astype(np.float32)
+    bottom_rows = image[y1c].astype(np.float32)
+    top = top_rows[:, x0c] * (1 - wx) + top_rows[:, x1c] * wx
+    bottom = bottom_rows[:, x0c] * (1 - wx) + bottom_rows[:, x1c] * wx
+    # official pipeline resizes uint8 images, so round like cv2 does
+    return np.rint(top * (1 - wy) + bottom * wy)
+
+
+class MiniFASNetAntispoof(Antispoof, name="minifasnet"):
+    """MiniFASNet passive anti-spoofing ensemble (Silent-Face-Anti-Spoofing).
+
+    Ensemble of the two released 80x80 models, each run on its own
+    scale-cropped patch around the face; the averaged softmax gives the
+    live-face probability.
+
+    .. note::
+        * both code and model weights are Apache-2.0 — usable in
+          commercial products.
+        * effective against printed photos and basic screen replays;
+          not a certified (ISO/IEC 30107-3) liveness solution.
+
+    References:
+        1. https://github.com/minivision-ai/Silent-Face-Anti-Spoofing
+    """
+
+    # filename -> official crop scale (each model has its own)
+    files = (
+        ("2.7_80x80_MiniFASNetV2.onnx", 2.7),
+        ("4_0_0_80x80_MiniFASNetV1SE.onnx", 4.0),
+    )
+    input_size = (80, 80)
+
+    def __init__(self):
+        extract_dir = os.path.join(RESOURCES, "models", "minifasnet")
+        self._sessions = []
+        for filename, scale in self.files:
+            fetch_file(_ASSET_URL.format(filename), extract_dir)
+            session = onnxruntime.InferenceSession(
+                os.path.join(extract_dir, filename), providers=_providers()
+            )
+            self._sessions.append((session, scale))
+
+    def predict(self, image, bounding_boxes):
+        n_faces = len(bounding_boxes)
+        if n_faces == 0:
+            return np.empty(0, dtype=np.float32)
+
+        # models are trained on BGR images
+        image = image[..., ::-1]
+        live_probs = np.zeros(n_faces, dtype=np.float32)
+        for session, scale in self._sessions:
+            batch = np.stack([self._patch(image, bb, scale) for bb in bounding_boxes])
+            logits = session.run(None, {"input": batch})[0]
+            # softmax classes are (fake, live, fake)
+            live_probs += _softmax(logits)[:, 1]
+        return live_probs / len(self._sessions)
+
+    def _patch(self, image, bounding_box, scale):
+        """Scale-cropped face patch as float32 CHW tensor in [0, 255].
+
+        Reproduces the official CropImage box math: aspect-preserving
+        scaled box around the face, shifted back inside the image, then
+        resized to the model input size (no normalization by design —
+        the models were trained on raw 0-255 inputs).
+        """
+        src_h, src_w = image.shape[:2]
+        left, upper, right, lower = bounding_box
+        box_w, box_h = right - left + 1, lower - upper + 1
+
+        scale = min((src_h - 1) / box_h, (src_w - 1) / box_w, scale)
+        new_w, new_h = box_w * scale, box_h * scale
+        center_x, center_y = left + box_w / 2, upper + box_h / 2
+
+        left_top_x = center_x - new_w / 2
+        left_top_y = center_y - new_h / 2
+        right_bottom_x = center_x + new_w / 2
+        right_bottom_y = center_y + new_h / 2
+        if left_top_x < 0:
+            right_bottom_x -= left_top_x
+            left_top_x = 0
+        if left_top_y < 0:
+            right_bottom_y -= left_top_y
+            left_top_y = 0
+        if right_bottom_x > src_w - 1:
+            left_top_x -= right_bottom_x - src_w + 1
+            right_bottom_x = src_w - 1
+        if right_bottom_y > src_h - 1:
+            left_top_y -= right_bottom_y - src_h + 1
+            right_bottom_y = src_h - 1
+
+        patch = image[
+            int(left_top_y) : int(right_bottom_y) + 1,
+            int(left_top_x) : int(right_bottom_x) + 1,
+        ]
+        patch = _resize_bilinear(patch, *self.input_size)
+        return patch.transpose((2, 0, 1)).astype(np.float32)

{face_engine-3.0.0 → face_engine-3.1.0}/face_engine/tools.py

@@ -80,7 +80,7 @@ def import_module(filepath):
         spec.loader.exec_module(module)
     except ImportError:
         # skip raising on project [optional] default models
-        if path.stem not in ["dlib_models", "insightface_models"]:
+        if path.stem not in ["dlib_models", "insightface_models", "minifasnet"]:
             raise
 
 

{face_engine-3.0.0 → face_engine-3.1.0/face_engine.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: face-engine
-Version: 3.0.0
+Version: 3.1.0
 Summary: Face Recognition Engine
 Author-email: Daniyar Kussainov <ohw0sseug@gmail.com>
 License-Expression: Apache-2.0
@@ -68,23 +68,25 @@ FaceEngine is supported only on Python 3.11 and above.
 Models
 ------
 
-FaceEngine is built on top of three model interfaces ``Detector``, ``Embedder``
-and ``Estimator`` (see `models`_), and leans on user provided implementations
-of these models.
+FaceEngine is built on top of four model interfaces ``Detector``, ``Embedder``,
+``Estimator`` and ``Antispoof`` (see `models`_), and leans on user provided
+implementations of these models.
 
 The default backend is `insightface`_ (the ``[insightface]`` extra), with
 these bundled model implementations:
 
-======================= ========== ============ ===========================
+======================= ========== ============ ==========================
 name                    role       model pack   notes
-======================= ========== ============ ===========================
+======================= ========== ============ ==========================
 ``scrfd``               detector   buffalo_l    default; deprecated alias
                                                 ``retina_face``
 ``arcface``             embedder   buffalo_l    default, 512-d
 ``scrfd_antelopev2``    detector   antelopev2   opt-in
 ``arcface_antelopev2``  embedder   antelopev2   strongest insightface
                                                 embedder, 512-d
-======================= ========== ============ ===========================
+``minifasnet``          antispoof  --           passive anti-spoofing,
+                                                opt-in
+======================= ========== ============ ==========================
 
 .. note::
    The ``[insightface]`` extra installs the CPU build of onnxruntime.
@@ -111,6 +113,24 @@ To work with your own custom models you have to implement required
 `models`_ and import it. FaceEngine models are used to register all inheriting
 imported subclasses (subclass registration `PEP 487`_).
 
+Face anti-spoofing
+------------------
+
+Since 3.1 the engine has an opt-in liveness (presentation attack detection)
+step powered by the ``Antispoof`` model interface:
+
+.. code-block:: python
+
+    >>> engine = FaceEngine(antispoof="minifasnet")
+    >>> engine.check_liveness('bubbles1.jpg')
+    array([0.971], dtype=float32)
+
+The bundled ``minifasnet`` model is an ensemble of the two released
+`Silent-Face-Anti-Spoofing`_ MiniFASNet models (requires ``onnxruntime``,
+already present with the ``[insightface]`` extra). It is effective against
+printed photos and basic screen replays; it is **not** a certified
+(ISO/IEC 30107-3) liveness solution.
+
 Model weights licensing
 -----------------------
 
@@ -120,6 +140,9 @@ come with their own terms:
 * insightface model packs (``buffalo_l``, ``antelopev2``) are available for
   **non-commercial research purposes only** (see `insightface`_).
 * dlib model files have their own terms, see `dlib-models`_.
+* ``minifasnet`` model weights are **Apache-2.0** (usable commercially) —
+  ONNX exports of the `Silent-Face-Anti-Spoofing`_ checkpoints, reproducible
+  with ``extra/export_minifasnet.py``.
 
 Breaking changes in 3.0
 -----------------------
@@ -139,6 +162,7 @@ For more information read the full `documentation`_.
 
 .. _models: https://github.com/guesswh0/face_engine/blob/master/face_engine/models/__init__.py
 .. _insightface: https://github.com/deepinsight/insightface
+.. _Silent-Face-Anti-Spoofing: https://github.com/minivision-ai/Silent-Face-Anti-Spoofing
 .. _dlib python api: http://dlib.net/python/index.html
 .. _files: https://github.com/davisking/dlib-models
 .. _dlib-models: https://github.com/davisking/dlib-models

{face_engine-3.0.0 → face_engine-3.1.0}/face_engine.egg-info/SOURCES.txt

@@ -14,9 +14,11 @@ face_engine.egg-info/dependency_links.txt
 face_engine.egg-info/requires.txt
 face_engine.egg-info/top_level.txt
 face_engine/models/__init__.py
+face_engine/models/_onnx.py
 face_engine/models/basic_estimator.py
 face_engine/models/dlib_models.py
 face_engine/models/insightface_models.py
+face_engine/models/minifasnet.py
 tests/test_face_engine.py
 tests/test_face_engine_models.py
 tests/test_face_engine_persistence.py

{face_engine-3.0.0 → face_engine-3.1.0}/tests/test_face_engine.py

@@ -5,9 +5,9 @@ import numpy as np
 
 from face_engine import FaceEngine
 from face_engine.exceptions import FaceNotFoundError, TrainError
-from face_engine.models import Detector, Embedder, Estimator
+from face_engine.models import Antispoof, Detector, Embedder, Estimator
 from face_engine.tools import imread
-from tests import TestCase, dlib, insightface
+from tests import TestCase, dlib, insightface, onnxruntime
 
 
 class TestFaceEngine(TestCase):
@@ -140,6 +140,44 @@ class TestFaceEngine(TestCase):
         self.assertIsInstance(self.test_engine.detector, str)
         self.assertIsInstance(self.test_engine.embedder, str)
         self.assertIsInstance(self.test_engine.estimator, str)
+        self.assertIsInstance(self.test_engine.antispoof, str)
+
+    def test_init_default_antispoof_is_abstract(self):
+        # antispoof is opt-in regardless of installed backends
+        self.assertEqual(self.test_engine.antispoof, "abstract_antispoof")
+
+    def test_setter_antispoof_with_not_existing_model(self):
+        logging.disable(logging.WARNING)
+        self.test_engine.antispoof = "my_antispoof"
+        self.assertEqual(self.test_engine.antispoof, "abstract_antispoof")
+
+    def test_check_liveness_with_abstract_raises(self):
+        with self.assertRaises(NotImplementedError):
+            self.test_engine.check_liveness(
+                imread(self.bubbles1), np.array([[278, 132, 618, 471]])
+            )
+
+    @unittest.skipUnless(onnxruntime, "onnxruntime package is not installed")
+    def test_setter_antispoof_minifasnet(self):
+        self.test_engine.antispoof = "minifasnet"
+        self.assertEqual(self.test_engine.antispoof, "minifasnet")
+        self.assertIsInstance(self.test_engine._antispoof, Antispoof)
+
+    @unittest.skipUnless(onnxruntime, "onnxruntime package is not installed")
+    def test_check_liveness_with_bounding_boxes(self):
+        self.test_engine.antispoof = "minifasnet"
+        scores = self.test_engine.check_liveness(
+            imread(self.bubbles1), np.array([[278, 132, 618, 471]])
+        )
+        self.assertEqual(scores.shape, (1,))
+        self.assertTrue(0.0 <= scores[0] <= 1.0)
+
+    @unittest.skipUnless(insightface, "insightface package is not installed")
+    def test_check_liveness_finds_faces(self):
+        engine = FaceEngine(antispoof="minifasnet")
+        scores = engine.check_liveness(self.family)
+        self.assertGreater(len(scores), 1)
+        self.assertTrue(all(0.0 <= s <= 1.0 for s in scores))
 
     @unittest.skipUnless(dlib, "dlib package is not installed")
     def test_fit_bubbles(self):

{face_engine-3.0.0 → face_engine-3.1.0}/tests/test_face_engine_models.py

@@ -5,10 +5,10 @@ import numpy as np
 
 from extra.dataset import load_dataset
 from face_engine.exceptions import FaceNotFoundError
-from face_engine.models import Detector, Embedder, Estimator
+from face_engine.models import Detector, Embedder, Estimator, _models
 from face_engine.models.basic_estimator import BasicEstimator
 from face_engine.tools import imread
-from tests import TestCase, dlib, insightface
+from tests import TestCase, dlib, insightface, onnxruntime
 
 if dlib:
     from face_engine.models.dlib_models import HOGDetector, MMODDetector, ResNetEmbedder
@@ -160,6 +160,42 @@ class TestArcFaceAntelopeV2Embedder(TestInsightFaceEmbedder):
         self.embedder = ArcFaceAntelopeV2Embedder()
 
 
+@unittest.skipUnless(onnxruntime, "onnxruntime package is not installed")
+class TestMiniFASNetAntispoof(TestCase):
+
+    def setUp(self):
+        from face_engine.models.minifasnet import MiniFASNetAntispoof
+
+        self.antispoof = MiniFASNetAntispoof()
+        self.image = imread(self.bubbles1)
+        self.bbs = np.array([[278, 132, 618, 471]])
+
+    def test_registered_under_canonical_name(self):
+        self.assertIs(_models["minifasnet"], type(self.antispoof))
+
+    def test_predict_return_data_shape_and_range(self):
+        scores = self.antispoof.predict(self.image, self.bbs)
+        self.assertIsInstance(scores, np.ndarray)
+        self.assertEqual(scores.shape, (1,))
+        self.assertTrue(0.0 <= scores[0] <= 1.0)
+
+    def test_predict_live_photo_scores_high(self):
+        scores = self.antispoof.predict(self.image, self.bbs)
+        self.assertGreater(scores[0], 0.5)
+
+    def test_predict_multiple_faces(self):
+        image = imread(self.family)
+        bbs = np.array(
+            [[100, 100, 200, 220], [300, 120, 400, 240], [500, 110, 600, 230]]
+        )
+        scores = self.antispoof.predict(image, bbs)
+        self.assertEqual(scores.shape, (3,))
+
+    def test_predict_empty_bounding_boxes(self):
+        scores = self.antispoof.predict(self.image, np.empty((0, 4)))
+        self.assertEqual(scores.shape, (0,))
+
+
 class TestEstimator(TestCase):
     """Test cases to test estimators.
 

{face_engine-3.0.0 → face_engine-3.1.0}/tests/test_face_engine_persistence.py

@@ -53,6 +53,18 @@ class TestFaceEnginePersistence(TestCase):
         self.assertEqual(engine.detector, self.test_engine.detector)
         self.assertEqual(engine.embedder, self.test_engine.embedder)
         self.assertEqual(engine.estimator, self.test_engine.estimator)
+        self.assertEqual(engine.antispoof, self.test_engine.antispoof)
+
+    def test_load_engine_pre31_file_without_antispoof(self):
+        self.test_engine.save(self.filename)
+        with open(self.filename) as file:
+            data = json.load(file)
+        # files saved by face-engine 3.0 have no antispoof key
+        del data["antispoof"]
+        with open(self.filename, "w") as file:
+            json.dump(data, file)
+        engine = load_engine(self.filename)
+        self.assertEqual(engine.antispoof, "abstract_antispoof")
 
     @unittest.skipUnless(dlib or insightface, "no face recognition backend installed")
     def test_load_engine_with_estimator_state(self):