Face Tracking Gizmos
DeGirum Face API Reference. Composable gizmos powering the NiceGUI tracking experience.
Functions
Classes
FaceAnnotator
FaceAnnotator
Bases: ResultAnalyzerBase
Object annotating analyzer
FaceAnnotator Methods
__init__(object_map, ...)
__init__(object_map, *, label_map={})
Constructor.
Parameters:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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
Last updated