IOS-SDK4.1.5

更新时间：2023-06-29

如果您的需求是与人脸比对、人脸实名认证、在线图片活体检测API搭配使用，请创建APP方案获取最新5.2版本SDK及示例工程。

1.简介

1.1 功能介绍

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

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

离线动作活体检测：通过让用户做出指定人脸配合式的交互动作，识别当前操作者是否为活体，此功能为离线使用，可设定指定动作是否使用及应用顺序。动作包含：眨眼、张嘴、左摇头，右摇头，向上抬头，向下低头六个。可有效抵御高清图片、3D建模、视频等攻击。
离线人脸质量检测：判断视频流中的图片帧中，哪些图片质量较佳，即人脸图像特征清晰（满足遮挡、姿态、光照、模糊度等校验）。
离线人脸图像采集：通过本地SDK能力，采集人脸图像，同时经过人脸质量检测，确保采集到的人脸图像符合各条件校验（遮挡、姿态、光照、模糊度等），为设备前端获取有效可分析人脸的主要功能。

离线授权：SDK的授权判断，授权介质也称为license，在SDK使用中，优先验证本地离线鉴权文件，验证通过可离线使用；在本地鉴权失败情况下需要向授权服务器发起请求，远程拉取授权进行验证。

1.2 兼容性

系统：支持iOS11以上系统。需要开发者通过Deployment Target 来保证支持系统的检测。
机型：手机和平板皆可（暂不支持横屏）
架构：arm64、armv7
网络：支持 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，上面创建应用为了使用人脸在线接口，如注册、识别等）

把脸移入框内

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

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;

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

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

/**
 *  人脸过远框比例 默认：0.4
 */
- (void)setMinRect:(float) minRectScale;

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:480];
    // 设置截取人脸图片宽
    [[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:2.5];
    // 设置照片采集张数
    [[FaceSDKManager sharedInstance] setMaxCropImageNum:3];
    // 设置超时时间
    [[FaceSDKManager sharedInstance] setConditionTimeout:1500];
    // 设置原始图缩放比例
    [[FaceSDKManager sharedInstance] setImageWithScale:0.8f];
    // 设置图片加密类型，type=0 基于base64 加密；type=1 基于百度安全算法加密
    [[FaceSDKManager sharedInstance] setImageEncrypteType:0];
    // 设置人脸过远框比例
    [[FaceSDKManager sharedInstance] setMinRect:0.4];
    // 初始化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：人脸图片大小(下图黄色框)
detectRect：人脸检测区域大小，实际采集区域，间接定义的最大距离的 maxRect 和最小距离的 minRect。（下图蓝色框）
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.1.5

SDK合规使用指南