AFR能力

以下描述了如何使用灵云AFR能力。

1. AFR简介

AFR 人脸识别能力，对图像中的人脸进行检测、注册，支持对未知图像人脸的的确认和辨识。

2. 选择模块和能力

灵云可以提供人脸识别能力。 无论使用云端或本地端的人脸识别能力，基础模块 hci_afr都是需要的。 使用云端能力时，需要加上hci_afr_cloud_recog模块； 使用本地能力时，需要加上hci_afr_local_recog模块。

3. 人脸检测

通过对会话图像进行检测，提取其中的人脸特征。

示例代码如下：

AFR_DETECT_RESULT result = { 0 };
// 替换为实际的待检测图像路径。
char *filename = "face.jpg"; 
// 加载图像(可使用hci_afr_set_image_buffer函数，直接加载图像缓存区。)
HCI_ERR_CODE err_code = hci_afr_set_image_file(session_id, filename);
if (err_code != HCI_ERR_NONE)
{
        printf("failed to set image.\n");
        break;
}
// AFR人脸检测
err_code = hci_afr_detect(session_id, session_config.c_str(), &result);
if (err_code != HCI_ERR_NONE)
{
        printf("failed to detect face from image.\n");
        break;
}

// 释放AFR人脸检测结果。
hci_afr_free_detect_result(&result);

4. 人脸注册

接口中的人脸ID(faceId)，由同一会话中的检测接口返回。 使用云端能力，调用hci_afr_enroll接口进行注册时，用户唯一标识可以由服务端产生，也可以由用户自己指定，必须要保证该标识的唯一性。 使用本地能力，调用hci_afr_enroll接口进行注册时，用户唯一标识由用户指定（应用层维护用户标识），需要保证该标识的唯一性。 注册成功后，可以对该人脸模型进行多次训练。

示例代码如下：

string session_config = "capkey=" + capkey;

// AFR人脸注册
string enrollConfig;
// 人脸ID(faceId)必填，通过检测接口获取，多个faceid之间使用分号隔开，例如faceid=123;456。目前支持使用1至3个人脸进行训练。 
// 用户ID(userId)可选，字符串，最多64个字符，如：abc123。注册成功时，结果返回userid；若指定此参数，将覆盖该userid已存在的模型。
enrollConfig += ",faceid=" + faceId;
printf("hci_afr_enroll config [%s]\n", enrollConfig.c_str());

AFR_ENROLL_RESULT enrollResult;
err_code = hci_afr_enroll(session_id,enrollConfig.c_str(),&enrollResult);
if (err_code != HCI_ERR_NONE)
{
        printf("hci_afr_enroll return (%d:%s) \n",err_code,hci_get_error_info(err_code));
        break;
}

hci_afr_free_enroll_result(&enrollResult);

5. 人脸确认

接口中的人脸ID(faceId)，由同一会话中的检测接口返回。 使用人脸ID与已注册的用户ID的特征进行匹配性确认。确认时可以设置阈值(threshold)。

示例代码如下：

string session_config = "capkey=";
session_config += capkey;
string verify_config = "userid=" + userId;
verify_config += ",faceid=" + faceId;
printf("hci_afr_verify config [%s]\n", verify_config.c_str());

AFR_VERIFY_RESULT verifyResult;
err_code = hci_afr_verify(session_id, verify_config.c_str(), &verifyResult);
if( err_code != HCI_ERR_NONE )
{
        printf("hci_afr_verify return (%d:%s) \n",err_code,hci_get_error_info(err_code));
}
printf( "hci_afr_verify success\n" );

if (verifyResult.eStatus == AFR_VERIFY_STATUS_MATCH)
{
        printf( "voice data matches with user id:%s!\n",userId.c_str() );
        printf("the result score is :%d \n",verifyResult.uiScore);
}
else
{
        printf("voice data doesn't match with user id:%s !\n",userId.c_str());
}       

hci_afr_free_verify_result(&verifyResult);

6. 人脸辨识

接口中的人脸ID(faceId)，由同一会话中的检测接口返回。 待辨识用户ID需要加入加入用户组（hci_add_user）。 不需要继续辨识的用户ID需要从用户组删除（hci_remove_user）。 对于云端识别，可以使用hci_create_group和hci_delete_group创建和删除用户组。 对于本地识别，使用空字符串作为组名，进行本地用户组维护（即本地只支持一个用户组）。 可以在一组用户中进行指定人脸ID(通过检测获取)的用户辨识。可以指定辨识结果的候选数量和阈值。

示例代码如下：

// 添加用户组(hci_sys_ext.h)
// 用户组类型。
HciGroupType type = kHciGroupTypeShare;
string groupId = "testgroup"; // 本地组groupId = ""
// 创建用户组
HCI_ERR_CODE err_code = hci_create_group(groupID.c_str(),type);
if (err_code != HCI_ERR_NONE)
{
        printf("hci_create_group return (%d:%s) \n",err_code,hci_get_error_info(err_code));     
} else {
        printf("hci_create_group Success \n");
}

// 用户加入用户组
err_code = hci_add_user(groupID.c_str(),userID.c_str());
if (err_code == HCI_ERR_NONE)
{   
        printf("hci_add_user Success \n");
}
else
{
        printf("hci_add_user return (%d:%s) \n",err_code,hci_get_error_info(err_code));
}

// AFR人脸辨识
// 通过sessionConfig指定用户组ID(groupid)和人脸ID(faceid)
string sessionConfig = "capkey=";
sessionConfig += capkey;
string config = "groupid=" + groupId;
config += ",faceid=" + faceId;

printf("hci_afr_verify config [%s]\n", config.c_str());

AFR_IDENTIFY_RESULT result;
err_code = hci_afr_identify(sessionId, config.c_str(), &result);
if( err_code != HCI_ERR_NONE )
{
        printf("hci_afr_identify return (%d:%s) \n",err_code,hci_get_error_info(err_code));
}

if (result.uiIdentifyResultItemCount != 1)
{
        printf("failed to identify");
}
printf( "hci_afr_identify success\n" );
// 释放辨识结果
hci_afr_free_identify_result(&result);

// 删除用户组中的用户
HCI_ERR_CODE err_code = hci_remove_user(groupID.c_str(),userID.c_str());
if (err_code != HCI_ERR_NONE)
{
        printf("hci_remove_user return (%d:%s) \n",err_code,hci_get_error_info(err_code));      
}
printf("hci_remove_user Success \n");

// 删除用户组
err_code = hci_delete_group(groupID.c_str());
if (err_code == HCI_ERR_NONE)
{
        printf("hci_delete_group Success \n");
}
else
{
        printf("hci_delete_group return (%d:%s) \n",err_code,hci_get_error_info(err_code));
}