# Python API Reference

## Module

```python
import realeyes.face_verification
```

---

## Classes

### FaceVerifier

The main entry point for face detection, embedding, and verification operations.

#### Constructor

```python
FaceVerifier(model_file: str, max_concurrency: int = 0)
```

Loads the model file and sets up processing.

| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| model_file | `str` | Path to the `.realZ` model file | — |
| max_concurrency | `int` | Maximum allowed concurrency. 0 means automatic (all cores) | `0` |

#### Methods

##### detect_faces

```python
def detect_faces(self, image: numpy.ndarray[numpy.uint8]) -> list[Face]
```

Detects faces on an image.

| Parameter | Type | Description |
|-----------|------|-------------|
| image | `numpy.ndarray[numpy.uint8]` | Image in RGB format, shape `(height, width, channels)` |

**Returns:** `list[`[`Face`](#face)`]` — the detected faces.

##### embed_face

```python
def embed_face(self, face: Face) -> list[float]
```

Returns the embedding vector of a detected face.

| Parameter | Type | Description |
|-----------|------|-------------|
| face | [`Face`](#face) | The previously detected face |

**Returns:** `list[float]` — the face embedding vector.

##### compare_faces

```python
def compare_faces(self, embedding1: list[float], embedding2: list[float]) -> Match
```

Compares two face embeddings.

| Parameter | Type | Description |
|-----------|------|-------------|
| embedding1 | `list[float]` | Embedding of the first face |
| embedding2 | `list[float]` | Embedding of the second face |

**Returns:** [`Match`](#match) — match result with similarity score.

##### get_model_name

```python
def get_model_name(self) -> str
```

Returns the name (version, etc.) of the loaded model.

**Returns:** `str` — model name.

---

## Module Functions

### get_sdk_version_string

```python
def get_sdk_version_string() -> str
```

Returns the version string of the SDK (not the model version).

**Returns:** `str` — SDK version string.

---

## Result Classes

### Face

Represents a detected face with landmarks, bounding box, and quality information.

#### Constructor

```python
Face(image: numpy.ndarray[numpy.uint8],
     landmarks: list[Point2d],
     bbox: BoundingBox = BoundingBox(x=0, y=0, width=0, height=0),
     confidence: float = 0.0)
```

Creates a Face object to support 3rd party face detectors.

| Parameter | Type | Description                                                                       | Default |
|-----------|------|-----------------------------------------------------------------------------------|---------|
| image | `numpy.ndarray[numpy.uint8]` | Image of the face (RGB format)                                                    | — |
| landmarks | `list[`[`Point2d`](#point2d)`]` | Face landmarks (5 points). See [landmarks specification](../overview.md#results). | — |
| bbox | [`BoundingBox`](#boundingbox) | Bounding box of the face                                                          | `BoundingBox(x=0, y=0, width=0, height=0)` |
| confidence | `float` | Detection confidence score                                                        | `0.0` |

#### Methods

##### bounding_box

```python
def bounding_box(self) -> BoundingBox
```

**Returns:** [`BoundingBox`](#boundingbox) — the bounding box of the detected face.

##### confidence

```python
def confidence(self) -> float
```

**Returns:** `float` — the detection confidence score.

##### detection_quality

```python
def detection_quality(self) -> DetectionQuality
```

**Returns:** [`DetectionQuality`](#detectionquality) — the detection quality of the face.

##### landmarks

```python
def landmarks(self) -> list[Point2d]
```

**Returns:** `list[`[`Point2d`](#point2d)`]` — the 5 facial landmarks.

---

### Point2d

2D point for landmark coordinates.

```python
Point2d(x: float, y: float)
```

| Attribute | Type | Description |
|-----------|------|-------------|
| x | `float` | X coordinate of the point |
| y | `float` | Y coordinate of the point |

### BoundingBox

Bounding box for detected faces.

```python
BoundingBox(x: int, y: int, width: int, height: int)
```

| Attribute | Type | Description |
|-----------|------|-------------|
| x | `int` | X coordinate of the top-left corner |
| y | `int` | Y coordinate of the top-left corner |
| width | `int` | Width of the bounding box in pixels |
| height | `int` | Height of the bounding box in pixels |

### Match

Result of face comparison.

| Attribute | Type | Description |
|-----------|------|-------------|
| similarity | `float` | Similarity score between the two faces |

---

## Enums

### DetectionQuality

Detection quality indicator.

| Value | Description |
|-------|-------------|
| `DetectionQuality.Good` | No issues detected |
| `DetectionQuality.BadQuality` | Bad quality detected |
| `DetectionQuality.MaybeRolled` | Face may be rolled; embeddings could be incorrect |