WIN-C++-SDK
版本日志
- 全方面兼容Windows全系统平台,支持win7/win10/XP系统,同时兼容X32、X64系统,深度适配X32系统工控机「赛扬」J1900、「奔腾」G4400等旧设备CPU,已推出C++/C#/Java多语言版本
- 此页面仅把C++语言版本作为示例,若需获取C#、Java版本SDK及相关技术文档,请登陆百度智能云控制台
- Windows 版本SDK官网介绍:点击跳转
- Windows 版本SDK常见问题:点击跳转
备注:由于部分Windows设备机型较旧、性能较弱,全流程耗时会增加
版本 | 日期 | 更新说明 |
---|---|---|
v8.2 | 2022.12.20 | 1. 优化多线程 2. 删除facebox中的无用姿态角angle 3. 对容易引发内存泄漏的示例做说明,引导客户注意使用 4. 更新授权库,支持多网卡按顺序排序读取 |
v8.1 | 2022.06.21 | 1. 模型升级最新8.0版本,并基于8.0增加业务层二次开发接口 2. 提升对儿童、老人、外国人和戴口罩场景的识别准确率,优化活体算法对复杂光线泛化性 |
v6.3 | 2021.12.28 | 1. 依赖库拆减、使sdk主库不依赖镜头模组库,镜头模组库需要时候单独添加; 2. sdk自动授权激活; 3. 新增设备指纹接口; 4. 人脸库优化,支持中文路径、用户信息支持中文参数,人脸图片入库等; 5. 模型可根据需要删减、模型能力可定制化设置; 6. 新增特征值多端对齐示例代码。 |
v6.2 | 2021.12.07 | 基于6.1业务层接口,开发带UI界面(QT编译)demo。 |
v6.1 | 2021.08.25 | 基于V6.0版本增加如下业务层二次开发接口,帮助客户快速集成上手 一、人脸检测跟踪接口(传入opencv转换的mat) 1. 人脸检测track 2. 人脸跟踪detect 二、人脸管理接口 (传入opencv转换的mat) 1. 人脸注册接口 2. 人脸更新接口 3. 人脸删除接口 4. 用户删除接口 5. 创建用户组接口 6. 用户组删除 7. 用户信息查询接口 8. 用户组列表查询接口 9. 组列表查询接口 三、人脸对比及识别接口(传入opencv转换的mat) 1. 人脸识别identify接口 2. 特征值提取接口 3. 特征值比较接口 四、活体检测接口 (传入opencv转换的mat) 1. 近红外(NIR)活体检测接口 2. 可见光(RGB)活体检测接口 3. 可见光(RGB)&深度(Depth)活体检测接口 4. 有动作活体检测接口(action_live) 五、属性及质量接口(传入opencv转换的mat) 1. 人脸属性接口 六、其他接口能力 1. 检测参数可定制化,包括最大检测人数、最小人脸大小,跟踪时候的检测间隔等 2. 暗光恢复 3. 最佳人脸 4. 人脸遮挡、光照、模糊度 5. 人脸扣图 6. 头角度 |
v6.0 多语言通用版 |
2021.06.22 | 1. 更新人脸检测模型,提升在强光、暗光、逆光、阴阳光等复杂光线场景下人脸检测的召回率; 2. 更新RGB、NIR和Depth三种模态的活体检测模型,提升在复杂光线场景下真人活体检测通过率,同步提升高清2D和高质量3D道具的活体攻击防御效果; 3. 更新人脸识别模型,提升复杂光线场景下人脸识别的准确率; 4. 新增暗光恢复功能,对暗光场景下的图片进行亮度提升,提高检测和识别的准确率; 5. 更新「证件照」模型,深度优化人证1:1比对场景准确率和泛化性; 6. 适配兼容奔腾G4400、赛扬J1900老旧CPU,支持X32/X64多操作系统,支持win7/win10/XP系统。 |
v4.2 | 2021.03.30 | 1. 增加端到端人脸识别示例工程,提供快速验证和测试的工具及二次开发的范例参考; 2. 增加人脸识别设置示例工程,提供人脸识别相关参数配置功能的参考可配合人脸识别工程使用。 |
v4.1 | 2020.07.10 | 1. 优化人脸检测、关键点检测模型,提升人脸检测准确率; 2. 增加口罩检测功能,支持对用户是否佩戴口罩这个属性进行检测; 3. 新增激活工具,该工具支持在连网状态下通过授权序列号完成激活; 4. 完善各功能接口调用的示例工程。 |
v4.0 | 2020.02.27 | 1. 全面升级人脸检测、关键点检测模型,提升人脸检测和追踪的准确率,解决部分场景下的人脸漏检问题; 2. 全面升级三模态活体检测模型,提升RGB、NIR、Depth三模态活体检测的准确率; 3. 全面优化人脸特征抽取和特征比对模型,提升人脸识别模型的准确率和泛化性; 4. 全面重构SDK的接口设计,降低二次开发难度的同时提升了二次开发的灵活性。 |
目 录
1、设计背景
2、名词解释
3、sdk简介
3.1 功能架构
3.2 人脸技术流程
3.3 版本及兼容性
3.4 依赖库及运行环境
4、sdk包结构
5、授权激活
5.1 sdk自动激活
5.2 激活工具激活(LicenseTool.exe)
5.3 官网离线激活
6、sdk集成及demo示例工程
6.1 sdk的集成
6.2 sdk工程的集成及库文件说明
7、模型能力加载及模型说明
7.1 模型删减说明
7.2 模型路径的定制化
7.3 能力定制化说明
7.3.1 detect.json (人脸检测能力定制配置文件)
7.3.2 track.json (人脸追踪能力定制配置文件)
7.3.3 action_live.json (动作活体能力定制配置文件)
7.3.4 crop.json (人脸抠图能力定制配置文件)
8、功能接口
8.1 人脸检测detect接口
8.2 人脸跟踪track接口
8.3 清除人脸跟踪历史接口
8.4 人脸关键点接口
8.5 注意力检测接口
8.6 人脸属性检测接口
8.7 人脸抠图接口
8.8 暗光恢复接口
8.9 眼部状态检测接口
8.10 嘴巴闭合检测接口
8.11 口罩佩戴检测接口
8.12 人脸质量
8.12.1 人脸姿态角接口
8.12.2 人脸光照检测接口
8.12.3 人脸遮挡检测接口
8.12.4 人脸模糊度检测接口
8.12.5 最优人脸检测接口
8.13 特征值及人脸比对(1:1)
8.13.1 人脸特征值接口
8.13.2 人脸活体特征值接口
8.13.3 深度人脸特征值接口
8.13.4 特征值比对接口
8.13.5 人脸1:1比对接口
8.14 动作活体和静默活体
8.14.1 动作活体接口
8.14.2 清除动作活体历史接口
8.14.3 rgb静默活体接口
8.14.4 nir静默活体接口
8.14.5 rgb+depth双目静默活体接口
8.15 人脸库管理
8.15.1 人脸注册接口(通过传入图片帧)
8.15.2 人脸注册接口(通过传入特征值)
8.15.3 人脸更新接口(传入opencv图片帧)
8.15.4 用户删除接口
8.15.5 创建用户组接口
8.15.6 用户组删除接口
8.15.7 用户信息查询接口
8.15.8 用户人脸图片查询接口
8.15.9 用户组列表查询接口
8.15.10 群组列表查询接口
8.15.11 人脸库人脸数量查询
8.15.12 人脸识别接口(1:N) (传入opencv图片帧)
8.15.13 人脸识别接口(1:N) (传入特征值)
8.15.14 人脸识别接口(1:N) (传入opencv图片帧)
8.15.15 人脸识别接口(1:N) (传入特征值)
8.16 sdk系统信息接口
8.16.1 获取sdk版本号接口
8.16.2 获取设备指纹接口
9、功能接口对应结构体描述
9.1 人脸跟踪信息结构体
9.2 人脸框信息结构体
9.3 人脸关键点信息结构体
9.4 人脸特征值结构体
9.5 人脸姿态角结构体
9.6 人脸属性信息结构体
9.7 嘴巴闭合结构体
9.8 口罩佩戴结构体
9.9 最优人脸置信度结构体
9.10 人脸模糊度置信度结构体
9.11 人脸光照置信度结构体
9.12 人脸遮挡置信度结构体
9.13 人眼闭合状态结构体
9.14 注意力结构体
9.15 静默活体置信度结构体
10、多端特征值对齐
11、适配的深度双目摄像头特别说明
12、错误码及错误信息
13、常见问题
1、设计背景
(1) 场景特点:
- 网络:对于无网、局域网等情况,无法连接公网,API方式无法运作。如政府单位、金融保险、教育机构等,其中内网情况最为常见,私有化部署是项目开展的前提条件。
- 安全:即使可以连接外网,因为人脸数据的敏感性,许多客户不希望将人脸数据传入百度服务器,如大学学生照片、部分企业员工数据等,API形式也往往不被接受。
- 速度:由于各地网络线路、机房部署、图片采集方式等诸多原因,API形式往往耗时较高,容易存在部分请求耗时过长的情况,容易影响业务正常运转。
- 稳定:API形式容易受网络抖动、机房故障、线上连带bug等影响,存在一定的不稳定因素,可用性保障,往往成为在线调用最容易出现问题的地方。
(2) 客户特点:
- 1:N-小型人脸库检索:多为通道通行、固定区域人群验证等需求,如写字楼闸机门禁、企业考勤打卡等,人脸库范围较小,且不易经常变动。
- 1:1-自有数据源对比:将当前采集的人脸,与其他数据源中的人脸进行对比,如身份证芯片照、教务系统图片、档案图片等,进行快速的1:1对比验证。
(3) 核心需求:
- 基础的人脸采集:包含人脸检测、跟踪、捕获、质量校验等基础功能,获取符合识别条件的人脸。为之前的客户端SDK的标准功能,离线版本SDK保留以上所有能力。
- 本地特征抽取:所有在SDK中运行的人脸图片,都可以完成本地特征抽取,以便进行对比或识别操作。
- 1:1对比:支持两张图片的相似度对比,可直接传入图片,也可调用本地某个人脸特征;
- 1:N搜索:支持一定库大小的人脸查找,在指定的人脸集合中查找最相似的人脸,并返回相似度分值;
2、名词解释
名词 | 定义 |
---|---|
sdk | windows c++离线人脸识别sdk(须支持c++11) |
vs2015 | 微软的开发工具visual studio 2015 (推荐安装vs community 2015) |
license | 人脸识别激活所需要的激活文件,文档介绍了三种激活方式 |
key | 人脸激活所需的序列号,可从百度AI官网申请(ai.baidu.com) |
feature | 人脸特征值,用来表示人脸特征的128个float浮点值 |
landmark | 人脸关键点(72个关键点) |
face_token | 对应人脸图片的唯一编码,若一个人上传了2张不同图片,则可能有2个不同的face_token,它和图片一一对应 |
3、sdk简介
本sdk适应于windows平台下的人脸识别系统,为支持c++语言开发的sdk,开发者可在vs2015下面进行开发(推荐使用,不保证其他版本vs都兼容)。sdk采用导出动态库dll的方式提供接口,另外随sdk附带一个示例工程FaceOfflineSdk,提供了sdk的各种能力及调用示例。
3.1 功能架构
sdk具有人脸检测、追踪、特征值、静默活体、人脸库、镜头模组集成等诸多功能。架构如下图所示:
3.2 人脸技术流程
sdk的人脸识别技术流程可如下图所示,通过人脸检测进行人脸特征值的提取,同时,在人脸检测或特征值提取之前可通过人脸质量判断和活体检测进行按需过滤。人脸信息变成可量化的特征值后,可实现人脸特征值的1:1比对和人脸的1:N识别(N个人脸特征信息可保存在人脸库中)
3.3 版本及兼容性
本sdk支持x86、x64两个平台的版本。
支持win7、win10操作系统(windows server能用但不推荐)。
针对赛扬、奔腾等cpu我们有noavx版本(通用版不适应这类cpu)。
推荐使用vs2015 community或professional或vs2015以上版本的开发工具。
sdk未提供debug的库文件,所以请选择release模式开发测试。
3.4 依赖库及运行环境
本sdk在vs环境下编译会在x64或x86(根据您选择的版本不同)下生成exe可执行文件。
依赖的其他dll库文件包括如opencv等都在该exe目录,请勿删除。
若exe执行提示找不到依赖dll库文件,可根据您的版本在sdk的tools->vc_redist
目录执行vc_redist.x64.exe
或vc_redist.x86.exe
进行安装(该vc_redst为vs2015的依赖)。
4、sdk包结构
sdk包结构如下图所示:
5、授权激活
sdk需要授权激活后才能正常使用,在sdk初始化后,若报错误码-13(错误码参考文档最后定义),一般为没有通过授权。
通常,sdk分按设备授权和按应用授权两种方式,大部分采用按设备授权的方式,按应用授权可针对批量大规模客户使用(文档中先只介绍按设备授权,按应用授权可工单或联系百度商务我们提供另外的文档或技术支持)。
按设备授权的方式中,sdk自动激活和激活工具激活需要设备能联网,若设备不能连外网,可采用官网离线激活的方式。
5.1 sdk自动激活
在sdk的目录中有license
文件夹,里面存放了2个文件,license.key
和license.ini
,分别是授权key和授权文件,若在百度官网申请了授权系列号key(16位),可按sdk中的license
文件夹中license.key
原格式样子覆盖填写您申请的key。
在设备能联网的情况下,运行sdk会自动授权激活并拉取新的授权文件license.ini
覆盖sdk中的旧文件。
5.2 激活工具激活(LicenseTool.exe)
在百度官网申请系列号key(16位)后,在FaceOfflineSdk的tools->license_tool
目录夹下,双击运行LicenseTool.exe
激活工具,可见如下所示界面。
在输入框中输入16位的系列号后,点击激活按钮,稍等片刻,即可见弹出的激活成功对话框,若激活失败,请参考对话框中弹出的message信息查找原因。激活成功后会生成license.zip
文件,解压后获取license.ini
和license.key
文件,拿这2个文件拷贝覆盖到sdk中的license
文件夹,覆盖对应旧文件,重启sdk,即可完成授权激活。
5.3 官网离线激活
若设备不能连外网、通过授权还有另外一种方法,即通过如上5.2的激活工具,获取到设备硬件指纹信息,通过百度官网填入指纹信息和申请到的系列号key,可完成激活并下载获取到license.ini
文件和license.key
文件,把这2个文件拷贝到FaceOfflineSdk的license
目录下,重新运行sdk亦可通过授权激活。
6、sdk集成及demo示例工程
6.1 sdk的集成
sdk集成的include需包含sdk的接口头文件:baidu_face_api.h
;
引入库lib文件:BaiduFaceApi.lib
、face_sdk.lib
;
运行动态库dll文件以及部分底层算法库文件:BaiduFaceApi.dll
、face_sdk.dll
、bd_license.dll
、libcurl.dll
、libeay32.dll
、libopenblas.dll
、libiomp5md.dll
、mkldnn.dll
、mklml.dll
、ssleay32.dll
。(这些库文件在sdk中的win32或x64目录);
除此之外,第三方头文件及库文件也建议保留,如json
、opencv
。
6.2 sdk工程的集成及库文件说明
sdk工程FaceOfflineSdk包含了sdk接口及demo示例工程。其中:sdk接口头文件为前述include
目录的baidu_face_api.h
,该文件定义了sdk的各api接口方法。sdk接口的lib
库文件为前述lib
目录。根据x64和x86分别放置在不同目录。其中的lib文件描述如下列表:
lib文件名称 | lib文件说明 | 对应动态库dll | 是否可删除 |
---|---|---|---|
BaiduFaceApi.lib | 百度人脸库引入文件 | BaiduFaceApi.dll | 否 |
face_sdk.lib | 百度人脸库引入文件 | face_sdk.dll | 否 |
opencv_world320.lib | opencv库文件,用来显示图片,视频等 | opencv_ffmpeg320.dll | 否 |
json_vc71_libmt.lib | json cpp库文件,用来做json解析 | 无 | 是(若不使用人脸库等用到json的部分,可删除该库) |
OrbeCamera.lib | 3d结构光镜头:奥比中光引入库文件 | 对应的动态库在camera_driver文件夹的orbe文件夹里面,可根据x64或x86选择64位和32位,使用的时候需要把dll的文件夹里面的内容全部拷贝到exe所在目录 | 是(若不用奥比中光3d结构光做深度活体检测,可删除该库),另外include里面的头文件orbe_camera.h也可删除 |
AimiCamera.lib | 3d结构光镜头:华捷艾米引入库文件 | 对应的动态库在camera_driver文件夹的hjimi文件夹里面,可根据x64或x86选择64位和32位,使用的时候需要把dll的文件夹里面的内容全部拷贝到exe所在目录 | 是(若不用奥比中光3d结构光做深度活体检测,可删除该库),另外include里面的头文件aimi_camera.h也可删除 |
用vs2015打开sln工程文件后,默认便已设置好工程的include
及lib
库路径。若需要手动设置,则include
如下图所示:
右键工程->属性,在c++常规中添加包含目录。(include
的文件夹的头文件为sdk的使用头文件,建议接入客户自己工程时候附带,third_party
中为json
和opencv
的头文件,也建议引入)
同样:右键工程->属性,链接器->常规中输入如(假设64位,32位请输入x86)
demo示例工程FaceOfflineSdk展示了如何集成百度人脸识别离线sdk,并调用sdk的方法及各示例demo等。
在FaceOfflineSdk中的face.cpp
的main()
方法中,有使用sdk的各个接口方法示例。接入sdk及其简单,如下图及解释:
sdk使用主要三步:1)初始化实例指针;2)初始化sdk;3) 调用示例demo,实现功能。
sdk末尾需要释放sdk实例化指针delete api
。初始化sdk返回值若不为0,可通过文档查询对应错误码,查找sdk初始化失败原因。
另外,可通过is_auth()
方法查看是否通过了授权,通常,需要通过授权,才可以使用sdk的各种能力。
示例工程中:分别有以下几个文件夹放置文件对应几个常用sdk的调用demo。
解析如下:
文件夹或文件名 | 文件说明 |
---|---|
face.cpp | sdk总入口,初始化,模型加载,销毁等,见main方法 |
face_demo.cpp | demo总入口,可打开注释运行各类demo示例 |
face_detect | 人脸检测接口及示例demo |
face_track | 人脸跟踪接口及示例demo |
face_feature | 人脸特征值接口及示例demo |
face_compare | 人脸1:1 1:N 比对,特征值比较等接口及示例demo |
face_liveness | 可见光RGB、红外IR活体检测、RGB&IR双目摄像头静默活体检测,RGB&DEPTH双目摄像头静默活体检测等 |
face_manager | 人脸库管理类,包括人脸注册、删除,更新、组管理,人脸信息查询等 |
face_attr | 人脸属性(年龄、性别、种族等) 接口及示例 |
face_head_pose | 人脸姿态角接口及示例 |
face_illumination | 人脸光照检测接口及示例 |
face_occlusion | 人脸遮挡度检测接口及示例 |
face_blur | 人脸模糊度检测接口及示例 |
face_action_live | 动作活体检测接口及示例 |
face_best | 优人脸接口及示例 |
face_crop | 人脸抠图接口及示例 |
face_gaze | 双眼注意力检测接口及示例 |
face_eye_close | 眼睛闭合检测接口及示例 |
face_mouth_close | 嘴巴闭合检测接口及示例 |
face_mouth_mask | 是否佩戴口罩检测接口及示例 |
face_scene | 该示例亦展示了如何使用sdk原子接口等,如不用该示例,则引入的头文件处 face_scene\include可删除 |
7、模型能力加载及模型说明
7.1 模型删减说明
sdk支持按需配置模型和加载能力,若sdk有某部分功能不需要使用,可尝试删除一些模型,删除后模型即不会加载也不会占用内存。sdk中models文件夹里的模型及是否可删减说明如下表:
模型文件夹名称 | 说明 | 是否可删减 | 删减说明 |
---|---|---|---|
detect | 人脸检测模型 | 是 | 若不使用nir近红外功能,可删除detect_nir开头的模型文件 |
align | 人脸关键点模型 | 是 | 若不使用nir近红外功能,可删除align_nir开头的模型文件 |
attribute | 人脸属性 | 是 | 若不使用人脸属性检测功能,该文件夹可删除 |
best_image | 最佳人脸 | 是 | 若不使用最佳人脸检测功能,该文件夹可删除 |
blur | 人脸质量模糊度检测 | 是 | 若不使用该功能,该文件夹可删除 |
dark_enhance | 暗光恢复 | 是 | 若不使用该功能,该文件夹可删除 |
eye_close | 眼睛闭合 | 是 | 若不使用眼睛闭合及动作活体功能,该文件夹可删除 |
feature | 人脸特征值 | 是 | 若仅使用rgb可见光人脸特征值,除feature_life_float32_paddle.encrypted文件外,该文件夹其他文件可删除 |
gaze | 人脸注意力检测 | 是 | 若不使用该功能,该文件夹可删除 |
mouth_close | 嘴巴闭合检测 | 是 | 若不使用嘴巴闭合及动作活体功能,该文件夹可删除 |
mouth_mask | 口罩佩戴检测 | 是 | 若不使用该功能,该文件夹可删除 |
occlusion | 人脸遮挡检测 | 是 | 若不使用该功能,该文件夹可删除 |
silent_live | 静默活体检测 | 是 | 若只使用rgb可见光单目静默活体,则除silent_live_rgb_float32_paddle.encrypted文件外其他皆可删除 |
7.2 模型路径的定制化
sdk支持模型文件夹models
的路径自定义,当sdk初始化api->sdk_init(nullptr)
传null时候,为sdk支持模型文件夹路径在默认路径,即models
在sdk现有位置。同时也支持models通过sdk_init
中传入绝对路径。若把models
文件夹拷贝到d盘的face文件夹下面,则可定义:
api->sdk_init(“d:\\face”);
此时,授权文件夹license
也需要随之变为d盘的face
文件夹下面。否则会出现授权不通过的问题。
另外,若使用了能力自定义的config
文件夹,也需要拷贝到d盘的face
文件夹下面。否则能力定制化也不会生效而是使用的系统默认。
7.3 能力定制化说明
sdk支持能力自定义、通过读取配置文件的方式进行能力定制化。sdk默认能力加载无需定制化,若需要定制化,请把sdk根目录里面的conf
文件夹重命名为config
文件夹。并且在sdk中,把里面的json
配置按如下说明做修改,可起到定制化能力加载的效果,配置文件简要说明如下(若需定制化修改,请参考示例json
,修改json
字段的值来达到定制化的目的)
7.3.1 detect.json (人脸检测能力定制配置文件)
配置文件名:detect.json
说明:人脸检测自定义能力配置文件
{
"max_detect_num":5,
"min_face_size":0,
"scale_ratio":-1,
"not_face_thr":0.5
}
参数 | 类型 | 说明 |
---|---|---|
max_detect_num | int | 最大检测的人脸数量,最多支持50,最小1,默认5 |
min_face_size | int | 默认0,可用来设置检测的最小人脸,比如可设为10,则表示小于10*10的人脸,sdk检测不到 |
scale_radio | int | 默认-1,表示进行人脸检测时候的图片缩放比率。建议用-1表示传入原图sdk自己缩放(为保证检测效果,该参数建议用默认) |
not_face_thr | float | 默认0.5,表示非人脸的阈值,取值范围0-1 |
7.3.2 track.json (人脸追踪能力定制配置文件)
配置文件名:track.json
说明:人脸追踪自定义能力配置文件
{
"detect_intv_before_track":0.02,
"detect_intv_during_track":0.02
}
参数 | 类型 | 说明 |
---|---|---|
detect_intv_before_track | float | 表示人脸追踪前进行人脸检测的时间间隔(单位毫秒) |
detect_intv_during_track | float | 表示人脸追踪时候进行人脸检测的时间间隔(单位毫秒) |
7.3.3 action_live.json (动作活体能力定制配置文件)
配置文件名:action_live.json
说明:人脸动作活体自定义能力配置文件
{
"eye_open_threshold":0.5,
"eye_close_threshold":0.5,
"mouth_open_threshold":0.5,
"mouth_close_threshold":0.5,
"look_up_threshold":0.5,
"look_down_threshold":0.5,
"turn_left_threshold":0.5,
"turn_right_threshold":0.5,
"nod_threshold":0.5,
"shake_threshold":0.5,
"max_cache_num":1
}
参数 | 类型 | 说明 |
---|---|---|
eye_open_threshold | float | 表示人脸动作活体眼睛睁开的置信度阈值 |
eye_close_threshold | float | 表示人脸动作活体眼睛闭合的置信度阈值 |
mouth_open_threshold | float | 表示人脸动作活体嘴巴张开的置信度阈值 |
mouth_close_threshold | float | 表示人脸动作活体嘴巴闭合的置信度阈值 |
look_up_threshold | float | 表示人脸动作活体抬头的置信度阈值 |
look_down_threshold | float | 表示人脸动作活体低头的置信度阈值 |
turn_left_threshold | float | 表示人脸动作活体向左转头的置信度阈值 |
turn_right_threshold | float | 表示人脸动作活体向右转头的置信度阈值 |
nod_threshold | float | 表示人脸动作活体点头的置信度阈值 |
shake_threshold | float | 表示人脸动作活体摇头的置信度阈值 |
max_cache_num | float | 最大缓存数、推荐为1不做修改 |
7.3.4 crop.json (人脸抠图能力定制配置文件)
配置文件名:crop.json
说明:人脸抠图自定义能力配置文件
{
"is_flat":0,
"crop_size":200,
"enlarge_ratio":1
}
参数 | 类型 | 说明 |
---|---|---|
is_flat | int | 默认为0,表示是否是镜像,该参数目前无效 |
crop_size | int | 表示抠图的大小,如200,则表示抠出来的是200*200的图片 |
enlarge_ratio | float | 默认是1,若小于1,比如0.8,图片有点放大,会稍微模糊,建议自定义可设为1 |
8、功能接口
sdk功能接口的调用可参考各示例cpp文件,接口定义在baidu_face_api.h
sdk实现的主要功能有人脸实时跟踪检测、人脸特征值提取、动作活体、RGB&IR静默活体检测、RGB&DEPTH静默活体检测、人脸注册、人脸更新、组管理、用户管理以及1:1人脸对比,1:N人脸识别、特征值的比对和通过usb或笔记本自带摄像头检测视频帧,返回识别出的人脸信息、人脸属性等,另外支持对人脸检测进行能力加载设置,达到根据设置进行识别的目的。
各接口功能及传入参数和返回结果等定义如下:
8.1 人脸检测detect接口
方法名:detect
说明:人脸检测,返回人脸信息
函数:int detect(std::vector<FaceBox> &out, const cv::Mat* mat, int type = 0)
请求参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
out | 通过引用返回的人脸结构体数组 | 是 | std::vector |
人脸框信息结构体 |
mat | 传入的opencv视频帧 | 是 | Opencv mat | 请参考示例 |
type | 检测类型(传0表示rgb可见光人脸检测,1表示nir) | 否 | int | 0或1,不传默认为0 |
返回信息 | 函数的返回 | 是 | int | <=0 为未检测到人脸或错误码 >0时候为检测到的人脸数量 |
8.2 人脸跟踪track接口
方法名:track
说明:人脸跟踪,返回人脸信息
函数:int track(std::vector<TrackFaceInfo>&out, const cv::Mat* mat, int type = 0)
请求参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
out | 通过引用返回的人脸结构体数组 | 是 | std::vector |
人脸跟踪结构体信息 |
mat | 传入的opencv视频帧 | 是 | Opencv mat | 请参考示例 |
type | 检测类型(传0表示rgb可见光人脸检测,1表示nir) | 否 | int | 0或1,不传默认为0 |
返回信息 | 函数的返回 | 是 | int | <=0 为未检测到人脸或错误码 >0时候为检测到的人脸数量 |
8.3 清除人脸跟踪历史接口
方法名:clear_track_history
说明:清除人脸跟踪的历史信息
函数:int clear_track_history(int type = 0)
请求参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
type | 检测类型(传0表示rgb可见光人脸检测,1表示nir) | 否 | int | 0或1,不传默认为0 |
返回信息 | 函数的返回 | 是 | void |
8.4 人脸关键点接口
方法名:face_landmark
说明:人脸关键点,返回人脸关键点信息
函数:int face_landmark(std::vector<Landmarks>&out, const cv::Mat* mat, int type)
请求参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
out | 通过引用返回的人脸关键点数组 | 是 | std::vector |
人脸关键点信息结构体 |
mat | 传入的opencv视频帧 | 是 | Opencv mat | 请参考示例 |
type | 检测类型(传0可见光生活照特征值,1、可见光证件照特征值 2、表示近红外特征值) | 是 | int | |
返回信息 | 函数的返回 | 是 | int | <=0 为未检测到人脸或错误码 >0时候为检测到的人脸数量 |
8.5 注意力检测接口
方法名:face_gaze
说明:人脸注意力检测
函数:int face_gaze(std::vector<GazeInfo>& out, const cv::Mat* mat)
请求参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
out | 通过引用返回的人脸注意力结构体数组 | 是 | std::vector |
注意力结构体 |
mat | 传入的opencv视频帧 | 是 | Opencv mat | 请参考示例 |
返回信息 | 函数的返回 | 是 | int | <=0 为未检测到人脸或错误码 >0时候为检测到的人脸数量 |
8.6 人脸属性检测接口
方法名:face_attr
说明:人脸属性检测
函数:int face_attr(std::vector<Attribute>& out, const cv::Mat *mat)
请求参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
out | 通过引用返回的人脸属性结构体数组 | 是 | std::vector |
人脸属性结构体 |
mat | 传入的opencv视频帧 | 是 | Opencv mat | 请参考示例 |
返回信息 | 函数的返回 | 是 | int | <=0 为未检测到人脸或错误码 >0时候为检测到的人脸数量 |
8.7 人脸抠图接口
方法名:face_crop
说明:人脸扣图,返回人脸扣图(仅支持单人脸抠图)
函数:int face_crop(cv::Mat&out, const cv::Mat* mat)
请求参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
out | 抠图结果图片帧 | 是 | Opencv mat | |
mat | 传入的opencv视频帧 | 是 | Opencv mat | |
返回信息 | 函数的返回 | 是 | int | 返回:<0 为未检测到人脸或错误码 =0 表示抠图成功 |
8.8 暗光恢复接口
方法名:dark_enhance
说明:暗光恢复,用于图片比较暗的使之变亮利于人类检测(仅支持单人脸抠图)
函数:int dark_enhance(cv::Mat&out, const cv::Mat* mat)
请求参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
out | 暗光恢复结果图片帧 | 是 | Opencv mat | |
mat | 传入的opencv视频帧 | 是 | Opencv mat | |
返回信息 | 函数的返回 | int | 返回:<0 为错误码 =0表示成功 |
8.9 眼部状态检测接口
方法名:face_eye_close
说明:人脸眼部状态检测
函数:int face_eye_close(std::vector<EyeClose> &out, const cv::Mat* mat)
请求参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
out | 通过引用返回的人脸眼部状态结构体数组 | 是 | std::vector |
眼部状态信息结构体 |
mat | 传入的opencv视频帧 | 是 | Opencv mat | 请参考示例 |
返回信息 | 函数的返回 | 是 | int | <=0 为未检测到人脸或错误码 >0时候为检测到的人脸数量 |
8.10 嘴巴闭合检测接口
方法名:face_mouth_close
说明:人脸嘴巴闭合检测
函数:int face_mouth_close(std::vector<MouthClose>& out, const cv::Mat* mat)
请求参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
out | 通过引用返回的人脸嘴巴闭合结构体数组 | 是 | std::vector |
嘴巴闭合结构体 |
mat | 传入的opencv视频帧 | 是 | Opencv mat | 请参考示例 |
返回信息 | 函数的返回 | 是 | int | <=0 为未检测到人脸或错误码 >0时候为检测到的人脸数量 |
8.11 口罩佩戴检测接口
方法名:face_mouth_mask
说明:人脸口罩佩戴检测
函数:int face_mouth_mask(std::vector<MouthMask>& out, const cv::Mat* mat)
请求参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
out | 通过引用返回的人脸口罩佩戴结构体数组 | 是 | std::vector |
佩戴口罩结构体 |
mat | 传入的opencv视频帧 | 是 | Opencv mat | 请参考示例 |
返回信息 | 函数的返回 | 是 | int | <=0 为未检测到人脸或错误码 >0时候为检测到的人脸数量 |
8.12 人脸质量
人脸质量判断可由以下几个因素自由组合综合判断,如姿态角、光照、遮挡、模糊以及最佳人脸。
8.12.1 人脸姿态角接口
方法名:face_head_pose
说明:人脸姿态角检测(yaw:左右边转角 roll:屏幕旋转角 pitch:上下偏转角 姿态角推荐范围 -15~15,越大角度越不正不合格)
函数:int face_head_pose(std::vector<HeadPose>&out, const cv::Mat* mat)
请求参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
out | 通过引用返回的人脸姿态角数组 | 是 | std::vector |
人脸姿态角信息结构体 |
mat | 传入的opencv视频帧 | 是 | Opencv mat | 请参考示例 |
返回信息 | 函数的返回 | 是 | int | <=0 为未检测到人脸或错误码 >0时候为检测到的人脸数量 |
8.12.2 人脸光照检测接口
方法名:face_illumination
说明:人脸光照检测、(光照分值0-255、分值越大光照越强,推荐阈值100)
函数:int face_illumination(std::vector<Illumination>&out, const cv::Mat* mat)
请求参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
out | 通过引用返回的人脸光照信息数组 | 是 | std::vector |
光照置信度结构体 |
mat | 传入的opencv视频帧 | 是 | Opencv mat | 请参考示例 |
返回信息 | 函数的返回 | 是 | int | <=0 为未检测到人脸或错误码 >0时候为检测到的人脸数量 |
8.12.3 人脸遮挡检测接口
方法名:face_occlusion
说明:人脸遮挡检测(遮挡分值0-1,分值越大遮挡度越高,推荐阈值0.6)
函数:int face_occlusion(std::vector<Occlusion>& out, const cv::Mat* mat)
请求参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
out | 通过引用返回的人脸遮挡结构体数组 | 是 | std::vector |
遮挡置信度结构体 |
mat | 传入的opencv视频帧 | 是 | Opencv mat | 请参考示例 |
返回信息 | 函数的返回 | 是 | int | <=0 为未检测到人脸或错误码 >0时候为检测到的人脸数量 |
8.12.4 人脸模糊度检测接口
方法名:face_blur
说明:人脸模糊检测(模糊度分值0-1,分值越大模糊度越高,推荐阈值0.6)
函数:int face_blur(std::vector<Blur> &out, const cv::Mat * mat)
请求参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
out | 通过引用返回的人脸模糊结构体数组 | 是 | std::vector |
模糊度结构体 |
mat | 传入的opencv视频帧 | 是 | Opencv mat | 请参考示例 |
返回信息 | 函数的返回 | 是 | int | <=0 为未检测到人脸或错误码 >0时候为检测到的人脸数量 |
8.12.5 最优人脸检测接口
方法名:face_best
说明:最佳人脸检测(最优人脸分值0-100,分值越高,最佳人脸图片得分越高,推荐阈值50)
函数:int face_best(std::vector<Best> &out, const cv::Mat *mat)
请求参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
out | 通过引用返回的最佳人脸结构体数组 | 是 | std::vector |
最优人脸结构体 |
mat | 传入的opencv视频帧 | 是 | Opencv mat | 请参考示例 |
返回信息 | 函数的返回 | 是 | int | <=0 为未检测到人脸或错误码 >0时候为检测到的人脸数量 |
8.13 特征值及人脸比对(1:1)
人脸比对的原理实际是特征值比对,通过提取图片中的人脸特征值,根据特征值调用compare_feature
接口进行比对,推荐比对分值超过80分为同一人,可根据实际检测比对情况动态调整。
人脸1:1比对流程可如下图,实现如人证比对功能。(人的照片和实时视频比对,可根据使用情况选择是否启用质量检测)
8.13.1 人脸特征值接口
方法名:face_feature
说明:人脸特征值提取,并返回人脸信息
函数:int face_feature(std::vector<Feature> &out_fea, std::vector<FaceBox> &out_box, const cv::Mat *mat , int type = 0)
请求参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
out_fea | 通过引用返回的人脸特征值结构体数组 | 是 | std::vector |
人脸特征值结构体信息 |
out_box | 通过引用返回的人脸框结构体数组 | 是 | std::vector |
人脸框结构体信息 |
mat | 传入的opencv视频帧 | 是 | Opencv mat | 请参考示例 |
type | 检测类型(传0可见光生活照特征值,包含1寸照,1、网格证件照特征值 2、表示近红外特征值) | 否 | int | 0或1、2,未传默认为0 |
返回信息 | 函数的返回 | 是 | int | <=0 为未检测到人脸或错误码 >0时候为检测到的人脸数量 |
8.13.2 人脸活体特征值接口
方法名:liveness_feature
说明:人脸特征值提取,并返回活体分值,人脸信息
函数:int liveness_feature(std::vector<Feature> &out_fea, std::vector<FaceBox> &out_box, float& score, const cv::Mat *mat , int type = 0)
请求参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
out_fea | 通过引用返回的人脸特征值结构体数组 | 是 | std::vector |
人脸特征值结构体信息 |
out_box | 通过引用返回的人脸框结构体数组 | 是 | std::vector |
人脸框结构体信息 |
mat | 传入的opencv视频帧 | 是 | Opencv mat | 请参考示例 |
score | 返回的活体分值 | 是 | float | |
type | 检测类型(传0可见光特征值,1表示近红外特征值) | 否 | int | 0或1,未传默认为0 |
返回信息 | 函数的返回 | 是 | int | <=0 为未检测到人脸或错误码 >0时候为检测到的人脸数量 |
8.13.3 深度人脸特征值接口
方法名:rgbd_feature
说明:人脸特征值提取,返回人脸信息
函数:int rgbd_feature(std::vector<Feature> &out_fea, std::vector<Feature> &out_box, const cv::Mat* rgb_mat, const cv::Mat* depth_mat)
请求参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
out_fea | 通过引用返回的人脸特征值结构体数组 | 是 | std::vector |
人脸特征值结构体信息 |
out_box | 通过引用返回的人脸框结构体数组 | 是 | std::vector |
人脸框结构体信息 |
rgb_mat | 传入可见光的opencv视频帧 | 是 | Opencv mat | 请参考示例 |
depth_mat | 传入深度的opencv视频帧 | 是 | int | 请参考示例 |
返回信息 | 函数的返回 | 是 | int | <=0 为未检测到人脸或错误码 >0时候为检测到的人脸数量 |
8.13.4 特征值比对接口
方法名:compare_feature
说明:人脸跟踪,返回人脸信息
函数:float compare_feature(Feature* f1, Feature *f2, int type)
请求参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
f1 | 人脸特征值结构体 | 是 | Feature* | 人脸特征值结构体信息(仅支持单个结构体的比对) |
f2 | 人脸特征值结构体 | 是 | Feature* | 人脸特征值结构体信息(仅支持单个结构体的比对) |
type | 特征值类型(0,1,2) | 否 | int | 0:生活照、包含1寸照 1:网格证件照 2:近红外特征值 未传默认为0(1寸或2寸的证据照也推荐当作生活照模式) |
返回信息 | 函数的返回 | 是 | float | 特征值比对分值 |
8.13.5 人脸1:1比对接口
方法名:match
说明:人脸比对,返回人脸比对分值
函数:int match(const cv::Mat& img1, const cv::Mat& img2, int type)
请求参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
img1 | 传入可见光的opencv图片帧 | 是 | cv::Mat | |
img2 | 传入可见光的opencv图片帧 | 是 | cv::Mat | |
type | 比对类型(0,1,2) | 否 | int | 0:生活照、包含1寸照 1:网格证件照 2:近红外特征值 未传默认为0(1寸或2寸的证据照也推荐当作生活照模式) |
返回信息 | 函数的返回 | 是 | int | 人脸比对分值(同特征值比对分值结果应该是float,这里返回int是做了四舍五入) |
8.14 动作活体和静默活体
8.14.1 动作活体接口
方法名:face_action_live
说明:动作活体(眨眨眼、张张嘴等动作校验活体)
函数:int face_action_live(std::vector<FaceBox>& out, int action_type, int& action_result, const cv::Mat* mat)
请求参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
out | 返回的人脸框结构体数组 | 是 | std::vector |
人脸框结构体 |
action_type | 传入的活体动作 | 是 | int | 动作活体类型,如0表示眨眨眼,1表示张嘴等 |
action_result | 动作活体的返回结果 | 是 | int | 返回结果为1表示存在该动作活体 |
mat | 传入的opencv视频帧 | 是 | Mat | 视频帧 |
返回字段描述 | |
---|---|
返回字段 | int,>=0返回人脸个数,<0时候为错误码 |
返回示例 |
8.14.2 清除动作活体历史接口
方法名:action_live_clear_history
说明:清除动作活体历史
函数:int action_live_clear_history()
请求参数 | 说明 | 必须 | 类型 | 示例描述 |
---|
返回字段描述 | |
---|---|
返回字段 | 0表示成功,其他错误码 int |
返回示例 |
8.14.3 rgb静默活体接口
方法名:rgb_liveness
说明:rgb可见光单目静默活体(推荐rgb+nir或rgb+depth进行双目活体校验)
函数:int rgb_liveness(std::vector<TrackFaceInfo>& out, float &score, const cv::Mat* mat)
请求参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
out | 返回的人脸框结构体数组 | 是 | std::vector |
人脸框结构体(多人则返回最大人脸) |
score | 返回的动作活体分值 | 是 | float | |
mat | 传入的opencv视频帧 | 是 | Mat | 视频帧 |
返回字段描述 | |
---|---|
返回字段 | int,>=0返回人脸个数,<0时候为错误码 |
返回示例 |
8.14.4 nir静默活体接口
方法名:nir_liveness
说明:Nir近红外单目静默活体(推荐rgb+nir
或rgb+depth
进行双目活体校验)
函数:int nir_liveness(std::vector<TrackFaceInfo>& out, float &score, const cv::Mat* mat)
请求参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
out | 返回的人脸框结构体数组 | 是 | std::vector |
人脸框结构体(多人则返回最大人脸) |
score | 返回的动作活体分值 | 是 | float | |
mat | 传入的opencv视频帧 | 是 | Mat | 视频帧 |
返回字段描述 | |
---|---|
返回字段 | int,>=0返回人脸个数,<0时候为错误码 |
返回示例 |
8.14.5 rgb+depth双目静默活体接口
方法名:rgb_depth_liveness
说明:rgb+depth
双目静默活体
函数:int rgb_depth_liveness(std::vector<TrackFaceInfo> &out, float &rgbscore, float &depthcore, const cv::Mat * rgb, const cv::Mat* depth)
请求参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
out | 返回的人脸框结构体数组 | 是 | std::vector |
人脸框结构体(多人则返回最大人脸) |
rgbscore | 返回的rgb动作活体分值 | 是 | float | |
depthscore | 返回的depth动作活体分值 | 是 | float | |
rgb | 传入的opencv视频帧 | 是 | Mat | 视频帧 |
depth | 传入的opencv视频帧 | 是 | Mat | 视频帧 |
返回字段描述 | |
---|---|
返回字段 | int,>=0返回人脸个数,<0时候为错误码 |
返回示例 |
8.15 人脸库管理
sdk提供支持5万以下的人脸库管理,采用的是sqlite
数据库,sdk启动后会自动生成db
文件夹和face.db
文件(人脸库数据文件)、db
文件夹可手动删除,删除后人脸数据库即被整体删除,sdk重启后会自动重新创建新库。人脸库数据结构可采用sqlLiteExpert
等可视化工具查看人脸库表结构。人脸库创建后有三张表,feature
表(用来保存人脸特征值),user
表(用来保存人脸用户信息,如userid
,groupid
以及人脸图片信息,用户信息等)以及user_group
表(用户组表)。
人脸库可按组(group_id
)划分,组就好比一个集团的子公司,人脸注册或查找既可以按整个库查找,也可以按组(子公司)查找,按组查找速度更快(范围小)。用户id(user_id)
是用来标识人脸用户的唯一id,组id(group_id
)是用来标识组(子公司)的唯一id。用户信息(user_info
)可作为用户id的说明,如标识用户名称、住址等信息,也可不填写。人脸的比对或识别、归根结底是人脸特征值的比对。人脸库的保存实际上是保存了对应用户user_id
的特征值在人脸库上,同时保存了用户user_id
和group_id
及其对应关系(一个用户对应一张人脸、一个特征值数据)。除user_info
字段(用户信息)支持中文外,user_id
和group_id
仅支持英文、数字和下划线的参数组合。
人脸库1:N识别可如如下图所示流程:
8.15.1 人脸注册接口(通过传入图片帧)
方法名:user_add
说明:用户注册,该接口支持传入opencv
图片帧(通常指生活照,1寸或2寸的证件照也可以用这种类型)(图片帧注册会把人脸图片缩略图入库)
函数:void user_add(std::string& res, const cv::Mat *img, const char* user_id, const char* group_id, const char* user_info=””)
请求参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
res | 返回的结果 | 是 | string json | 数据 |
img | opencv图片帧指针 | 是 | cv::Mat * | 人脸图片opencv图片帧指针 |
user_id | 用户id | 是 | const char* | 用户id(由数字、字母、下划线组成),长度限制128B |
group_id | 组id | 是 | const char* | 用户组id,标识一组用户(由数字、字母、下划线组成),长度限制128B |
user_info | 用户资料 | 否 | const char* | 256个字符以内(中文数减半) |
返回字段描述(json) | ||
---|---|---|
errno及msg映射 | errno | Msg |
0 | Success | |
<0 | 失败的原因 | |
返回示例 |
8.15.2 人脸注册接口(通过传入特征值)
方法名:user_add
说明:用户注册,该接口通过传入提取的人脸图片特征值注册(特征值注册无法把人脸缩略图入库)
函数:void user_add(std::string& res, Feature* f1, const char* user_id, const char* group_id, const char* user_info=””)
请求参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
res | 返回的结果 | 是 | string json | 数据 |
f1 | 特征值结构体 | 是 | Feature* | 人脸特征值结构体 |
user_id | 用户id | 是 | const char* | 用户id(由数字、字母、下划线组成),长度限制128B |
group_id | 组id | 是 | const char* | 用户组id,标识一组用户(由数字、字母、下划线组成),长度限制128B |
user_info | 用户资料 | 否 | const char* | 256个字符以内(中文数减半) |
返回字段描述(json) | ||
---|---|---|
errno及msg映射 | errno | Msg |
0 | Success | |
<0 | 失败的原因 | |
返回示例 |
8.15.3 人脸更新接口(传入opencv图片帧)
方法名:user_update
说明:人脸更新
函数:void user_update(std::string& res, const cv::Mat* img, const char* user_id, const char* group_id, const char* user_info=””)
请求参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
res | 返回的结果 | 是 | string json | 数据 |
img | opencv图片帧指针 | 是 | cv::Mat * | 人脸图片opencv图片帧指针 |
user_id | 用户id | 是 | const char* | 用户id(由数字、字母、下划线组成),长度限制128B |
group_id | 组id | 是 | const char* | 用户组id,标识一组用户(由数字、字母、下划线组成),长度限制128B |
user_info | 用户信息 | 否 | const char* | 用户资料,长度限制256个字符以内(中文数减半) |
返回字段描述(json) | ||
---|---|---|
errno及message映射 | errno | Msg |
0 | Success | |
<0 | 失败的原因 | |
返回示例 |
8.15.4 用户删除接口
方法名:user_delete
说明:用户删除(用户删除后,人脸数据也随即被删除,一个用户对应一张人脸)
函数:void user_delete(std::string&res, const char* user_id, const char* group_id)
请求参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
res | 返回的结果 | 是 | string json | 数据 |
user_id | 用户id | 是 | const char* | 用户id(由数字、字母、下划线组成),长度限制128B |
group_id | 组id | 是 | const char* | 用户组id,标识一组用户(由数字、字母、下划线组成),长度限制128B |
返回字段描述(json) | |||
---|---|---|---|
errno及msg映射 | errno | Msg | |
0 | Success | ||
<0 | 失败的原因 | ||
data字段 | log_id | string | 请求日志标识 |
返回示例 |
8.15.5 创建用户组接口
方法名:group_add
说明:创建用户组
函数:void group_add(std::string&res, const char* gourp_id)
请求参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
res | 返回的结果 | 是 | string | json 数据 |
group_id | 用户组id | 是 | const char* | 用户组id,标识一组用户(由数字、字母、下划线组成),长度限制128B |
返回字段描述(json) | |||
---|---|---|---|
errno及msg映射 | errno | msg | |
0 | Success | ||
<0 | 失败的原因 | ||
data字段 | log_id | string | 请求日志标识 |
返回示例 |
8.15.6 用户组删除接口
方法名:group_delete
说明:用户组删除
函数:void group_delete(std::string&res, const char* group_id)
请求参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
res | 返回的结果 | 是 | string | json 数据 |
group_id | 组id | 是 | const char* | 用户组id,标识一组用户(由数字、字母、下划线组成),长度限制128B |
返回字段描述(json) | |||
---|---|---|---|
errno及msg映射 | errno | msg | |
0 | Success | ||
<0 | 失败的原因 | ||
data字段 | log_id | string | 请求日志标识 |
返回示例 |
8.15.7 用户信息查询接口
方法名:get_user_info
说明:用户信息查询接口
函数:void get_user_info(std::string&res, const char* user_id, const char* group_id)
请求参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
res | 返回的结果 | 是 | string | json 数据 |
user_id | 用户id | 是 | const char* | 用户id(由数字、字母、下划线组成),长度限制128B |
group_id | 组id | 是 | const char* | 用户组id,标识一组用户(由数字、字母、下划线组成),长度限制128B |
返回字段描述(json) | |||
---|---|---|---|
errno及msg映射 | errno | msg | |
0 | Success | ||
<0 | 失败的原因 | ||
data字段 | log_id | string | 请求日志标识 |
result | array | 识别结果列表 | |
group_id | string | 组id | |
face_token | string | 人脸特征的唯一标识 | |
user_info | string | 用户信息 | |
create_time | string | 人脸首次注册时间 | |
返回示例 |
8.15.8 用户人脸图片查询接口
方法名:get_user_image
说明:用户人脸图片查询接口
函数:int get_user_image(cv::Mat & img, const char* user_id, const char* group_id)
请求参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
img | 通过引用返回的图片结果 | 是 | cv::Mat & | |
user_id | 用户id | 是 | const char* | 用户id(由数字、字母、下划线组成),长度限制128B |
group_id | 组id | 是 | const char* | 用户组id,标识一组用户(由数字、字母、下划线组成),长度限制128B |
返回字段描述 | 返回int,0为成功,其他为错误码 |
8.15.9 用户组列表查询接口
方法名:get_user_list
说明:用户组列表查询接口
函数:void get_user_list(std::string&res, const char* group_id, int start = 0, int length = 100)
请求参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
res | 返回的结果 | 是 | string | json 数据 |
group_id | 用户组id | 是 | const char* | 用户组id |
start | 查询起始序号 | 否 | int | 默认值为0 |
length | 返回数量 | 否 | int | 默认值100,最大值1000 |
返回字段描述(json) | |||
---|---|---|---|
errno及msg映射 | errno | msg | |
0 | Success | ||
<0 | 失败的原因 | ||
data字段 | log_id | string | 请求日志标识 |
user_id_list | array | user_id列表数组 | |
返回示例 |
8.15.10 群组列表查询接口
方法名:get_group_list
说明:组列表查询
函数:void get_group_list(std::string& res, int start = 0, int length = 100)
请求参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
res | 返回的结果 | 是 | string | json 数据 |
start | 起始序号 | 否 | Int | 默认值为0,从0开始 |
length | 返回数量 | 否 | Int | 默认值为100,最大为1000 |
返回字段描述(json) | |||
---|---|---|---|
errno及msg映射 | errno | msg | |
0 | Success | ||
<0 | 失败的原因 | ||
data字段 | log_id | string | 请求日志标识 |
user_id_list | array | user_id列表数组 | |
返回示例 |
8.15.11 人脸库人脸数量查询
方法名:db_face_count
说明:查询数据库人脸数量 (传入组id表示查询该组都人脸数量,null表示查整个库的人脸数量)
函数:int db_face_count(const char* group_id = nullptr)
请求参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
group_id | 组id | 是 | const char* | 人脸分组的组id(传null表示查询整个库的数量) |
返回示例 | int >=0 (返回的数量) |
8.15.12 人脸识别接口(1:N) (传入opencv图片帧)
方法名:identify
说明:人脸识别(1:N),可传入人脸组,比对某个组的所有人脸(人脸库可按单位分组,缩小组范围,减少识别比对时间)
函数:void identify(std::string&res, const cv::Mat *img, const char* group_id_list, const char* user_id, int type = 0)
参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
res | 返回的结果 | 是 | string | json 数据 |
img | opencv图片帧指针 | 是 | cv::Mat * | 人脸opencv图片帧指针 |
group_id_list | 组列表 | 是 | const char* | 组列表 |
user_id | 用户id | 否 | const char* | 用户id |
type | 特征值类型 | 否 | shi | 特征值类型(0、是生活照、1、证件照2、近红外,参考特征值提取),未传默认为0 |
返回字段描述 | ||
---|---|---|
返回字段 | 比对分值 | float |
返回示例 |
8.15.13 人脸识别接口(1:N) (传入特征值)
方法名:identify
说明:人脸识别(1:N),可传入人脸组,比对某个组的所有人脸(人脸库可按单位分组,缩小组范围,减少识别比对时间)
函数:void identify(std::string&res, Feature* f1, const char* group_id_list, const char* user_id, int type = 0)
参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
res | 返回的结果 | 是 | string | json 数据 |
f1 | 起始序号 | 是 | Feature* | 特征值结构体 |
group_id_list | 组列表 | 是 | const char* | 组列表 |
user_id | 用户id | 否 | const char* | 用户id |
type | 特征值类型 | 否 | shi | 特征值类型: 0、是生活照,包含1寸照 1、网格证件照 2、近红外,参考特征值提取) 未传默认为0 |
返回字段描述 | ||
---|---|---|
返回字段 | 比对分值 | float |
返回示例 |
8.15.14 人脸识别接口(1:N) (传入opencv图片帧)
方法名:identify_with_all
说明:人脸识别(1:N),和整个人类库比对
函数:void identify_with_all(std::string& res, const cv::Mat *img, int type = 0)
参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
res | 返回的结果 | 是 | string | json 数据 |
img | opencv图片帧 | 是 | cv::Mat * | 人脸opencv图片帧 |
type | 特征值类型 | 否 | int | 特征值类型: 0、是生活照,包含1寸照 1、网格证件照 2、近红外,参考特征值提取) 未传默认为0 |
返回字段描述 | ||
---|---|---|
返回字段 | 比对分值 | float |
返回示例 |
8.15.15 人脸识别接口(1:N) (传入特征值)
方法名:identify_with_all
说明:人脸识别(1:N),和整个人类库比对
函数:void identify_with_all(std::string& res, Feature *f1, int type = 0)
参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
res | 返回的结果 | 是 | string | json 数据 |
f1 | 起始序号 | 是 | Feature* | 特征值结构体 |
type | 特征值类型 | 否 | int | 特征值类型: 0、是生活照,包含1寸照 1、网格证件照 2、近红外,参考特征值提取) 未传默认为0 |
返回字段描述 | ||
---|---|---|
返回字段 | 比对分值 | float |
返回示例 |
8.16 sdk系统信息接口
8.16.1 获取sdk版本号接口
方法名:sdk_version
说明:通过引用返回sdk版本号
函数:void sdk_version(std::string& version)
参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
version | 返回的sdk版本号结果 | 是 | string | 如:6.3.3 |
返回字段描述 |
8.16.2 获取设备指纹接口
方法名:get_device_id
说明:通过引用返回sdk的设备指纹信息(可用来标识sdk的唯一性)
函数:void get_device_id(std::string& version)
参数 | 说明 | 必须 | 类型 | 示例描述 |
---|---|---|---|---|
device_id | 返回的sdk设备指纹结果 | 是 | string | 如:0BAF96961A8377AB74797B05F7F2C805 |
返回字段描述 |
9、功能接口对应结构体描述
9.1 人脸跟踪信息结构体
结构体名:TrackFaceInfo
说明:人脸跟踪信息结构体
struct TrackFaceInfo
{
long face_id;
FaceBox box;
Landmarks facelandmarks;
}
参数 | 类型 | 说明 |
---|---|---|
face_id | long | 人脸id |
box | FaceBox | 人脸框结构体 |
facelandmarks | Landmarks | 人脸关键点结构体 |
9.2 人脸框信息结构体
结构体名:FaceBox
说明:人脸框信息结构体
struct FaceBox
{
int index;
float center_x;
float center_y;
float width;
float height;
float angle;
float score;
}
参数 | 类型 | 说明 |
---|---|---|
index | int | 人脸索引值 |
center_x | float | 人脸中心点x坐标 |
center_y | float | 人脸中心点y坐标 |
width | float | 人脸宽度 |
height | float | 人脸高度 |
angle | float | 人脸角度 |
score | float | 人脸置信度 |
9.3 人脸关键点信息结构体
结构体名:Landmarks
说明:人脸关键点信息结构体
struct Landmarks
{
int index;
int size;
float data[144];
float score;
}
参数 | 类型 | 说明 |
---|---|---|
index | int | 人脸关键点索引 |
size | int | 人脸关键点数量(size的值通常为144,72个x,y坐标) |
data | float[144] | 人脸关键点坐标数组(144)(72个x,y坐标) |
score | float | 人脸关键点置信度 |
9.4 人脸特征值结构体
结构体名:Feature
说明:人脸特征值结构体
struct Feature
{
int size;
float data[128];
}
参数 | 类型 | 说明 |
---|---|---|
size | int | 特征值大小(通常为128个float浮点值数据) |
data | float[] | 128个浮点值数组 |
9.5 人脸姿态角结构体
结构体名:HeadPose
说明:人脸姿态角结构体
struct HeadPose
{
float yaw;
float roll;
float pitch;
}
参数 | 类型 | 说明 |
---|---|---|
yaw | float | 左右偏转角 |
roll | float | 与人脸平行平面内的头部旋转角 |
pitch | float | 上下偏转角 |
9.6 人脸属性信息结构体
结构体名:Attribute
说明:人脸属性信息结构体
struct Attribute
{
int age;
Race race;
AttributeEmotionType emotion;
Glasses glasses;
Gender gender;
}
参数 | 类型 | 说明 |
---|---|---|
age | int | 年龄 |
race | Race | 种族 enum Race { BDFace_RACE_YELLOW = 0, // 黄种人 BDFace_RACE_WHITE = 1, //白种人 BDFace_RACE_BLACK = 2, // 黑种人 BDFace_RACE_INDIAN = 3, // 印第安人 } |
emotion | AttributeEmotionType | 表情 enum AttributeEmotionType { BDFACE_ATTRIBUTE_EMOTION_FROWN = 0,//皱眉 BDFACE_ATTRIBUTE_EMOTION_SMILE = 1, //笑 BDFACE_ATTRIBUTE_EMOTION_CALM = 2, //平静 } |
glasses | Glasses | 戴眼镜状态 enum Glasses { BDFACE_NO_GLASSES = 0 , // 无眼镜 BDFACE_GLASSES = 1, // 有眼镜 BDFACE_SUN_GLASSES = 2 //墨镜 } |
gender | Gender | 性别 enum Gender { BDFACE_GENDER_FEMILE = 0, // 女性 BDFACE_GENDER_MALE = 1, // } |
9.7 嘴巴闭合结构体
结构体名:MouthClose
说明:嘴巴闭合置信度结构体
struct MouthClose
{
float score;
}
参数 | 类型 | 说明 |
---|---|---|
score | float | 置信度分值 |
9.8 口罩佩戴结构体、
结构体名:MouthMask
说明:口罩佩戴置信度结构体
struct MouthMask
{
float score;
}
参数 | 类型 | 说明 |
---|---|---|
score | float | 置信度分值 |
9.9 最优人脸置信度结构体
结构体名:Best
说明:最优人脸置信度结构体
struct Best
{
float score;
}
参数 | 类型 | 说明 |
---|---|---|
score | float | 置信度分值 |
9.10 人脸模糊度置信度结构体
结构体名:Blur
说明:人脸模糊度置信度结构体
struct Blur
{
float score;
}
参数 | 类型 | 说明 |
---|---|---|
score | float | 置信度分值 |
9.11 人脸光照置信度结构体
结构体名:Illumination
说明:光照置信度结构体
struct Illumination
{
int score;
}
参数 | 类型 | 说明 |
---|---|---|
score | int | 置信度分值 |
9.12 人脸遮挡置信度结构体
结构体名:Illumination
说明:人脸遮挡置信度结构体
struct Illumination
{
float left_eye;
float right_eye;
float nose;
float mouth;
float left_cheek;
float right_cheek;
float chin;
}
参数 | 类型 | 说明 |
---|---|---|
left_eye | float | 左眼遮挡置信度 |
right_eye | float | 右眼遮挡置信度 |
nose | float | 鼻子遮挡置信度 |
mouth | float | 嘴巴遮挡置信度 |
left_cheek | float | 左脸遮挡置信度 |
right_cheek | float | 右脸遮挡置信度 |
chin | float | 下巴遮挡置信度 |
9.13 人眼闭合状态结构体
结构体名:EyeClose
说明:人眼闭合状态结构体
struct EyeClose
{
float left_eye_close_conf;
float right_eye_close_conf;
}
参数 | 类型 | 说明 |
---|---|---|
float | left_eye_close_conf | float |
float | right_eye_close_conf | float |
9.14 注意力结构体
结构体名:GazeInfo
说明:注意力结构体
struct GazeInfo
{
Gaze left_eye;
Gaze right_eye;
}
struct Gaze
{
GazeDirection direction; // 凝视方向
float confidence; // 置信度
}
struct GazeDirection
{
BDFACE_GAZE_DIRECTION_UP = 0, // 向上看
BDFACE_GAZE_DIRECTION_DOWN = 1, // 向下看
BDFACE_GAZE_DIRECTION_RIGHT = 2, // 向右看
BDFACE_GZE_DIRECTION_LEFT = 3, // 向左看
BDFACE_GAZE_DIRECTION_FRONT = 4, // 向前看
BDFACE_GAZE_DIRECTION_EYE_CLOSE = 5, // 闭眼
}
参数 | 类型 | 说明 |
---|---|---|
left_eye | Gaze | 左眼注意力 |
right_eye | Gaze | 右眼注意力 |
9.15 静默活体置信度结构体
结构体名:LivenessScore
说明:活体信度结构体
struct LivenessScore
{
int score;
}
参数 | 类型 | 说明 |
---|---|---|
score | float | 置信度分值 |
10、多端特征值对齐
对于windows sdk来说,支持和安卓特征值对齐,windows sdk6.x系列,特征值对齐安卓6.x系列,但和如安卓7.x系列或5.x系列,则不对齐,且只支持rgb可见光特征值对齐。
在windows c++ sdk中,可通过提取的特征值128个float
数组,保存成二进制数据,即和安卓中的512个byte保存成字节流的数据对齐。
sdk中提供了float
数组转换为二进制buffer
的示例代码以及二进制buffer
数据转换为特征值float
数组的示例代码。可参考util
文件夹中的FeatureAlign
类。
11、适配的深度双目摄像头特别说明
sdk自带了奥比中光以及华捷艾米的双目摄像头,支持rgb+depth
,同时也支持迪威泰或视派尔的rgb+nir
双目摄像头,奥比中光或华捷艾米的双目摄像头,需要安装驱动,在sdk目录的tools
->camera_driver
里面,分别双击安装即可(奥比的驱动对应orbe
目录,华捷艾米的对应hjimi
,注意双击安装后可能需要重启设备生效),安装完毕后,可参考示例demo接入奥比或华捷的双目摄像头进行活体检测。因为sdk需要用动态库dll
,所以需要根据您的x64或x86平台,分别拷贝奥比或华捷的dll里面的所有文件到sdk的exe
目录所在文件夹里面,才能保证镜头模组能够正常运行(若未拷贝,运行sdk会提示找不到对应的如奥比或华捷的动态库dll
文件)。若运行镜头模组的时候还提示找不到依赖,可选择奥比的镜头时候安装一下vc_redist.exe(vs2013
的依赖库,可微软官网查找下载)。华捷艾米的则可能需要安装vc_redist.exe(vs2010
的依赖库,可微软官网查找下载)
12、错误码及错误信息
各接口返回结果error_code
及msg
信息如下:
错误码 | 错误内容 | 错误描述 |
---|---|---|
0 | SUCCESS | 成功 |
-1 | ILLEGAL_PARAMS | 失败或非法参数 |
-2 | MEMORY_ALLOCATION_FAILED | 内存分配失败 |
-3 | INSTANCE_IS_EMPTY | 实例对象为空 |
-4 | MODEL_IS_EMPTY | 模型内容为空 |
-5 | UNSUPPORT_ABILITY_TYPE | 不支持的能力类型 |
-6 | UNSUPPORT_INFER_TYPE | 不支持的预测库类型 |
-7 | NN_CREATE_FAILED | 预测库对象创建失败 |
-8 | NN_INIT_FAILED | 预测库对象初始化失败 |
-9 | IMAGE_IS_EMPTY | 图像数据为空 |
-10 | ABILITY_INIT_FAILED | 人脸能力初始化失败 |
-11 | ABILITY_UNLOAD | 人脸能力未加载 |
-12 | ABILITY_ALREADY_LOADED | 人脸能力已加载 |
-13 | NOT_AUTHORIZED | 未授权 |
-14 | ABILITY_RUN_EXCEPTION | 人脸能力运行异常 |
-15 | UNSUPPORT_IMAGE_TYPE | 不支持的图像类型 |
-16 | IMAGE_TRANSFORM_FAILED | 图像转换失败 |
-1001 | SYSTEM_ERROR | 系统错误 |
-1002 | PARARM_ERROR | 参数错误 |
-1003 | DB_OP_FAILED | 数据库操作失败 |
-1004 | NO_DATA | 没有数据 |
-1005 | RECORD_UNEXIST | 记录不存在 |
-1006 | RECORD_ALREADY_EXIST | 记录已经存在 |
-1007 | FILE_NOT_EXIST | 文件不存在 |
-1008 | GET_FEATURE_FAIL | 提取特征值失败 |
-1009 | FILE_TOO_BIG | 文件太大 |
-1010 | FACE_RESOURCE_NOT_EXIST | 人脸资源文件不存在 |
-1011 | FEATURE_LEN_ERROR | 特征值长度错误 |
-1012 | DETECT_NO_FACE | 未检测到人脸 |
-1013 | CAMERA_ERROR | 摄像头错误或不存在 |
-1014 | FACE_INSTANCE_ERROR | 人脸引擎初始化错误 |
-1015 | LICENSE_FILE_NOT_EXIST | 授权文件不存在 |
-1016 | LICENSE_KEY_EMPTY | 授权序列号为空 |
-1017 | LICENSE_KEY_INVALID | 授权序列号无效 |
-1018 | LICENSE_KEY_EXPIRE | 授权序序列号过期 |
-1019 | LICENSE_ALREADY_USED | 授权序列号已被使用 |
-1020 | DEVICE_ID_EMPTY | 设备指纹为空 |
-1021 | NETWORK_TIMEOUT | 网络超时 |
-1022 | NETWORK_ERROR | 网络错误 |
13、常见问题:
- sdk推荐使用vs2015 community或professional版本进行开发。若未安装该ide想运行sdk中的exe,可能需要安装vc运行环境,请参考sdk目录的vc_redist文件夹的exe双击安装,根据平台选择x64或x86安装。
- 工程运行过程中,若不能正常运行功能,可在sdk的x64或win32目录下,把face_conf.json中字段false修改为true为打开日志模式,通过日志输出及各接口返回的错误码判断问题所在。
- 模型文件可定制化:在main方法入口,可在sdk_init方法中传入模型文件夹的绝对路径,达到模型文件定制化的目的。若不定制化路径,sdk_init中传入null即可,默认模型文件在bin目录的models文件夹里面,无需更改。
- 激活后是否可以把激活文件license.ini和license.key拷贝到其他设备运行?
不能,离线sdk和设备绑定,每个设备对应一个key和一个license文件,换设备无法运行。但对同一台设备,可把Release下的license.ini和license.key拷贝到本电脑的另外sdk,该设备也等同于激活,可以使用。 - 是否支持debug模式?
只支持Release模式,不支持debug模式 - sdk支持x64和x86两种模式,推荐使用x64模式。支持运行在win7或win10系统中。
- 人脸库不支持中文参数?
用户信息user_info支持中文,其他人脸管理参数目前暂只支持英文、数字下划线组合模式,工程所在的路径也建议不用放入中文路径中,可能影响人脸库创建。 - 特征值多端是否对齐?
在人脸6.0系列sdk中,win端,安卓和linux端生活照模式下的特征值都是对齐的。win中请把提取出来的128个float数据保存成二进制数据即可和安卓的512个byte二进制数据对齐。 - 老版本的接口如4.1、4.2和新版本6.0为啥差别比较大?
新版本对原子接口进行了封装,更易用,若想使用老版本的接口,可参考face_scene.cpp文件。 - sdk的依赖库是否可以删减?
新版支持sdk的依赖库进行精简,详细可参考文档说明。 - sdk是否支持多线程运行?
sdk不推荐采用多线程运行。 - sdk是否支持二进制转opencv mat以及base64字符串的转换?
sdk中的util文件夹里提供了大量转换示例代码,可参考查看。 - 生活照和证件照模式有啥区别,是否可切换使用?
sdk中,即使是1寸,2寸的证件照,比对或提取特征值也推荐用生活照模式处理,sdk中的证件照模式通常用作有网纹(比如身份证上带网格的),sdk中选择用了生活照模式,则所有接口都必须用该模式,