ArcSoft ArcFace SDK Android 平台 接入指南 V2.2

1. 简介

1.1 产品概述

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

1.2 环境要求

1.2.1 运行环境

Android armeabi-v7a

1.2.2 系统要求

支持Android 4.4 (API Level 19)及以上系统。

1.2.3 权限申明

获取设备唯一标识，用于SDK激活授权
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
允许应用联网，用于SDK联网激活授权
<uses-permission android:name="android.permission.INTERNET" />  

1.2.4 支持的颜色空间格式

1.3 产品功能简介

1.3.1 人脸检测

对传入的图像数据进行人脸检测，返回人脸的边框以及朝向信息，可用于后续的人脸识别、活体检测等操作；
支持image模式和video模式；
支持单人脸、多人脸检测，最多支持检测人脸检测数为50。

1.3.2 人脸跟踪

对来自于视频流中的图像数据，进行人脸检测，并对检测到的人脸进行持续跟踪。

1.3.3 人脸属性检测

人脸属性分析，支持性别、年龄等。

1.3.4 人脸三维角度检测

分析人脸的三维角度信息，具体为：俯仰角（pitch）， 横滚角（roll）， 偏航角（yaw）。

1.3.5 人脸特征提取

提取人脸视觉特征信息。

1.3.6 人脸比对

对两个人脸特征数据进行比对，来判断是否为同一个人，返回比对相似度值。

1.3.7 活体检测

离线活体检测，静默式识别，在人脸识别过程中判断操作用户是否为真人，有效防御照片、视频、纸张等不同类型的作弊攻击，提高业务安全性，让人脸识别更安全、更快捷，体验更佳。支持单目RGB活体检测、双目（IR/RGB）活体检测，可满足各类人脸识别终端产品活体检测应用。

1.4 SDK授权说明

SDK授权按设备进行授权，每台硬件设备需要一个独立的授权，此授权的校验是基于设备的唯一标识，被授权的设备在初次授权时需在线进行授权，授权成功后可以离线运行SDK。
在线授权：
a) 首次激活需保证与公网连通；
b) 调用在线激活接口激活SDK；
注意事项：
a) 设备授权后，若设备授权信息被删除（重装系统/应用被卸载等），需重新联网重新激活；
b) 硬件信息发生变更，需要重新激活；

2. SDK接入指南

2.1 获取SDK

2.1.1 注册开发者账号

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

2.1.2 SDK下载

创建对应的应用， 添加SDK

选择对应平台，确认后即可下载SDK和查看激活码。

 

点击【查看激活码】即可查看所需要APPID、SDKKEY，点击【下载SDK】获取SDK开发包。

2.1.3 SDK包结构

|---doc
|   |---ARCSOFT_ARCFACE_DEVELOPER'S_GUIDE.pdf              开发说明文档
|   |---ArcFaceAPI-Android.zip                              API说明
|---libs
|   |---armeabi-v7a
|   |   |---libarcsoft_face.so                            引擎库
|   |   |---libarcsoft_face_engine.so                     引擎库
|   |---arcsoft_face.jar                                  引擎库
|---samplecode
|   |---ArcfaceDemo                                        示例工程
|---releasenotes.txt                                       更新说明
            

2.1.4 工程配置

1. 1. 新建一个Android Project，切换到Project视图；
2. 2. 将libarcsoft_face.so和libarcsoft_face_engine.so添加到src->main->jniLibs->armeabi-v7a路径下；
3. 3. 将arcsoft_face.jar放入libs目录下，并依赖进工程；

方法一：

方法二：

2.1.5 调用流程

2.2 核心类介绍

2.2.1 Class FaceEngine

类描述：
人脸引擎类，其中定义了人脸操作相关的函数，包含SDK的授权激活、引擎初始化以及人脸处理相关方法。
具体说明见 JavaDoc 。

2.2.2 Class FaceInfo

类描述：
人脸信息类，用于存储人脸框以及人脸在图片中的朝向信息，对于VIDEO模式的人脸检测，还回传了faceId属性。
具体说明见 JavaDoc 。

