# C++ API Reference

## Namespace

`fvl`

---

## Classes

### FaceVerifier

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

#### Constructor

```cpp
FaceVerifier(const std::string& modelFile, int maxConcurrency = 0);
```

Loads the model file and sets up processing.

| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| modelFile | `const std::string&` | Path to the `.realZ` model file | — |
| maxConcurrency | `int` | Maximum allowed concurrency. 0 means automatic (using all cores) | `0` |

#### Destructor

```cpp
~FaceVerifier();
```

#### Methods

##### detectFaces (Future)

```cpp
std::future<std::vector<fvl::Face>> detectFaces(const fvl::ImageHeader& imageHeader);
```

Detects the faces on an image. Returns a future that resolves with the detected faces.

| Parameter | Type | Description |
|-----------|------|-------------|
| imageHeader | `const` [`ImageHeader`](#imageheader)`&` | Image descriptor |

**Returns:** `std::future<std::vector<`[`Face`](#face)`>>` — the detected faces.

The given [`ImageHeader`](#imageheader) doesn't own the image data; it is safe to delete the data after the call — a copy is made internally.

This call is non-blocking. You can call it again with the next image without waiting for the result. See [`getConcurrentCalculations()`](#getconcurrentcalculations).

##### detectFaces (Callback)

```cpp
void detectFaces(const fvl::ImageHeader& imageHeader,
                 std::function<void(ResultOrError<std::vector<Face>>)> callback);
```

Detects the faces on an image and invokes the callback with the result.

| Parameter | Type | Description |
|-----------|------|-------------|
| imageHeader | `const` [`ImageHeader`](#imageheader)`&` | Image descriptor |
| callback | `std::function<void(`[`ResultOrError`](#resultorerror)`<std::vector<`[`Face`](#face)`>>)>` | Callback invoked with the result |

##### embedFace (Future)

```cpp
std::future<std::vector<float>> embedFace(const fvl::Face& face);
```

Returns the embedding of a detected face.

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

**Returns:** `std::future<std::vector<float>>` — the face embedding vector.

This call is non-blocking.

##### embedFace (Callback)

```cpp
void embedFace(const fvl::Face& face,
               std::function<void(ResultOrError<std::vector<float>>)> callback);
```

Returns the embedding of a detected face via callback.

| Parameter | Type | Description |
|-----------|------|-------------|
| face | `const` [`Face`](#face)`&` | The previously detected face to embed |
| callback | `std::function<void(`[`ResultOrError`](#resultorerror)`<std::vector<float>>)>` | Callback invoked with the result |

##### compareFaces

```cpp
fvl::Match compareFaces(const std::vector<float>& embedding1,
                        const std::vector<float>& embedding2);
```

Compares two face embeddings.

| Parameter | Type | Description |
|-----------|------|-------------|
| embedding1 | `const std::vector<float>&` | Embedding of the first face |
| embedding2 | `const std::vector<float>&` | Embedding of the second face |

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

##### getConcurrentCalculations

```cpp
int getConcurrentCalculations() const;
```

Returns the approximate number of calculations currently in-flight. Use this to limit the number of concurrent calculations.

**Returns:** `int` — the number of concurrent calculations.

##### getModelName

```cpp
std::string getModelName() const;
```

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

**Returns:** `std::string` — name of the model.

##### getSDKVersion

```cpp
static fvl::Version getSDKVersion();
```

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

**Returns:** [`Version`](#version) — SDK version.

##### getSDKVersionString

```cpp
static std::string getSDKVersionString();
```

Returns the version of the SDK as a string.

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

---

### Face

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

#### Constructor

```cpp
Face(const fvl::ImageHeader& imageHeader,
     const std::vector<fvl::Point2d>& landmarks,
     const fvl::BoundingBox& bbox = fvl::BoundingBox(),
     float confidence = 0.0f);
```

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

| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| imageHeader | `const` [`ImageHeader`](#imageheader)`&` | Image containing the face | — |
| landmarks | `const std::vector<`[`Point2d`](#point2d)`>&` | Face landmarks (5 points) | — |
| bbox | `const` [`BoundingBox`](#boundingbox)`&` | Bounding box of the face | `BoundingBox()` |
| confidence | `float` | Detection confidence score | `0.0f` |

#### Methods

##### detectionQuality

```cpp
DetectionQuality detectionQuality() const;
```

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

##### boundingBox

```cpp
BoundingBox boundingBox() const;
```

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

##### confidence

```cpp
float confidence() const;
```

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

##### landmarks

```cpp
std::vector<fvl::Point2d> landmarks() const;
```

**Returns:** `std::vector<`[`Point2d`](#point2d)`>` — the 5 facial landmarks. See [landmarks specification](../overview.md#results).

---

## Types

### ImageHeader

Descriptor for image data (non-owning).

```cpp
struct ImageHeader {
    const uint8_t* data;
    int width;
    int height;
    int stride;
    fvl::ImageFormat format;
};
```

| Field | Type | Description |
|-------|------|-------------|
| data | `const uint8_t*` | Pointer to the byte array of the image |
| width | `int` | Width of the image in pixels |
| height | `int` | Height of the image in pixels |
| stride | `int` | Length of one row of pixels in bytes (e.g., `3*width + padding`) |
| format | [`ImageFormat`](#imageformat) | Image pixel format |

### Point2d

2D point for landmark coordinates.

```cpp
struct Point2d {
    float x;
    float y;
};
```

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

### BoundingBox

Bounding box for detected faces.

```cpp
struct BoundingBox {
    int x;
    int y;
    int width;
    int height;
};
```

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

### Match

Result of face comparison.

```cpp
struct Match {
    float similarity;
};
```

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

### Version

Semantic version number for the SDK.

```cpp
struct Version {
    int major;
    int minor;
    int patch;
};
```

| Field | Type | Description |
|-------|------|-------------|
| major | `int` | Major version number |
| minor | `int` | Minor version number |
| patch | `int` | Patch version number |

### ErrorType

Error information for the callback interface.

```cpp
struct ErrorType {
    std::string errorString;
};
```

| Field | Type | Description |
|-------|------|-------------|
| errorString | `std::string` | Human-readable description of the error |

### ResultOrError

Type representing the result or the error in the callback interface.

```cpp
template <typename ResultType>
using ResultOrError = std::variant<ResultType, ErrorType>;
```

Use `std::get_if` or `std::visit` to extract the result or error:

```cpp
if (auto* value = std::get_if<ResultType>(&result)) {
    // success
} else {
    auto& error = std::get<ErrorType>(result);
    // handle error
}
```

---

## Enums

### ImageFormat

```cpp
enum class ImageFormat {
    Grayscale = 0,
    RGB       = 1,
    RGBA      = 2,
    BGR       = 3,
    BGRA      = 4,
};
```

| Value | Description |
|-------|-------------|
| `Grayscale` | 8-bit grayscale |
| `RGB` | 24-bit RGB |
| `RGBA` | 32-bit RGBA or RGB with padding |
| `BGR` | 24-bit BGR |
| `BGRA` | 32-bit BGRA or BGR with padding |

### DetectionQuality

```cpp
enum class DetectionQuality {
    Good        = 0,
    BadQuality  = 1,
    MaybeRolled = 2,
};
```

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

---

## Thread Safety

- [`FaceVerifier`](#faceverifier) methods can be called concurrently from multiple threads.
- [`detectFaces()`](#detectfaces-future) and [`embedFace()`](#embedface-future) calls can execute concurrently.
- Use [`getConcurrentCalculations()`](#getconcurrentcalculations) to monitor and limit concurrency.