face-engine 3.0.0

Face Recognition Engine

FaceEngine is a lightweight python library that provides an easy interface to work with face recognition tasks.

>>> 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:

$ pip install face-engine[insightface]

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.

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.