# C++ API Reference

fvl

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

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

Loads the model file and sets up processing.

~FaceVerifier();

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.

Returns: std::future<std::vector<Face>> — the detected faces.

The given 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().

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.

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

Returns the embedding of a detected face.

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

This call is non-blocking.

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

Returns the embedding of a detected face via callback.

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

Compares two face embeddings.

Returns: Match — match result with the similarity metric.

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.

std::string getModelName() const;

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

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

static fvl::Version getSDKVersion();

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

Returns: Version — SDK version.

static std::string getSDKVersionString();

Returns the version of the SDK as a string.

Returns: std::string — SDK version string.

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

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.

DetectionQuality detectionQuality() const;

Returns: DetectionQuality — the detection quality of the face.

BoundingBox boundingBox() const;

Returns: BoundingBox — the bounding box of the face.

float confidence() const;

Returns: float — the detection confidence score.

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

Returns: std::vector<Point2d> — the 5 facial landmarks. See landmarks specification.

Descriptor for image data (non-owning).

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

2D point for landmark coordinates.

struct Point2d {
    float x;
    float y;
};

Bounding box for detected faces.

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

Result of face comparison.

struct Match {
    float similarity;
};

Semantic version number for the SDK.

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

Error information for the callback interface.

struct ErrorType {
    std::string errorString;
};

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

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

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

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

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

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

• FaceVerifier methods can be called concurrently from multiple threads.
• detectFaces() and embedFace() calls can execute concurrently.
• Use getConcurrentCalculations() to monitor and limit concurrency.