Skip to content

Python API minimal examples

Video processing

This example shows how to initialize the video intelligence class and process a video frame.

import numpy as np
import plumerai_video_intelligence as pvi_api

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

# Initialize the video intelligence algorithm
pvi = pvi_api.VideoIntelligence(height, width)

# 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.0 / 30.0

    # Process the frame
    error_code = pvi.process_frame(image, delta_t)
    if error_code != pvi_api.ErrorCode.SUCCESS:
        raise RuntimeError(f"Error in 'process_frame': {error_code}")

    error_code, predictions = pvi.object_detection.get_detections()
    if error_code != pvi_api.ErrorCode.SUCCESS:
        raise RuntimeError(f"Error in 'get_detections': {error_code}")

    # Display the results
    for p in predictions:
        print(
            f"Box #{p.id} of class {p.class_id} "
            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")

Automatic Face Enrollment

This example extends the code above and shows how to use the automatic face enrollment functionality.

The changes compared to the minimal example above are highlighted.

import numpy as np
import plumerai_video_intelligence as pvi_api

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

# Initialize the video intelligence algorithm
pvi = pvi_api.VideoIntelligence(height, width)

# Loop over frames in a video stream (example: 20 frames)
for t in range(20):
    # 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.0 / 30.0

    # Process the frame
    error_code = pvi.process_frame(image, delta_t)
    if error_code != pvi_api.ErrorCode.SUCCESS:
        raise RuntimeError(f"Error in 'process_frame': {error_code}")

    # Report the number of faces in the library so far. At first the library
    # will be empty, but as soon as a face is well visible for a while, it
    # will be added to the library with a new unique face-ID. The library
    # will grow over time, unless `remove_face_embedding` is called.
    error_code, face_ids = pvi.face_enrollment_automatic.get_face_ids()
    if error_code != pvi_api.ErrorCode.SUCCESS:
        raise RuntimeError(f"Error in 'get_face_ids': {error_code}")
    print(f"Total of {len(face_ids)} people in the familiar face-ID library")

    error_code, predictions = pvi.object_detection.get_detections()
    if error_code != pvi_api.ErrorCode.SUCCESS:
        raise RuntimeError(f"Error in 'get_detections': {error_code}")

    # Display the results
    for p in predictions:
        if p.class_id == pvi_api.DetectionClass.CLASS_PERSON:
            # After a few frames of showing a clear face in view, the face-ID should
            # become non-negative as the face is automatically enrolled.
            face_id = pvi.get_face_id(p)
            print(
                f"Person box #{p.id} with face id {face_id} "
                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")

Manual face enrollment

This example shows how to use the manual face enrollment functionality. It consists of two main loops:

  1. An example enrollment loop, which runs for a fixed number of frames and computes a face embedding vector to enroll one person in the face library.
  2. An example video processing loop, similar to the first example.
# Initialize the video intelligence algorithm
pvi = pvi_api.VideoIntelligence(height, width)

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

error_code = pvi.face_enrollment_manual.start_enrollment()
if error_code != pvi_api.ErrorCode.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 = pvi.single_image(image)
    if error_code != pvi_api.ErrorCode.SUCCESS:
        raise RuntimeError(f"Error in 'single_image': {error_code}")

# Finish enrollment
error_code, embedding = pvi.face_enrollment_manual.finish_enrollment()
if error_code != pvi_api.ErrorCode.SUCCESS:
    raise RuntimeError(f"Error in 'finish_face_enrollment': {error_code}")

# Add the embedding to the library with face id '1'.
error_code = pvi.face_enrollment_manual.add_embedding(embedding, face_id=1)
if error_code != pvi_api.ErrorCode.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.0 / 30.0

    # Process the frame
    error_code = pvi.process_frame(image, delta_t)
    if error_code != pvi_api.ErrorCode.SUCCESS:
        raise RuntimeError(f"Error in 'process_frame': {error_code}")

    error_code, predictions = pvi.object_detection.get_detections()
    if error_code != pvi_api.ErrorCode.SUCCESS:
        raise RuntimeError(f"Error in 'get_detections': {error_code}")

    # Display the results
    for p in predictions:
        if p.class_id == pvi_api.DetectionClass.CLASS_PERSON:
            face_id = pvi.face_identification.get_face_id(p)
            print(
                f"Person box #{p.id} with face id {face_id} "
                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")