Plumerai Familiar Face Identification Python API¶

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

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

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

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

FaceIdentification.remove_face_embedding(face_id: int) -> ErrorCodeFamiliarFaceID

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

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

FaceIdentification.get_face_id(person_box: BoxPrediction) -> int

class BoxPrediction(NamedTuple):
    y_min: float  # top coordinate between 0 and 1 in height dimension
    x_min: float  # left coordinate between 0 and 1 in width dimension
    y_max: float  # bottom coordinate between 0 and 1 in height dimension
    x_max: float  # right coordinate between 0 and 1 in width dimension
    confidence: float  # between 0 and 1, higher means more confident
    id: int = 0  # the tracked identifier of this box
    class_id: int = DetectionClass.CLASS_UNKNOWN  # the class of the object

class DetectionClass(Enum):
    CLASS_UNKNOWN = 0
    CLASS_PERSON = 1
    CLASS_HEAD = 2
    CLASS_FACE = 3

class ErrorCodeFamiliarFaceID(Enum):
    # All went well
    SUCCESS = 0

    # Should not occur, contact Plumerai if this happens
    INTERNAL_ERROR = -1

    # The `delta_t` parameter should be >= 0
    INVALID_DELTA_T = -2

    # Everything OK, enrollment is in progress.
    ENROLLMENT_IN_PROGRESS = -1000

    # This library is not built with support for face identification.
    FACE_IDENTIFICATION_DISABLED = -1001

    # Called `start_face_enrollment` but enrollment is already started.
    ALREADY_ENROLLING = -1002

    # Last frame was ignored because multiple faces were detected within the
    # specified region of interest. Try again with one face visible.
    MULTIPLE_FACES_IN_VIEW = -1003

    # Last frame was ignored because no face was detected, or it was not clearly
    # visible, or the lighting was not good enough for enrollment. Try again with
    # one face clearly visible.
    NO_FACE_IN_VIEW = -1004

    # Last frame was ignored because the face detection was too close to the
    # edge. Too close to the edge means that the border of the face bounding-box
    # is within 2% of the edge of the image. In theory, it is OK if a face is
    # close to edge, however, it can also mean that a face is only partially
    # visible. Thus, this check is added to prevent partial faces from being
    # enrolled.
    FACE_CLOSE_TO_EDGE = -1005

    # Called `finish_face_enrollment` but enrollment was not started.
    NOT_ENROLLING = -1006

    # This is returned by `finish_face_enrollment` when the enrollment failed
    # because no faces could be detected in any of the images.
    ENROLLMENT_FAILED = -1007

    # This is returned by `finish_face_enrollment` when a face embedding vector
    # is returned but the quality of the enrollment is very low. In this case
    # re-enrolllment is recommended.
    LOW_QUALITY_ENROLLMENT = -1008

    # Returned by `add_face_embedding` or `remove_face_embedding` when the
    # provided face ID is invalid.
    INVALID_FACE_ID = -1009

    # Returned by `add_face_embedding` when the provided face embedding is
    # invalid.
    INVALID_EMBEDDING = -1010

FACE_ID_UNIDENTIFIED = -1
FACE_ID_NOT_IN_LIBRARY = -2

import numpy as np
import plumerai_people_detection as ppd_api

# Settings, to be changed as needed
width = 1600  # camera image width in pixels
height = 1200  # camera image height in pixels

# Initialize the `FaceIdentification` object
ffid = ppd_api.FaceIdentification(height, width)

# ---------------------- Enrollment starting ------------------------------

error_code = ffid.start_face_enrollment()
if error_code != ppd_api.ErrorCodeFamiliarFaceID.ENROLLMENT_IN_PROGRESS:
    raise RuntimeError(f"Error in 'start_face_enrollment': {error_code}")

# Enroll for 10 frames (just an example, more frames is better)
for t in range(10):
    # Some example input here, normally this is where camera data is acquired
    image = np.zeros((height, width, 3), dtype=np.uint8)

    # Process the frame. If the enrollment frames come from a video source,
    # then use 'process_frame' instead.
    error_code, predictions = ffid.single_image(image)
    if error_code != ppd_api.ErrorCodeFamiliarFaceID.SUCCESS:
        raise RuntimeError(f"Error in 'single_image': {error_code}")

# Finish enrollment
error_code, embedding = ffid.finish_face_enrollment()
if error_code != ppd_api.ErrorCodeFamiliarFaceID.SUCCESS:
    raise RuntimeError(f"Error in 'finish_face_enrollment': {error_code}")

# Add the embedding to the library with face id '1'.
error_code = ffid.add_face_embedding(embedding, face_id=1)
if error_code != ppd_api.ErrorCodeFamiliarFaceID.SUCCESS:
    raise RuntimeError(f"Error in 'add_face_embedding': {error_code}")

# ---------------------- Enrollment finished ------------------------------

# Loop over frames in a video stream (example: 10 frames)
for t in range(10):
    # Some example input here, normally this is where camera data is acquired
    image = np.zeros((height, width, 3), dtype=np.uint8)

    # The time between two video frames in seconds. In this example we assume
    # a constant frame rate of 30 fps, but variable rates are supported.
    delta_t = 1. / 30.

    # Process the frame
    error_code, predictions = ffid.process_frame(image, delta_t)
    if error_code != ppd_api.ErrorCodeFamiliarFaceID.SUCCESS:
      raise RuntimeError(f"Error in 'process_frame': {error_code}")

    # Display the results
    for p in predictions:
        if p.class_id != ppd_api.DetectionClass.CLASS_PERSON:
          continue
        face_id = ffid.get_face_id(p)
        print(
            f"Box #{p.id} with face ID {face_id} with confidence {p.confidence} "
            f"@(x,y)->({p.x_min:.2f},{p.y_min:.2f})-({p.x_max:.2f},{p.y_max:.2f})"
        )
    if len(predictions) == 0:
        print("No bounding boxes found in this frame")