Core API

FaceEngine core module.

face_engine.core.load_engine(filename)

Loads and restores engine object from the file.

This function is convenient wrapper of pickle.load() function, and is used to deserialize and restore the engine object from the persisted state.

Estimator model’s state is loaded separately and is loaded only if there is something saved before by save() method. Estimator model serialization (.save) and deserialization (.load) process steps are the responsibility of it’s inheriting class.

Parameters:filename (str) – serialized by save() method file name
Returns:restored engine object
Return type:FaceEngine
class face_engine.core.FaceEngine(**kwargs)

Bases: object

Face recognition engine base class.

This object provides all steps and tools which are required to work with face recognition task.

Keyword arguments:
  • detector (str) – face detector model to use
  • embedder (str) – face embedder model to use
  • estimator (str) – face estimator model to use
detector
Returns:detector model name
Return type:str
embedder
Returns:embedder model name
Return type:str
estimator
Returns:estimator model name
Return type:str
save(filename)

Save engine object state to the file.

Persisting the object state as lightweight engine instance which contains only model name strings instead of model objects itself. Upon loading model objects will have to be re-initialized.

fit(images, class_names, **kwargs)

Fit (train) estimator model with given images for given class names.

Estimator’s fit() wrapping method.

Note

  • the number of images and class_names has to be equal
  • the image will be skipped if the face is not found inside
Parameters:
  • images (list[str]) – image file names or uri strings
  • class_names (list) – sequence of class names
  • kwargs – estimator model and data dependent
Returns:

self
Raises:

TrainError
predict(embeddings)

Make predictions for given embeddings.

Estimator’s predict() wrapping method.

Parameters:embeddings (numpy.ndarray) – array of embedding vectors with shape (n_faces, embedding_dim)
Returns:prediction scores and class names
Return type:(list, list)
Raises:TrainError
make_prediction(image, **kwargs)

Lazy prediction method to make prediction by given image.

Convenient wrapper method to go over all steps of face recognition problem by one call.

In particular:
  1. find_faces() - detector
  2. compute_embeddings() - embedder
  3. predict() - estimator

Keyword arguments are all parameters of find_faces() method. Returns image all face bounding boxes with predicted class names. May raise same exceptions of all calling methods.

Parameters:image (Union[str, bytes, file, os.PathLike, numpy.ndarray]) – RGB image content or image file uri.
Returns:bounding boxes and class_names
Return type:tuple(list, list)
Raises:FaceNotFoundError
Raises:TrainError
find_faces(image, limit=None, normalize=False)

Find multiple faces in the image.

Detector’s detect_all() wrapping method.

Parameters:
  • image (Union[str, bytes, file, os.PathLike, numpy.ndarray]) – RGB image content or image file uri.
  • limit (int) – limit the number of detected faces on the image by bounding box size.
  • normalize (bool) – normalize output bounding boxes
Returns:

face bounding box with shape (n_faces, 4), detector model dependent extra information.
Return type:

(numpy.ndarray, dict)
Raises:

FaceNotFoundError
compute_embeddings(image, bounding_boxes, **kwargs)

Compute image embeddings for given bounding boxes.

Embedder’s compute_embeddings() wrapping method.

Parameters:
  • image (numpy.ndarray) – RGB image with shape (rows, cols, 3)
  • bounding_boxes (numpy.ndarray) – face bounding boxes
  • kwargs – model dependent
Returns:

array of embedding vectors with shape (n_faces, embedding_dim)
Return type:

numpy.ndarray

Exceptions

Handled exceptions raised by FaceEngine

exception face_engine.exceptions.FaceNotFoundError

Bases: Exception

Raised when the face is not found in the image

exception face_engine.exceptions.TrainError

Bases: Exception

Raised when the fit(train) process is failed