Luxand FaceSDK – Face Matching

Luxand FaceSDK provides the API to extract face templates and match them. A template extracted from a face can be stored in a database and can then be used to match faces using the FSDK_MatchFaces function.

To extract a face template, use the FSDK_GetFaceTemplate, FSDK_GetFaceTemplateInRegion or FSDK_GetFaceTemplateUsingFeatures functions. The FSDK_MatchFaces function returns the facial similarity level. You may consider similarity to be equal to the probability that templates belong to the same person.

More precisely: if the access control system provides access to a person when similarity is higher of threshold x, the possibility of providing erroneous access to another person is 1-x. For example, if the decision to provide access to a person is based on the code

the possibility of erroneous access to another person is 0.01, or 1%.

A facial template contains data that describes the face. There is no direct way to re-create the original face image from a template. However, when using Tracker API, it may store the original facial images in Tracker memory (see the Storing original facial images section).

Note: it is recommended to retain both the original face images and their templates in the database. This is because future versions of Luxand FaceSDK may offer an improved template extraction algorithm, together with changes to the template format. If you are using Tracker API, there is an option to convert its memory automatically if the template format changes (see the Storing original facial images section section).

A face template is stored in the FSDK_FaceTemplate data structure.

In .NET, there is no specific data type for a template. Instead, it is stored in an array of bytes of FSDK.TemplateSize length. Below is an example of retrieving facial template in C#.

C# Example:

C++ Declaration:

typedef struct {
    char ftemplate [1040];
} FSDK_FaceTemplate;

Delphi Declaration:

FSDK_FaceTemplate = record
    Template: array[0.. 1040-1] of byte;
end;
PFSDK_FaceTemplate = ^FSDK_FaceTemplate;

Java and Android Declaration:

The class FSDK_FaceTemplate has the following property:

FSDK_FaceTemplate = record
    public byte template[];

VB Declaration:

Public Type FSDK_FaceTemplate
    FaceTemplate(1040) as Byte
End Type

Python Declaration:

FSDK.FaceTemplate = c_char*const.FSDK_FACE_TEMPLATE_SIZE

  FSDK_GetFaceTemplate Function

This function is used to extract a template from a facial image. The function first detects a face, then detects its facial features and extracts the template.

If there is more than one face in the image, the template is extracted for the face with the most clearly visible details. If there is no clearly visible face, the function returns an error code. To set the threshold determining the accepted quality for faces, use the FSDK_SetFaceDetectionThreshold function.

If the face position or its features or eye centers are known, it is more efficient to use the FSDK_GetFaceTemplateInRegion or FSDK_GetFaceTemplateUsingEyes functions. To extract the template for a specific face, use the FSDK_GetFaceTemplateInRegion function.

C++ Syntax:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java Syntax:

Android Syntax:

CImage Syntax:

Parameters:

Image – handle of the image from which to extract the face template.

FaceTemplate – pointer to the FSDK_FaceTemplate structure, used to receive the face template.

Return Value:

Returns FSDKE_OK if successful. If no faces are found, or the quality of the image is not sufficient, the function returns the FSDKE_FACE_NOT_FOUND code.

Python Syntax:

Return Value:

The FaceTemplate object.

  FSDK_GetFaceTemplateInRegion Function

Extracts a template for a face located in a specific region returned by FSDK_DetectFace or FSDK_DetectMultipleFaces.

The function detects facial features in a specific region and extracts a template. The face detection stage is not performed. This function can be useful if an approximate face size and position is known, or to process a specific face returned by FSDK_DetectFace or FSDK_DetectMultipleFaces. The function returns no error if the face is not clearly visible. This is because it assumes that if face detection functions return a detected face position, the face is of sufficient quality.

If facial features or eye centers are known, it is more efficient to use the FSDK_GetFaceTemplateUsingFeatures or FSDK_GetFaceTemplateUsingEyes function.

C++ Syntax:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java Syntax:

