Face Tracking Gizmos

DeGirum Face API Reference. Composable gizmos powering the NiceGUI tracking experience.

This API Reference is based on DeGirum Face version 1.4.1.

Functions

Classes

FaceAnnotator

FaceAnnotator

Bases: ResultAnalyzerBase

Object annotating analyzer

FaceAnnotator Methods

__init__(object_map, ...)

__init__(object_map, *, label_map={})

Constructor.

Parameters:

Name	Type	Description	Default
object_map	FaceMap	The map of object IDs to attributes.	required
label_map	dict	Map of special labels (FaceStatus.lbl_*) to their display names.	{}

analyze(result)

analyze(result)

Analyze inference result and update labels based on object map

FaceCropCombiningGizmo

FaceCropCombiningGizmo

Bases: Gizmo

Gizmo that combines full frames with face crop inference results.

Input 0: Full frames Input 1: Face crops with inference results

FaceCropCombiningGizmo Methods

__init__(*, ...)

__init__(*, face_map=None)

Constructor.

run

run()

Run gizmo to combine full frames with crop inference results.

FaceDetectorGizmo

FaceDetectorGizmo

Bases: AiGizmoBase

Face detector AI inference gizmo which applies all necessary analyzers for face tracking

FaceDetectorGizmo Methods

__init__(model, ...)

__init__(model, *, analyzers, stream_depth=10, allow_drop=False)

Constructor.

Parameters:

Name	Type	Description	Default
analyzers	List[ResultAnalyzerBase]	List of analyzers to apply to the inference results.	required
stream_depth	int	Depth of the input stream queue. Defaults to 10.	10
allow_drop	bool	If True, allow dropping frames on input overflow. Defaults to False.	False

on_result(result)

on_result(result)

Append the inference result to the input frame's metadata and send it downstream. Adds face_tracking_frame_id attribute to the inference result.

Parameters:

Name	Type	Description	Default
result	InferenceResults	The inference result for the current frame.	required

run

run()

Run the model inference loop.

FaceEventNotifier

FaceEventNotifier

Bases: ResultAnalyzerBase

Analyzer to generate notifications and save video clips in case of face events

FaceEventNotifier Methods

__init__(*, ...)

__init__(*, face_map, config, clip_target_fps)

Constructor.

Parameters:

Name	Type	Description	Default
face_map	FaceMap	The map of tracked faces.	required
config	FaceTrackerConfig	Configuration for face tracking.	required
clip_target_fps	float	Target frames per second for video clips.	required

analyze(result)

analyze(result)

Analyze inference result and generate notifications for face events

finalize

finalize()

Finalize the analyzer and clean up resources

FaceFilter

FaceFilter

Bases: ResultAnalyzerBase

Analyzer to filter and prepare face detection results for reID processing.

Adds two results for each face

key_face_filter_applied: flag indicating which filter (if any) filtered-out this face from reID processing key_face_tracking_keypoints: face keypoints as numpy arrays

FaceFilter Methods

__init__(config, ...)

__init__(config, face_reid_map=None)

Constructor.

Parameters:

Name	Type	Description	Default
config	FaceFilterConfig	Configuration for face filtering.	required
face_reid_map	Optional[FaceMap]	The map of face IDs to face attributes.	None

analyze(result)

analyze(result)

Analyze inference result and mark faces for reID processing

FacePropertiesSmoothingAnalyzer

FacePropertiesSmoothingAnalyzer

Bases: ResultAnalyzerBase

Analyzer to persist face optional properties (gender, age, emotion, etc.) across frames.

Face optional properties are generated by the ReID model, which may not run on every frame due to ReID filtering. This analyzer caches the most recently seen properties for each tracked face and injects them into frames where the ReID model did not run, so that downstream consumers always see up-to-date attribute data.

FacePropertiesSmoothingAnalyzer Methods

__init__(smoothing_factor=0.8)

__init__(smoothing_factor=0.8)

Constructor.

Parameters:

Name	Type	Description	Default
smoothing_factor	float	IIR smoothing coefficient in [0, 1) applied to smoothed keys ("age", "age_sigma"). 0 means no smoothing.	0.8

