IOS SDK

更新时间：2021-12-27

目录~~
1、简介
   1.1 功能介绍
   1.2 兼容性
   1.3 开发包说明
2、集成指南
   2.1 准备工作
      2.1.1 申请license
      2.1.2 下载SDK
   2.2 运行示例工程
      2.2.1 自动配置授权信息集成
      2.2.2 未使用自动配置授权信息的集成
   2.3 添加SDK到工程
   2.4 权限声明
3、接口说明
   3.1 FaceSDK 鉴权初始化
      3.1.1 设置鉴权功能
      3.1.2 鉴权成功的凭证
   3.2 FaceSDK 功能初始化
      3.2.1 FaceSDK 参数配置
      3.2.2 FaceSDK 初始化
      3.2.3 FaceSDK 释放
   3.3 人脸采集
   3.4 动作采集
   3.5 活体动作设置
4、常见问题

1、简介

1.1 功能介绍

百度Face SDK IOS 版是一种面向 IOS 移动设备人脸技术开发包，此版SDK包含人脸检测、活体识别等功能。

基于该方案，开发者可以轻松的构建包含人脸检测、采集和活体识别的应用。在您使用SDK之前，我们首先为您介绍以下SDK本身及相关人脸能力，以便您能更方便使用人脸服务。

此版SDK所包含的能力如下：

本地版活体检测：通过让用户做出指定人脸配合式的交互动作，识别当前操作者是否为活体。此功能为离线使用，可设定指定动作是否使用及应用顺序。动作包含：眨眼、张嘴、左摇头，右摇头，摇摇头、向上抬头，向下低头。可有效抵御高清图片、3D建模、视频等攻击。说明：用户完成相应动作即判断为活体，不返回相应分数。

建议搭配线上的在线活体检测接口配合使用，在本地做动作活体检测，云端进行视频翻拍、模型攻击以及合成图攻击的二次校验
本地版人脸质量检测：判断视频流中的图片帧中，哪些图片质量较佳，即人脸图像特征清晰（满足角度、姿态、光照、模糊度等校验）。
本地版人脸图像采集：通过本地SDK能力，采集人脸图像，同时经过人脸质量检测，确保采集到的人脸图像符合各条件校验（角度、姿态、光照、模糊度等），为设备前端获取有效可分析人脸的主要功能。
离线授权：SDK的授权判断，授权介质也称为license，在SDK使用中，需要通过license向授权服务器发起请求，判断SDK的使用合法性及使用有效期。

此版SDK全部功能为离线版本，所有功能均本地化使用，主要用于在客户端（IOS）获取人脸，实际业务使用中，可以按照业务需要，配合在线API完成全流程的业务集成。

业务流程

1.2 兼容性

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

1.3 开发包说明

文件/文件夹名	说明
FaceSDK	FaceSDK 包、bundle 资源文件、bundle 模型文件、鉴权文件
Public/Common	视频流处理类
Public/Utils	图像处理类
UI/Controller	DEMO工程
UI/View	View控制类
FaceParameterConfig.h	配置信息

2、集成指南

2.1 准备工作

2.1.1 申请license

人脸SDK License：此license用于SDK离线功能使用，在您的申请人脸SDK的后台⻚面，全局->产品服务->人脸识别->本地化部署->离线采集SDK申请

人脸控制台路径如下：

把脸移入框内

点击客户端SDK管理，弹出如下图：创建应用（这里创建应用是为了使用离线SDK，上面创建应用为了使用人脸在线接口，如注册、识别等）

把脸移入框内

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

把脸移入框内

2.1.2 下载SDK

把脸移入框内

下载SDK分为自动配置授权信息（创建license后就可以选择为该应用，下载后SDK自动帮您配置授权，不用下载license拷贝到工程中，初始化参数licenseID,包名也帮您配置好了）和未配置授权信息两种方式：

把脸移入框内

2.2 运行示例工程

2.2.1 自动配置授权信息集成

如果您是通过自动配置授权信息下载的示例工程，只需配置好证书即可。查看下项目中的FaceParameterConfig.h文件，已经自动配置

配置好证书，即可运行。注意已经设置好的bundle id不要随意改动。

2.2.2 未使用自动配置授权信息的集成

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

2.3 添加SDK到工程

打开或者新建一个项目。
右键点击项目，会出现一个添加菜单，在菜单中选择『Add Files to“此处是你的项目名字”…… 』,如下图所示：

在添加文件弹出框里面选择申请到的license和SDK添加进来。如下图：

注意：license为百度官方提供的。

