Android-SDK4.0
所有文档

          人脸识别

          Android-SDK4.0

          Android端人脸采集SDK4.0使用文档(4.6.0.5)

          目录

          1 简介	
            1.1 功能介绍	
            1.2 兼容性	
            1.3 开发包说明	
          2 集成指南	
            2.1 Sample示例	
            2.2 准备工作	
              2.2.1 申请license
              2.2.2 下载SDK	
            2.3 运行示例工程	
              2.3.1 运行自动配置授权信息的示例工程	
              2.3.2 运行未配置授权信息的示例工程	
            2.4添加SDK到工程	
            2.5权限声明	
          3 功能使用	
            3.1 活体识别	
            3.2人脸采集	
            3.3质量校验设置	
            3.4 界面定制说明	
              3.4.1 修改faceplatform_ui界面	
          4 接口设计说明	
            4.1人脸功能管理器	
              4.1.1 创建实例	
              4.1.2人脸功能管理器初始化	
              4.1.3设置人脸功能控制参数	
              4.1.4取得人脸图像采集功能接口	
              4.1.5取得活体检测功能接口	
            4.2人脸图像采集器	
              4.2.1设置人脸图像采集功能参数	
              4.2.2人脸图像采集	
            4.3活体检测器	
              4.3.1设置人脸功能控制参数	
              4.3.2活体检测	
            4.4人脸图像采集界面
            4.5 活体检测界面
          5 常见问题	

          1、简介

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

          1.1 功能介绍

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

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

            建议搭配线上的在线活体检测接口配合使用,在本地做动作活体检测,云端进行视频翻拍、模型攻击以及合成图攻击的二次校验

          • 本地版人脸质量检测:判断视频流中的图片帧中,哪些图片质量较佳,即人脸图像特征清晰(满足角度、姿态、光照、模糊度等校验)。
          • 本地版人脸图像采集:通过本地SDK能力,采集人脸图像,同时经过人脸质量检测,确保采集到的人脸图像符合各条件校验(角度、姿态、光照、模糊度等),为设备前端获取有效可分析人脸的主要功能。
          • 离线授权:SDK的授权判断,授权介质也称为license,在SDK使用中,需要通过license向授权服务器发起请求,判断SDK的使用合法性及使用有效期。

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

          业务流程


          1.2 兼容性

          系统:支持 Android 4.0.3(API Level 15)及以上系统。需要开发者通过 minSdkVersion来保证支持系统的检测。

          机型:手机,平板暂不支持

          构架:支持 CPU架构平台【arm-v7,arm-64,x86】

          网络:支持 WIFI 及移动网络,移动网络支持使用NET 网关及 WAP 网关(CMWAP、CTWAP、UNIWAP、3GWAP)。


          1.3 开发包说明

          文件/文件夹名 说明
          /faceplatform-release SDK lib 库相关代码的 aar
          /faceplatform-ui SDK的UI库,封装拍照裁剪等功能,以及各平台的so库。so包含以下几个平台如果关注包大小,请自行删减。/armeabi-v7a/arm64-v8a/x86,
          /app DEMO工程

          2、集成指南

          本章将进行 Step-By-Step的讲解,如何快速的集成 人脸Sdk到现有应用中。一个完整的Demo 请参考开发包中的示例程序 FacePlatform。方案架构参考下图:

          方案架构


          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.3.1 运行自动配置授权信息的示例工程

          该下载的示例工程,已经帮你改好了license和包名

          • Android Studio导入下载的示例工程
          • 配置打包签名文件,由于SDK运行时会校验签名文件的MD5是否和申请时填入一样。为了便于debug能正常使用SDK,需要配置打包签名文件。
          • 运行示例工程

          2.3.2 运行未配置授权信息的示例工程

          (1)Android Studio导入下载的示例工程

          (2)下载license拷贝到工程的assets目录

          image

          image

          (3)修改Config类

          image

          image

          (4)修改app.gradle和AndroidManifest里面的包名为申请license填入的包名,如上图安卓包名。

          image

          image

          (5)配置打包签名文件,由于SDK运行时会校验签名文件的MD5是否和申请时填入一样。为了便于debug能正常使用SDK,需要配置打包签名文件。

          image

          image

          (6)运行示例工程。如果无法正常体验,请查看logcat日志。是否有 FaceSDK-License LICENSE_INFO_CHECK_ERROR日志。如果有说明授权没有成功,可以查看本文档最后的常见问题进行解决。

          2.4 添加SDK到工程

          FaceSdk以androidstudio开发方式提供,以下介绍在android studio开发工具导入FaceSdk

          (1)将开发包中的faceplatform-release库Copy 到工程根目录。

          img

          (2)将开发包中的faceplatform-ui库Copy 到工程根目录。

          (3)SDK提供的了开源的faceplatform-ui库,把活体检测和人脸图像采集功能等功能进行了封装,适配了主流机型机型。如果需要使用,请添加faceplatform-ui模块到的工程中。faceplatform-ui目录结构如下图

          img

          (4)在build.gradle使用compile project引人faceplatform-ui库工程。

          img

          (5)Setting.gradle中include faceplatfrom-ui和facepaltfrom-release

          img

          (6)从官网下载授权文件license,复制到app/src/main/assets目录下。

          (7)申请的license已经和打包签名key进行了绑定(申请时用到了签名的md5,为了便于debug模式也能调用SDK的功能,需要把debug的key改成申请license的key。

          • 把key拷贝到项目根目录下
          • 主appbuild.gradle android 下面添加(修改)signingConfigs相关的配置。如下图。

          img


          2.5 权限声明

          名称 用途
          android.permission.INTERNET 允许应用联网,SDK联网授权。
          android.permission.READ_PHONE_STATE 获取用户手机的 IMEI,用来唯一的标识用户
          android.permission.CAMERA 允许调用相机进行拍照
          android.hardware.camera.autofocus 允许相机对焦
          android.permission.WRITE_EXTERNAL_STORAGE 图片裁剪临时存储
          android.permission.INTERNET 允许访问网络
          android.permission.WRITE_SETTINGS 允许修改系统设置

          3、功能使用

          3.1 人脸采集(包含动作活体)

          (1)初始化SDK 调用FaceSDKManager.getIntance().initialize(Context context, String licenseID, String licenseFileName, IInitCallback callback); Demo中此段代码在HomeActivity中。

          (2)初始化参数设置

                  FaceConfig config = FaceSDKManager.getInstance()
          	        .getFaceConfig();
                  // 设置可检测的最小人脸阈值
                  config.setMinFaceSize(FaceEnvironment.VALUE_MIN_FACE_SIZE);
                  // 设置可检测到人脸的阈值
                  config.setNotFaceValue(FaceEnvironment.VALUE_NOT_FACE_THRESHOLD);
                  // 设置模糊度阈值
                  config.setBlurnessValue(FaceEnvironment.VALUE_BLURNESS);
                  // 设置光照阈值(范围0-255)
                  config.setBrightnessValue(FaceEnvironment.VALUE_BRIGHTNESS);
                  // 设置遮挡阈值
                  config.setOcclusionValue(FaceEnvironment.VALUE_OCCLUSION);
                  // 设置人脸姿态角阈值
                  config.setHeadPitchValue(FaceEnvironment.VALUE_HEAD_PITCH);
                  config.setHeadYawValue(FaceEnvironment.VALUE_HEAD_YAW);
                  // 设置闭眼阈值
                  config.setEyeClosedValue(FaceEnvironment.VALUE_CLOSE_EYES);
                  // 设置图片缓存数量
                  config.setCacheImageNum(FaceEnvironment.VALUE_CACHE_IMAGE_NUM);
                  // 设置活体动作,通过设置list,LivenessTypeEunm.Eye, LivenessTypeEunm.Mouth,
                  // LivenessTypeEunm.HeadUp, LivenessTypeEunm.HeadDown, LivenessTypeEunm.HeadLeft,
                  // LivenessTypeEunm.HeadRight, LivenessTypeEunm.HeadLeftOrRight
                  config.setLivenessTypeList(ExampleApplication.livenessList);
                  // 设置动作活体是否随机
                  config.setLivenessRandom(ExampleApplication.isLivenessRandom);
                  // 设置开启提示音
                  config.setSound(ExampleApplication.isOpenSound);
          	// 原图缩放系数
                  config.setScale(FaceEnvironment.VALUE_SCALE);
                  // 抠图高的设定,为了保证好的抠图效果,我们要求高宽比是4:3,所以会在内部进行计算,只需要传入高即可
                  config.setCropHeight(FaceEnvironment.VALUE_CROP_HEIGHT);
                  // 加密类型,0:Base64加密,上传时image_sec传false;1:百度加密文件加密,上传时image_sec传true
                  config.setSecType(FaceEnvironment.VALUE_SEC_TYPE);
                  FaceSDKManager.getInstance().setFaceConfig(config);

          关于抠图内部实现方案如下图所示: img

          (3) startActivity(new Intent(this, FaceLivenessExpActivity.class)),开启预览。

          (4)调用FaceSDKManager.getInstance().getLivenessStrategyModule()获得ILivenessStrategy对象。(该方法每次调用都会返回一个新对象).

          (6)调用ILivenessStrategy.setPreviewDegree();设置预览图片的旋转角度。调用setDetectStrategySoundEnable设置是否开启语音。调用setDetectStrategyConfig设置,预览图的大小,人脸检测框的坐标和回调。

          (7)多次调用livenessStrategy进行人脸图片采集,人脸跟踪、质量检测、动作活体检测。

          (8)实现ILivenessStrategyCallback的onLivenessCompletion并处理结果。其中base64ImageCropMap为存放最佳人脸抠图图片,base64ImageSrcMap为存放最佳人脸原图图片可以查看起父类FaceLivenessActivity的saveImage和base64ToImage方法,获取对于的bitamap。

          img

          (9)Demo中针对最优抠图或者最优原图,都会调用SecRequest类下的sendMessage(Context, String secBase64);方法将加密后的base64发送到服务端。

          3.2 人脸采集(不包含动作活体)

          (1)调用FaceSDKManager.getIntance().initialize(context,Config.licenseID, Config.licenseFileName, IInitCallback callback);初始化SDK.。

          (2)初始化SDK参数

          	     FaceConfig config = FaceSDKManager.getInstance()
          			.getFaceConfig();
                  // 设置可检测的最小人脸阈值
                  config.setMinFaceSize(FaceEnvironment.VALUE_MIN_FACE_SIZE);
                  // 设置可检测到人脸的阈值
                  config.setNotFaceValue(FaceEnvironment.VALUE_NOT_FACE_THRESHOLD);
                  // 设置模糊度阈值
                  config.setBlurnessValue(FaceEnvironment.VALUE_BLURNESS);
                  // 设置光照阈值(范围0-255)
                  config.setBrightnessValue(FaceEnvironment.VALUE_BRIGHTNESS);
                  // 设置遮挡阈值
                  config.setOcclusionValue(FaceEnvironment.VALUE_OCCLUSION);
                  // 设置人脸姿态角阈值
                  config.setHeadPitchValue(FaceEnvironment.VALUE_HEAD_PITCH);
                  config.setHeadYawValue(FaceEnvironment.VALUE_HEAD_YAW);
                  // 设置闭眼阈值
                  config.setEyeClosedValue(FaceEnvironment.VALUE_CLOSE_EYES);
                  // 设置图片缓存数量
                  config.setCacheImageNum(FaceEnvironment.VALUE_CACHE_IMAGE_NUM);
                  // 设置活体动作,通过设置list,LivenessTypeEunm.Eye, LivenessTypeEunm.Mouth,
                  // LivenessTypeEunm.HeadUp, LivenessTypeEunm.HeadDown, LivenessTypeEunm.HeadLeft,
                  // LivenessTypeEunm.HeadRight, LivenessTypeEunm.HeadLeftOrRight
                  config.setLivenessTypeList(ExampleApplication.livenessList);
                  // 设置动作活体是否随机
                  config.setLivenessRandom(ExampleApplication.isLivenessRandom);
                  // 设置开启提示音
                  config.setSound(ExampleApplication.isOpenSound);
                  // 原图缩放系数
                  config.setScale(FaceEnvironment.VALUE_SCALE);
                  // 抠图高的设定,为了保证好的抠图效果,我们要求高宽比是4:3,所以会在内部进行计算,只需要传入高即可
                  config.setCropHeight(FaceEnvironment.VALUE_CROP_HEIGHT);
                  // 加密类型,0:Base64加密,上传时image_sec传false;1:百度加密文件加密,上传时image_sec传true
                  config.setSecType(FaceEnvironment.VALUE_SEC_TYPE);
                  FaceSDKManager.getInstance().setFaceConfig(config);

          (3)startActivity(new Intent(this, FaceDetectExpActivity.class)),开启预览。

          (4)调用FaceSDKManager.getInstance().getDetectStrategyModule()获得IDetectStrategy对象。(该方法每次调用都会返回一个新对象).

          (5)调用IDetectStrategy.setPreviewDegree();设置预览图片的旋转角度。调用setDetectStrategySoundEnable设置是否开启语音。调用setDetectStrategyConfig设置,预览图的大小,人脸检测框的坐标和回调。

          (6) 多次调用detectStrategy进行人脸图片采集。(不带动作活体中支持口罩检测,当口罩分值大于0.7时便认为戴口罩,这时将不会进行遮挡检测)

          (7) 实现IDetectStrategyCallback的onDetectCompletion并处理结果。其中base64ImageCropMap为存放最佳抠图人脸,base64ImageSrcMap为存放最佳原图人脸。可以查看起父类FaceDetectActivity的saveImage和base64ToImage方法,获取对于的bitmap。

          img

          (8)Demo中针对最优抠图或者最优原图,都会调用SecRequest类下的sendMessage(Context, String secBase64);方法将加密后的base64发送到服务端。

          3.3 质量校验设置

          com.baidu.idl.face.platform.FaceConfig类用于人脸检测参数设置。

          参数 名称 默认值 取值范围
          minFaceSize 最小人脸阈值 200
          notFaceValue 非人脸阈值 0.6f 0~1.0f
          brightnessValue 图片光照阈值 82f 0-255f
          blurnessValue 图像模糊阈值 0.3f 0~1.0f
          occlusionValue 人脸遮挡阀值 0.5f 0~1.0f
          headPitchValue 低头抬头角度 9 0~45
          headYawValue 左右摇头角度 9 0~45
          eyeClosedValue 闭眼阈值 0.7f 0~1.0f
          cacheImageNum 图片缓存数量(非动作活体使用) 3

          3.4 界面定制说明

          3.4.1 修改faceplatform_ui界面

          (1)如果SDK自带的UI和您的APP不统一,您可以自行修改FaceDetectRoundView。

          img

          (2)修改提示语音音频文件,有两种方式。

          a、直接替换FaceUI工程raw下的mp3文件和string.xml。

          b、FaceEnvironment 提供了setSoundId(FaceStatusNewEnum status, int soundId); 设置提示音资源。 FaceStatusNewEnum为不同的状态。soundId为资源文件所对应的resource id。


          4、接口设计说明#

          4.1 人脸功能管理器

          4.1.1创建实例

          • 方法

            FaceSDKManager getInstance()
          • 参数

          • 返回

            人脸功能管理器

          • 说明

            创建人脸功能管理器

          4.1.2 人脸功能管理器初始化

          • 方法

            public void initialize(final Context context, String licenseID, StringlicenseFileName, IInitCallback callback)
          • 参数

            context 上下文环境,licenseID 传入申请License时获取的应用名称+_face_android后缀,licenseFileName 鉴权文件名称, callback 鉴权成功与否回调

          • 返回

          • 说明

            初始化人脸检测功能。进行人脸检测功能License鉴权验证。

          4.1.3 设置人脸功能控制参数

          • 方法

            void setFaceConfig(FaceConfig config)   
          • 参数

            config 人脸功能控制参数对象

          • 返回

          • 说明

            设置人脸功能控制参数对象。

            FaceConfig对象参数:

            光照阀值

            图像模糊阀值

            人脸遮挡阀值

            头部姿态角度

            最小人脸检测阀值

            人脸检测精度阀值

            截取人脸图片大小

            进行活体检测的动作类型列表

            是否进行人脸图片质量检测

          4.1.4 取得人脸图像采集功能接口

          • 方法

             IDetectStrategy getDetectStrategyModule()
          • 参数

          • 返回

            人脸图像采集功能接口

          • 说明

            取得人脸图像采集功能接口。人脸图像采集接口完成,解析图片人脸信息,返回检测结果。

          4.1.5 取得活体检测功能接口

          • 方法
          • ILivenessStrategy getLivenessStrategyModule()
          • 参数

          • 返回

            活体检测功能接口

          • 说明

            取得活体检测功能接口。活体检测功能接口完成,解析图片人脸信息,返回活体检测结果。

          4.1.6 内存释放接口

          • 方法

            void release()
          • 参数

          • 返回

          • 说明

            主要针对模型的释放,以减少内存

          4.2 人脸图像采集器

          人脸图像采集器IDetectStrategy,检测图片中人脸信息,返回人脸检测状态,完成人脸图像采集。

          4.2.1 设置人脸图像采集功能参数

          • 方法

            void setDetectStrategyConfig(Rect previewRect, Rect detectRect,IDetectStrategyCallback callback)
          • 参数

            previewRect 人脸图片大小,类型:Rect

            detectRect 人脸检测区域大小,类型:Rect

            callback 人脸图像采集功能状态监听器

          • 返回

          • 说明

            设置人脸功能控制参数对象。

          4.2.2 人脸图像采集

          • 方法

            void detectStrategy(byte[] imageData)
          • 参数

            imageData 图片信息

          • 返回 无
          • 说明

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

          4.3 活体检测器

          活体检测器LivenessStrategy,检测图片人脸信息,活体检测结果状态。

          4.3.1 设置人脸功能控制参数

          • 方法

            voidsetLivenessStrategyConfig(
            
                 List<LivenessTypeEnum> livenessList, 
            
                 Rect previewRect, 
            
                 Rect detectRect, 
            
                 ILivenessStrategyCallback callback);
          • 参数

            livenessList 活体动作列表

            previewRect 人脸图片大小,类型:Rect

            detectRect 人脸检测区域大小,类型:Rect

            callback 人脸图像采集功能状态监听器

          • 返回

          • 说明

            设置活体检测功能参数对象。

          4.3.2 活体检测

          • 方法

            void livenessStrategy(byte[] imageData);
          • 参数

            imageData 图片信息

          • 返回

          • 说明

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

          4.4 人脸图像采集界面

          人脸图像采集器界面FaceDetectActivity,包括UI界面,系统相机控制,使用人脸图像采集器IDetectStrategy处理相机采集到的图像。

          4.5 活体检测界面

          活体检测界面FaceLivenessActivity,包括UI界面,系统相机控制,使用活体检测器ILivenessStrategy处理相机采集到的图像,完成活体检测功能。

          4.6 图片加密请求类

          图片加密请求类SecRequest,里面的sendMessage方法是为了测试图片加密之后secBase64是否可以通过云端解密的一个示例代码

          5、常见问题

          (1)license文件有什么用,该放在什么地方?

          license文件需要申请,目的是作为sdk校验开发者的使用合法性,license文件放置位置不对或未放置license文件会导致没法使用sdk,一般应先申请license文件,并把申请得到的license文件,放置在assets目录下面。

          (2)FaceSDK-LicenseLICENSE_INFO_CHECK_ERROR =license id

          licenseID为您申请时填appname+“_face_android”。如下图demo-turnstile-face-android为license里面的licenseID, demo-turnstile-face-android1为app运行时Config.licenseID,两者必须一致

          img

          (3)FaceSDK-LicenseLICENSE_INFO_CHECK_ERROR =signature md5

          md5不一致错误,签名的为license里面的md5,后面的为app运行时获取的签名文件的md5,这两个md5必须一致且区分大小写。img

          (4)FaceSDK-License LICENSE_INFO_CHECK_ERROR =package name

          PackageName不一致错误。License里面的packagename为申请license时填的,需要保证和app里面的packagename一致。

          (5)活体检测常见有那些动作?是否可配置?

          常见有7个动作,眨眼、张嘴、左摇头,右摇头,摇摇头、向上抬头,向下低头。 sdk提供FaceConfig参数设置类,如活体检测角度、光线,检测动作,检测动作数量等设置。

          (6)使用sdk一般会用到活体检测拍照等功能,有什么需要注意?

          Android 6.0+,需要注意相机拍摄权限问题。如没申请权限,可能导致没法调起相机。

          (7)在有些机型上出现特别卡或出现无响应?

          SDK在armeabi上性能非常差,建议删掉其他so只留下armeabi-v7a,包括使用的其他第三方so。因为如果其他so有armeabi,根据android系统查找so的逻辑,在armeabi的机型上只会去该目录下查找so,而人脸SDK没有,就会出现找不到so。

          (8)license 文件失效了,不能用了怎么办?

          license文件申请时候有期限,如过期会导致校验失效,需要在后台申请延期。

          上一篇
          REST API SDK-v2
          下一篇
          IOS-SDK4.0版