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

face_engine-3.1.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: face-engine
+Version: 3.1.0
+Summary: Face Recognition Engine
+Author-email: Daniyar Kussainov <ohw0sseug@gmail.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/guesswh0/face_engine
+Classifier: Natural Language :: English
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.11
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Requires-Dist: numpy<3,>=1.26
+Requires-Dist: pillow>=12.2
+Requires-Dist: tqdm<5,>=4.66.3
+Requires-Dist: platformdirs>=4
+Provides-Extra: insightface
+Requires-Dist: insightface>=1.0.1; extra == "insightface"
+Requires-Dist: onnxruntime>=1.19; extra == "insightface"
+Provides-Extra: dlib
+Requires-Dist: dlib>=19.24; extra == "dlib"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: sphinx; extra == "dev"
+Requires-Dist: sphinx-rtd-theme; extra == "dev"
+Requires-Dist: face-engine[insightface]; extra == "dev"
+Dynamic: license-file
+
+FaceEngine
+==========
+
+FaceEngine is a lightweight python library that provides an easy interface to
+work with **face recognition** tasks.
+
+.. code-block:: python
+
+    >>> from face_engine import FaceEngine
+    >>> engine = FaceEngine()
+    >>> engine.fit(['bubbles1.jpg', 'drive.jpg'], [1, 2])
+    >>> engine.make_prediction('bubbles2.jpg')
+    ([(270, 75, 406, 211)], [1])
+
+
+Installation
+------------
+
+It is distributed on `PyPi`_, and can be installed with pip:
+
+.. code-block:: console
+
+    $ pip install face-engine[insightface]
+
+FaceEngine is supported only on Python 3.11 and above.
+
+.. _PyPi: https://pypi.org/project/face-engine/
+
+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.
+   For NVIDIA GPU inference replace it with the GPU build — both
+   packages provide the same ``onnxruntime`` module, so the CPU build
+   must be removed first::
+
+       pip uninstall onnxruntime && pip install onnxruntime-gpu
+
+   The models use the CUDA execution provider automatically when
+   available.
+
+Legacy `dlib python api`_ models (``hog``, ``mmod`` detectors and ``resnet``
+embedder with dlib pre-trained model `files`_) are kept as an optional
+fallback backend used when insightface is not installed.
+
+.. note::
+   FaceEngine installation is not installing dlib by default.
+   To install it, either run ``pip install dlib`` (requires cmake),
+   install prebuilt wheels with ``pip install dlib-bin``, or follow
+   `build instructions`_.
+
+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
+-----------------------
+
+The library code is Apache-2.0, but the downloaded pre-trained model weights
+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
+-----------------------
+
+* Python >= 3.11 is required.
+* Pickle persistence was removed for security reasons: engines are saved as
+  JSON (``engine.save('engine.json')``) and estimator state as ``.npz`` +
+  ``.json`` files. Engines saved with face-engine < 3.0 cannot be loaded —
+  re-fit and save again.
+* With insightface installed the default models are ``scrfd``/``arcface``
+  (previously dlib ``hog``/``resnet``).
+* The ``retina_face`` detector was renamed to ``scrfd`` (the actual model
+  architecture); the old name is kept as a deprecated alias.
+* Model downloads are verified against pinned SHA-256 checksums.
+
+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
+.. _build instructions: http://dlib.net/compile.html
+.. _PEP 487: https://www.python.org/dev/peps/pep-0487/
+.. _documentation: https://face-engine.readthedocs.io/en/latest/

face_engine-3.1.0/README.rst

@@ -0,0 +1,132 @@
+FaceEngine
+==========
+
+FaceEngine is a lightweight python library that provides an easy interface to
+work with **face recognition** tasks.
+
+.. code-block:: python
+
+    >>> from face_engine import FaceEngine
+    >>> engine = FaceEngine()
+    >>> engine.fit(['bubbles1.jpg', 'drive.jpg'], [1, 2])
+    >>> engine.make_prediction('bubbles2.jpg')
+    ([(270, 75, 406, 211)], [1])
+
+
+Installation
+------------
+
+It is distributed on `PyPi`_, and can be installed with pip:
+
+.. code-block:: console
+
+    $ pip install face-engine[insightface]
+
+FaceEngine is supported only on Python 3.11 and above.
+
+.. _PyPi: https://pypi.org/project/face-engine/
+
+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.
+   For NVIDIA GPU inference replace it with the GPU build — both
+   packages provide the same ``onnxruntime`` module, so the CPU build
+   must be removed first::
+
+       pip uninstall onnxruntime && pip install onnxruntime-gpu
+
+   The models use the CUDA execution provider automatically when
+   available.
+
+Legacy `dlib python api`_ models (``hog``, ``mmod`` detectors and ``resnet``
+embedder with dlib pre-trained model `files`_) are kept as an optional
+fallback backend used when insightface is not installed.
+
+.. note::
+   FaceEngine installation is not installing dlib by default.
+   To install it, either run ``pip install dlib`` (requires cmake),
+   install prebuilt wheels with ``pip install dlib-bin``, or follow
+   `build instructions`_.
+
+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
+-----------------------
+
+The library code is Apache-2.0, but the downloaded pre-trained model weights
+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
+-----------------------
+
+* Python >= 3.11 is required.
+* Pickle persistence was removed for security reasons: engines are saved as
+  JSON (``engine.save('engine.json')``) and estimator state as ``.npz`` +
+  ``.json`` files. Engines saved with face-engine < 3.0 cannot be loaded —
+  re-fit and save again.
+* With insightface installed the default models are ``scrfd``/``arcface``
+  (previously dlib ``hog``/``resnet``).
+* The ``retina_face`` detector was renamed to ``scrfd`` (the actual model
+  architecture); the old name is kept as a deprecated alias.
+* Model downloads are verified against pinned SHA-256 checksums.
+
+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
+.. _build instructions: http://dlib.net/compile.html
+.. _PEP 487: https://www.python.org/dev/peps/pep-0487/
+.. _documentation: https://face-engine.readthedocs.io/en/latest/

face_engine-3.1.0/docs/source/conf.py

@@ -0,0 +1,61 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+import os
+import sys
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+
+autodoc_mock_imports = ["dlib", "insightface", "onnxruntime"]
+sys.path.insert(0, os.path.abspath("../.."))
+
+# -- Project information -----------------------------------------------------
+
+project = "FaceEngine"
+copyright = "2019-2026, Daniyar Kussainov"
+author = "Daniyar Kussainov"
+
+# The full version, including alpha/beta/rc tags
+from face_engine import __version__
+
+release = __version__
+
+# -- General configuration ---------------------------------------------------
+
+# The master toctree document.
+master_doc = "index"
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ["sphinx.ext.autodoc"]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = []
+
+autodoc_member_order = "bysource"

face_engine-3.1.0/face_engine/__init__.py

@@ -0,0 +1,16 @@
+"""
+Face Recognition Engine
+"""
+
+__all__ = ["logger", "RESOURCES", "FaceEngine", "_models", "load_engine"]
+__version__ = "3.1.0"
+__author__ = "Daniyar Kussainov"
+__license__ = "Apache License, Version 2.0"
+__copyright__ = "Copyright 2019-2026 Daniyar Kussainov"
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+from face_engine.fetching import RESOURCES  # noqa: E402
+from face_engine.core import FaceEngine, _models, load_engine  # noqa: E402