Skip to content

Python api autogen

FaceIdentification

init

FaceIdentification.__init__(height: int, width: int)

Initializes a new face identification object.

This needs to be called only once at the start of the application.

Arguments:

  • height:: The height of the input image in pixels.
  • width:: The width of the input image in pixels.

Returns:

  • Nothing.

process_frame

FaceIdentification.process_frame(
    image, delta_t: float = 0.0
) -> tuple[ErrorCodeFamiliarFaceID, tuple[BoxPrediction, ...]]

Process a single frame from a video sequence with RGB input.

The image must have the height and width that was specified when the FaceIdentification object was created.

Arguments:

  • image: A tensor of shape (video_height, video_width, 3) with RGB image data. It can be a Numpy array or TensorFlow, PyTorch or Jax tensor.
  • delta_t: The time in seconds it took between this and the previous video frame (1/fps). If left to the default of 0, then the system clock will be used to compute this value.

Returns:

single_image

FaceIdentification.single_image(
    image
) -> tuple[ErrorCodeFamiliarFaceID, tuple[BoxPrediction, ...]]

Process a single image not part of a video sequence.

This should not be used for video data. It can be used for face enrollments from a set of images. The returned box id values are not related to those returned by process_frame or other calls to single_frame.

Arguments:

  • image: A tensor of shape (*, *, 3) with RGB image data. It can be a Numpy array, or TensorFlow, PyTorch or Jax tensor.

Returns:

add_face_embedding

FaceIdentification.add_face_embedding(
    face_embedding: np.ndarray, face_id: int
) -> ErrorCodeFamiliarFaceID

Add a face embedding to the face library for any process_frame calls that follow.

A second embedding for the same face id will overwrite the previous one.

When process_frame detects a person that matches a face, it will use the face_id provided here in the returned BoxPrediction.

Arguments:

  • face_embedding: A NumPy face embedding as returned by finish_face_enrollment. If an empty NumPy array is given, the specified face_id is removed.
  • face_id: A non-negative integer face-ID, which is not allowed to be equal to FACE_ID_UNIDENTIFIED or FACE_ID_NOT_IN_LIBRARY.

Returns:

  • Returns the error code "SUCCESS" on success, "INVALID_FACE_ID" or "INVALID_EMBEDDING" on failure.

remove_face_embedding

FaceIdentification.remove_face_embedding(face_id: int) -> ErrorCodeFamiliarFaceID

Remove a face embedding from the face library for any process_frame calls that follow.

Arguments:

Returns:

  • Returns the error code "SUCCESS" on success.

start_face_enrollment

FaceIdentification.start_face_enrollment(
    region_of_interest: tuple[float, float, float, float] = (0, 0, 1, 1),
) -> ErrorCodeFamiliarFaceID

This starts the enrollment procedure for a new face.

During subsequent calls to process_frame or single_image, face embeddings will be computed. During enrollment there should be a single face in the image, or in the optional region specified by region_of_interest, ideally clearly and completely visible. The enrollment procedure can be finalized by calling finish_face_enrollment.

Arguments:

  • region_of_interest: This can be set to a region of interest in the image as y_min, x_min, y_max, x_max in relative coordinates. Only faces that have overlap with this region will be used for enrollment. The default of 0, 0, 1, 1 includes the entire image.

Returns:

  • Returns the error code "ENROLLMENT_IN_PROGRESS" if the enrollment procedure was started successfully, otherwise returns "ALREADY_ENROLLING".

finish_face_enrollment

FaceIdentification.finish_face_enrollment() -> tuple[ErrorCodeFamiliarFaceID, np.ndarray]

Finalize the face enrollment procedure started by start_face_enrollment and obtain the face embedding.

The application is responsible for storing this embedding on persistent storage and passing it to add_face_embedding every time an instance of this class is created. The face enrollment procedure does not automatically call add_face_embedding.

Arguments:

  • None.

Returns:

  • A tuple with an error code of type ErrorCodeFamiliarFaceID and the resulting face embedding vector

get_face_id

FaceIdentification.get_face_id(person_box: BoxPrediction) -> int

Retrieve the face ID that belongs to a person box.

Retrieves the face ID given a person box returned by process_frame. This function has three possible return values:

  • FACE_ID_UNIDENTIFIED when the provided box is not of CLASS_PERSON or when a face is not yet identified, e.g. the face is not fully visible.
  • FACE_ID_NOT_IN_LIBRARY when the face is visible but not found in the library, e.g. when a stranger is in view.
  • Any integer face-ID provided previously to add_face_embedding when a familiar face is identified.

This function should not be called directly after restoring from a previous state.

Arguments:

  • person_box: A box returned by process_frame with class_id equal to DetectionClass::CLASS_PERSON.

Returns:

  • Returns an integer face-ID as provided when calling add_face_embedding when a face is identified, FACE_ID_UNIDENTIFIED or FACE_ID_NOT_IN_LIBRARY when it is not identified successfully, or FACE_ID_UNIDENTIFIED when the provided box is not a valid person box.