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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: face-engine
-Version: 3.0.0
+Version: 3.2.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,40 @@ 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.
+
+Face verification
+-----------------
+
+Since 3.2 the engine has a model-agnostic 1:1 verification primitive —
+cosine similarity between two embeddings of the same embedder:
+
+.. code-block:: python
+
+    >>> bbs, extra = engine.find_faces(image, limit=1)
+    >>> source = engine.compute_embeddings(image, bbs, **extra)[0]
+    >>> engine.compare(source, target)
+    0.83
+
+``compare`` returns the raw score in ``[-1, 1]``; accept/reject
+thresholding is left to the caller and should be calibrated per embedder.
+
 Model weights licensing
 -----------------------
 
@@ -120,6 +156,21 @@ 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``.
+
+Changes in 3.2
+--------------
+
+* Unknown explicit model names now raise ``ModelNotFoundError`` instead of
+  warning and falling back to the abstract no-op models. This applies to the
+  ``FaceEngine`` constructor, the model property setters, and
+  ``load_engine``. Empty names keep the installed-backend fallback chains.
+* New ``engine.compare(source, target)`` — cosine similarity between two
+  embeddings for 1:1 verification (raw score, no thresholding).
+* ``tools.imread`` now reads raw ``bytes`` image content, as its
+  documentation always claimed.
 
 Breaking changes in 3.0
 -----------------------
@@ -139,6 +190,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.2.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,40 @@ 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.
+
+Face verification
+-----------------
+
+Since 3.2 the engine has a model-agnostic 1:1 verification primitive —
+cosine similarity between two embeddings of the same embedder:
+
+.. code-block:: python
+
+    >>> bbs, extra = engine.find_faces(image, limit=1)
+    >>> source = engine.compute_embeddings(image, bbs, **extra)[0]
+    >>> engine.compare(source, target)
+    0.83
+
+``compare`` returns the raw score in ``[-1, 1]``; accept/reject
+thresholding is left to the caller and should be calibrated per embedder.
+
 Model weights licensing
 -----------------------
 
@@ -81,6 +117,21 @@ 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``.
+
+Changes in 3.2
+--------------
+
+* Unknown explicit model names now raise ``ModelNotFoundError`` instead of
+  warning and falling back to the abstract no-op models. This applies to the
+  ``FaceEngine`` constructor, the model property setters, and
+  ``load_engine``. Empty names keep the installed-backend fallback chains.
+* New ``engine.compare(source, target)`` — cosine similarity between two
+  embeddings for 1:1 verification (raw score, no thresholding).
+* ``tools.imread`` now reads raw ``bytes`` image content, as its
+  documentation always claimed.
 
 Breaking changes in 3.0
 -----------------------
@@ -100,6 +151,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.2.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.2.0"
 __author__ = "Daniyar Kussainov"
 __license__ = "Apache License, Version 2.0"
 __copyright__ = "Copyright 2019-2026 Daniyar Kussainov"

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

@@ -8,8 +8,8 @@ import os
 
 import numpy as np
 
-from . import __version__, logger
-from .exceptions import FaceNotFoundError
+from . import __version__
+from .exceptions import FaceNotFoundError, ModelNotFoundError
 from .models import _models
 from .tools import imread
 
@@ -17,11 +17,32 @@ 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 = ()
+
+# in-tree optional models: absence from the registry means the backend
+# dependency failed to import (tools.import_module swallows it), not that
+# a plugin-module import was forgotten
+_OPTIONAL_BACKENDS = {
+    "scrfd": "insightface",
+    "scrfd_antelopev2": "insightface",
+    "retina_face": "insightface",
+    "arcface": "insightface",
+    "arcface_antelopev2": "insightface",
+    "hog": "dlib",
+    "mmod": "dlib",
+    "resnet": "dlib",
+    "minifasnet": "onnxruntime",
+}
 
 
 def _resolve(name: Optional[str], defaults: Tuple[str, ...], kind: str) -> str:
     """Resolve model name to a registered one, with installed-backend
-    fallbacks for empty names and abstract fallback for unknown names."""
+    fallbacks for empty names.
+
+    Explicit unknown names raise :class:`~.exceptions.ModelNotFoundError`
+    (since 3.2; previously they warned and fell back to the abstract no-op).
+    """
 
     if not name:
         for candidate in defaults:
@@ -29,8 +50,17 @@ def _resolve(name: Optional[str], defaults: Tuple[str, ...], kind: str) -> str:
                 return candidate
         return "abstract_" + kind
     if name not in _models:
-        logger.warning("%s model '%s' not found!", kind.capitalize(), name)
-        return "abstract_" + kind
+        if name in _OPTIONAL_BACKENDS:
+            raise ModelNotFoundError(
+                "%s model '%s' is not registered because its backend "
+                "dependency '%s' is not installed"
+                % (kind.capitalize(), name, _OPTIONAL_BACKENDS[name])
+            )
+        raise ModelNotFoundError(
+            "%s model '%s' is not registered; make sure the module "
+            "providing it is imported. Registered models: %s"
+            % (kind.capitalize(), name, sorted(_models))
+        )
     return name
 
 
@@ -59,6 +89,8 @@ def load_engine(filename: str) -> "FaceEngine":
     :rtype: :class:`.FaceEngine`
 
     :raises RuntimeError: on legacy (pre-3.0) pickle files
+    :raises ModelNotFoundError: when the file names a model that is not
+        registered (e.g. its plugin module is not imported)
     """
 
     with open(filename, "rb") as file:
