1. 简介

1.1 产品概述

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

1.2 环境要求

1.2.1 运行环境

Linux x64

1.2.2 开发环境

库依赖GLIBC 2.17及以上 库依赖GLIBCXX 3.4.19及以上 编译器GCC 4.8.2及以上

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 人脸属性检测

对检测到的人脸进行属性分析，支持性别、年龄、3D角度、活体的属性分析，支持图像模式和视频流模式。

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 视觉开放平台门户：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
|   |---linux_x64
|   |	|---libarcsoft_face.so             			算法库
|   |	|---libarcsoft_face_engine.so            		引擎库
|---samplecode
|   |---ASFTestDemo                                    示例Demo
|   |---ReadMe.txt                                     Demo使用说明
|---releasenotes.txt                                   说明文件

2.1.4 工程配置

CMakeLists.txt的步骤：
cmake_minimum_required(VERSION 2.0)		#指定cmake版本
project(项目名称)						#指定项目的名称
set(CMAKE_CXX_STANDARD 11)				#设置c++标准

#指定头文件目录
include_directories(./)
include_directories(./inc)

#指定静态和动态文件目录
link_directories(../linux_so)

add_executable(arcsoft_face_engine_test
./inc/amcomdef.h
./inc/arcsoft_face_sdk.h
./inc/asvloffscreen.h
./inc/merror.h
./AFCTestDemo.cpp)

#在给定的作用域内设置一个命名的属性
set_property(TARGET arcsoft_face_engine_test PROPERTY POSITION_INDEPENDENT_CODE ON)
#链接库文件

target_link_libraries(arcsoft_face_engine_test
arcsoft_face
arcsoft_face_engine
)

相对路径说明： CMakeLists.txt通过cmake命令编译生成makefile文件为起点，去找工程中文件配置目录。上面的CMakeLists.txt编写示例是基于如下工程目录： 生成的makefile文件在build文件夹中： 头文件在inc文件夹中； so文件在linux_so文件中；

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：调用初始化引擎接口返回设备不匹配（90118）的情况下，应该怎么解决？

A：工程激活之后拷贝到其他设备上或激活文件被损坏时，在初始化引擎时会返回设备不匹配的错误码提示信息，应该到执行程序同级目录下找到.asf_install.dat（此文件为隐藏文件）文件删除并重新激活SDK；

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 其他帮助

虹助手微信：Hongzhushou88；

QQ交流群：659920696；

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