人脸识别算法

REVISION HISTORY¶

Revision No.	Description	Date
100	Initial release	04/27/2023
101	Add Face Arrribute Recognition	07/04/2023
102	Sync with latest api & add error code	05/20/2024

1. 算法描述¶

人脸识别主要是对人脸进行区分，判断抓拍人脸是否是白名单人员。整个算法包含人脸检测、人脸属性识别、人脸表情识别、人脸关键点、人脸过滤、人脸跟踪、人脸对齐、特征提取以及人脸比对。其中，人脸属性可以判断人脸的眼镜、性别、口罩、胡子、年龄五个属性；人脸表情可以判断人脸7个表情，分别是正常、高兴、难过、惊讶、害怕、厌恶、生气。

算法精度

ALGO	阈值	43	44	45	46	47	48	49	50	51	52	53	54	55	56	57	58
FR	TAR%	99.4	98.9	98.5	98.1	97.6	96.9	96.4	95.2	93.9	93.4	92.1	90.9	89.1	86.7	85.4	84.2
FR	FAR%	2.3	1.8	1	0.7	0.4	0.1	0	0	0	0	0	0	0	0	0	0

算法性能

model	耗时	rom	ram	分辨率(w*h)	输入格式
fr_det_y24s.img	1.8ms	0.93m	1.2m	480*288	yuvsp420_nv12
fr_feature_as.img	3.3ms	3.3m	3.3m	112*112	BGRA8888
fr_feature_am.img	3.3ms	7.3m	7.3m	112*112	BGRA8888
fr_cos256.img	-	0.03m	0.03m	112*112	BGRA8888
far101_224y.img	5.2ms	4.1m	5.3m	224*224	yuvsp420_nv12
far101_224y_s45.img	2.4ms	1.1m	1.8m	224*224	yuvsp420_nv12
far101_224y_emo.img	5.0ms	3.6m	4.8m	224*224	yuvsp420_nv12
far101_224y_emo_s45.img	2.4ms	0.9m	1.7m	224*224	yuvsp420_nv12
far103_224y.img	2.5ms	1.1m	1.7m	224*224	yuvsp420_nv12

2. 接口调用流程¶

人脸识别主要包含两个过程，一个是人脸注册过程，这个过程是生成人脸白名单（底库）。另外一个是人脸识别过程，这个过程就是对抓拍到的人脸进行识别，判断是否是白名单人员。

2.1. 注册过程¶

注册过程的接口调用：ALGO_FR_Init → ALGO_FR_CreateHandle → ALGO_FR_Detect → ALGO_FR_Align → ALGO_FR_FeatureExtract。最后将提取到的特征保存起来成为底库。

2.2. 识别过程¶

识别过程的接口调用为：ALGO_FR_Init → ALGO_FR_CreateHandle → ALGO_FR_Detect → ALGO_FR_Align → ALGO_FR_FeatureExtract → ALGO_FR_FeatureCompare，通过抓拍到的图片特征和底库的特征进行比对，判断是不是同一个人。

2.3. 人脸属性识别过程¶

人脸属性识别的接口调用：ALGO_FR_Init → ALGO_FR_CreateHandle → ALGO_FR_Detect → ALGO_FR_Attr，通过抓拍到的人脸图片进行人脸属性识别。注意：裁剪后送入该接口的人脸图像需要做一定范围的外扩，外扩的宽高分别为：1.25 * bbox_w, 1.25 * bbox_h

3. 功能模块API¶

API名	功能
ALGO_FR_Init	SDK初始化
ALGO_FR_CreateHandle	创建句柄
ALGO_FR_Detect	人脸检测
ALGO_FR_Attr	人脸属性识别
ALGO_FR_Align	人脸对齐
ALGO_FR_FeatureExtract	特征提取
ALGO_FR_FeatureCompare	特征比对
ALGO_FR_ReleaseHandle	释放句柄
ALGO_FR_Cleanup	释放整个SDK环境
ALGO_FR_HandleResetParam	重设算法的可配置参数
ALGO_FR_FaceQuanlity	执行人脸角度估计以及质量过滤
ALGO_FR_BatchFeatureCompare	执行批量人脸特征比对（需要拷贝一份比对特征）
ALGO_FR_BatchFeatureCompareV2	执行批量人脸特征比对(不需要拷贝比对特征)

