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

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.

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:

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

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

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.

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

• 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.