Face Data Classes

Overview

Face data in degirum-face is represented by two related classes:

• FaceAttributes - Contains face identity data (embeddings, attributes, images)

• FaceRecognitionResult - Includes all FaceAttributes properties plus detection metadata (bounding box, scores, landmarks)

FaceAttributes

Contains face identity data without detection-specific information. Used primarily for enrollment workflows.

Properties

Property	Type	Description
attributes	dict or str or None	Person metadata. Can be any Python dictionary containing person information (first name, last name, address, etc.) or a simple string for the person's name. Examples in this documentation use simple strings for clarity.
db_id	str or None	Database ID if stored
embeddings	list	Face embedding vector(s) (512-D each). May contain multiple embeddings when returned by find_faces_in_file() / find_faces_in_clip()
images	list	Cropped face images (numpy arrays) corresponding to embeddings. May contain multiple images when returned by find_faces_in_file() / find_faces_in_clip()

When It's Used

find_faces_in_file() and find_faces_in_clip() return Dict[int, FaceAttributes] - a mapping of track IDs to face data. Each FaceAttributes object contains:

• Multiple embeddings - One for each frame where the face was detected (or sampled based on reid_expiration_frames)

• Multiple images - Corresponding cropped face images for each embedding

• This accumulated data across frames provides robust face representations for enrollment

Also used as input to FaceTracker.enroll() for batch enrollment.

Usage Example

# Analyze video to extract faces
faces = tracker.find_faces_in_file("video.mp4")

# faces is Dict[int, FaceAttributes] - maps track_id to face data
for track_id, face_data in faces.items():
    print(f"Track {track_id}:")
    print(f"  Person: {face_data.attributes}")
    print(f"  Embeddings: {len(face_data.embeddings)}")  # Multiple per track
    print(f"  Images: {len(face_data.images)}")  # Multiple per track
    
    # Enroll if unknown
    if not face_data.attributes:
        # Assign person identifier - could be a name, ID, or dict with metadata
        face_data.attributes = f"Person_{track_id}"
        tracker.enroll(face_data)

FaceRecognitionResult

Subclasses FaceAttributes to add detection-specific metadata. Used for real-time recognition results.

Properties

Inherits all FaceAttributes properties (attributes, db_id, embeddings, images) plus:

Property	Type	Description
bbox	list	Bounding box [x1, y1, x2, y2]
detection_score	float	Face detection confidence 0.0-1.0
similarity_score	float or None	Match confidence 0.0-1.0 (None if unknown)
landmarks	array	Facial keypoints (eyes, nose, mouth)
frame_id	int or None	Frame number (when applicable)

Important notes:

• The embeddings and images lists contain a single item when returned by enroll_image(), enroll_batch(), predict(), or predict_batch(). Access using result.embeddings[0] and result.images[0]. This is different from find_faces_in_file() / find_faces_in_clip() which return multiple embeddings/images per track.

• When using FaceTracker, track_id is in InferenceResults.results, not as a property. Access via result.results[i].get("track_id")

When It's Used

• Returned by enroll_image() and enroll_batch()

• Contained in InferenceResults.faces from predict() and predict_batch()

Usage Examples

Check if face was detected:

result = recognizer.enroll_image("photo.jpg", "Alice")
if result:
    print(f"Enrolled: {result.attributes}")
else:
    print("No face detected")

Access detection properties:

result = recognizer.predict("photo.jpg")

for face in result.faces:
    if face.attributes:
        print(f"Known: {face.attributes} (confidence: {face.similarity_score:.2f})")
    else:
        print(f"Unknown person (detection score: {face.detection_score:.2f})")
    
    # Access bounding box
    x1, y1, x2, y2 = face.bbox
    print(f"Face location: ({x1}, {y1}) to ({x2}, {y2})")

Access embeddings and cropped images:

result = recognizer.enroll_image("photo.jpg", "Alice")
embedding_vector = result.embeddings[0]  # 512-D numpy array
cropped_face = result.images[0]  # Aligned 112×112 face image

print(f"Embedding shape: {embedding_vector.shape}")  # (512,)
cv2.imwrite("cropped_face.jpg", cropped_face)

FaceTracker - Access tracking data:

for result in tracker.predict_batch(video_source):
    # result.faces and result.results correspond at the same index
    for i in range(len(result.faces)):
        track_id = result.results[i].get("track_id")
        person = result.faces[i].attributes
        print(f"Track {track_id}: {person}")

Return Types by Method

FaceRecognizer

Method	Return Type
enroll_image()	Optional[FaceRecognitionResult]
enroll_batch()	List[FaceRecognitionResult]
predict()	InferenceResults (.faces property yields FaceRecognitionResult objects)
predict_batch()	Iterator of InferenceResults

FaceTracker

Method	Return Type
predict_batch()	Iterator of InferenceResults (.faces property yields FaceRecognitionResult objects)
find_faces_in_file()	Dict[int, FaceAttributes]
find_faces_in_clip()	Dict[int, FaceAttributes]