SDK包含下面三个文件:
- IDLFaceSDK.framework
- com.baidu.idl.face.faceSDK.bundle
- com.baidu.idl.face.model.faceSDK.bundle

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

填写正确的FACE_LICENSE_ID。

（即后台展示的LicenseID）

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

选择链接C++标准库。

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

2.4 权限声明

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

Privacy- Camera Usage Description 的Key值，Value为使用相机时候的提示语，可以填写：『使用相机』。

3、接口说明

3.1 FaceSDK 鉴权初始化

3.1.1 设置鉴权功能

- (void)setLicenseID:(NSString *)licenseID andLocalLicenceFile:(NSString *)licensePath andRemoteAuthorize:(BOOL)remoteAuthorize;

参数：

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

返回：

参考AppDelegate.m 实现，使用方法如下：

    NSString* licensePath = [[NSBundle mainBundle] pathForResource:FACE_LICENSE_NAME ofType:FACE_LICENSE_SUFFIX];
    NSAssert([[NSFileManager defaultManager] fileExistsAtPath:licensePath], @"license文件路径不对，请仔细查看文档");
    [[FaceSDKManager sharedInstance] setLicenseID:FACE_LICENSE_ID andLocalLicenceFile:licensePath andRemoteAuthorize:true];

3.1.2 鉴权成功的凭证

- (BOOL)canWork

参数：

返回：

True代表成功，false代表失败

参考ViewController.m 实现，判断鉴权是否通过：

if (![[FaceSDKManager sharedInstance] canWork]){
   NSLog(@"授权失败，请检测ID 和 授权文件是否可用");
   return;
}

3.2 FaceSDK 功能初始化

3.2.1 FaceSDK 参数配置

具体方法详见如下：

/**
 *  设置预测库耗能模式
 *  默认 LITE_POWER_NO_BIND
 */
- (void)setLitePower:(int)litePower;

/**
 *  需要检测的最大人脸数目
 *  默认1
 */
- (void)setMaxDetectNum:(int)detectNum ;

/**
 *  需要检测的最小人脸大小
 *  默认40
 */
- (void)setMinFaceSize:(int)width;

/**
 *  人脸置信度阈值（检测分值大于该阈值认为是人脸
 *  RGB
 *  默认 0.5f
 */
- (void)setNotFaceThreshold:(CGFloat)thr ;

/**
 *  质量检测遮挡阈值
 *  默认0.5
 */
- (void)setOccluThreshold:(CGFloat)thr ;

/**
 * 质量检测光照阈值
 *  默认100
 */
- (void)setIllumThreshold:(CGFloat)thr ;

/**
 *  质量检测模糊阈值
 *  默认0.5
 */
- (void)setBlurThreshold:(CGFloat)thr ;

/**
 *  姿态检测阈值
 *  默认pitch=12，yaw=12，row=10
 */
- (void)setEulurAngleThrPitch:(float)pitch yaw:(float)yaw roll:(float)roll ;

/**
 * 输出图像个数
 * 默认3
 */
- (void)setMaxCropImageNum:(int)imageNum ;

/**
 * 输出图像宽，设置为有效值(大于0)则对图像进行缩放，否则输出原图抠图结果
 * 默认 480
 */
- (void)setCropFaceSizeWidth:(CGFloat)width ;

/**
 * 输出图像高，设置为有效值(大于0)则对图像进行缩放，否则输出原图抠图结果
 * 默认 680
 */
- (void)setCropFaceSizeHeight:(CGFloat)height ;

/**
 * 输出图像，下巴扩展，大于等于0，0：不进行扩展
 * 默认0.1
 */
- (void)setCropChinExtend:(CGFloat)chinExtend ;

/**
 * 输出图像，额头扩展，大于等于0，0：不进行扩展
 * 默认0.2
 */
- (void)setCropForeheadExtend:(CGFloat)foreheadExtend ;

/**
 * 输出图像，人脸框与背景比例，大于等于1，1：不进行扩展
 * 默认1.5f
 */
- (void)setCropEnlargeRatio:(float)cropEnlargeRatio;

/**
 * 动作超时配置
 */
- (void)setConditionTimeout:(CGFloat)timeout ;

/**
 * 语音间隔提醒配置
 */
- (void)setIntervalOfVoiceRemind:(CGFloat)timeout;

/**
 * 是否开启静默活体，默认false
 */
- (void)setIsCheckSilentLive:(BOOL)isCheck;

/**
 * 口罩检测阈值配置，默认0.8。
 * 大于阈值判定为戴口罩，低于阈值判定为未戴口罩
 */
