Face Data

DeGirum Face API Reference. Face metadata utilities plus LanceDB record structures.

This API Reference is based on DeGirum Face version 1.4.1.

Classes

FaceAttributes

FaceAttributes

dataclass

Class to hold detected face attributes

FaceAttributes Methods

from_subclass(obj)

from_subclass(obj)

staticmethod

Create FaceAttributes instance from a subclass object (e.g., FaceStatus or FaceRecognitionResult).

Parameters:

Name	Type	Description	Default
obj	FaceAttributes	Instance of FaceAttributes or any subclass	required

Returns:

Name	Type	Description
FaceAttributes	FaceAttributes	New instance with only base class attributes

FaceMap

FaceMap

Thread-safe map of object IDs to object attributes.

FaceMap Methods

__enter__

__enter__()

Context manager entry: acquire the lock.

Returns:

Type	Description
	Dict[int, Any]: Direct reference to the internal map (use with caution while lock is held).

__exit__(exc_type, ...)

__exit__(exc_type, exc_val, exc_tb)

Context manager exit: release the lock.

Parameters:

Name	Type	Description	Default
exc_type		Exception type if an exception occurred.	required
exc_val		Exception value if an exception occurred.	required
exc_tb		Exception traceback if an exception occurred.	required

Returns:

Name	Type	Description
bool		False to propagate exceptions.

__init__

__init__()

Constructor.

__len__

__len__()

Get the number of items in the map.

Returns:

Name	Type	Description
int	int	Number of items in the map.

delete(expr)

delete(expr)

Delete objects from the map

Parameters:

Name	Type	Description	Default
expr	lambda	logical expression to filter objects to delete	required

Returns:

Type	Description
Dict[int, Any]	Dict[int, Any]: Map of deleted object IDs to their values.

get(id)

get(id)

Get the object by ID

Parameters:

Name	Type	Description	Default
id	int	The ID of the tracked face.	required

Returns:

Type	Description
Optional[Any]	Optional[Any]: The deep copy of object attributes or None if not found.

items

items()

Get an iterator over all items in the map.

Note: This method should be called within a 'with face_map:' context to ensure thread safety.

Returns:

Type	Description
	Iterator of (id, face) tuples.

put(id, ...)

put(id, value)

Add/update an object in the map

Parameters:

Name	Type	Description	Default
id	int	Object ID	required
value	Any	Object attributes reference	required

read_alerts

read_alerts()

Read the alerts and reset them.

Returns:

Type	Description
Dict[str, list]	Dict[str, list]: The map of alert messages if triggered, empty map otherwise.

set_alert(alert, ...)

set_alert(alert, info)

Set the alert message.

Parameters:

Name	Type	Description	Default
alert	str	The alert ID to set.	required
info	Any	Additional information related to the alert.	required

FaceOptionalProperties

FaceOptionalProperties

dataclass

Class to hold detected face optional properties (model-dependent)

FaceOptionalProperties Methods

from_dict(result)

from_dict(result)

staticmethod

Create FaceOptionalProperties instance from face embedding result dictionary

Parameters:

Name	Type	Description	Default
result	Dict[str, Any]	Dictionary containing face embedding results as returned by face embedding model	required

Returns:

Name	Type	Description
FaceOptionalProperties	FaceOptionalProperties	New instance initialized from result data

FaceRecognitionResult

FaceRecognitionResult

dataclass

Bases: FaceAttributes

Class to hold face recognition results

FaceRecognitionResult Methods

__str__

__str__()

Pretty print the face recognition results.

Returns:

Name	Type	Description
str	str	Formatted string representation of the results

from_dict(result)

from_dict(result)

staticmethod

Create FaceRecognitionResult instance from object detection result dictionary augmented with face recognition data.

Parameters:

Name	Type	Description	Default
result	Dict[str, Any]	Dictionary containing face detection/recognition results as returned by face recognition pipeline	required

Returns:

Name	Type	Description
FaceRecognitionResult	FaceRecognitionResult	New instance initialized from result data

FaceStatus

FaceStatus

dataclass

Bases: FaceAttributes

Class to hold detected face runtime status.