Android Syntax:

CImage Syntax:

Parameters:

Image – handle of the image from which to extract the face template.

FacePosition – pointer to the face position structure.

FaceTemplate – pointer to the FSDK_FaceTemplate structure, used to receive the face template.

Return Value:

Returns FSDKE_OK if successful.

Python Syntax:

Return Value:

The FaceTemplate object.

  FSDK_GetFaceTemplateUsingEyes Function

Extracts a face template using the detected eye centers.

The function receives eye centers coordinates detected by the FSDK_DetectFacialFeatures, FSDK_DetectFacialFeaturesInRegion, FSDK_DetectEyes or FSDK_DetectEyesInRegion functions and extracts a face template. Face detection, facial feature detection, and eye centers detection are not performed. This function can be useful when facial features or eye centers for a specific face are already detected. The function returns no error if the face is not clearly visible, since it assumes that if the face and its facial features or eye centers are already detected, the face is of sufficient quality.

Note that the FSDK_GetFaceTemplate, FSDK_GetFaceTemplateInRegion and FSDK_GetFaceTemplateUsingFeatures functions return templates that could be matched with higher accuracy, so it is recommended to use these functions instead.

C++ Syntax:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java Syntax:

Android Syntax:

CImage Syntax:

Parameters:

Image – handle of the image to extract the face template from.

eyeCoords – pointer to the FSDK_Features array containing eye centers coordinates.

FaceTemplate – pointer to the FSDK_FaceTemplate structure for receiving the face template.

Return Value:

Returns FSDKE_OK if successful.

Python Syntax:

Return Value:

The FaceTemplate object.

  FSDK_GetFaceTemplateUsingFeatures Function

Extracts a face template using the detected facial feature coordinates.

The function receives facial feature coordinates detected by the FSDK_DetectFacialFeatures or FSDK_DetectFacialFeaturesInRegion functions and extracts a face template. Face detection, facial feature detection, and eye centers detection are not performed. This function can be useful when facial features for a specific face are already detected. The function produces no error if the face is not clearly visible, since it assumes that if the face and its facial features are already detected, the face is of sufficient quality.

The function determines if facial features, starting with the 2nd, are equal to zero or uninitialized. In this case, the functions calls FSDK_GetFaceTemplateUsingEyes instead.

C++ Syntax:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java Syntax:

Android Syntax:

CImage Syntax:

Parameters:

Image – handle of the image to extract the face template from.

FacialFeatures – pointer to the FSDK_Features array containing facial feature coordinates.

FaceTemplate – pointer to the FSDK_FaceTemplate structure for receiving the face template.

Return Value:

Returns FSDKE_OK if successful.

Python Syntax:

Return Value:

The FaceTemplate object.

  FSDK_MatchFaces

Match two face templates. The returned value determines the similarity of the faces.

C++ Syntax:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java Syntax:

Android Syntax:

Parameters:

FaceTemplate1 – pointer to the FSDK_FaceTemplate structure, using the first template for comparison.

FaceTemplate2 – pointer to the FSDK_FaceTemplate structure, using the second template for comparison.

Similarity – pointer to an integer value, used to receive the similarity of the face templates.

Return Value:

Returns FSDKE_OK if successful. Returns FSDKE_INVALID_TEMPLATE if any of the face templates is in an invalid format.

Returns FSDKE_UNSUPPORTED_TEMPLATE_VERSION if any of the templates is created with an unsupported version of FaceSDK.

Python Syntax:

Return Value:

The similarity of the face templates.

  FSDK_GetMatchingThresholdAtFAR Function

This function returns the threshold value for similarity to determine if two matched templates belong to the same person at a given FAR (False Acceptance Rate) value. The FAR determines the acceptable error rate when two different people’s templates are mistakenly recognized as the same person. Decreasing FAR leads to an increase in FRR – i.e. with low FAR it becomes more probable that two templates from the same person will be determined as belonging to different people.

C++ Syntax: