IOS-1.0
1.简介
1.1 功能介绍
百度Face SDK IOS 版是一种面向 IOS 移动设备人脸技术开发包,此版SDK包含人脸检测、活体识别等功能。基于该方案,开发者可以轻松的构建包含人脸检测、采集和活体识别的应用。在您使用SDK之前,我们首先为您介绍以下SDK本身及相关人脸能力,以便您能更方便使用人脸服务。
此版SDK所包含的能力如下:
- 离线炫瞳活体检测:通过屏幕上闪烁不同颜色的光线,判断当前用户是否真人操作。通过颜色活体进行面部反光鉴别的同时,百度特加入独有的瞳孔反光识别,提升整体的攻击拒绝率指标,可有效抵御高清图片、3D建模、视频等攻击。
- 端云互验加密:在采集SDK端加入端云互验加密功能,在采集SDK端对数据进行加密,云端进行解密,从而可以有效识别第三方非法黑产通过绕过APP用脚本攻击接口的行为发生。
- 大数据风控:与百度安全实验室联合推出大数据风控功能,与云端接口配合对设备端进行环境校验,可有效识别ROM注入、视频劫持、云手机等行为。
- 离线人脸质量检测:判断视频流中的图片帧中,哪些图片质量较佳,即人脸图像特征清晰(满足姿态角、光照、模糊度、遮挡等校验)。
- 离线人脸图像采集:通过本地SDK能力,采集人脸图像,同时经过人脸质量检测,确保采集到的人脸图像符合各条件校验(满足姿态角、光照、模糊度、遮挡等校验),为设备前端获取有效可分析人脸的主要功能。
- 离线授权:SDK的授权判断,授权介质也称为license,在SDK使用中,优先验证本地离线鉴权文件,验证通过可离线使用;在本地鉴权失败情况下需要向授权服务器发起请求,远程拉取授权进行验证。
为了方便您的开发,我们已经为您准备了多种场景的示例工程,您可以根据业务需要,在后台进行直接下载,目前支持【人脸核身】【人脸闸机/门禁】【人脸登录/考勤】【多人脸识别】,示例工程参考下图:
1.2 兼容性
- 系统:支持iOS9以上系统。需要开发者通过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;
/**
* 口罩检测阈值配置,默认0.8。
* 大于阈值判定为戴口罩,低于阈值判定为未戴口罩
*/
- (void)setMouthMaskThreshold:(CGFloat)thr ;
/**
* 设置原始图片缩放比例,默认1不缩放,scale 阈值0~1
*/
- (void)setImageWithScale:(CGFloat)scale;
/**
* 设置图片加密类型,type=0 非加密原图base64 ;type=1 基于百度安全算法加密
*/
- (void)setImageEncrypteWithType:(int) type;
/**
* 人脸过远框比例 默认:0.4
*/
- (void)setMinRect:(float) minRectScale;
/**
* 活体检测阈值 默认:0.8
*/
- (void)setliveThresholdValue:(float) liveThresholdValue;
/**
* 视频录制能力 默认:关闭
*/
- (void)setRecordAbility:(BOOL) recordAbility;
/**
* 炫彩颜色判断能力 默认:关闭
*/
- (void)setColorJudgeAbility:(BOOL) colorJudgeAbility;
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] setIsCheckMouthMask:true];
// 设置开启口罩检测情况下,非动作活体检测口罩过滤阈值,默认0.8 不需要修改
[[FaceSDKManager sharedInstance] setMouthMaskThreshold:0.8f];
// 设置原始图缩放比例
[[FaceSDKManager sharedInstance] setImageWithScale:0.8f];
// 设置图片加密类型,type=0 非加密原图base64 ;type=1 基于百度安全算法加密
[[FaceSDKManager sharedInstance] setImageEncrypteType:0];
// 设置人脸过远框比例
[[FaceSDKManager sharedInstance] setMinRect:0.4];
// 活体检测阈值
[[FaceSDKManager sharedInstance] setliveThresholdValue:0.8];
//视频录制能力
[[FaceSDKManager sharedInstance] setRecordAbility:NO];
//炫彩颜色判断能力
[[FaceSDKManager sharedInstance] setColorJudgeAbility:NO];
// 初始化SDK功能函数
[[FaceSDKManager sharedInstance] initCollect];
}
3.2.3 FaceSDK 释放
- (int)uninitCollect
3.3 炫瞳活体采集
调用IDLFaceColorfulManager类的:
/**
* 人脸采集,成功之后返回扣图图片,原始图片
* @param image 镜头拿到的图片
* @param detectRect 预览的Rect
* @param previewRect 检测的Rect
* @param colorQuality 炫彩当前颜色是否通过质量检测
* return completion 回调信息
*/
- (void)colorStratrgyWithNormalImage:(UIImage *)image previewRect:(CGRect)previewRect detectRect:(CGRect)detectRect isColorQuality:(BOOL)colorQuality completionHandler:(ColorStrategyCompletion)completion;
温馨提示:NSDictionary * images 返回FaceCropImageInfo 对象包含带黑边的图片,主要是为了配合在线 API 方式的活体检测使用,本地算法会对图片做一定的预处理操作;而不带黑边的图片,如果无需使用活体,则可使用不带黑边的图片采集方式。
参数说明:
previewRect
与detctRect
是为了做距离检测而定义的,为了在上层封装判断脸是否在框内/离太远/离太近。
- image:相机获取的图片
- previewRect:人脸图片大小,间接定义的最大距离的 maxRect 和最小距离的 minRect。
- detectRect:人脸检测区域大小,实际采集区域
- completion:完成后返回照片和状态结果
参考BDFaceColorfulViewController 实现,使用方法如下:
[[IDLFaceColorfulManager sharedInstance] colorStratrgyWithNormalImage:image previewRect:weakSelf.previewRect detectRect:weakSelf.detectRect isColorQuality:(BOOL)weakSelf.colorQuality completionHandler:^(FaceInfo *faceinfo, NSDictionary *images, ColorRemindCode remindCode){
switch (remindCode) {
case ColorRemindCodeOK: {
[weakSelf 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 ZID参数获取
调用金融级实名认证接口配合金融级SDK使用时,需传入zid参数打开大数据风控功能。
获取方法:
[[FaceSDKManager sharedInstance] getZtoken]
4.常见问题
Q:鉴权问题。提示「验证失败」 A:先确定网络情况是否正常,本地鉴权文件失效了才走网络鉴权。定位错误码,排查鉴权失败的原因。一般是 licenseID 和 bundleID 配置不一致导致的鉴权失败。请注意上线前授权文件一定要更新。
Q:license 文件失效了,不能用了怎么办? A:License 文件申请时候有期限,如过期会导致校验失效,需要在后台进行申请延期。
Q:使用 iOS 采集端,采集到的图片是斜着的,这个正常吗,会影响识别吗?
A:不会影响识别。有黑边和倾斜是因为图片质量算法造成的,我们是按 1:3 对图像进行背景填充使人脸居中,为的是更好的识别图像。这个版本提供了detectStratrgyWithQualityControlImage
和detectStratrgyWithNormalImage
两种方法供选择。
Q:鉴权初始化的错误码对应的信息 A: | ErrorCode | 常量值 | 说明 | | -------------------------------- | ------ | ---------------------------- | | SUCCESS | 0 | 成功 | | LICENSE_NOT_INIT_ERROR | 1 | license未初始化 | | LICENSE_DECRYPT_ERROR | 2 | license数据解密失败 | | LICENSE_INFO_FORMAT_ERROR | 3 | license数据格式错误 | | LICENSE_KEY_CHECK_ERROR | 4 | license-key(api-key)校验错误 | | LICENSE_ALGORITHM_CHECK_ERROR | 5 | 算法ID校验错误 | | LICENSE_MD5_CHECK_ERROR | 6 | MD5校验错误 | | LICENSE_DEVICE_ID_CHECK_ERROR | 7 | 设备ID校验错误 | | LICENSE_PACKAGE_NAME_CHECK_ERROR | 8 | 包名(应用名)校验错误 | | LICENSE_EXPIRED_TIME_CHECK_ERROR | 9 | 过期时间不正确 | | LICENSE_FUNCTION_CHECK_ERROR | 10 | 功能未授权 | | LICENSE_TIME_EXPIRED | 11 | 授权已过期 | | LICENSE_LOCAL_FILE_ERROR | 12 | 本地文件读取失败 | | LICENSE_REMOTE_DATA_ERROR | 13 | 远程数据拉取失败 | | LICENSE_LOCAL_TIME_ERROR | 14 | 本地时间校验错误 | | OTHER_ERROR | 0xff | 其他错误 |
更多问题请点击 常见问题