3.1. ALGO_FR_Init¶

功能

初始化SDK，只需初始化一次。

语法

MI_S32 ALGO_FR_Init(InitFrParam_t initParam);

形参

参数名称 描述 输入/输出

initParam 初始化参数输入
返回值

返回值描述

0 成功

其它失败（详见错误码）
依赖

头文件：algo_fr_api.h

库文件：libsstaralgo_fr.so, libsstaralgo_fr.a

举例

{
    int ret=0;
    InitFrParam_t initParam;
    memcpy(initParam.ipu_firware_bin,"/config/dla/ipu_firmware.bin", IPU_MAX_LENGTH);
    memcpy(initParam.det_model_path, "./models/fr_det_y24s.img", MODEL_MAX_LENGTH);
    memcpy(initParam.attr_model_path, "./models/far101_224y_s45.img", MODEL_MAX_LENGTH);
    memcpy(initParam.emo_model_path, "./models/far101_224y_emo_s45.img", MODEL_MAX_LENGTH);
    memcpy(initParam.feature_model_path, "./models/fr_feature_as.img", MODEL_MAX_LENGTH);
    memcpy(initParam.cos_model_path, "./models/i6c/fr_cos256.img", MODEL_MAX_LENGTH);
    initParam.box_min_size = 5;
    initParam.det_thredhold = 0.5;
    initParam.attr_thredhold = 0.3;
    initParam.eye_distance = 20;
    initParam.filter_angle_ratio = 0.2;
    initParam.fr_mode = FR_MODE_FACE_DET | FR_MODE_FACE_DET_RECOG | FR_MODE_FACE_ATTR | FR_MODE_FACE_EMOTION;
    ret= ALGO_FR_Init(initParam);
}

3.2. ALGO_FR_CreateHandle¶

功能

创建句柄，一个线程创建一个句柄。

语法

MI_S32 ALGO_FR_CreateHandle(MI_S64* detectorId)

形参

参数名称 描述 输入/输出

detectorId 句柄指针输入
返回值

返回值描述

0 成功

其它失败（详见错误码）
依赖

头文件：algo_fr_api.h

库文件：libsstaralgo_fr.so, libsstaralgo_fr.a

3.3. ALGO_FR_Detect¶

功能

人脸检测。

语法

MI_S32 ALGO_FR_Detect(MI_S64 detectId, AlgoFrInputInfo_t *stBufInfo,MI_S32 width,MI_S32 height, ParamDet_t* params, DetectBox_t** detectout,MI_S32* facecount)

形参

参数名称	描述	输入/输出
detectorId	句柄	输入
stBufInfo	数据指针（yuv420_nv12）（大小480x288）	输入
width	输入原始图像的宽	输入
height	输入原始图像的高	输入
params	检测的配置参数	输入
detectOut	检测人脸box的输出	输出
faceCount	检测人脸框的个数	输出

返回值

返回值描述

0 成功

其它失败（详见错误码）
依赖

头文件：algo_fr_api.h

库文件：libsstaralgo_fr.so, libsstaralgo_fr.a

3.4. ALGO_FR_Attr¶

功能

人脸属性识别。

语法

MI_S32 ALGO_FR_Attr(MI_S64 detectId, AlgoFrInputInfo_t *stBufInfo, FaceAttr_t *results);

形参

参数名称 描述 输入/输出

detectorId 句柄输入

stBufInfo 数据指针（argb8888）（大小224x224）输入

results 人脸属性结果输出
说明

