完善个人信息

完善您的账号信息，便于为您提供更精准的服务

跳过
开发者类型：
企业名称：
联系人姓名：
真实姓名：
行业：
地区：

 无标题文档

ArcSoft ArcFace SDK Windows平台 接入指南 V2.0~2.1

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 视觉开放平台门户：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 其他帮助

虹助手微信：Hongzhushou88；

QQ交流群：659920696；

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