- (void)setMouthMaskThreshold:(CGFloat)thr ;

/**
 * 设置原始图片缩放比例，默认1不缩放，scale 阈值0~1
 */
- (void)setImageWithScale:(CGFloat)scale;

/**
 * 设置图片加密类型，type=0 基于base64 加密；type=1 基于百度安全算法加密
 */
- (void)setImageEncrypteWithType:(int) type;

3.2.2 FaceSDK 初始化

- (int)initCollect;

参数:

返回：

参考ViewController.m initSDK 方法实现：

- (void) initSDK {
    
    if (![[FaceSDKManager sharedInstance] canWork]){
        NSLog(@"授权失败，请检测ID 和 授权文件是否可用");
        return;
    }
    
    // 初始化SDK配置参数，可使用默认配置
    // 设置最小检测人脸阈值
    [[FaceSDKManager sharedInstance] setMinFaceSize:200];
    // 设置截取人脸图片高
    [[FaceSDKManager sharedInstance] setCropFaceSizeWidth:400];
    // 设置截取人脸图片宽
    [[FaceSDKManager sharedInstance] setCropFaceSizeHeight:640];
    // 设置人脸遮挡阈值
    [[FaceSDKManager sharedInstance] setOccluThreshold:0.5];
    // 设置亮度阈值
    [[FaceSDKManager sharedInstance] setIllumThreshold:40];
    // 设置图像模糊阈值
    [[FaceSDKManager sharedInstance] setBlurThreshold:0.3];
    // 设置头部姿态角度
    [[FaceSDKManager sharedInstance] setEulurAngleThrPitch:10 yaw:10 roll:10];
    // 设置人脸检测精度阈值
    [[FaceSDKManager sharedInstance] setNotFaceThreshold:0.6];
    // 设置抠图的缩放倍数
    [[FaceSDKManager sharedInstance] setCropEnlargeRatio:3.0];
    // 设置照片采集张数
    [[FaceSDKManager sharedInstance] setMaxCropImageNum:6];
    // 设置超时时间
    [[FaceSDKManager sharedInstance] setConditionTimeout:1500];
    // 设置开启口罩检测，非动作活体检测可以采集戴口罩图片
    [[FaceSDKManager sharedInstance] setIsCheckMouthMask:true];
    // 设置开启口罩检测情况下，非动作活体检测口罩过滤阈值，默认0.8 不需要修改
    [[FaceSDKManager sharedInstance] setMouthMaskThreshold:0.8f];
    // 设置原始图缩放比例
    [[FaceSDKManager sharedInstance] setImageWithScale:0.8f];
    // 设置图片加密类型，type=0 基于base64 加密；type=1 基于百度安全算法加密
    [[FaceSDKManager sharedInstance] setImageEncrypteType:0];
    // 初始化SDK功能函数
    [[FaceSDKManager sharedInstance] initCollect];
}

3.2.3 FaceSDK 释放

- (int)uninitCollect

参数:

返回：

3.3 人脸采集

调用IDLFaceDetectionManager类的:

/**
 * 人脸采集，成功之后返回扣图图片，原始图片
 * @param image 镜头拿到的图片
 * @param previewRect 预览的Rect
 * @param detectRect 检测的Rect
 * return completion 回调信息
 */
- (void)detectStratrgyWithNormalImage:(UIImage *)image previewRect:(CGRect)previewRect detectRect:(CGRect)detectRect completionHandler:(DetectStrategyCompletion)completion; 

typedef void (^DetectStrategyCompletion) (FaceInfo * faceinfo,NSDictionary * images, DetectRemindCode remindCode);

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

参数说明：

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

image：相机获取的图片
previewRect：人脸图片大小，间接定义的最大距离的 maxRect 和最小距离的 minRect。
detectRect：人脸检测区域大小，实际采集区域
completion：完成后返回照片和状态结果

