无标题文档

1. 简介

1.1 产品概述

ArcFace 离线SDK,包含人脸检测、性别检测、年龄检测、人脸识别、活体等能力,初次使用时需联网激活,激活后即可本地无网络环境下工作,可根据业务需求结合人脸识别等SDK灵活的进行应用层开发。

1.2 环境要求

1.2.1 系统要求

Win7及以上

1.2.2 开发环境

VS2013及以上

1.2.3 支持的颜色空间格式

支持图像的颜色空间格式: NV21,NV12, BGR24,I420,YUYV

常量名 常量值 常量说明
CP_PAF_NV21 2050 8-bit Y 通道,8-bit 2x2 采样 V 与 U 分量交织通道
ASVL_PAF_NV12 2049 8-bit Y 通道,8-bit 2x2 采样 U 与 V 分量交织通道
CP_PAF_BGR24 513 RGB 分量交织,按 B, G, R, B 字节序排布
ASVL_PAF_I420 1537 8-bit Y 通道, 8-bit 2x2 采样 U 通道, 8-bit 2x2 采样 V 通道
ASVL_PAF_YUYV 1289 YUV 分量交织, V 与 U 分量 2x1 采样,按 Y0, U0, Y1, V0 字节序排布

1.3 产品功能简介

1.3.1 人脸检测

对传入图像数据进行人脸检测,返回人脸位置信息和人脸在图像中的朝向信息,可用于后续的人脸分析、人脸比对操作,支持图像模式和视频流模式。 支持单人脸、多人脸检测,最多支持检测人脸数为50。

1.3.2 人脸跟踪

捕捉视频流中的人脸信息,并对人脸进行跟踪。

1.3.3 人脸属性检测

对检测到的人脸进行属性分析,支持性别、年龄的属性分析,支持图像模式和视频流模式。

1.3.4 人脸三维角度检测

检测输入图像数据指定区域人脸的三维角度信息,包含人脸三个空间角度:俯仰角(pitch), 横滚角(roll), 偏航角(yaw),支持图像模式和视频流模式。

1.3.5 人脸比对

将两个人脸进行比对,来判断是否为同一个人,返回比对相似度值。

1.3.6 活体检测

离线活体检测,基于RGB单目摄像头实现静默式识别。针对视频流/图片,通过采集人像的破绽来判断目标对象是否为活体,可有效防止照片、屏幕二次翻拍等作弊攻击。

1.4 SDK授权说明

SDK授权按设备进行授权,每台硬件设备需要一个独立的授权,此授权的校验是基于设备的唯一标识,被授权的设备,初次授权时需要联网进行授权,授权成功后可以离线运行SDK。

激活一台设备后,遇以下情况,设备授权不变,但需要重新联网激活:

 删除基于SDK开发的应用或删除应用数据

 重新安装系统

 激活一台设备后,硬件信息发生变更

2. 接入指南

2.1 引擎获取

2.1.1 注册为开发者

访问ArcSoft AI开放平台门户:https://ai.arcsoft.com.cn,注册开发者账号并登录。

2.1.2 SDK下载

创建对应的应用,并选择需要下载的SDK、对应平台以及版本,确认后即可下载SDK和查看激活码。

可在查看激活码链接中获取APPID、SDKKey,点击下载SDK下载SDK包。

点击【下载SDK】即可下载SDK开发包;

点击【查看激活码】即可查看所需要APPID、SDKKEY;

2.1.3 SDK包结构

|---doc
|   |---ARCSOFT_ARC_FACE_DEVELOPER'S_GUIDE.PDF   		开发说明文档
|---inc
|   |---amcomdef.h                  					平台文件
|   |---asvloffscreen.h                                平台文件
|   |---arcsoft_face_sdk.h                             接口文件
|   |---merror.h                                       错误码文件
|---lib
|---|---Win32
|   |---|---libarcsoft_face.dll             			算法库
|   |---|---libarcsoft_face_engine.dll            		引擎库
|   |---|---libarcsoft_face_engine.lib            		引擎库
|---samplecode
|   |---samplecode.txt                                 示例代码
|---releasenotes.txt                                   说明文件

2.1.4 工程配置

方法1:VS中添加lib库及头文件(外部依赖项)的步骤:

1、 添加工程的头文件目录:

a) 右键单击工程名, 选择属性---配置属性---c/c++---常规---附加包含目录

