IOS-基础版

更新时间：2021-12-27

版本记录

版本	日期	更新说明
v3.3.0	2018.06.15	增加多人脸检测功能；性能优化，修复部分bug

1 基础信息
  1.1 产品概述
  1.2 规格信息
  1.3 兼容性
  1.4 开发包说明
2 业务介绍
  2.1 功能简介
  2.2 业务流程
3 快速集成
  3.1 创建SDK使用的鉴权文件
  3.2 下载SDK
  3.3 快速测试
4 接口说明
  4.1 人脸采集
  4.2 多人脸追踪
  4.3 FaceSDK鉴权方法
  4.4 鉴权成功的凭证
  4.5 设置人脸功能控制参数
  4.6 人脸质量检测配置
  4.7 人脸图像检测
  4.8 人脸精准对齐
  4.9 人脸追踪
  4.10 人脸姿态获取
  4.11 人脸姿态获取(常用方法)
  4.12 多人脸追踪
  4.13 人脸追踪识别
  4.14 最大人脸追踪识别
  4.15 人脸图片质量检测
  4.16 人脸抠图
5 常见问题

1、基础信息

1.1 产品概述

百度FaceSDK iOS基础版是一种面向iOS移动设备人脸技术开发包，此版SDK包含人脸检测、活体识别等API。基于该方案，开发者可以轻松的构建包含人脸检测、采集的应用。在您使用SDK之前，我们首先为您介绍以下SDK本身及相关人脸能力，以便您能更方便使用人脸服务。

1.2 规格信息

包大小：~10M
最小人脸检测大小：50px * 50px
可识别人脸角度：yaw ≤ ±30°, pitch ≤ ±30°
检测速度：100ms 720p*
追踪速度：30ms 720p*
人脸检测耗时：< 100ms

备注：以上指标，由最新版SDK运行在真实设备上，采用真实数据集所得，但算法性能受实际运行设备、实际数据集等情况影响，以上数字仅供参考。

1.3 兼容性

系统：支持iOS 8及以上系统。需要开发者通过Deployment Target来保证支持系统的检测。
机型：手机和平板皆可
网络：支持 WIFI 及移动网络,移动网络支持使用 NET 网关及WAP 网关(CMWAP、CTWAP、UNIWAP、3GWAP)。

1.4 开发包说明

文件/文件夹名	说明
FaceSDK	FaceSDK 包、bundle资源文件、模型文件、鉴权文件
Core	相机视频流处理类
Utils	图片坐标转换、图片资源加载类
ViewController	DEMO工程
FaceParameterConfig.h	配置信息

1.4 授权介绍

FaceSDK iOS版本，基于产品线授权，

2、业务介绍

2.1 功能简介

2.1.1 人脸检测与跟踪

可在设备端，离线实时检测视频流中的人脸。同时支持处理静态图片或者视频流，并对当前检测到的人脸持续跟踪，动态定位人脸轮廓，稳定贴合人脸。

2.1.2 质量控制

在人脸检测及追踪过程中，实时校验人脸的姿态角度、遮挡、清晰度、光照条件，符合质量条件的人脸图片才会被采集。

2.1.3 人脸采集

针对视频流实时完成人脸图片采集，并输出满足质量过滤条件的人脸图片，可自定义采集人脸大小，采集频率，采集质量等设置。

2.2 业务流程

人脸识别的应用场景，核心可以分为三大类：

身份核验：即1:1对比，判断两张脸的相似度，判断你是你，通常用于需要验证用户身份真实性的场景，如人证对比。
身份识别：即1:N识别，在一个人脸集合中找到最相似的人脸，判断你是谁，通常用于判断用户身份是否存在，及身份信息内容的场景，如人脸门禁、人脸支付等。
属性分析：即人脸属性分析，基于人脸信息，返回年龄、性别等属性值，通常用于客群分析、娱乐营销等场景，如统计线下客群年龄分布。

而以上场景的几乎所有业务过程，核心可以分为两个步骤：

人脸采集：人脸识别的前置步骤，即获取到人脸图片，用于对比、识别、属性分析等操作。
人脸分析：包括人脸图片的加工处理，特征抽取与对比，结果返回等一系列操作，也是通常理解为的人脸识别操作。

要想确保人脸识别的应用效果得到保障，最为核心的一个环节即人脸的获取，即人脸采集。目前市面上所有人脸识别应用落地，面临的主要问题就是应用环境复杂，包括光照、遮挡、作弊攻击等一系列环境因素干扰，涉及产品策略、硬件选型、施工方案等多个维度地综合作用，才能不断提升最终效果。

3、快速集成

3.1 创建SDK使用的鉴权文件

人脸SDK License：此license用于SDK离线功能使用，在您的申请人脸SDK的后台页面，全局->产品服务->人脸识别->采集SDK , 点击创建授权文件。

创建授权