传入到该接口的人脸buff需要做一定范围的外扩操作，外扩的宽高分别为：+0.25 * bbox_w，+0.25 * bbox_h
返回值

返回值描述

0 成功

其它失败（详见错误码）
依赖

头文件：algo_fr_api.h

库文件：libsstaralgo_fr.so, libsstaralgo_fr.a

3.5. ALGO_FR_Align¶

功能

人脸对齐。

语法

MI_S32 ALGO_FR_Align(MI_U8* imageData,MI_S32 width,MI_S32 height,MI_S32 type, DetectBox_t detectOut,MI_U8* outData);

形参

参数名称	描述	输入/输出
imageData	原图像数据指针	输入
width	原图像宽	输入
height	原图像高	输入
type	图像类型，yuv420_nv12为1，argb8888为0	输入
detectOut	人脸框	输入
outData	输出对齐后的112x112ARGB888数据，不能为空	输出

返回值

返回值描述

0 成功

其它失败（详见错误码）
依赖

头文件：algo_fr_api.h

库文件：libsstaralgo_fr.so, libsstaralgo_fr.a

3.6. ALGO_FR_FeatureExtract¶

功能

人脸特征提取。

语法

MI_S32 ALGO_FR_FeatureExtract(MI_S64 detectId, MI_U8* imageData, MI_S16* featureOut);

形参

参数名称 描述 输入/输出

detectId 句柄

imageData 输入Algin接口出来的112*112图像数据输入

featureOut 人脸的特征数据，长度为514的MI_S16特征输出
返回值

返回值描述

0 成功

其它失败（详见错误码）
依赖

头文件：algo_fr_api.h

库文件：libsstaralgo_fr.so, libsstaralgo_fr.a

3.7. ALGO_FR_FeatureCompare¶

功能

特征比对。

语法

MI_S32 ALGO_FR_FeatureCompare(MI_S16* feature1,MI_S16* feature2,MI_S32 length, MI_FLOAT* simility);

形参

参数名称	描述	输入/输出
feature1	第一张人脸的特征	输入
feature2	第二张人脸的特征	输入
length	特征长度，当前版本为514	输入
simility	两张人脸的相似度	输出

返回值

返回值描述

0 成功

其它失败（详见错误码）
依赖

头文件：algo_fr_api.h

库文件：libsstaralgo_fr.so, libsstaralgo_fr.a

3.8. ALGO_FR_ReleaseHandle¶

功能

释放句柄。

语法

MI_S32 ALGO_FR_ReleaseHandle(MI_S64 detectorId);

形参

参数名称 描述 输入/输出

DetectorId 句柄输入
返回值

返回值描述

0 成功

其它失败（详见错误码）
依赖

头文件：algo_fr_api.h

库文件：libsstaralgo_fr.so, libsstaralgo_fr.a

3.9 ALGO_FR_Cleanup¶

功能

释放整个SDK环境。
语法
```
MI_S32 ALGO_FR_Cleanup();
```
返回值

返回值描述

0 成功

其它失败（详见错误码）
依赖

头文件：algo_fr_api.h

库文件：libsstaralgo_fr.so, libsstaralgo_fr.a

3.10 ALGO_FR_HandleResetParam¶

功能

重设算法的可配置参数

语法

MI_S32 ALGO_FR_HandleResetParam(MI_S64 detectorID, AlgoFrFilterParam_t param);

形参

参数名称 描述 输入/输出

detectorID 句柄输入

param 算法参数,详见AlgoFrFilterParam_t 输入
返回值

返回值描述

0 成功

其它失败（详见错误码）
依赖

头文件：algo_fr_api.h

库文件：libsstaralgo_fr.so, libsstaralgo_fr.a

3.11 ALGO_FR_FaceQuanlity¶

功能

执行人脸角度估计以及质量过滤

语法

