# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.degirum.com/face-recognition/complete-api-reference/face_data.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.