# .NET API Reference

## Namespace

`Realeyes.FaceVerification`

---

## Classes

### FaceVerifier

Main entry point for face detection, embedding, and verification operations. Implements `IDisposable`.

#### Constructor

```csharp
public FaceVerifier(string modelPath, int maxConcurrency = 0)
```

Creates a new FaceVerifier instance.

| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| modelPath | `string` | Path to the `.realZ` model file | — |
| maxConcurrency | `int` | Maximum concurrency. 0 for automatic (all cores) | `0` |

**Throws:**
- `ArgumentNullException` — when `modelPath` is null
- [`FaceVerificationException`](#faceverificationexception) — when model loading fails

#### Properties

| Property | Type | Description |
|----------|------|-------------|
| ConcurrentCalculations | `int` | Number of calculations currently running concurrently (read-only) |
| ModelName | `string` | Name/version of the loaded model (read-only) |
| SdkVersion | [`Version`](#version) | SDK version (read-only, static) |
| SdkVersionString | `string` | SDK version as a string (read-only, static) |

#### Methods

##### DetectFacesAsync

```csharp
public Task<FaceList> DetectFacesAsync(ImageHeader imageHeader)
```

Detects faces in an image asynchronously.

| Parameter | Type | Description |
|-----------|------|-------------|
| imageHeader | [`ImageHeader`](#imageheader) | Image to process |

**Returns:** `Task<`[`FaceList`](#facelist)`>` — disposable collection of detected faces.

**Throws:** [`FaceVerificationException`](#faceverificationexception) — when detection fails.

##### EmbedFaceAsync

```csharp
public Task<float[]> EmbedFaceAsync(Face face)
```

Computes the embedding vector for a detected face asynchronously.

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

**Returns:** `Task<float[]>` — embedding vector.

**Throws:**
- `ArgumentNullException` — when `face` is null
- [`FaceVerificationException`](#faceverificationexception) — when embedding fails

##### CompareFaces

```csharp
public Match CompareFaces(float[] embedding1, float[] embedding2)
```

Compares two face embeddings and returns a similarity score.

| Parameter | Type | Description |
|-----------|------|-------------|
| embedding1 | `float[]` | First face embedding |
| embedding2 | `float[]` | Second face embedding |

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

**Throws:**
- `ArgumentNullException` — when either embedding is null
- `ArgumentException` — when embeddings have different lengths

##### Dispose

```csharp
public void Dispose()
```

Disposes the FaceVerifier and releases native resources.

---

### FaceList

A disposable collection of [`Face`](#face) objects that automatically disposes all faces when disposed. Inherits from `List<Face>` and implements `IDisposable` and `IAsyncDisposable`.

#### Methods

##### Dispose

```csharp
public void Dispose()
```

Disposes all Face objects in the collection synchronously.

##### DisposeAsync

```csharp
public ValueTask DisposeAsync()
```

Disposes all Face objects in the collection asynchronously.

---

### Face

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

#### Constructor

```csharp
public Face(ImageHeader imageHeader, Point2d[] landmarks, BoundingBox boundingBox, float confidence)
```

Creates a Face object from a third-party face detector.

| Parameter | Type | Description |
|-----------|------|-------------|
| imageHeader | [`ImageHeader`](#imageheader) | Image containing the face |
| landmarks | [`Point2d`](#point2d)`[]` | Face landmarks (exactly 5 points) |
| boundingBox | [`BoundingBox`](#boundingbox) | Bounding box of the face |
| confidence | `float` | Detection confidence score |

**Throws:**
- `ArgumentNullException` — when `imageHeader` or `landmarks` is null
- `ArgumentException` — when landmarks count is not exactly 5
- [`FaceVerificationException`](#faceverificationexception) — when face creation fails

#### Properties

| Property | Type | Description |
|----------|------|-------------|
| DetectionQuality | [`DetectionQuality`](#detectionquality) | Detection quality of this face (read-only) |
| BoundingBox | [`BoundingBox`](#boundingbox) | Bounding box of this face (read-only) |
| Confidence | `float` | Detection confidence score (read-only) |

#### Methods

##### GetLandmarks

```csharp
public Point2d[] GetLandmarks()
```

Gets the facial landmarks.

**Returns:** [`Point2d`](#point2d)`[]` — array of 5 landmark points.

##### Clone

```csharp
public Face Clone()
```

Creates a copy of this face.

**Returns:** [`Face`](#face) — a new Face instance with the same data.

##### Dispose

```csharp
public void Dispose()
```

Disposes the face and releases native resources.

---

## Data Types

### ImageHeader

Image descriptor for passing image data to the Face Verification Library. (`readonly record struct`)

#### Constructor

```csharp
public ImageHeader(byte[] Data, int Width, int Height, int Stride, ImageFormat Format)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| Data | `byte[]` | Image data bytes |
| Width | `int` | Width in pixels |
| Height | `int` | Height in pixels |
| Stride | `int` | Length of one row in bytes (e.g., `3 * width + padding`) |
| Format | [`ImageFormat`](#imageformat) | Pixel format |

**Throws:**
- `ArgumentNullException` — when `Data` is null
- `ArgumentOutOfRangeException` — when `Width`, `Height`, or `Stride` is not positive

#### Properties

| Property | Type | Description |
|----------|------|-------------|
| Data | `byte[]` | Image data bytes (read-only) |
| Width | `int` | Width of the image in pixels (read-only) |
| Height | `int` | Height of the image in pixels (read-only) |
| Stride | `int` | Length of one row of pixels in bytes (read-only) |
| Format | [`ImageFormat`](#imageformat) | Image pixel format (read-only) |

### BoundingBox

Bounding box representing a rectangular region. (`readonly record struct`)

#### Constructor

```csharp
public BoundingBox(int X, int Y, int Width, int Height)
```

| Parameter | 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 |
| Height | `int` | Height of the bounding box |

#### Properties

| Property | Type | Description |
|----------|------|-------------|
| X | `int` | X coordinate of the top-left corner (read-only) |
| Y | `int` | Y coordinate of the top-left corner (read-only) |
| Width | `int` | Width of the bounding box (read-only) |
| Height | `int` | Height of the bounding box (read-only) |
| Right | `int` | Right edge X coordinate (`X + Width`) (read-only) |
| Bottom | `int` | Bottom edge Y coordinate (`Y + Height`) (read-only) |
| Area | `int` | Area of the bounding box (`Width * Height`) (read-only) |

### Point2d

2D point representing a landmark coordinate. (`readonly record struct`)

#### Constructor

```csharp
public Point2d(float X, float Y)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| X | `float` | X coordinate |
| Y | `float` | Y coordinate |

#### Properties

| Property | Type | Description |
|----------|------|-------------|
| X | `float` | X coordinate (read-only) |
| Y | `float` | Y coordinate (read-only) |

### Match

Result of face comparison indicating similarity. (`readonly record struct`)

#### Constructor

```csharp
public Match(float Similarity)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| Similarity | `float` | Similarity score |

#### Properties

| Property | Type | Description |
|----------|------|-------------|
| Similarity | `float` | Similarity score (read-only) |

#### Methods

##### ExceedsThreshold

```csharp
public bool ExceedsThreshold(float threshold)
```

Checks if the similarity score exceeds a threshold.

| Parameter | Type | Description |
|-----------|------|-------------|
| threshold | `float` | Similarity threshold |

**Returns:** `bool` — `true` if `Similarity >= threshold`.

### Version

Semantic version number. (`readonly record struct`)

#### Constructor

```csharp
public Version(int Major, int Minor, int Patch)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| Major | `int` | Major version number |
| Minor | `int` | Minor version number |
| Patch | `int` | Patch version number |

#### Properties

| Property | Type | Description |
|----------|------|-------------|
| Major | `int` | Major version number (read-only) |
| Minor | `int` | Minor version number (read-only) |
| Patch | `int` | Patch version number (read-only) |

#### Methods

##### ToString

```csharp
public override string ToString()
```

**Returns:** `string` — version in `"Major.Minor.Patch"` format.

---

## Enumerations

### ImageFormat

Image pixel format.

| Value | Int | Description |
|-------|-----|-------------|
| `Grayscale` | 0 | 8-bit grayscale |
| `RGB` | 1 | 24-bit RGB |
| `RGBA` | 2 | 32-bit RGBA or RGB with padding |
| `BGR` | 3 | 24-bit BGR |
| `BGRA` | 4 | 32-bit BGRA or BGR with padding |

### DetectionQuality

Detection quality indicator.

| Value | Int | Description |
|-------|-----|-------------|
| `Good` | 0 | No issues detected |
| `BadQuality` | 1 | Bad quality detected |
| `MaybeRolled` | 2 | Face may be rolled; embeddings could be incorrect |

---

## Exceptions

### FaceVerificationException

Exception thrown when Face Verification Library operations fail. Inherits from `Exception`.

#### Constructors

```csharp
public FaceVerificationException()
public FaceVerificationException(string message)
public FaceVerificationException(string message, Exception innerException)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| message | `string` | Error message |
| innerException | `Exception` | Inner exception |