在弹出的框中输入授权标识，选择应用类型，应用系统，以及包名，详情请查看输入框右边提示。

填写授权信息

3.2 下载SDK

基础采集SDK下载请点击SDK的下载地址

SDK下载分两种：

1、自动配置授权信息。（license创建后可以选择该方式，下载SDK后自动帮您配置授权，不用单独导入license，初始化参数licenseID、包名自动配置）

2、手动导入授权信息。需要手动导入license文件，配置好bundleID、licenseID等信息；

3.3 快速测试

3.3.1 自动配置授权信息集成

如果您是通过自动配置授权信息下载的示例工程，只需配置好证书即可。查看下项目中的FaceParameterConfig.h文件，已经自动配置。配置好证书，即可运行。注意已经设置好的bundle id不要随意改动。

3.3.2 手动导入授权信息的集成

打开或者新建一个项目。

右键点击项目，会出现一个添加菜单，在菜单中选择『Add Files to“此处是你的项目名字”…… 』,在添加文件弹出框里面选择申请到的license添加进来。下载license文件，根据要求配置项目中的FaceParameterConfig.h文件中的内容。如下图所示：

3.3.3 添加SDK到工程

1、打开或者新建一个项目。

2、右键点击项目，会出现一个添加菜单，在菜单中选择『Add Files to“此处是你的项目名字”…… 』, 在添加文件弹出框里面的 FaceSDK开发工具包添加进来。SDK的下载地址

如下图所示：

SDK包含下面3个文件:

文件名/包名	说明
com.baidu.idl.face.faceSDK.bundle	图片音频资源包
com.baidu.idl.face.model.bundle	模型捆绑包
IDLFaceSDK.framework	FaceSDK

导入SDK

3、确认下Bundle Identifier 是否是申请license时填报的那一个，注意：license和Bundle Identifier是一一对应关系，填错了会导致SDK不能用。

4、填写正确的FACE_LICENSE_ID。

（即后台展示的LicenseID）

在FaceParameterConfig.h文件里面填写拼接好的FACE_LICENSE_ID。

5、选择链接C++标准库。

6、如果没有使用pod管理第三方库的话，请在Build Setting >Linking > Other Linker Flags 上面加入–ObjC选项。如果用了pod请忽略，因为pod会自动添加上。

3.3.4 权限声明

需要使用相机权限：编辑Info.plist文件，添加

Privacy- Camera Usage Description的Key值，Value为使用相机时候的提示语，可以填写:「使用相机」

4、接口说明

4.1 人脸采集

/*带黑边的方法-通过图片质量控制*/
- (void)detectStratrgyWithQualityControlImage:(UIImage *)image previewRect:(CGRect)previewRect detectRect:(CGRect)detectRect completionHandler:(DetectStrategyCompletion)completion;

/*不带黑边*/
- (void)detectStratrgyWithNormalImage:(UIImage *)image previewRect:(CGRect)previewRect detectRect:(CGRect)detectRect completionHandler:(DetectStrategyCompletion)completion;

温馨提示：带黑边的图片，主要是为了配合在线API方式的活体检测使用，本地算法会对图片做一定的预处理操作；而不带黑边的图片，如果无需使用活体，则可使用不带黑边的图片采集方式。

参数说明：

previewRect与detctRect是为了做距离检测而定义的，为了在上层封装判断脸是否在框内／离太远／离太近。

image：相机获取的图片
previewRect：间接定义的最大距离的maxRect和最小距离的minRect。
detectRect：实际采集区域
completion：回调

使用方法见下图：

4.2 多人脸追踪

- (void)detectMultiFacesImage:(UIImage *)image withMaxFaceCount:(NSInteger)maxFaceCount handler:(TrackDetectStrategyCompletion)completion;

参数说明：

image：相机获取的图片
maxFaceCount：定义追踪的人脸数目
completion：回调

使用方法见下图：

4.3 FaceSDK鉴权方法

- (void)initLicenseID:(NSString *)licenseId localLicenceFile:(NSString *)localLicencePath
remoteAuthorize:(BOOL)remoteAuthorize;

参数：

licenseId : 平台申请的 licenseID
localLicencePath : 鉴权文件路径
remoteAuthorize：是否开启网络鉴权

4.4 鉴权成功的凭证

 - (FaceLicenseErrorCode)canWork;

参数：

FaceLicenseErrorCode 返回值

4.5 设置人脸功能控制参数

具体方法详见如下：

 // 设置鉴权
