# C API Documentation

The C API provides a plain C interface to the Face Verification Library, suitable for integration with C programs and other languages through FFI.

Opaque handles to FaceVerifier and Face instances (typedef to struct pointers).

typedef struct FVLFaceVerifier FVLFaceVerifier;

typedef struct FVLFace FVLFace;

FVLFaceVerifier* fvl_face_verifier_new(const char* model_file,
                                       int max_concurrency,
                                       char** errorMessage)

Constructor: loads model file, sets up the processing.

Parameters:

• model_file - path for the used model
• max_concurrency - maximum allowed concurrency, 0 means automatic (using all cores), default: 0
• errorMessage - pointer to a char* that will be set to an error message string on failure, or NULL on success. The caller is responsible for freeing the string using free(). If errorMessage is a NULL pointer, no error message will be returned.

Returns: pointer to the new FaceVerifier instance, or NULL on failure

void fvl_face_verifier_free(FVLFaceVerifier* verifier)

Destructor

Parameters:

• verifier - pointer to the FaceVerifier instance to free

void fvl_face_verifier_detect_faces(FVLFaceVerifier* verifier,
                                    const FVLImageHeader* image_header,
                                    FVLDetectFacesCallback callback,
                                    void* user_data)

Detects the faces on an image with a callback API.

Note: The given ImageHeader doesn't own the image data, and it is safe to delete the data after the call, a copy is happening internally. See FVLImageHeader for details.

Note: Calling this function is non-blocking, so calling it again with the next frame without waiting for the result is possible. Also see fvl_face_verifier_get_concurrent_calculations().

Parameters:

• verifier - pointer to the FaceVerifier instance
• image_header - image descriptor
• callback - callback to call with the result
• user_data - user data to pass to the callback

void fvl_face_verifier_embed_face(FVLFaceVerifier* verifier,
                                  const FVLFace* face,
                                  FVLEmbedFaceCallback callback,
                                  void* user_data)

Returns the embedding of the detected face.

Note: Calling this function is non-blocking, so calling it again with the next frame without waiting for the result is possible. Also see fvl_face_verifier_get_concurrent_calculations().

Parameters:

• verifier - pointer to the FaceVerifier instance
• face - the previously detected face to embed
• callback - callback to call with the result
• user_data - user data to pass to the callback

FVLMatch fvl_face_verifier_compare_faces(FVLFaceVerifier* verifier,
                                         const float* embedding1,
                                         int size1,
                                         const float* embedding2,
                                         int size2)

Compares two embeddings

Parameters:

• verifier - pointer to the FaceVerifier instance
• embedding1 - embedding of one of the faces to compare
• size1 - size of the first embedding
• embedding2 - embedding of the other face to compare
• size2 - size of the second embedding

Returns: match object with the similarity metric

int fvl_face_verifier_get_concurrent_calculations(const FVLFaceVerifier* verifier)

Returns the value of the atomic counter for the number of calculations currently running concurrently. You can use this to limit the number of concurrent calculations.

Parameters:

• verifier - pointer to the FaceVerifier instance

Returns: The (approximate) number of calculations currently in-flight.

char* fvl_face_verifier_get_model_name(const FVLFaceVerifier* verifier)

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

Parameters:

• verifier - pointer to the FaceVerifier instance

Returns: name of the model. The caller is responsible for freeing the returned string using free().

FVLVersion fvl_face_verifier_get_sdk_version()

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

Returns: version of the SDK

char* fvl_face_verifier_get_sdk_version_string()

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

Returns: version string of the SDK. The caller is responsible for freeing the returned string using free().

FVLFace* fvl_face_new(const FVLImageHeader* image_header,
                      const FVLPoint2d* landmarks,
                      int num_landmarks,
                      const FVLBoundingBox* bbox,
                      float confidence,
                      char** errorMessage)

Constructor for the Face object to support 3rd party face detectors

Parameters:

• image_header - image descriptor
• landmarks - face landmarks
• num_landmarks - number of landmarks
• bbox - face bounding box
• confidence - face detection confidence
• errorMessage - pointer to a char* that will be set to an error message string on failure, or NULL on success. The caller is responsible for freeing the string using free(). If errorMessage is a NULL pointer, no error message will be returned.

Returns: pointer to the new Face instance, or NULL on failure

FVLFace* fvl_face_copy(const FVLFace* other)

Copy constructor

Parameters:

• other - pointer to the Face instance to copy

Returns: pointer to the new Face instance, or NULL on failure

void fvl_face_free(FVLFace* face)