@@ -84,6 +116,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 +141,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 +151,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 +228,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 +264,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 +285,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 +472,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:
@@ -427,3 +528,31 @@ class FaceEngine:
 
         embeddings = self._embedder.compute_embeddings(image, bounding_boxes, **kwargs)
         return embeddings
+
+    def compare(self, source: np.ndarray, target: np.ndarray) -> float:
+        """Compare two face embeddings by cosine similarity.
+
+        The 1:1 verification primitive: returns the raw similarity score
+        in ``[-1, 1]`` (1 — same direction, 0 — orthogonal, -1 — opposite;
+        0 also for zero-norm inputs). Both embeddings must come from the
+        same embedder model. Accept/reject thresholding is left to the
+        caller and should be calibrated per embedder.
+
+        :param source: embedding vector with shape (embedding_dim,)
+            or (1, embedding_dim)
+        :type source: numpy.ndarray
+
+        :param target: embedding vector with shape (embedding_dim,)
+            or (1, embedding_dim)
+        :type target: numpy.ndarray
+
+        :returns: cosine similarity score
+        :rtype: float
+        """
+
+        source = np.asarray(source, dtype=np.float64).ravel()
+        target = np.asarray(target, dtype=np.float64).ravel()
+        denominator = float(np.linalg.norm(source) * np.linalg.norm(target))
+        if denominator == 0.0:
+            return 0.0
+        return float(np.dot(source, target) / denominator)

{face_engine-3.0.0 → face_engine-3.2.0}/face_engine/exceptions.py

@@ -7,5 +7,9 @@ class FaceNotFoundError(Exception):
     """Raised when the face is not found in the image"""
 
 
+class ModelNotFoundError(Exception):
+    """Raised when an explicit model name is not in the registry"""
+
+
 class TrainError(Exception):
     """Raised when the fit(train) process is failed"""

{face_engine-3.0.0 → face_engine-3.2.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.2.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.2.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.2.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.2.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.2.0}/face_engine/tools.py

@@ -58,6 +58,10 @@ def imread(uri, mode=None):
         data = _download_url(uri)
         uri = io.BytesIO(data)
 
+    # raw image bytes: PIL treats a bare bytes object as a file path
+    if isinstance(uri, bytes):
+        uri = io.BytesIO(uri)
+
     image = Image.open(uri)
     if mode:
         image = image.convert(mode)
@@ -80,7 +84,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.2.0/face_engine.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: face-engine
-Version: 3.0.0
+Version: 3.2.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,40 @@ 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.
+
+Face verification
+-----------------
+
+Since 3.2 the engine has a model-agnostic 1:1 verification primitive —
+cosine similarity between two embeddings of the same embedder:
+
+.. code-block:: python
+
+    >>> bbs, extra = engine.find_faces(image, limit=1)
+    >>> source = engine.compute_embeddings(image, bbs, **extra)[0]
+    >>> engine.compare(source, target)
+    0.83
+
+``compare`` returns the raw score in ``[-1, 1]``; accept/reject
+thresholding is left to the caller and should be calibrated per embedder.
+
 Model weights licensing
 -----------------------
 
@@ -120,6 +156,21 @@ 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``.
+
+Changes in 3.2
+--------------
+
+* Unknown explicit model names now raise ``ModelNotFoundError`` instead of
+  warning and falling back to the abstract no-op models. This applies to the
+  ``FaceEngine`` constructor, the model property setters, and
+  ``load_engine``. Empty names keep the installed-backend fallback chains.
+* New ``engine.compare(source, target)`` — cosine similarity between two
+  embeddings for 1:1 verification (raw score, no thresholding).
+* ``tools.imread`` now reads raw ``bytes`` image content, as its
+  documentation always claimed.
 
 Breaking changes in 3.0
 -----------------------