analyze(result)

analyze(result)

Analyze inference result, caching new face properties and injecting cached ones.

For each tracked face and each property key individually

• If the key is present (non-None) in the result, call add() on the cached IIR object.
• If the key is absent, inject get() from the cached IIR object into the face result.

FaceRecognizerGizmo

FaceRecognizerGizmo

Bases: Gizmo

Face detection gizmo that combines face extraction, reID inference, and embeddings database face search.

FaceRecognizerGizmo Methods

__init__(face_reid_map, ...)

__init__(face_reid_map, *, config, face_embedding_model, delete_expired_faces=True, accumulate_embeddings=False, credence_count=1, alert_mode=AlertMode.NONE, alert_once=True, stream_depth=10, allow_drop=False)

Constructor.

Parameters:

Name	Type	Description	Default
face_reid_map	Optional[FaceMap]	The map of face IDs to face attributes.	required
config	FaceRecognizerConfig	Configuration for face recognition.	required
face_embedding_model		The face embedding model for reID inference.	required
delete_expired_faces	bool	Whether to delete expired faces from the map.	True
accumulate_embeddings	bool	Whether to accumulate embeddings in the face map.	False
credence_count	int	Number of times the face is recognized before confirming it.	1
alert_mode	AlertMode	Mode of alerting for the face search.	NONE
alert_once	bool	Whether to trigger the alert only once for the given face.	True
stream_depth	int	Depth of the stream.	10
allow_drop	bool	Whether to allow dropping frames.	False

extract_embeddings(result)

extract_embeddings(result)

staticmethod

Extract face embeddings from the result.

Returns:

Type	Description
ndarray	np.ndarray: embeddings vector.

get_tags

get_tags()

Get list of tags assigned to this gizmo

require_tags(inp)

require_tags(inp)

Get the list of meta tags this gizmo requires in upstream meta for a specific input.

Returns:

Type	Description
List[str]	List[str]: Tags required by this gizmo in upstream meta for the specified input.

run

run()

Run gizmo

HeadPoseAnalyzer

HeadPoseAnalyzer

Bases: ResultAnalyzerBase

Analyzer to detect head pose from face landmarks.

Computes confidence scores (0.0 to 1.0) for the following head poses:

• Head Turned Left
• Head Turned Right
• Head Tilted Left
• Head Tilted Right
• Head Tilted Up

Adds pose scores to face_properties dictionary in each face detection result.

HeadPoseAnalyzer Methods

__init__

__init__()

Constructor.

analyze(result)

analyze(result)

Analyze inference result and compute head pose confidence scores

LivenessDetector

LivenessDetector

Bases: ResultAnalyzerBase

Analyzer to detect liveness by tracking facial feature changes over time.

Maintains trails of facial feature scores for each tracked face to enable liveness detection based on natural head movements and expressions.

It adds the following keys to each face detection result with active track ID

"liveness_score": the computed liveness score based on feature changes "liveness_trails": the history of facial feature scores for this face

LivenessDetector Methods

__init__(*, ...)

__init__(*, trail_length=100, sensitivity=0.3, confidence_threshold=0.5, feature_list=None)

Constructor.

Parameters:

Name	Type	Description	Default
trail_length	int	Maximum length of facial feature trails in frames. Defaults to 100.	100
sensitivity	float	Sensitivity parameter for liveness detection. Defaults to 0.3. Higher values make the detector more sensitive. sensitivity=1/N gives ~50% score at N changes in one feature trail.	0.3
confidence_threshold	float	Confidence threshold for liveness detection. Defaults to 0.5. Used for detecting facial feature changes by comparing feature scores against this threshold.	0.5
feature_list	Optional[dict]	Optional dict mapping feature names to holdoff values. Holdoff is the minimum number of samples to ignore after a crossing before counting a new one. If None, defaults to head turn features with 10% of trail_length holdoff, others with 0.	None

analyze(result)

analyze(result)

Analyze inference result and track facial feature changes over time.

Adds the following keys to each face detection result with active track ID

"liveness_score": the computed liveness score based on feature changes "liveness_trails": the history of facial feature scores for this face