Gender, Age and Facial Expression Recognition

The SDK recognizes the gender, age and facial expressions of subjects. It recognizes if a smile is present and if the eyes are open or closed. To accomplish this, first you must detect facial features in an image, and then pass these features to the FSDK_DetectFacialAttributeUsingFeatures function, specifying the "Gender", the "Age" or the "Expression" attribute.

FSDK_DetectFacialAttributeUsingFeatures Function

Detects an attribute of a face, and returns the Values of a particular attribute, and Confidences in these Values.

Each facial attribute has a number of Values, and each Value has an associated Confidence. A Value is a string, and a Confidence is a float from 0 to 1, which represents confidence level of this particular value of the attribute.

The following attribute names are supported:

"Liveness" - to get the liveness probability (see the Passive Liveness section).

"Gender" - to detect the gender of a face. The attribute has "Male" and "Female" values.

"Age" - to detect the age of a face. The attribute has "Age" value.

"Expression" - to detect the expression of a face. The attribute has "Smile" and "EyesOpen" values.

The Values and their Confidences are returned in a string of the following format:

"Value1=Confidence1[;Value2=Confidence2[;...]]"

For example, when calling the function with the "Gender" attribute, the following string may be returned:

"Male=0.95721;Female=0.04279"

It means that the subject has male gender with a confidence of 95.7%, and female gender with a confidence of 4.3%.

When calling the function with the "Age" attribute, the following string may be returned:

"Age=37"

When calling the function with the "Expression" attribute, the following string may be returned:

"Smile=0.987;EyesOpen=0.9952"

It means that the subject smiles with a confidence of 98.7%, and the eyes are open with a confidence of 99.5%.

You may use several attributes in a single function call separated by ";". For example, if AttributeName is "Gender; Age; Expression", the result may be the following: "Male=0.95721;Female=0.04279;Age=37;Smile=0.987;EyesOpen=0.9952".

You may use the FSDK_GetValueConfidence to parse the returned string and retrieve the Confidences for individual Values.

C++ Syntax:

int FSDK_DetectFacialAttributeUsingFeatures(HImage Image, const FSDK_Features * FacialFeatures, const char * AttributeName, char * AttributeValues, long long MaxSizeInBytes);

Delphi Syntax:

function FSDK_DetectFacialAttributeUsingFeatures(Image: HImage; FacialFeatures: PFSDK_Features; AttributeName, AttributeValues: PAnsiChar; MaxSizeInBytes: int64): integer;

C# Syntax:

int DetectFacialAttributeUsingFeatures(int Image, ref TPoint [] FacialFeatures, string AttributeName, out string AttributeValues, long MaxSizeInBytes);

Java and Android Syntax:

int FSDK.DetectFacialAttributeUsingFeatures(int Image, FSDK_Features FacialFeatures, String AttributeName, String AttributeValues[], long MaxSizeInBytes);

Parameters:

Image - HImage handle in which to detect the attribute.

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

AttributeName - name of the attribute. You may specify several attributes separated by ";".

AttributeValues - pointer to the null-terminated string that will receive the attribute Names and their Confidences.

MaxSizeInBytes - amount of memory allocated for the output string.

Return Value:

Returns FSDKE_OK if successful. Returns FSDKE_INSUFFICIENT_BUFFER_SIZE if there is not enough room to store the output string; however, the output string still fills up all the space available.

Python Syntax:

def FSDK.DetectFacialAttributeUsingFeatures(image: Image, facialFeatures: Features, attributeName: str, ret_dict: bool = False) -> str

def Image.DetectFacialAttributeUsingFeatures(facialFeatures: Features, attributeName: str, ret_dict: bool = False) -> str

Return Value:

If ret_dict is False (default) the return value is a string object with the attribute Names and their Confidence. If ret_dict is True the return value is a dict object with the attribute Names as keys and Confidence floats as values.

FSDK_GetValueConfidence Function

Parses the string returned by FSDK_DetectFacialAttributeUsingFeatures or FSDK_GetTrackerFacialAttribute, and returns the Confidence in an individual Value.

C++ Syntax:

int FSDK_GetValueConfidence(const char * AttributeValues, const char * Value, float * Confidence);

Delphi Syntax:

function FSDK_GetValueConfidence(AttributeValues, Value: PAnsiChar; Confidence: PSingle): integer;

C# Syntax:

int GetValueConfidence(string AttributeValues, string Value, ref float Confidence);

Java and Android Syntax:

int FSDK.GetValueConfidence(String AttributeValues, String Value, float Confidence[]);

Parameters:

AttributeValues - pointer to the null-terminated string containing the attribute Values and their Confidences.

Value - pointer to the null-terminated string containing the desired Value.

Confidence - pointer to the float variable to store the Confidence in a Value.

Return Value:

Returns FSDKE_OK if successful.

Example:

char AttributeValues[1024];
FSDK_DetectFacialAttributeUsingFeatures(image, features, "Gender", AttributeValues, sizeof(AttributeValues));
float ConfidenceMale = 0.0f;
float ConfidenceFemale = 0.0f;
FSDK_GetValueConfidence(AttributeValues, "Male", &ConfidenceMale);
FSDK_GetValueConfidence(AttributeValues, "Female", &ConfidenceFemale);

Python Syntax:

def FSDK.GetValueConfidence(attributeValues: str, value: str) -> float

Return Value:

The Confidence value. Use DetectFacialAttributeUsingFeatures function with ret_dict argument set to True to get a dict object with Confidence float values.

Complete Attribute Detection Workflow

To extract gender, age, and expression from a face, you must first initialize the library, load an image, detect facial features, and then call the attribute detection function. Below are complete working examples with error handling.

Complete Example (C++)

#include "LuxandFaceSDK.h"
#include <cstdio>

int main() {
    // Step 1: Activate with your license key
    int err = FSDK_ActivateLibrary("your-license-key-here");
    if (err != FSDKE_OK) {
        printf("Failed to activate FaceSDK (error %d)\n", err);
        return 1;
    }

    // Step 2: Initialize FaceSDK
    err = FSDK_Initialize("");
    if (err != FSDKE_OK) {
        printf("Failed to initialize FaceSDK (error %d)\n", err);
        return 1;
    }

    // Step 3: Load image
    HImage image;
    err = FSDK_LoadImageFromFile(&image, "photo.jpg");
    if (err != FSDKE_OK) {
        printf("Failed to load image (error %d)\n", err);
        return 1;
    }

    // Step 4: Detect facial features
    FSDK_Features features;
    err = FSDK_DetectFacialFeatures(image, &features);
    if (err != FSDKE_OK) {
        printf("No face detected (error %d)\n", err);
        FSDK_FreeImage(image);
        return 1;
    }

    // Step 5: Detect all attributes in a single call
    char attrValues[1024];
    err = FSDK_DetectFacialAttributeUsingFeatures(image, &features,
        "Gender;Age;Expression", attrValues, sizeof(attrValues));
    if (err != FSDKE_OK) {
        printf("Attribute detection failed (error %d)\n", err);
        FSDK_FreeImage(image);
        return 1;
    }

    // Step 6: Parse results
    float confMale, confFemale, confSmile, confEyesOpen;
    FSDK_GetValueConfidence(attrValues, "Male", &confMale);
    FSDK_GetValueConfidence(attrValues, "Female", &confFemale);
    FSDK_GetValueConfidence(attrValues, "Smile", &confSmile);
    FSDK_GetValueConfidence(attrValues, "EyesOpen", &confEyesOpen);

    // Determine gender (use 0.5 threshold)
    printf("Gender: %s (confidence: %.1f%%)\n",
        confMale > confFemale ? "Male" : "Female",
        (confMale > confFemale ? confMale : confFemale) * 100.0);

    // Parse age from the raw string (format: "...;Age=37;...")
    float age;
    FSDK_GetValueConfidence(attrValues, "Age", &age);
    printf("Age: %.0f\n", age);

    // Expression (smile confidence > 0.5 means smiling)
    printf("Smiling: %s (confidence: %.1f%%)\n",
        confSmile > 0.5 ? "Yes" : "No", confSmile * 100.0);
    printf("Eyes open: %s (confidence: %.1f%%)\n",
        confEyesOpen > 0.5 ? "Yes" : "No", confEyesOpen * 100.0);

    // Cleanup
    FSDK_FreeImage(image);
    return 0;
}

Complete Example (Python)

from fsdk import FSDK

# Activate and initialize
FSDK.ActivateLibrary("your-license-key-here")
FSDK.Initialize()

# Load image and detect features
image = FSDK.LoadImageFromFile("photo.jpg")
features = image.DetectFacialFeatures()

# Detect all attributes at once, get results as a dictionary
attrs = image.DetectFacialAttributeUsingFeatures(
    features, "Gender;Age;Expression", ret_dict=True
)

# Parse results
gender = "Male" if attrs["Male"] > 0.5 else "Female"
gender_conf = attrs["Male"] if attrs["Male"] > 0.5 else attrs["Female"]
print(f"Gender: {gender} (confidence: {gender_conf:.1%})")
print(f"Age: {attrs['Age']:.0f}")
print(f"Smiling: {'Yes' if attrs['Smile'] > 0.5 else 'No'} ({attrs['Smile']:.1%})")
print(f"Eyes open: {'Yes' if attrs['EyesOpen'] > 0.5 else 'No'} ({attrs['EyesOpen']:.1%})")

# Cleanup
FSDK.FreeImage(image)

Interpreting Confidence Values

• Gender: Male and Female confidences sum to 1.0. Use a threshold of 0.5 to determine the predicted gender.
• Age: The Age value is an estimated integer age, not a confidence score.
• Smile: A confidence above 0.5 indicates the subject is likely smiling. Values above 0.9 indicate a clear smile.
• EyesOpen: A confidence above 0.5 indicates the eyes are likely open. Use this for blink detection by monitoring changes across frames.