@@ -139,6 +190,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.2.0}/face_engine.egg-info/SOURCES.txt

@@ -14,10 +14,13 @@ 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
-tests/test_fetching.py
+tests/test_fetching.py
+tests/test_tools.py

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

@@ -1,13 +1,12 @@
-import logging
 import unittest
 
 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.exceptions import FaceNotFoundError, ModelNotFoundError, TrainError
+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):
@@ -48,14 +47,13 @@ class TestFaceEngine(TestCase):
         self.assertEqual(self.empty_engine.embedder, "abstract_embedder")
         self.assertEqual(self.empty_engine.estimator, "abstract_estimator")
 
-    def test_explicit_init_with_not_existing_models(self):
-        logging.disable(logging.WARNING)
-        engine = FaceEngine(
-            detector="my_detector", embedder="my_embedder", estimator="my_estimator"
-        )
-        self.assertEqual(engine.detector, "abstract_detector")
-        self.assertEqual(engine.embedder, "abstract_embedder")
-        self.assertEqual(engine.estimator, "abstract_estimator")
+    def test_explicit_init_with_not_existing_models_raises(self):
+        with self.assertRaises(ModelNotFoundError):
+            FaceEngine(detector="my_detector")
+        with self.assertRaises(ModelNotFoundError):
+            FaceEngine(embedder="my_embedder")
+        with self.assertRaises(ModelNotFoundError):
+            FaceEngine(estimator="my_estimator")
 
     @unittest.skipUnless(dlib, "dlib package is not installed")
     def test_setters_with_dlib_models(self):
@@ -95,16 +93,19 @@ class TestFaceEngine(TestCase):
         self.assertIsInstance(self.test_engine._estimator, Estimator)
         self.assertEqual(self.test_engine.estimator, "abstract_estimator")
 
-    def test_setters_with_not_existing_models(self):
-        logging.disable(logging.WARNING)
-        self.empty_engine.detector = "my_detector"
-        self.empty_engine.embedder = "my_embedder"
-        self.empty_engine.estimator = "my_estimator"
-        self.assertNotEqual(self.empty_engine.detector, "my_detector")
+    def test_setters_with_not_existing_models_raise(self):
+        with self.assertRaises(ModelNotFoundError) as context:
+            self.empty_engine.detector = "my_detector"
+        # the message names the model and hints at the plugin import
+        self.assertIn("my_detector", str(context.exception))
+        self.assertIn("imported", str(context.exception))
+        with self.assertRaises(ModelNotFoundError):
+            self.empty_engine.embedder = "my_embedder"
+        with self.assertRaises(ModelNotFoundError):
+            self.empty_engine.estimator = "my_estimator"
+        # the failed assignments left the previous models in place
         self.assertEqual(self.empty_engine.detector, "abstract_detector")
-        self.assertNotEqual(self.empty_engine.embedder, "my_embedder")
         self.assertEqual(self.empty_engine.embedder, "abstract_embedder")
-        self.assertNotEqual(self.empty_engine.estimator, "my_estimator")
         self.assertEqual(self.empty_engine.estimator, "abstract_estimator")
 
     @unittest.skipUnless(insightface, "insightface package is not installed")
