# Face Data

{% hint style="info" %}
This API Reference is based on DeGirum Face version 1.4.1.
{% endhint %}

## Classes <a href="#classes" id="classes"></a>

## FaceAttributes <a href="#faceattributes" id="faceattributes"></a>

`FaceAttributes`

`dataclass`

Class to hold detected face attributes

### FaceAttributes Methods <a href="#faceattributes-methods" id="faceattributes-methods"></a>

#### from\_subclass(obj) <a href="#from_subclass" id="from_subclass"></a>

`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 <a href="#facemap" id="facemap"></a>

`FaceMap`

Thread-safe map of object IDs to object attributes.

### FaceMap Methods <a href="#facemap-methods" id="facemap-methods"></a>

#### \_\_enter\_\_ <a href="#enter" id="enter"></a>

`__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, ...) <a href="#exit" id="exit"></a>

`__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\_\_ <a href="#init" id="init"></a>

`__init__()`

Constructor.

#### \_\_len\_\_ <a href="#len" id="len"></a>

`__len__()`

Get the number of items in the map.

Returns:

| Name  | Type  | Description                 |
| ----- | ----- | --------------------------- |
| `int` | `int` | Number of items in the map. |

#### delete(expr) <a href="#delete" id="delete"></a>

`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) <a href="#get" id="get"></a>

`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 <a href="#items" id="items"></a>

`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, ...) <a href="#put" id="put"></a>

`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 <a href="#read_alerts" id="read_alerts"></a>

`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, ...) <a href="#set_alert" id="set_alert"></a>

`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 <a href="#faceoptionalproperties" id="faceoptionalproperties"></a>

`FaceOptionalProperties`

`dataclass`

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

### FaceOptionalProperties Methods <a href="#faceoptionalproperties-methods" id="faceoptionalproperties-methods"></a>

#### from\_dict(result) <a href="#from_dict" id="from_dict"></a>

`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 <a href="#facerecognitionresult" id="facerecognitionresult"></a>

`FaceRecognitionResult`

`dataclass`

Bases: `FaceAttributes`

Class to hold face recognition results

### FaceRecognitionResult Methods <a href="#facerecognitionresult-methods" id="facerecognitionresult-methods"></a>

#### \_\_str\_\_ <a href="#str" id="str"></a>

`__str__()`

Pretty print the face recognition results.

Returns:

| Name  | Type  | Description                                    |
| ----- | ----- | ---------------------------------------------- |
| `str` | `str` | Formatted string representation of the results |

#### from\_dict(result) <a href="#from_dict" id="from_dict"></a>

`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 <a href="#facestatus" id="facestatus"></a>

`FaceStatus`

`dataclass`

Bases: `FaceAttributes`

Class to hold detected face runtime status.