b) 添加头文件存放目录路径

2、 添加文件引用的lib静态库路径:

a) 右键单击工程名,选择属性---配置属性---链接器---常规---附加库目录

b) 添加lib文件存放目录

3、 添加工程引用的lib库:

a) 右键单击工程名,选择属性---配置属性---链接器---输入---附加依赖项

b) 添加依赖的lib库名称

4、 添加工程引用的dll动态库:

a) 把引用的dll放到工程的可执行文件所在的目录下(例如:debug、relese或工程目录下)。

方法2:相对路径的设置

在VS的工程中常常要设置头文件的包含路径和库目录,如果使用绝对路径,其他人拷贝你的工程到其他机器上就可能无法运行,原因是在建工程时可能把工程放在了E:盘,但是拷贝后的工程路径和拷贝前的工程路径不一致,会导致找不到头文件问题。因此,建议配置包含路径和库目录时使用相对路径。

这里的相对路径就是相当于工程文件(XXXX.vcproj)为起点计算出的能找到包含所需头文件(也就是找包含所需头文件的include目录)的路径。

例如你的工程文件(Count.vcproj)所在目录路径为:

E:\projects\Count\Count\Count.vcproj

该工程需要包含一个图片参数,该图片所在路径如下:

E:\projects\Count\pic\pic01.jpg

这里程序中的相对路径设置如下:

..\pic\pic02.jpg

程序代码中的参数路径设置时要用双斜线: 例如:

#include "..\TestLib\lib.h"

#pragma comment(lib,"..\debug\TestLib.lib");

2.1.5 调用流程

Step 1:激活,调用ASFActivation

接口所需AppId、SDKKey在申请SDK时获取,只需在第一次使用时调用激活成功即可;

Step 2:初始化,调用ASFInitEngine初始化引擎

 VIDEO模式:处理连续帧的图像数据,并返回检测结果,需要将所有图像帧的数据都传入接口进行处理;

 IMAGE模式:处理单帧的图像数据,并返回检测结果;

Step 3: 调用ASFDetectFaces进行人脸检测

接口所需的图像信息,format参数支持NV21/NV12/YUYV/BGR24/I420五种颜色空间格式,图像处理结果可从detectedFaces参数中获取;

Step 4:调用ASFFaceFeatureExtract接口进行人脸特征提取

接口只支持单人脸特征提取,处理结果可从feature参数中获取;

Step 5: 调用ASFFaceFeatureCompare接口进行人脸比对

接口只支持单人脸比对,处理结果可从confidenceLevel参数中获取;

Step 6: 调用ASFProcess接口进行人脸信息检测

接口中combinedMask参数传入只能是初始化中参数combinedMask与ASF_AGE | ASF_GENDER | ASF_FACE3DANGLE| ASF_LIVENESS的交集的子集;

Step 7: 调用ASFGetAge、ASFGetGender、ASFGetFace3Dangle、ASFGetLivenessScore接口,年龄、性别、人脸角度、活体信息;

Step 8: 调用ASFUninitEngine销毁引擎

2.1.6 阈值推荐

阈值区间为[0~1],建议阈值设置为0.8,可根据实际场景需求进行调整。

2.2 枚举

2.2.1 检测方向的优先级

根据应用场景,推荐选择单一角度,检测效果更优;

enum ArcSoftFace_OrientPriority {
	ASF_OP_0_ONLY = 0x1,		// 仅检测0
	ASF_OP_90_ONLY = 0x2,		// 仅检测90
	ASF_OP_270_ONLY = 0x3,		// 仅检测270
	ASF_OP_180_ONLY = 0x4,		// 仅检测180
	ASF_OP_0_HIGHER_EXT = 0x5,	// 检测0,90,270,180全角度
};

2.2.2 检测到的人脸角度(按逆时针方向)

enum ArcSoftFace_OrientCode {
	ASF_OC_0 = 0x1,			// 0 degree 
	ASF_OC_90 = 0x2,		// 90 degree 
	ASF_OC_270 = 0x3,		// 270 degree 
	ASF_OC_180 = 0x4,   	// 180 degree 
	ASF_OC_30 = 0x5,		// 30 degree 
	ASF_OC_60 = 0x6,		// 60 degree 
	ASF_OC_120 = 0x7,		// 120 degree 
	ASF_OC_150 = 0x8,		// 150 degree 
	ASF_OC_210 = 0x9,		// 210 degree 
	ASF_OC_240 = 0xa,		// 240 degree 
	ASF_OC_300 = 0xb,		// 300 degree 
	ASF_OC_330 = 0xc		// 330 degree 
};