Destructor

Parameters:

• face - pointer to the Face instance to free

FVLDetectionQuality fvl_face_detection_quality(const FVLFace* face)

Returns the detection quality of the detected face

Parameters:

• face - pointer to the Face instance

Returns: FVLDetectionQuality

FVLBoundingBox fvl_face_bounding_box(const FVLFace* face)

Returns the bounding box of the detected face

Parameters:

• face - pointer to the Face instance

Returns: FVLBoundingBox

float fvl_face_confidence(const FVLFace* face)

Returns the confidence value of the detected face

Parameters:

• face - pointer to the Face instance

Returns: float

FVLPoint2dArray* fvl_face_landmarks(const FVLFace* face)

Returns the landmarks of the face

Parameters:

• face - pointer to the Face instance

Returns: pointer to FVLPoint2dArray. The caller is responsible for freeing the returned array using free().

typedef struct FVLPoint2d {
    float x;
    float y;
} FVLPoint2d;

Point2d class for landmarks

Members:

• x - x coordinate of the point
• y - y coordinate of the point

typedef struct FVLPoint2dArray {
    int count;
    FVLPoint2d* points;
} FVLPoint2dArray;

Array of Point2d

Members:

• count - number of points
• points - pointer to the array of points

typedef struct FVLBoundingBox {
    int x;
    int y;
    int width;
    int height;
} FVLBoundingBox;

Bounding Box class for the faces

Members:

• x - x coordinate of the top-left corner
• y - y coordinate of the top-left corner
• width - width of the bounding box in pixels
• height - height of the bounding box in pixels

typedef struct FVLImageHeader {
    const uint8_t* data;
    int width;
    int height;
    int stride;
    FVLImageFormat format;
} FVLImageHeader;

Descriptor class for image data (non-owning)

Members:

• data - pointer to the byte array of the image
• width - width of the image in pixels
• height - height of the image in pixels
• stride - length of one row of pixels in bytes (e.g: 3*width + padding)
• format - image format

typedef struct FVLMatch {
    float similarity;
} FVLMatch;

Face match class

Members:

• similarity - similarity of the faces

typedef struct FVLVersion {
    int major;
    int minor;
    int patch;
} FVLVersion;

Semantic version number for the SDK

typedef struct FVLFaceArray {
    int count;
    FVLFace** faces;
} FVLFaceArray;

Array of Faces

Members:

• count - number of faces
• faces - pointer to the array of face pointers

typedef struct FVLFloatArray {
    int count;
    float* data;
} FVLFloatArray;

Array of floats

Members:

• count - number of floats
• data - pointer to the array of floats

typedef enum FVLDetectionQuality {
    FVLDetectionQualityGood = 0,
    FVLDetectionQualityBadQuality = 1,
    FVLDetectionQualityMaybeRolled = 2,
} FVLDetectionQuality;

Detection quality enum

Values:

• FVLDetectionQualityGood = 0 - No issues detected
• FVLDetectionQualityBadQuality = 1 - Bad quality
• FVLDetectionQualityMaybeRolled = 2 - Face maybe rolled, embeddings could be incorrect

typedef enum FVLImageFormat {
    FVLImageFormatGrayscale = 0,
    FVLImageFormatRGB  = 1,
    FVLImageFormatRGBA = 2,
    FVLImageFormatBGR  = 3,
    FVLImageFormatBGRA = 4,
} FVLImageFormat;

Image format enum

Values:

• FVLImageFormatGrayscale = 0 - 8-bit grayscale
• FVLImageFormatRGB = 1 - 24-bit RGB
• FVLImageFormatRGBA = 2 - 32-bit RGBA or 32-bit RGB_
• FVLImageFormatBGR = 3 - 24-bit BGR
• FVLImageFormatBGRA = 4 - 32-bit BGRA or 32-bit BGR_

typedef void (*FVLDetectFacesCallback)(void* user_data,
                                       FVLFaceArray* faces,
                                       const char* error_msg);

Callback for face detection

Parameters:

• user_data - user data passed to the function
• faces - array of detected faces. The array and its contents are owned by the library and are valid only during the callback.
• error_msg - error message if any, otherwise NULL

typedef void (*FVLEmbedFaceCallback)(void* user_data,
                                     FVLFloatArray* embedding,
                                     const char* error_msg);

Callback for face embedding

Parameters:

• user_data - user data passed to the function
• embedding - embedding vector. The array is owned by the library and is valid only during the callback.
• error_msg - error message if any, otherwise NULL