Face tracking¶

The FaceTracker class tracks faces in consecutive frames, and allows to follow a person by attributing it a unique ID based on its identity. It also automatically creates and consolidates templates over time.

Important

The face tracker requires the relevant AI models to run. See Face detection models for details.

The face tracker outputs a list of TrackedFace objects containing similar information as in a DetectedFace:

An identifier
A face detection score
The face bounds
The interocular distance (IOD)
The 5 landmark features (eyes, nose and mouth)

Plus the following:

The Parameters
The consolidated FaceTemplate Class

Parameters¶

The face tracker defines the following parameters:

Name	Description
Detection model	Face detection models used to detect faces.
Detection threshold	Confidence threshold of the face detector. Range is 0-100. Default value is 50.
Encoding model	Model used to create features and assess consistancy among views of a given face. We recommend Face Encoder 10C. Some better accuracy/speed balances can be found by choosing another model.
Matching threshold	Minimum match score to reach to preserve the ID of a tracked face between frame ‘t-1’ and frame ‘t’. Default value is 3000 which corresponds to a False Match Rate of 1/1000.
Maximum tracked face age	Maximum number of consecutive non-detections to reach before deleting a tracked face. Default value is 30 which corresponds to 2s at a frame rate of 15 FPS. One must adapt this value to its needs in terms of tracker identity memory (in seconds) and measured frame rate on target platform.
Minimum tracked face age	Minimum number of consecutive detections to reach before creating a tracked face. Default value is 1 for FaceDetector3B since the false detection rate is low enough. If using a less accurate detector (such as FaceDetector3C) one might consider increasing a bit this value to avoid false tracks.
NMS IOU threshold	Non-maximum suppression (NMS) intersection-over-union (IOU) threshold. Setting a high threshold allows to detect more overlapping faces which can be useful in a multi-face scenario. On the contrary, in a portrait scenario, a low NMS IOU threshold should be preferred.
Thread count	Number of threads to use for face detection. Default is 1.

Example¶

import id3face as id3

# Initialization
id3.FaceLibrary.load_model("models", id3.FaceModel.FACE_DETECTOR_4B, id3.ProcessingUnit.CPU)
id3.FaceLibrary.load_model("models", id3.FaceModel.FACE_ENCODER_10C, id3.ProcessingUnit.CPU)

face_tracker = id3.FaceTracker(
    detection_model= id3.FaceModel.FACE_DETECTOR_4B, 
    encoding_model= id3.FaceModel.FACE_ENCODER_10C,
    maximum_tracked_face_age=10,
    minimum_tracked_face_age=2,
    thread_count=2)


# placeholder functions
def capture_image() -> id3.Image:
    return id3.Image.from_file("data/placeholder.jpg", id3.PixelFormat.BGR_24_BITS)
def draw_bounds(image: id3.Image, bounds: id3.Rectangle):
    pass

# Application loop
tracked_faces_list = id3.TrackedFaceList()
while True:
    # Capture image
    image = capture_image()

    try:
        image_downscaled = image.clone()
        ratio = image_downscaled.downscale(256)

        face_tracker.track_faces(image_downscaled, tracked_faces_list)

    except id3.FaceException as ex:
        print(ex)
        continue
    
    # Process results
    for tracked_face in tracked_faces_list:
        if tracked_face.tracking_status == id3.TrackingStatus.INITIALIZED:
            print("New user detected, waiting for confirmation...")
        if tracked_face.tracking_status == id3.TrackingStatus.CONFIRMED:
            print("Tracked user " + str(tracked_face.id))
            tracked_face.rescale(1/ ratio)
            draw_bounds(image, tracked_face.bounds)
        elif tracked_face.tracking_status == id3.TrackingStatus.TEMPORARY_LOST:
            print("Temporary lost user " + str(tracked_face.id))
    

Face tracking¶

Parameters¶

Example¶

See also¶