Using C++ API¶

To use the IDLive Face C++ API you need a supported compiler. We compile our releases with GCC 7.5 and Microsoft Visual C++ 2019. Only 64-bit is supported.

Basics¶

The main header for the IDLive Face C++ API is facesdk/FaceSDK.h:

#include <facesdk/FaceSDK.h>

You can find IDLive Face header files in the SDK's include directory.

All API entities are defined in the namespace facesdk. The API will need a path to the SDK's data directory, the examples below will rely on this constant:

const std::string IDLIVEFACE_HOME = "/opt/idliveface";

Initialize pipeline¶

The main entity of the IDLive Face API is a pipeline (represented by the class Pipeline). The SDK contains several pipelines, each one is described by the configuration file stored in the data/pipelines directory. To initialize a pipeline first you need to load its configuration. For example to load the configuration for the Astraea pipeline do:

auto config_path = IDLIVEFACE_HOME + "/data/pipelines/astraea.json";
facesdk::InitConfigPtr config = facesdk::InitConfig::createConfig(config_path);

List of all available pipelines can be found in the Pipelines article.

Next use the loaded configuration to create a pipeline:

facesdk::PipelinePtr pipeline = facesdk::FaceSDK::getPipeline("ConfigurablePipeline", config);

The PipelinePtr is a shared pointer, you can freely copy it. The object it points to is thread-safe.

Load image¶

To load an image into the memory you need to create an Image object that will contain the image's content. The image can be loaded from a file:

auto image_path = IDLIVEFACE_HOME + "/examples/images/real_face.jpg";
facesdk::ImagePtr image = facesdk::Image::createImage(image_path);

Or from a memory buffer, either a vector or a raw pointer:

std::vector<uint8_t> image_bytes = ...

facesdk::ImagePtr image_from_vector = facesdk::Image::createImage(image_bytes);
facesdk::ImagePtr image_from_buffer = facesdk::Image::createImage(image_bytes.data(), image_bytes.size());

IDLive Face supports JPEG, PNG and other image formats.

Perform liveness check¶

To perform a liveness check call the pipeline's checkLiveness method:

facesdk::PipelineResult result = pipeline->checkLiveness(image);

The result contains measurements of the image's liveness and quality. The main factor to decide if the image is live or spoofed is the result.liveness_result.probability. The image can be considered live if the probability is higher than 0.5:

if (result.liveness_result.probability >= 0.5) {
    // Image is live
} else {
    // Image is spoofed
}

Additional factor to take into consideration is result.quality_result.score. It measures how "appropriate" the image is for the liveness check. Images with the quality values lower than 0.5 should generally be rejected:

if (result.quality_result.score < 0.5) {
    // Image has a bad quality, reject it
}

Both measurements are float values in a range of [0,1]. The detailed explanation of the results of the liveness check can be found in the Liveness check result article.

Error handling¶

When an error occurs the IDLive Face API throws the FaceException exception. Generally you should wrap all invocations of the API into a try-catch block:

try {
    ...
} catch (const facesdk::FaceException& e) {
    std::cout << "Error code: " << e.status() << ", message: " << e.what() << std::endl;
}

The status of the exception is an enumeration you can use to react to specific errors. For example when the Pipeline::checkLiveness rejects an image it returns statuses that classify the rejection reason:

switch (e.status()) {
    case facesdk::FaceException::STATUS::FACE_TOO_SMALL:
        // Inform a user to get closer to a camera.
        break;
    ...
}

The list of all statuses is available in the Error statuses article.

Example program¶

Here is a program that uses everything described in the previous section:

#include <iostream>
#include <string>

#include <facesdk/FaceSDK.h>

const std::string IDLIVEFACE_HOME = "/opt/idliveface";

void ProcessLivenessResult(const facesdk::PipelineResult& result) {
    std::cout << "Result: " << result << std::endl;

    if (result.quality_result.score < 0.5) {
        std::cout << "Image has a bad quality" << std::endl;
    } else if (result.liveness_result.probability >= 0.5) {
        std::cout << "Image is genuine" << std::endl;
    } else {
        std::cout << "Image is spoofed" << std::endl;
    }
}

int main() {
    try {
        std::cout << "Initializing..." << std::endl;
        facesdk::InitConfigPtr config =
                facesdk::InitConfig::createConfig(IDLIVEFACE_HOME + "/data/pipelines/astraea.json");
        facesdk::PipelinePtr pipeline = facesdk::FaceSDK::getPipeline("ConfigurablePipeline", config);

        std::cout << "\nChecking liveness for real_face.jpg" << std::endl;
        facesdk::ImagePtr image = facesdk::Image::createImage(IDLIVEFACE_HOME + "/examples/images/real_face.jpg");
        facesdk::PipelineResult result = pipeline->checkLiveness(image);
        ProcessLivenessResult(result);

        std::cout << "\nChecking liveness for spoof_face.jpg" << std::endl;
        image = facesdk::Image::createImage(IDLIVEFACE_HOME + "/examples/images/spoof_face.jpg");
        result = pipeline->checkLiveness(image);
        ProcessLivenessResult(result);

        std::cout << "\nChecking liveness for face_not_found.jpg" << std::endl;
        image = facesdk::Image::createImage(IDLIVEFACE_HOME + "/examples/images/face_not_found.jpg");
        pipeline->checkLiveness(image);

    } catch (const facesdk::FaceException& e) {
        std::cout << "Error: " << e.what() << ", status: " << e.status() << std::endl;
    }

    return 0;
}

It performs the liveness check for several example images and prints the following output:

Checking liveness for real_face.jpg
Result: { "liveness_result": { "score": 2.3685, "probability": 0.914393 }, "quality_result": { "score": 0.843499, "class_": true } }
Image is genuine

Checking liveness for spoof_face.jpg
Result: { "liveness_result": { "score": -6.79468, "probability": 0.00111846 }, "quality_result": { "score": 0.811047, "class_": true } }
Image is spoofed

Checking liveness for face_not_found.jpg
Error: Failed to detect face, status: FACE_NOT_FOUND

To compile the program link it with the IDLive Face library, it can be found in SDK's libs directory:

g++ example.cpp -o example -l idliveface \
    -I /opt/idliveface/include \
    -L /opt/idliveface/libs \
    -Wl,-rpath,/opt/idliveface/libs

cl /EHsc example.cpp C:\idliveface\libs\idliveface.lib /I C:\idliveface\include

This will produce an executable named example (or example.exe) that you can run.