Metadata-Version: 2.4
Name: face-engine
Version: 3.0.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 three model interfaces ``Detector``, ``Embedder``
and ``Estimator`` (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
======================= ========== ============ ===========================

.. 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`_).

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`_.

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
.. _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/