MI_S32 ALGO_FR_FaceQuanlity(MI_S64 detectId, AlgoFrInputInfo_t* stBufInfo,DetectBox_t* box, AlgoFaceQuanlityParam_t param, FaceQuanlityAngle_t* angle);

形参

参数名称	描述	输入/输出
detectorID	句柄	输入
stBufInfo	帧数据指针（yuv420_nv12）（大小480x288）	输入
box	人脸检测输出框指针	输入/输出
param	算法参数,详见FaceQuanlityAngle_t	输出
angle	人脸角度输出结果	输出

返回值

返回值描述

0 成功

其它失败（详见错误码）
依赖

头文件：algo_fr_api.h

库文件：libsstaralgo_fr.so, libsstaralgo_fr.a

3.12 ALGO_FR_BatchFeatureCompare¶

功能

执行批量人脸特征比对（需要拷贝一份比对特征）

语法

MI_S32 ALGO_FR_BatchFeatureCompare(MI_S64 detectId, MI_S16* feature1, MI_S16* feature2, MI_S32 batch, MI_FLOAT* simility);

形参

参数名称	描述	输入/输出
detectorID	句柄	输入
feature1	特征比对的目标特征（1个）	输入
feature2	特征比对的源特征（batch个）	输入
batch	特征比对的源特征个数	输入
simility	特征比对输出的相似度	输出

返回值

返回值描述

0 成功

其它失败（详见错误码）
依赖

头文件：algo_fr_api.h

库文件：libsstaralgo_fr.so, libsstaralgo_fr.a

3.13 ALGO_FR_BatchFeatureCompareV2¶

功能

执行批量人脸特征比对(不需要拷贝比对特征)

语法

MI_S32 ALGO_FR_BatchFeatureCompareV2(MI_S64 detectId, AlgoFrInputInfo_t* feature1, AlgoFrInputInfo_t* batchFeature, MI_S32 batch, MI_FLOAT* simility);

形参

参数名称	描述	输入/输出
detectorID	句柄	输入
feature1	特征比对的目标特征（1个），以MMA buffer形式传入	输入
feature2	特征比对的源特征（batch个），以MMA buffer形式传入	输入
batch	特征比对的源特征个数	输入
simility	特征比对输出的相似度	输出

返回值

返回值描述

0 成功

其它失败（详见错误码）
依赖

头文件：algo_fr_api.h

库文件：libsstaralgo_fr.so, libsstaralgo_fr.a

4. 数据类型¶

数据类型	定义
ALGO_FrMode_e	算法模式。
InitFrParam_t	人脸算法的初始化参数。
ParamDet_t	算法检测输入参数，用于选择人脸检测模式。
AlgoFrInputInfo_t	算法输入数据结构体。
FrPoint_t	定义关键点坐标。
DetectBox_t	检测框信息。
FaceAttr_t	人脸属性类别信息。
AlgoFrFilterParam_t	人脸过滤参数结构体
FaceQuanlityAngle_t	人脸角度输出结构体

4.1. ALGO_FrMode_e¶

说明

算法模式。

定义

typedef enum
{
    FR_MODE_FACE_DET,
    FR_MODE_FACE_DET_RECOG,
    FR_MODE_FACE_DET_ATTR,
    FR_MODE_FACE_EMOTION,
} ALGO_FrMode_e;

成员

成员名称 描述

FR_MODE_FACE_DET 人脸检测

FR_MODE_FACE_RECOG 人脸识别

FR_MODE_FACE_ATTR 人脸属性识别

FR_MODE_FACE_EMOTION 人脸表情识别
相关数据类型及接口

ALGO_FR_Init

4.2. InitFrParam_t¶

说明

人脸算法的初始化参数。

定义

