Using C# API¶

IDLive Face C# API is available in the package Idrnd.FaceSdk:

using Idrnd.FaceSdk;

We support Microsoft .NET Framework 4.0+ or .NET Core 3.0+, Windows 64-bit only.

.NET library location¶

The .NET library FaceSdkClr.dll is located in the SDK's libs/csharp directory. You need to add it as a reference by using Add Reference... in the Visual Studio's Solution Explorer. You also need to set Platform target to x64, this can be done in the project's properties, in the Build section.

As the .NET library is backed by native libraries you also need to specify their location. They reside in the SDK's libs directory, and you need to add this directory to the Path environment variable. Please refer to the DLL discovery article.

Basics¶

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:

static String IDLIVEFACE_HOME = "c:/idliveface";
InitConfig config = new InitConfig(Path.Combine(IDLIVEFACE_HOME, "data/pipelines/astraea.json"));

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

Next use the loaded configuration to create a pipeline:

Pipeline pipeline = new Pipeline("ConfigurablePipeline", config);

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:

Image image = new Image(Path.Combine(IDLIVEFACE_HOME, "examples/images/real_face.jpg"));

Or from a memory buffer:

byte[] imageBytes = ...
Image imageFromArray = new Image(imageBytes);

IDLive Face supports JPEG, PNG and other image formats.

Perform liveness check¶

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

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.LivenessResult.Probability. The image can be considered live if the probability is higher than 0.5:

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

Additional factor to take into consideration is result.QualityResult.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.QualityResult.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 (FaceException e) {
    Console.WriteLine($"Error code: {e.Status}, message: {e.Message}");
}

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 FaceExceptionStatus.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:

using System;

using Idrnd.FaceSdk;

class Example
{
    static String IDLIVEFACE_HOME = "c:/idliveface";

    static Pipeline CreatePipeline()
    {
        Console.WriteLine("Initializing...");
        using (InitConfig config = new InitConfig($"{IDLIVEFACE_HOME}/data/pipelines/astraea.json"))
        {
            return new Pipeline("ConfigurablePipeline", config);
        }
    }

    static void ProcessLivenessResult(PipelineResult result)
    {
        Console.WriteLine($"Result: {result}");

        if (result.QualityResult.Score < 0.5)
        {
            Console.WriteLine("Image has a bad quality");
        }
        else if (result.LivenessResult.Probability >= 0.5)
        {
            Console.WriteLine("Image is genuire");
        }
        else
        {
            Console.WriteLine("Image is spoofed");
        }
    }

    static void Main(string[] args)
    {
        try
        {
            using (Pipeline pipeline = CreatePipeline())
            {
                Console.WriteLine("\nChecking liveness for real_face.jpg");

                using (Image image = new Image($"{IDLIVEFACE_HOME}/examples/images/real_face.jpg"))
                {
                    PipelineResult result = pipeline.CheckLiveness(image);
                    ProcessLivenessResult(result);
                }

                Console.WriteLine("\nChecking liveness for spoof_face.jpg");

                using (Image image = new Image($"{IDLIVEFACE_HOME}/examples/images/spoof_face.jpg"))
                {
                    PipelineResult result = pipeline.CheckLiveness(image);
                    ProcessLivenessResult(result);
                }

                Console.WriteLine("\nChecking liveness for face_not_found.jpg");

                using (Image image = new Image($"{IDLIVEFACE_HOME}/examples/images/face_not_found.jpg"))
                {
                    pipeline.CheckLiveness(image);
                }
            }
        }
        catch (FaceException e)
        {
            Console.WriteLine($"Error: {e.Status}, message: {e.Message}");
        }
    }
}

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

Checking liveness for real_face.jpg
Result: LivenessResult: {Score: 2,368498, Probability: 0,9143934}, QualityResult: {Score: 0,8434994, Class_: True}
Image is genuire

Checking liveness for spoof_face.jpg
Result: LivenessResult: {Score: -6,794679, Probability: 0,001118465}, QualityResult: {Score: 0,8110471, Class_: True}
Image is spoofed

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