@@ -140,6 +141,111 @@ 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_raises(self):
+        with self.assertRaises(ModelNotFoundError):
+            self.test_engine.antispoof = "my_antispoof"
+        self.assertEqual(self.test_engine.antispoof, "abstract_antispoof")
+
+    def test_unregistered_in_tree_model_names_missing_backend(self):
+        # simulate an install where minifasnet's backend failed to import
+        from unittest import mock
+
+        from face_engine import core
+
+        with mock.patch.dict(core._models):
+            core._models.pop("minifasnet", None)
+            with self.assertRaises(ModelNotFoundError) as context:
+                core._resolve("minifasnet", (), "antispoof")
+        # the hint names the missing dependency, not a module import
+        self.assertIn("onnxruntime", str(context.exception))
+        self.assertNotIn("imported", str(context.exception))
+
+    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))
+
+    def test_compare_identical_embeddings(self):
+        embedding = np.array([0.5, -0.25, 0.75])
+        self.assertAlmostEqual(self.test_engine.compare(embedding, embedding), 1.0)
+
+    def test_compare_orthogonal_embeddings(self):
+        source = np.array([1.0, 0.0])
+        target = np.array([0.0, 1.0])
+        self.assertAlmostEqual(self.test_engine.compare(source, target), 0.0)
+
+    def test_compare_opposite_embeddings(self):
+        embedding = np.array([0.5, -0.25, 0.75])
+        self.assertAlmostEqual(self.test_engine.compare(embedding, -embedding), -1.0)
+
+    def test_compare_zero_vector_scores_zero(self):
+        source = np.zeros(3)
+        target = np.array([1.0, 2.0, 3.0])
+        self.assertEqual(self.test_engine.compare(source, target), 0.0)
+
+    def test_compare_accepts_single_row_matrices(self):
+        # compute_embeddings returns (n_faces, dim); a single-face row
+        # must be comparable without an explicit squeeze
+        source = np.array([[1.0, 2.0, 3.0]])
+        target = np.array([1.0, 2.0, 3.0])
+        self.assertAlmostEqual(self.test_engine.compare(source, target), 1.0)
+
+    def test_compare_returns_python_float(self):
+        source = np.array([1.0, 2.0], dtype=np.float32)
+        target = np.array([2.0, 1.0], dtype=np.float32)
+        self.assertIsInstance(self.test_engine.compare(source, target), float)
+
+    def _assert_same_face_scores_higher(self, engine):
+        image1 = imread(self.bubbles1)
+        bbs1, extra1 = engine.find_faces(image1, limit=1)
+        same1 = engine.compute_embeddings(image1, bbs1, **extra1)[0]
+        image2 = imread(self.bubbles2)
+        bbs2, extra2 = engine.find_faces(image2, limit=1)
+        same2 = engine.compute_embeddings(image2, bbs2, **extra2)[0]
+        image3 = imread(self.drive)
+        bbs3, extra3 = engine.find_faces(image3, limit=1)
+        other = engine.compute_embeddings(image3, bbs3, **extra3)[0]
+        same_score = engine.compare(same1, same2)
+        other_score = engine.compare(same1, other)
+        self.assertGreater(same_score, other_score)
+
+    @unittest.skipUnless(dlib, "dlib package is not installed")
+    def test_compare_same_face_scores_higher_dlib(self):
+        self._assert_same_face_scores_higher(self.dlib_engine)
+
+    @unittest.skipUnless(insightface, "insightface package is not installed")
+    def test_compare_same_face_scores_higher_insightface(self):
+        engine = FaceEngine(detector="scrfd", embedder="arcface")
+        self._assert_same_face_scores_higher(engine)
 
     @unittest.skipUnless(dlib, "dlib package is not installed")
     def test_fit_bubbles(self):

{face_engine-3.0.0 → face_engine-3.2.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.2.0}/tests/test_face_engine_persistence.py

@@ -8,6 +8,7 @@ import numpy as np
 from tests import TestCase, dlib, insightface
 
 from face_engine import FaceEngine, load_engine
+from face_engine.exceptions import ModelNotFoundError
 from face_engine.models.basic_estimator import BasicEstimator
 
 
@@ -53,6 +54,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):
@@ -73,6 +86,17 @@ class TestFaceEnginePersistence(TestCase):
         np.testing.assert_array_equal(bbs, restored_bbs)
         self.assertEqual(class_names, restored_class_names)
 
+    def test_load_engine_unregistered_model_raises(self):
+        self.test_engine.save(self.filename)
+        with open(self.filename) as file:
+            data = json.load(file)
+        # e.g. a plugin model whose module is not imported on this install
+        data["detector"] = "unregistered_plugin_detector"
+        with open(self.filename, "w") as file:
+            json.dump(data, file)
+        with self.assertRaises(ModelNotFoundError):
+            load_engine(self.filename)
+
     def test_load_engine_legacy_pickle_raises(self):
         with open("test_engine.p", "wb") as file:
             pickle.dump({"detector": "hog"}, file)

face_engine-3.2.0/tests/test_tools.py

@@ -0,0 +1,34 @@
+import io
+import unittest
+
+import numpy as np
+
+from tests import TestCase
+
+from face_engine.tools import imread
+
+
+class TestImread(TestCase):
+
+    def test_imread_file_path(self):
+        image = imread(self.bubbles1)
+        self.assertEqual(image.dtype, np.uint8)
+        self.assertEqual(image.ndim, 3)
+
+    def test_imread_bytes(self):
+        with open(self.bubbles1, "rb") as file:
+            data = file.read()
+        np.testing.assert_array_equal(imread(data), imread(self.bubbles1))
+
+    def test_imread_file_object(self):
+        with open(self.bubbles1, "rb") as file:
+            data = file.read()
+        np.testing.assert_array_equal(imread(io.BytesIO(data)), imread(self.bubbles1))
+
+    def test_imread_mode_conversion(self):
+        image = imread(self.bubbles1, mode="L")
+        self.assertEqual(image.ndim, 2)
+
+
+if __name__ == "__main__":
+    unittest.main()