-(void)setLicenseID:(NSString )licenseID andLocalLicenceFile:(NSString)localLicencePath;
// 最小检测人脸阈值
-(void)setMinFaceSize:(NSInteger)width;
// 截取人脸图片大小
-(void)setCropFaceSizeWidth:(CGFloat)width;
// 人脸检测精度阈值
-(void)setNotFaceThreshold:(CGFloat)th; 
// 人脸遮挡阈值
-(void)setOccluThreshold:(CGFloat)thr;
// 亮度阈值
-(void)setIllumThreshold:(NSInteger)thr;
// 图像模糊阈值
-(void)setBlurThreshold:(CGFloat)thr;
// 头部姿态角度
-(void)setEulurAngleThrPitch:(NSInteger)pitch yaw:(NSInteger)yawroll:(NSInteger)roll; 
// 是否进行人脸图片质量检测
-(void)setIsCheckQuality:(BOOL)isCheck;

4.6 人脸质量检测配置

- (void)setQualityCheckAbility:(FaceQualityType)type isOpen:(BOOL)open;

注意：质量检测默认关闭，要想开启对应功能需要先调用setIsCheckQuality接口方法参数:

参数：

type: 质量检测类型 FaceQualityType
open：是否开启

4.7 人脸图像检测

- (void)detectFaceInImage:(UIImage *)image
           withMethodType:(FaceSDKDetectMethodType)methodType
          andGetFaceRects:( NSArray *_Nullable*_Nullable)faceRects
            andFaceNumber:(NSInteger *)faceNumber
       andMinimumFaceSize:(NSInteger)minSize;

参数:

image 图像
methodType 检测算法模型 CNN（可见光图片检测）、NIR（近红外图片检测）
minSize 最小检测人脸size

faceRects output 人脸框的位置
faceNumber 检测出的人脸的数目

4.8 人脸精准对齐

- (void)fineAlignFaceInImage:(UIImage *)image
              withMethodType:(FaceSDKMethodType)methodType
                andFaceShape:(NSArray *_Nullable*_Nullable)faceShape
              andNumOfPoints:(NSInteger)numberOfPoints;

参数：

image 图像
methodType 识别算法模型 SDM / CDNN（建议用）

faceShape input/output人脸特征点
numberOfPoints 人脸特征点个数

4.9 人脸追踪

- (void)trackFaceInImage:(UIImage *)image
          withMethodType:(FaceSDKMethodType)methodType
            andFaceShape:( NSArray *_Nullable*_Nullable)faceShape
          andNumOfPoints:(NSInteger )numberOfPoints
                andScore:(CGFloat *)score;

参数：

image 图像
methodType 识别算法模型 SDM / CDNN（建议用）
faceShape 72个人脸特征点坐标数组
numberOfPoints 人脸特征点个数，目前只支持72个点

score output置信度

4.10 人脸姿态获取

- (NSDictionary *)headPostEstimationWithFaceShape:(NSArray *)faceShape
                                 andImgDataRowNum:(NSInteger)rows
                                   andImgColumNum:(NSInteger)colums
                                   andNumOfPoints:(NSInteger )numberOfPoints;

参数：

faceShape input and output 人脸特征点
numberOfPoints 人脸特征点个数
rows 图像宽
colums 图像高

NSDictionary pitch、row、yaw

4.11 人脸姿态获取(常用方法)

- (NSDictionary *)headPostEstimationWithImage:(UIImage *)image
                                 andFaceShape:(NSArray *)faceShape
                               andNumOfPoints:(NSInteger )numberOfPoints;

参数：

image 图像
faceShape input and output 人脸特征点
numberOfPoints 人脸特征点个数

NSDictionary pitch、row、yaw

4.12 多人脸追踪

- (void)trackWithImage:(UIImage *)image andMaxFaceCount:(NSUInteger)count;

参数：

image 图像
count 追踪人脸数目

4.13 人脸追踪识别

最先检测到人脸

- (FaceVerifierErrorCode)prepareDataWithImage:(UIImage *)image
andActionType:(FaceVerifierActionType)actionType;

参数：

image 图像
actionType 采集方式（FaceVerifierActionTypeRecognition）

FaceVerifierErrorCode 人脸识别结果

4.14 最大人脸追踪识别

- (FaceVerifierErrorCode)prepareDataForMaxFaceWithImage:(UIImage *)image andActionType:(FaceVerifierActionType)actionType;

参数：

image 图像
actionType 采集方式（FaceVerifierActionTypeRecognition）

FaceVerifierErrorCode 最大人脸识别结果

4.15 人脸图片质量检测

一般用于trackImage方法后用

- (void)imageQualityWith:(UIImage *)image
          andFaceShape:(NSArray *_Nullable*_Nullable)faceShape
        andNumOfPoints:(NSInteger)numberOfPoints
             bluriness:(CGFloat *)bluriness
                 illum:(NSInteger *)illum
             occlusion:(NSArray *_Nullable*_Nullable)occlusion
            nOccluPart:(NSInteger *)nOccluPart;

参数：

image 图像
faceShape 人脸特征点
numberOfPoints 人脸特征点个数

bluriness 人脸模糊值
illum 光照值
occlusion 人脸部位
nOccluPart 人脸遮挡部位数量

4.16 人脸抠图