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

{face_engine-3.1.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.1.0
+Version: 3.2.0
 Summary: Face Recognition Engine
 Author-email: Daniyar Kussainov <ohw0sseug@gmail.com>
 License-Expression: Apache-2.0
@@ -131,6 +131,22 @@ 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
 -----------------------
 
@@ -144,6 +160,18 @@ come with their own terms:
   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
 -----------------------
 

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

@@ -92,6 +92,22 @@ 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
 -----------------------
 
@@ -105,6 +121,18 @@ come with their own terms:
   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
 -----------------------
 

{face_engine-3.1.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.1.0"
+__version__ = "3.2.0"
 __author__ = "Daniyar Kussainov"
 __license__ = "Apache License, Version 2.0"
 __copyright__ = "Copyright 2019-2026 Daniyar Kussainov"

{face_engine-3.1.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
 
@@ -20,10 +20,29 @@ _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:
@@ -31,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
 
 
@@ -61,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:
@@ -498,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.1.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.1.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)

{face_engine-3.1.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.1.0
+Version: 3.2.0
 Summary: Face Recognition Engine
 Author-email: Daniyar Kussainov <ohw0sseug@gmail.com>
 License-Expression: Apache-2.0
@@ -131,6 +131,22 @@ 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
 -----------------------
 
@@ -144,6 +160,18 @@ come with their own terms:
   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
 -----------------------
 

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

@@ -22,4 +22,5 @@ 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.1.0 → face_engine-3.2.0}/tests/test_face_engine.py

@@ -1,10 +1,9 @@
-import logging
 import unittest
 
 import numpy as np
 
 from face_engine import FaceEngine
-from face_engine.exceptions import FaceNotFoundError, TrainError
+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, onnxruntime
@@ -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")
@@ -146,11 +147,25 @@ class TestFaceEngine(TestCase):
         # 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"
+    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(
@@ -179,6 +194,59 @@ class TestFaceEngine(TestCase):
         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):
         images = [self.bubbles1, self.bubbles2]

{face_engine-3.1.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
 
 
@@ -85,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()