typedef struct InitFrParam_
{
    MI_U8 ipu_firware_bin[IPU_MAX_LENGTH];
    MI_U8 det_model_path[MODEL_MAX_LENGTH];
    MI_U8 feature_model_path[MODEL_MAX_LENGTH];
    MI_U8 cos_model_path[MODEL_MAX_LENGTH];
    MI_U8 attr_model_path[MODEL_MAX_LENGTH];
    MI_U8 emo_model_path[MODEL_MAX_LENGTH];
    MI_FLOAT det_thredhold;
    MI_FLOAT attr_thredhold;
    MI_S32   box_min_size;
    MI_FLOAT filter_angle_ratio;
    MI_FLOAT eye_distance;
    MI_U8   fr_mode;
    MI_BOOL had_create_device;
} InitFrParam_t;

成员

成员名称	描述
ipu_firware_bin	Firware_bin的路径
det_model_path	检测模型的路径
feature_model_path	特征提取模型的路径
cos_model_path	相似度模型的路径
attr_model_path	人脸属性识别模型的路径
emo_model_path	人脸表情识别模型的路径
det_thredhold	检测设定的阈值，建议设0.5
attr_thredhold	人脸属性识别设定的阈值，建议设0.5
box_min_size	最小的检测框尺寸，建议设10
filter_angle_ratio	过滤人脸角度比例，建议设0.23
eye_distance	瞳距，建议设30
fr_mode	算法模式，默认为人脸识别模式
had_create_device	多handle，是否已经创建了device

相关接口

ALGO_FR_Init

4.3. ParamDet_t¶

说明

算法检测输入参数，用于选择人脸检测模式。

定义

typedef struct ParamDet_
{
    MI_S32 datatype;
}ParamDet_t;

成员

成员名称	描述
datatype	0表示检测取最大人脸；1表示检测，取所有人脸；2表示视频输入，取最大脸，加入跟踪id；3表示视频输入，取所有脸，加入跟踪id

相关数据类型及接口

ALGO_FR_Detect

4.4. AlgoFrInputInfo_t¶

说明

算法输入数据结构体。

定义

typedef struct AlgoFrInputInfo_
{
    void* pt_tensor_data;
    MI_PHY phy_tensor_addr;
    MI_U32 bufsize;
    MI_S64 pts;
} AlgoFrInputInfo_t;

成员

成员名称 描述

pt_tensor_data 输入数据虚拟地址

phy_tensor_addr 输入数据物理地址

bufsize 输入数据大小

pts 输入数据的时间戳
相关数据类型及接口

ALGO_FR_Detect

4.5. FrPoint_t¶

说明

定义关键点坐标。

定义

typedef struct FrPoint_
{
    MI_FLOAT x;
    MI_FLOAT y;
}FrPoint_t;

成员

成员名称 描述

x 关键点像素的横坐标

y 关键点像素的纵坐标
相关数据类型及接口

DetectBox_t

4.6. DetectBox_t¶

说明

检测框信息。

定义

typedef struct DetectBox_
    {
        MI_FLOAT x1;
        MI_FLOAT y1;
        MI_FLOAT x2;
        MI_FLOAT y2;
        MI_FLOAT score;
        FrPoint_t landmark[FR_POINT_LEN];
        MI_S32 face_id;
        MI_S32 befiltered;
    }DetectBox_t;

成员

成员名称	描述
X1	人脸框的左上点的x坐标
Y1	人脸框的左上点的y坐标
X2	人脸框的右下点的x坐标
Y2	人脸框的右下点的y坐标
score	人脸的置信度
landmark	人脸5个关键点
face_id	人脸的跟踪id
befiltered	人脸是否被过滤，True为被过滤了

相关数据类型及接口

ALGO_FR_Detect

4.7. FaceAttr_t¶

说明

属性类别信息。

定义

typedef struct FaceAttr_t_
{
    MI_BOOL   eye_glass;
    MI_BOOL   male;
    MI_BOOL   mask;
    MI_S32    age;
    MI_BOOL   mustache;
    MI_S32    emotion;
}FaceAttr_t;

成员

成员名称 描述

eye_glass 眼镜

male 男性

mask 口罩

