Extract Face Features

Face feature extraction interface

Windows/Linux/Arm_Linux interface is described here, for Android interface please refer to Android Interface Description.

stid_facepro_feature_extraction_create_handle

Function: Create a handle by loading a specified model file.

Declaration:

STID_SDK_API
stid_result_t
stid_facepro_feature_extraction_create_handle(
    stid_handle_t* out_handle,
    const char *model_filename
);

Parameters:

• [in] model_filename: Pass the location of the model file.

• [out] out_handle: Return the initialized handle, when not in use, call stid_face_feature_destroy_handle to release resource.

Return:

• [return] Return STID_OK if successful, otherwise return error code.

stid_facepro_feature_extraction_destroy_handle

Function: Release handle.

Declaration:

STID_SDK_API
void
stid_facepro_feature_extraction_destroy_handle(
    stid_handle_t handle
);

Parameters:

• [in] handle: Handle to be released.

Return: Return ST_OK if successful, otherwise return error type.

stid_facepro_verify_destroy_handle

Function: Obtain the version number of the model used for feature extraction.

Declaration:

STID_SDK_API
stid_result_t
stid_facepro_feature_extraction_get_version(
    stid_handle_t handle,
    int *out_version
);

Parameters:

• [in] handle: Initialized handle.

• [in] out_version: Return model version number.

Return:

• [return] Return STID_OK if successful, otherwise return error code.

stid_facepro_feature_extraction_extract

Function: Input one frame of image and face key points information to extract face features.

Declaration:

STID_SDK_API
stid_result_t
stid_facepro_feature_extraction_extract(
    stid_handle_t handle,
    const stid_image_t* input_image,
    const stid_landmarks_t* input_landmarks,
    char **out_feature
);

Parameters:

• [in] handle: Initialized handle.

• [in] input_image: Input image, support four orientations of up, down, left and right. Facing up is recommended for a better performance.

• [in] input_landmarks: Face key points.

• [out] out_feature: Return face feature information. API is responsible for allocating memory, need to call stid_facepro_feature_release_feature to release.

Return:

• [return] Return STID_OK if successful, otherwise return error code (return STID_E_NO_FACE when no face is detected).

stid_facepro_feature_release_feature

Function: Release face feature information.

Declaration:

STID_SDK_API
void
stid_facepro_feature_release_feature(
    const char *feature
);

Parameters:

• [in] feature: Face features to be released.

stid_facepro_verify_compare_feature

Function: Face 1:1 comparison.

Declaration:

ST_SDK_API
st_result_t stid_facepro_verify_compare_feature(
    st_handle_t verify_handle,
    const char *_feature_str1,
    const char *_feature_str2,
    float *score
);

Parameters:

• [in]verify_handle: Initialized face verification handle.

• [in]_feature_str1: First face feature string.

• [in]_feature_str2: Second face feature string.

• [out]score: Feature similarity score, ranging from 0 to 1, the closer to 1 the greater the probability is that two faces are of the same person. When setting the threshold, the lower the threshold is, the greater the probability is that two different faces are misjudged as one person; the higher the threshold is, the greater the probability is that two images of a same person are misjudged as two different people. We practically uses a threshold of 0.8, but it needs to be fine-tuned according to actual business scenarios and needs.

Return: Return ST_OK if successful, otherwise return error type.

stid_facepro_verify_search_face_from_list

Function: Search faces from a group of feature arrays. There is a limit on the maximum number of feature arrays. This limit needs to be defined in advance when purchasing products; the maximum limit cannot be exceeded when using this feature.

Declaration:

ST_SDK_API
st_result_t stid_facepro_verify_search_face_from_list(
    st_handle_t verify_handle,
    char *const *list_feature,
    int list_count,
    const char *query,
    unsigned int top_k,
    int *top_idxs,
    float *top_scores,
    unsigned int *result_length
);

Parameters:

• [in]verify_handle: Initialized face verification handle.

• [in]list_feature: Face feature information array.

• [in]list_count: The amount of face feature information (the parameter value cannot be greater than the maximum limit agreed upon purchasing).

• [in]query: Face feature information to be queried.

• [in]top_k: Maximum number of face queries.

• [out]top_idxs: Queried face database indexes array (allocated and released by user).

• [out]top_scores: Array of face similarity scores (allocated and released by user), ranging from 0-1. Scores closer to 1 indicate larger similarities.

• [out]result_length: Actual number of face queries.

Return: Return ST_OK if successful, otherwise return error type.

stid_facepro_verify_release_feature

Function: Release space allocated when extracting facial features.

Note:

1, Call this function to release resources after each function call, otherwise a large memory space will be taken.

Declaration:

ST_SDK_API
void stid_facepro_verify_release_feature(
    const unsigned char *feature
);

Parameters:

• [in]feature: Extracted face feature information.

Return: None.