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.

Set up¶

The header for the IDLive Face C++ API is idliveface/idliveface.h:

#include <idliveface/idliveface.h>

You can find it in the SDK's include directory. All API entities are defined in the namespace idliveface. For example here is how to find the release version and license expiration dates for each available feature:

idliveface::ReleaseInfo release_info = idliveface::GetReleaseInfo();
std::cout << release_info << std::endl;

To compile your 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

Initialize¶

The entry point to the IDLive Face is called the Blueprint. It's a factory for all main SDK objects, and it's also used to configure the IDLive Face. Initialize it with the path to the SDK's data directory (we assume the SDK was installed to /opt/idliveface):

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

idliveface::Blueprint blueprint(IDLIVEFACE_HOME + "/data");

Next use the blueprint to create the image decoder and the face analyzer:

idliveface::ImageDecoder decoder = blueprint.CreateImageDecoder();
idliveface::FaceAnalyzer analyzer = blueprint.CreateFaceAnalyzer();

You don't need the blueprint afterwards. IDLive Face reports all error via exceptions, you need to catch them in your exception handler:

try {
    ...
} catch (const idliveface::Exception& e) {
    std::cout << "Error: " << e.what() << std::endl;
}

idliveface::Exception derives from std::runtime_error.

Load image¶

To load a compressed image from a file, use the image decoder:

idliveface::Image image = decoder.DecodeFile(IDLIVEFACE_HOME + "/examples/images/real_face.jpg");

IDLive Face supports JPEG, PNG and BMP formats. You can also load the image from the memory:

std::vector<uint8_t> image_content;

idliveface::Image image = decoder.Decode(image_content);

If the image can't be decoded, the decoder will throw idliveface::ImageDecodingException.

If you have an uncompressed image, pass its content and dimensions to the Image's constructor:

uint8_t* pixels = ...;
int32_t width = 600;
int32_t height = 800;

idliveface::Image image(pixels, width, height, PixelFormat::kRGB);

IDLive Face supports RGB/BGR (3 bytes per pixel) and grayscale (1 byte per pixel) formats.

Analyze image¶

To analyze the image, use the face analyzer:

idliveface::FaceAnalysisResult result = analyzer.Analyze(image);

Once the analysis is complete, you need to first check the status field. If it's set to kInvalid, the image has failed to pass validations and was not analyzed. Such images do not conform to the requirements, and it's either not possible to analyze them, or produce the result with the decent accuracy. All validations the image has failed to pass are listed in the failed_validations field.

if (result.status == idliveface::FaceStatus::kInvalid) {
    std::cout << "Image did not pass validations and is not suitable for analysis\n"
              << "Failed validations: " << result.failed_validations << std::endl;
}

For the images that pass the validations, the status will be either kGenuine or kNotGenuine. The result's genuine_probability field will also be set. It's a float value showing how confident we are if the face on the image belongs to a real person, with 1 being the most confident. If the value is closer to 0, the face does not look genuine and may be spoofed. The decision threshold is 0.5. When the probability is this high or higher, the status will be set to kGenuine. For lower probabilities it will be set to kNotGenuine.

So you decision logic may look like this:

if (result.status == idliveface::FaceStatus::kInvalid) {
    // Ask to retake the image, use result.failed_validations as hints
} else if (result.status == idliveface::FaceStatus::kNotGenuine) {
    // Reject the image
} else {
    // Accept the image
}

Additionally the result contains a bounding box around the processed face. It will be returned when the face was detected, no matter if the image was analyzed or not. For example, if the face on the image is too small, the status will be kInvalid, but the box field will still be set. You can use it to diagnose why the image was not analyzed, along with failed_validations.

if (result.box) {
    std::cout << "Detected face: " << *result.box << std::endl;
}

Example program¶

Here is a program that uses everything described in this article:

#include <iostream>
#include <string>

#include <idliveface/idliveface.h>

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

void ProcessResult(const idliveface::FaceAnalysisResult& result) {
    std::cout << "Result: " << result << std::endl;

    if (result.status != idliveface::FaceStatus::kInvalid) {
        std::cout << "Image is " << result.status << ", probability is " << *result.genuine_probability << std::endl;
    } else {
        std::cout << "Image did not pass validations and is not suitable for analysis\n"
                  << "Failed validations: " << result.failed_validations << std::endl;
    }
}

int main() {
    try {
        idliveface::Blueprint blueprint(IDLIVEFACE_HOME + "/data");

        std::cout << "Initializing..." << std::endl;
        idliveface::ImageDecoder decoder = blueprint.CreateImageDecoder();
        idliveface::FaceAnalyzer analyzer = blueprint.CreateFaceAnalyzer();

        std::cout << "\nAnalyzing real_face.jpg" << std::endl;
        idliveface::Image image = decoder.DecodeFile(IDLIVEFACE_HOME + "/examples/images/real_face.jpg");
        idliveface::FaceAnalysisResult result = analyzer.Analyze(image);
        ProcessResult(result);

        std::cout << "\nAnalyzing spoof_face.jpg" << std::endl;
        image = decoder.DecodeFile(IDLIVEFACE_HOME + "/examples/images/spoof_face.jpg");
        result = analyzer.Analyze(image);
        ProcessResult(result);

        std::cout << "\nAnalyzing face_is_occluded.jpg" << std::endl;
        image = decoder.DecodeFile(IDLIVEFACE_HOME + "/examples/images/face_is_occluded.jpg");
        result = analyzer.Analyze(image);
        ProcessResult(result);

    } catch (const idliveface::Exception& e) {
        std::cout << "Error: " << e.what() << std::endl;
    }

    return 0;
}