age 年龄

mustache 胡子

emotion 表情
相关数据类型及接口

ALGO_FR_Attr

4.8. AlgoFrFilterParam_t¶

说明

人脸过滤参数结构体

定义

typedef struct AlgoFrFilterParam_
{
    MI_S32   box_min_size;
    MI_FLOAT filter_angle_ratio;
    MI_FLOAT eye_distance;
    MI_FLOAT det_thredhold;
    MI_FLOAT attr_thredhold;
    MI_FLOAT motion_sensitive;   //[0.0-1.0]
}AlgoFrFilterParam_t;

成员

成员名称	描述
box_min_size	最小人脸检测框大小,默认为20（像素）
filter_angle_ratio	头部偏转/俯仰角度要求（0.0~1.0），值越大要求角度越正，默认值为0.25
eye_distance	最小人脸瞳距，默认值为20（像素）
det_thredhold	最小人脸检测score，默认值为0.3
attr_thredhold	人脸属性识别的score阈值
motion_sensitive	人脸运动幅度要求（0.0~1.0），值越大要求人脸运动幅度越小

相关数据类型及接口

ALGO_FR_HandleResetParam

ALGO_FR_FaceQuanlity

4.9. FaceQuanlityAngle_t¶

说明

人脸角度输出结构体

定义

typedef struct FaceQuanlityAngle_
{
    MI_FLOAT pitch;
    MI_FLOAT yaw;
    MI_FLOAT roll;
    MI_FLOAT quanlity;
}FaceQuanlityAngle_t;

成员

成员名称 描述

pitch 人脸俯仰角

yaw 人脸偏航角

roll 人脸翻滚角

quanlity 人脸角度综合得分
相关数据类型及接口

ALGO_FR_FaceQuanlity

5. 错误码 ¶

错误码	数值	描述
E_ALGO_SUCCESS	0	操作成功
E_ALGO_HANDLE_NULL	1	算法句柄为空
E_ALGO_INVALID_PARAM	2	无效的输入参数
E_ALGO_DEVICE_FAULT	3	硬件错误
E_ALGO_LOADMODEL_FAIL	4	加载模型失败
E_ALGO_INIT_FAIL	5	算法初始化失败
E_ALGO_NOT_INIT	6	算法尚未初始化
E_ALGO_INPUT_DATA_NULL	7	算法输入数据为空
E_ALGO_INVALID_INPUT_SIZE	8	无效的算法输入数据维度
E_ALGO_INVALID_LICENSE	9	无效的license许可
E_ALGO_MEMORY_OUT	10	内存不足
E_ALGO_FILEIO_ERROR	11	文件读写操作错误
E_ALGO_INVALID_OUTPUT_SIZE	12	无效的算法输出数据维度

参数名称	描述	输入/输出
detectId	句柄
imageData	输入Algin接口出来的112*112图像数据	输入
featureOut	人脸的特征数据，长度为514的MI_S16特征	输出

成员名称	描述
FR_MODE_FACE_DET	人脸检测
FR_MODE_FACE_RECOG	人脸识别
FR_MODE_FACE_ATTR	人脸属性识别
FR_MODE_FACE_EMOTION	人脸表情识别

成员名称	描述
pt_tensor_data	输入数据虚拟地址
phy_tensor_addr	输入数据物理地址
bufsize	输入数据大小
pts	输入数据的时间戳

成员名称	描述
eye_glass	眼镜
male	男性
mask	口罩
age	年龄
mustache	胡子
emotion	表情

成员名称	描述
pitch	人脸俯仰角
yaw	人脸偏航角
roll	人脸翻滚角
quanlity	人脸角度综合得分

返回值	描述
0	成功
其它	失败（详见错误码）

返回值	描述
0	成功
其它	失败（详见错误码）

返回值	描述
0	成功
其它	失败（详见错误码）

返回值	描述
0	成功
其它	失败（详见错误码）