2.2.3 Class AgeInfo

类描述：
年龄信息类，用于存储年龄信息。
具体说明见JavaDoc 。

2.2.4 Class GenderInfo

类描述：
性别信息类，用于存储性别信息。
具体说明见JavaDoc 。

2.2.5 Class Face3DAngle

类描述：
人脸三维角度信息类，用于存储人脸三维角度信息。
具体说明见JavaDoc 。

2.2.6 Class LivenessInfo

类描述：
活体信息类，用于存储活体信息。
具体说明见JavaDoc 。

2.2.7 Class LivenessParam

类描述：
活体阈值配置类，用于配置活体阈值。
具体说明见JavaDoc 。

2.2.8 Class FaceFeature

类描述：
人脸特征信息类，用于存储人脸特征信息。
具体说明见JavaDoc 。

2.2.9 Class FaceSimilar

类描述：
人脸相似度信息类，用于存储人脸相似度信息。
具体说明见JavaDoc 。

2.2.10 Class VersionInfo

类描述：
SDK版本信息类，用于存储SDK版本信息。
具体说明见JavaDoc 。

2.2.11 Class ErrorInfo

类描述：
错误信息类，其中定义了引擎调用的错误码。

具体说明见JavaDoc。

 

2.3 错误码列表

 

2.4 阈值推荐

a) 人脸比对阈值,相似度区间为[0~1]，推荐阈值为0.8；
b) RGB活体检测阈值，设置区间为[0~1]，默认阈值0.75；
c) IR活体检测阈值，设置区间为[0~1]，默认阈值0.7；
以上阈值可根据实际使用场景具体调整。  

3. 常见问题

3.1 FAQ

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

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

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

A：人脸检测结果的人脸框位置是基于输入图像的，例如在竖屏模式下，假设View的宽高是1080x1920，相机是后置相机，为了适配画面，预览画面相对于相机的旋转角度为90度，并且预览数据宽高为1920x1080，有一个被检测到的人脸位置是（left,top,right,bottom），那么需要绘制到View上的Rect就是（bottom,left,1080-top,right），相当于顺时针旋转90度，其他角度可用类似的方法计算。另外，在一般情况下，安卓调用前置相机时在View上的显示的画面和实际预览数据成镜像关系。

Q：初始化引擎时检测方向应该怎么选择？

A：SDK初始化引擎中可选择仅对0度、90度、180度、270度单角度进行人脸检测，对于VIDEO模式也可选择全角度进行检测；根据应用场景，推荐使用单角度进行人脸检测，因为选择全角度的情况下，算法会对每个角度检测一遍，导致性能相对于单角度较慢。IMAGE模式下为了提高识别率不支持全角度检测。

Q：初始化引擎时（detectFaceScaleVal）参数多大比较合适？

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

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

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

Q：调用detectFaces、extractFaceFeature和process接口返回90127错误码，该怎么解决？

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

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

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

Q：为何调用引擎有时会出现crash？

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

Q：MERR_FSDK_FACEFEATURE_LOW_CONFIDENCE_LEVEL，人脸检测结果置信度低是什么情况导致的？

A：图片模糊或者传入的人脸框不正确。若是使用了RGB摄像头人脸检测 + IR摄像头活体检测的方案，则很有可能是两者成像差距很大或两者画面成镜像或旋转的关系。

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

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

Q：如何进行IR活体检测？

A：推荐的方案是采用双目（RGB/ IR）摄像头，RGB摄像头数据用于人脸检测，将人脸检测的结果用于IR活体检测。需要注意的是，IR活体检测不支持BGR24颜色格式的图像数据。

Q：初始化引擎时，传入检测模式为IMAGE模式，检测方向为全角度，为何会创建失败？

A：为了提高人脸检测识别率，该版本的IMAGE模式不支持全角度检测，开发者需要根据图像中的人脸方向确定人脸检测的角度。

3.2 其他帮助

虹助手微信：Hongzhushou88；

QQ交流群：659920696；

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