参考BDFaceDetectionViewController.m 实现，使用方法如下：

       __weak typeof(self) weakSelf = self;
    [[IDLFaceDetectionManager sharedInstance] detectStratrgyWithNormalImage:image previewRect:self.previewRect detectRect:self.detectRect completionHandler:^(FaceInfo *faceinfo, NSDictionary *images, DetectRemindCode remindCode) {
         switch (remindCode) {
            case DetectRemindCodeOK: {
                weakSelf.hasFinished = YES;
                [self warningStatus:CommonStatus warning:@"非常好"];
                if (images[@"image"] != nil && [images[@"image"] count] != 0) {
                    
                    NSArray *imageArr = images[@"image"];
                    for (FaceCropImageInfo * image in imageArr) {
                        NSLog(@"cropImageWithBlack %f %f", image.cropImageWithBlack.size.height, image.cropImageWithBlack.size.width);
                        NSLog(@"originalImage %f %f", image.originalImage.size.height, image.originalImage.size.width);
                    }

                    FaceCropImageInfo * bestImage = imageArr[0];
                    [[BDFaceImageShow sharedInstance] setSuccessImage:bestImage.originalImage];
                    [[BDFaceImageShow sharedInstance] setSilentliveScore:bestImage.silentliveScore];                   
                    // 公安验证接口测试
                    [self request:bestImage.cropImageWithBlackEncryptStr];                   
                    dispatch_async(dispatch_get_main_queue(), ^{
                        UIViewController* fatherViewController = weakSelf.presentingViewController;
                        [weakSelf dismissViewControllerAnimated:YES completion:^{
                            BDFaceSuccessViewController *avc = [[BDFaceSuccessViewController alloc] init];
                            
                            [fatherViewController presentViewController:avc animated:YES completion:nil];
                        }];
                        
                    });
                }
                [self singleActionSuccess:true];
                break;

3.4 动作采集

调用IDLFaceLivenessManager类的:

/**
 *  人脸活体验证，成功之后扣图图片，原始图片三种
 * @param image 镜头拿到的图片
 * @param previewRect 预览的Rect
 * @param detectRect 检测的Rect
 * return completion 回调信息
 */
-(void) livenessNormalWithImage:(UIImage *)image previewRect:(CGRect)previewRect detectRect:(CGRect)detectRect completionHandler:(LivenessNormalCompletion)completion;

typedef void (^LivenessNormalCompletion) (NSDictionary * images, FaceInfo *faceInfo, LivenessRemindCode remindCode);

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

参数说明：

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

image：相机获取的图片
previewRect：人脸图片大小，间接定义的最大距离的 maxRect 和最小距离的 minRect。
detectRect：人脸检测区域大小，实际采集区域
completion：完成后返回照片和状态结果

说明：

检测图片中的人脸信息，完成人脸图像采集和人脸活体检测，返回检测状态和结果。

    [[IDLFaceLivenessManager sharedInstance] livenessNormalWithImage:image previewRect:self.previewRect detectRect:self.detectRect completionHandler:^(NSDictionary *images, FaceInfo *faceInfo, LivenessRemindCode remindCode) {
        
        switch (remindCode) {
            case LivenessRemindCodeOK: {
                weakSelf.hasFinished = YES;
                [self warningStatus:CommonStatus warning:@"非常好"];
                if (images[@"image"] != nil && [images[@"image"] count] != 0) {
                    
                    NSArray *imageArr = images[@"image"];
                    for (FaceCropImageInfo * image in imageArr) {
                        NSLog(@"cropImageWithBlack %f %f", image.cropImageWithBlack.size.height, image.cropImageWithBlack.size.width);
                        NSLog(@"originalImage %f %f", image.originalImage.size.height, image.originalImage.size.width);
                    }

                    FaceCropImageInfo * bestImage = imageArr[0];

3.5 活体动作设置

调用IDLFaceLivenessManager类的:

- (void)livenesswithList:(NSArray *)array order:(BOOL)ordernumberOfLiveness:(NSInteger)numberOfLiveness

参数：

array: 活体动作列表
order: 是否按顺序进行活体动作
numberOfLiveness: 活体动作数目（array为nil是起作用）

返回：

说明：

活体动作设置

4、常见问题

Q：鉴权问题。提示「验证失败」 A：先确定网络情况是否正常，本地鉴权文件失效了才走网络鉴权。定位错误码，排查鉴权失败的原因。一般是 licenseID 和 bundleID 配置不一致导致的鉴权失败。请注意上线前授权文件一定要更新。

Q：license 文件失效了，不能用了怎么办？ A：License 文件申请时候有期限，如过期会导致校验失效，需要在后台进行申请延期。

Q：使用 iOS 采集端，采集到的图片是斜着的，这个正常吗，会影响识别吗？ A：不会影响识别。有黑边和倾斜是因为图片质量算法造成的，我们是按 1:3 对图像进行背景填充使人脸居中，为的是更好的识别图像。这个版本提供了detectStratrgyWithQualityControlImage和detectStratrgyWithNormalImage两种方法供选择。

更多问题请点击 [常见问题](

Android SDK4.0

V3.3.0.0版本