3. 常见问题

3.1 FAQ

Q:初始化引擎时检测方向(detectFaceOrientPriority)应该怎么选择?

A:SDK初始化引擎中可选择仅对0度、90度、180度、270度单角度进行人脸检测,也可选择全角度进行检测;根据应用场景,推荐使用单角度进行人脸检测,因为选择全角度的情况下,算法中会对每个角度检测一遍,导致性能相对于单角度较慢。

Q:初始化引擎时(detectFaceScaleVal)参数多大比较合适?

A:用于数值化表示的最小人脸尺寸,该尺寸代表人脸尺寸相对于图片长边的占比。video 模式有效值范围[2,16], Image 模式有效值范围[2,32],多数情况下推荐值为 16,特殊情况下可根据具体场景下进行设置。

Q:初始化引擎之后调用其他接口返回错误码86018,该怎么解决?

A:86018即需要检测的属性未初始化,需要查看调用接口的宏有没有在初始化引擎时在combinedMask参数中加入。

Q:进行人脸比对时一般会调用ASFDetectFaces和ASFFaceFeatureExtract两次,可能会导致比对的相似度一直为1?

A:初始化引擎之后会提前分配好需要使用的内存,所以第二次调用ASFDetectFaces和ASFFaceFeatureExtract接口输出的结果会覆盖第一次输出的结果,此时应用层定义的指针指向同一块内存,得到的数据是一样的,所以导致比对结果为1。

方案一:ASFDetectFaces和ASFFaceFeatureExtract接口可以在第一次调用时进行数据深拷贝。

方案二:ASFDetectFaces调用之后进行特征提取(ASFFaceFeatureExtract),如果ASFDetectFaces输出结果没用其他用途,则不需要进行深拷贝,但是ASFFaceFeatureExtract输出结果需要进行深拷贝用于比对。

Q:调用ASFDetectFaces、ASFFaceFeatureExtract和ASFProcess接口返回90127错误码,该怎么解决?

A:ArcSoft SDK对图像尺寸做了限制,宽高大于0,宽度为4的倍数,YUYV/I420/NV21/NV12格式的图片高度为2的倍数,BGR24格式的图片高度不限制;如果遇到90127请检查传入的图片尺寸是否符合要求,若不符合可对图片进行适当的裁剪。

Q: 人脸检测结果的人脸框Rect为何有时会溢出传入图像的边界?

A: Rect溢出边界可能是人脸只有一部分在图像中,算法会对人脸的位置进行估计。

Q: 为何调用引擎有时会出现crash?

A:若在引擎调用过程中进行销毁引擎则可能会导致crash。在使用过程中应避免在销毁引擎时还在使用引擎,尤其是做特征提取或活体检测等耗时操作时销毁引擎,如加锁解决。

Q: 如何将人脸识别1:1进行开发改为1:n?

A: 先将人脸特征数据用本地文件、数据库或者其他的方式存储下来,若检测出结果需要显示图像可以保存对应的图像。之后循环对特征值进行对比,相似度最高者若超过您设置的阈值则输出相关信息。

Q: Android人脸检测结果的人脸框绘制到View上为何位置不对?

A: 人脸检测结果的人脸框位置是基于输入图像的,例如在竖屏模式下,假设View的宽高是1080x1920,相机是后置相机,并且预览数据宽高为1920x1080,有一个被检测到的人脸位置是(left,top,right,bottom),那么需要绘制到View上的Rect就是(bottom,left,1080-top,right),相当于顺时针旋转90度,其他角度可用类似的方法计算。

Q: MERR_FSDK_FACEFEATURE_LOW_CONFIDENCE_LEVEL,人脸检测结果置信度低是什么情况导致的?

A: 图片模糊或者传入的人脸框不正确。

Q:哪些因素会影响人脸检测、人脸跟踪、人脸特征提取等SDK调用所用时间?

A:硬件性能、图片质量等。

3.2 其他帮助

SDK交流论坛:http://ai.arcsoft.com.cn/bbs/