版本日志

目录

1、简介
   1.1 产品概述
   1.2 规格信息
   1.3 兼容性
   1.4 授权方式
   1.5 产品定价
2、SDK详细介绍
   2.1 名词解释
   2.2 SDK简介
   2.3 SDK文件结构
   2.4 激活工具
   2.5 Demo示例工程
   2.6 特征抽取模型选择
3、功能接口
   3.1 人脸检测及设置
       3.1.1 人脸检测track接口(传入图片)
       3.1.2 人脸检测track接口(传入二进制图片buffer)
       3.1.3 人脸检测track_max_face接口
       3.1.4 人脸检测track_max_face接口(传入二进制图片buffer)
       3.1.5 人脸检测设置接口
       3.1.6 USB摄像头检测
       3.1.7 人脸检测track接口(传入opencv的mat)
   3.2 人脸对比及识别接口
       3.2.1 人脸对比接口
       3.2.2 人脸对比接口（传入二进制图片buffer）
   3.3 特征值提取接口
       3.3.1 特征值提取接口（通过传入图片）
       3.3.2 特征值提取接口（通过传入二进制图片buffer）
       3.3.3 特征值提取接口（通过传入opencv的视频帧）
       3.3.4 特征值比对接口
   3.4 属性及质量接口
   	   3.4.1 人脸属性（通过传入图片）
   	   3.4.2 人脸属性（通过传入二进制图片buffer）
   	   3.4.3 人脸质量接口（通过传入图片）
   	   3.4.4 人脸质量接口（通过传入二进制图片buffer）
4、错误码及错误信息
5、常见问题

1、简介

1.1 产品概述

人脸离线识别SDK，包含人脸采集、活体检测、人脸对比/识别、人脸库管理等能力，并全部离线化、本地化。此SDK一经授权激活，可完全在无网环境下工作，所有数据皆在设备本地运行处理，可根据业务需要进行灵活的上层业务开发。核心能力分布如下图所示，后文会详细介绍。

适用场景特点

• 网络：无网、局域网等情况，无法连接公网。如政府单位、金融保险、教育机构等。
• 安全：行业特点所带来的人脸数据敏感性，即使可以连接公网也不可请求。
• 速度：由于各地网络线路、机房部署等诸多原因，网络请求速度存在不可控因素。
• 稳定：需要尽可能避免网络抖动、机房故障等影响，进一步控制可用性影响因素。

1.2 规格信息

• 包大小：~500M
• 最小人脸检测大小：50px * 50px
• 可识别人脸角度：yaw ≤ ±30°, pitch ≤ ±30°
• 检测速度：100ms 720p*
• 追踪速度：30ms 720p*
• 人脸检测耗时：~= 100ms

备注：以上指标，由最新版SDK运行在真实设备上，采用真实数据集所得，但算法性能受实际运行设备、实际数据集等情况影响，以上数字仅供参考。

• 提供一个鉴权激活工具：tool_ubuntu.sh、tool_centos.sh，可根据平台选择对应的sh文件运行

1.3 兼容性

• Centos6.3 gcc4.8.2 以及 Ubuntu16.04 gcc5.4.0上编译
• 推荐基于vs2015进行开发

1.4 授权方式

按设备授权

离线识别SDK授权方式为以设备维度为主，每台硬件设备需要一个独立的授权，此授权的校验是基于设备的硬件指纹（指纹的获取SDK初始化时会自动读取并展示），被授权的设备，将在有效期内可以运行SDK。

重新拉取授权的情况：设备授权不变，仅需要重新激活而已。

• 删除SDK或基于SDK开发的应用
• 重新安装Windows系统

授权失效的情况：需要重新购买序列号，之前的序列号失效。

• 激活一台设备后，此设备硬件变更
• 硬件损坏

序列号

序列号为管理授权的依据。每台被授权的设备，都将对应一个序列号，用于标识对应的设备信息及授权记录。序列号的形式为16位随机英文数字组合，如：3G59-M5JK-889A-7LQA。您在管理后台购买SDK授权时，购买成功后系统将会发放对应数量的序列号。序列号不限制平台版本，任何开发平台的离线SDK，都可以使用此序列号激活。序列号不限制账号，可供任何设备激活使用。

激活

已购买的序列号，是用于激活的唯一凭证，激活流程主要是将序列号与具体的硬件进行绑定（硬件指纹），从而生成对应硬件设备的授权文件（License），SDK运行前，将会校验授权文件是否和实际硬件信息相匹配。

注意：激活时，设备系统时间需要和当前时间一致，如果差距太大（例如偏差5min以上），激活则无法完成。

联网激活

此种激活方式，适用于设备可首次联网的情况，优势在于激活过程极为简单。您只需将SDK安装到需要激活的设备上，然后填写已经购买的序列号，在界面上点击激活即可（为使用方便，我们为您设计了一个简单的激活用户界面）

1. 获取序列号：从管理后台购买获取序列号。
2. SDK中填写序列号：将序列号填写到SDK的可视化界面中。
3. 启动激活：点击「激活」按钮。
4. SDK自动激活：SDK自动拉取授权文件并完成授权，激活完毕。

如激活成功，将会立即在界面上有明确的弹窗提示，请留意查看；如激活失败，也会反馈具体的错误信息。

离线激活

此种激活方式，适用于设备完全不可联网的情况，优势在于可避免联网激活，满足业务对网络的严格要求，以及设备批量注册需求。您需要在后台配置好硬件指纹并完成和序列号的绑定，然后将授权文件放到SDK的指定位置。

1. 获取序列号：从管理后台购买获取序列号。
2. 采集硬件指纹：将SDK置于设备上，运行激活程序，获取硬件指纹。
3. 配置授权：在后台将硬件指纹绑定到具体序列号上。
4. 下载授权文件：绑定成功后下载授权文件。
5. 设备激活：将授权文件放到SDK中，并初始化SDK完成授权。

授权有效期

申请通过后，每个账户给2个测试序列号，用于激活及SDK试用，有效期为自激活日期后的3个月。这两个序列号在有效期内完全免费，您可以用于进行产品试用。试用期到期后也可以在后台申请延期，填写具体延期理由即可。

正式购买

正式购买的序列号，试用期限为永久有效。此「永久」是指绑定到具体设备维度，但如已绑定的硬件设备变更后，授权则可能会失效。

1.5 定价方式

离线SDK的授权基于设备维度，每个序列号仅可以授权一台设备。每个账号购买的序列号会累计计算，累计购买量越多，单价越便宜。具体如下所示：

立即去购买

2、SDK详细介绍

2.1 名词解释

2.2 SDK简介

本SDK适应于Linux（Centos、Ubuntu）平台下的人脸识别系统,分别在Centos6.3 gcc4.8.2 以及Ubuntu16.04 gcc5.4.0上编译（其他版本或平台的linux不保证兼容）。SDK采用动态库so方式提供给开发者，另外随sdk附带一个鉴权激活工具（可运行脚本 tool-ubuntu.sh或tool-centos运行，这2文件分别对应不同的OS），通过该激活工具可生成正常接入SDK的激活license文件（生成两个文件license.ini和license.key）达到通过鉴权，正常使用SDK的目的。

2.3 SDK文件结构

Sdk提供动态库BaiduFaceApi.so及头文件baidu_face_api.h。另外有附带的demo例子代码test-face-api以及鉴权激活工具tool。在此之外，还附带支撑sdk使用的人脸识别模型文件等在文件夹face-resource中，该文件夹在test-face-api例子工程里面(该文件夹存放路径请参考test-face-api，默认存放路径为您要开发的可执行文件路径同一目录下。若存放不对，可能会影响sdk正常使用,另外请勿删除该文件夹)。

为运行您开发的可执行文件，需要用到一些底层的库文件支持,相关库文件在test-face-api的lib3目录中（主要有opencv库，ffmpeg库，json，curl库等）。此外，随工程还有一些编译用的Makefile文件及sh脚本文件等，可通过Makefile编译工程，sh脚本文件运行编译的可执行文件。Makefile文件分别命名为Makefile_centos6.3及Makefile_ubuntu，若要编译相应平台版本，请把他重命名为Makefile。

2.4 激活工具（tool）

在百度官网申请系列号Key后，在test-face-api工程下有个tool_ubuntu.sh和tool_centos.sh。可根据您的OS平台选择对应sh文件运行，在运行之前，先修改脚本文件的最后一行，把如05QU-ATMA-SCWY-CAUB字样的key修改为您在百度官网申请到的key，然后再运行sh脚本文件（若是centos平台，输入sh tool_centos.sh即可）。激活成功后会在激活目录生成license.ini以及license.key文件，这2个文件是作为sdk通过鉴权使用的配置文件，请勿删除。

如果你不方便使用网络，可以通过离线激活进行操作：

通过如上的激活工具，获取到设备指纹信息，通过序列号管理后台找到需要绑定的序列号，选择「离线激活」，填入指纹设备信息，即可下载获取到license.ini文件和license.key文件，把这2个文件拷贝到test-face-api目录下，运行可执行文件亦可通过鉴权。

2.5 Demo示例工程

Demo示例工程代码在test-face-api中的cpp目录里面，其中的test_face.cpp里面有入口方法main()，展示了如何集成百度人脸识别离线SDK。即正确编写Makefile文件及引入头文件include以及对应的一些库文件。另外为了示例视频人脸跟踪等，用到了一些opencv的库文件以及一些实现demo的支持文件，如json等。（这些支持文件均为代码开源或是开源库）

在test-face-api中的test_face.cpp的main()方法中，有使用sdk的各个接口方法示例。接入sdk及其简单，分3步3行代码。如下：

BaiduFace *api = new BaiduFaceApi(); 
// 第一步：实例化人脸SDK

api->sdk_init();                     
// 第二步：初始化人脸SDK

std::string res = api->face_attr(“方法的传入参数，此处省略”);
// 第三步，调用功能接口，user_add为人脸注册接口，res为调用功能接口后的返回。

如上，即为调用sdk功能的最简单3步3行代码，当然调用SDK后，在程序退出后，需要释放sdk防止内存泄漏，需要删除SDK实例化的指针delete api;

示例工程中：分别有以下几个示例cpp文件对应几个常用sdk的调用demo。

2.6 特征抽取模型选择

模型介绍

v1.1版本起，SDK提供生活照和证件照两种特征抽取模型，主要适用场景如下:

• 生活照模型：如手机拍摄的图片、较为清晰的证件照片、USB镜头实时采集的图片、网络摄像头实时采集的图片等。
• 证件照模型：如身份证芯片照、各类证件照（工卡、学生卡、会员卡照片等）、人脸的像素普遍小于80px的图片等。

使用方法

在SDK初始化方法中控制：sdk_init(true); //传入true为使用证件照模型，传入fasle为普通生活照模型

注意事项

温馨提示：一经选择一个模型，则所有业务流程的特征抽取处理，都会使用此模型，两个模型不可同时作用。如业务中设计证件照的特征抽取，请务必选择使用证件照模型。

3、功能接口

SDK实现的主要功能有人脸实时跟踪检测、人脸特征值提取、1:1人脸对比、特征值的比对和通过USB或笔记本自带摄像头检测视频帧，返回识别出的人脸信息等，另外支持对人脸检测进行设置，达到根据设置进行识别的目的。各接口功能及传入参数和返回结果（返回结果一般为json格式的字符串）描述如下：

3.1 人脸检测及设置

3.1.1 人脸检测track接口(传入图片)

方法名

track

方法说明

人脸检测，返回人脸信息

请求信息

返回信息

返回结果为int，表示检测到几个人脸信息，1为1个人，0为没检测到人脸。

3.1.2 人脸检测track接口(传入二进制图片buffer)

方法名

track_by_buf

方法说明

人脸检测，返回人脸信息

请求信息

返回信息

返回结果为int，表示检测到几个人脸信息，1为1个人，0为没检测到人脸。

3.1.3 人脸检测track_max_face接口

方法名

track_max_face

方法说明

检测最大人脸。

请求信息

返回信息

返回结果为int，表示检测到几个人脸信息，1为1个人，0为没检测到人脸。

3.1.4 人脸检测track_max_face接口(传入二进制图片buffer)

方法名

track_max_face_by_buf

方法说明

检测最大人脸。

请求信息

返回信息

返回结果为int，表示检测到几个人脸信息，1为1个人，0为没检测到人脸。

3.1.5 人脸检测设置接口

请参考SDK工程中的代码示例及头文件baidu_face_api.h中的定义及setting.cpp里的代码注释。

3.1.6 USB摄像头检测

请参考TestFaceApi中的示例liveness.cpp中的usb_track_face_info，该方法中用到了人脸检测track视频帧，接口如下3.1.7：

3.1.7 人脸检测track接口(传入opencv的mat)

方法名

Track

方法说明

人脸检测，返回人脸信息。

请求信息

返回信息

返回结果为TrackedFaceInfo的向量指针,向量组为0时候表示没检测到人脸。TrackedFaceInfo结构体为检测到的人脸信息，其中：box为检测到的人脸框（为FaceInfo结构体,包含人脸框大小，中心点坐标，人脸宽度等信息）；landmarks为检测到的人脸关键点，一般为144个；score为人脸打分；headPose的向量组为人脸x,y,z的三个角度。

3.2 人脸对比及识别接口

3.2.1 人脸对比接口

方法名

match

方法说明

人脸对比接口（本接口中的image_type为1表示base64图片编码，为2表示文件路径，为3表示face_token）

请求信息

返回信息

errno信息：

• errno=0 : Success
• errno>0 : 错误码对应的详细msg

data信息:

3.2.2 人脸对比接口（传入二进制图片buffer）

方法名

match_by_buf

方法说明

人脸对比接口（传入二进制图片buffer）

请求信息

返回信息

errno信息：

• errno=0 : Success
• errno>0 : 错误码对应的详细msg

data信息:

3.3 特征值提取接口

3.3.1 特征值提取接口（通过传入图片）

方法名

get_face_feature

方法说明

提取人脸特征值，为512个浮点值，已加密 (本接口image_type 为1表示base64图片编码 为2表示文件路径)

请求信息

返回信息

errno信息：

• errno=0 : Success
• errno>0 : 错误码对应的详细msg

data信息:

int类型的特征抽取向量数。正常提取成功则返回特征值向量个数（512），若不为512则为返回的错误码.

3.3.2 特征值提取接口（通过传入二进制图片buffer）

方法名

get_face_feature_by_buf

方法说明

提取人脸特征值，为512个浮点值，已加密 (传入二进制图片buffer)

请求信息

返回信息

errno信息：

• errno=0 : Success
• errno>0 : 错误码对应的详细msg

data信息:

int类型的特征抽取向量数。正常提取成功则返回特征值向量个数（512），若不为512则为返回的错误码.

3.3.3 特征值提取接口（通过传入opencv的视频帧）

方法名

get_face_feature

方法说明

提取人脸特征值，为512个浮点值，已加密 (本接口image_type 为1表示base64图片编码 为2表示文件路径)

请求信息

返回信息

errno信息：

• errno=0 : Success
• errno>0 : 错误码对应的详细msg

data信息:

int类型的特征抽取向量数。正常提取成功则返回特征值向量个数（512），若不为512则为返回的错误码.

3.3.4 特征值比对接口

方法名

compare_feature

方法说明

对人脸特征值进行比较，可返回人脸特征相似分值（百分制）

请求信息

返回信息

errno信息：

• errno=0 : Success
• errno>0 : 错误码对应的详细msg

data信息:

相似度结果：float类型，百分制的分值

3.4 属性及质量检测接口

3.4.1 人脸属性（通过传入图片）

方法名

face_attr

方法说明

人脸属性检测接口(本接口 image_type 为1表示base64图片编码 为2表示文件路径)

请求信息

返回信息

errno信息：

• errno=0 : Success
• errno>0 : 错误码对应的详细msg

data信息:

3.4.2 人脸属性（通过传入二进制图片buffer）

方法名

face_attr_by_buf

方法说明

人脸属性检测接口

请求信息

返回信息

errno信息：

• errno=0 : Success
• errno>0 : 错误码对应的详细msg

data信息:

3.4.3 人脸质量接口（通过传入图片）

方法名

face_quality

方法说明

人脸质量检测接口

请求信息

返回信息

errno信息：

• errno=0 : Success
• errno>0 : 错误码对应的详细msg

data信息:

3.4.4 人脸质量接口（通过传入二进制图片buffer）

方法名

face_quality_by_buf

方法说明

人脸质量检测接口

请求信息

返回信息

errno信息：

• errno=0 : Success
• errno>0 : 错误码对应的详细msg

data信息:

4、错误码及错误信息

5、常见问题

Q：激活工具激活时候，提示timeout或者unsupport protocl
A：若提示timeout，请确认设备是否能联网；若提示unsupport protocl，请确认是否安装了openssl。

Q：工程运行过程中，提示face-resource不存在
A：SDK需要一些模型文件，在demo工程的face-resource文件夹中，该文件夹需要放置在exe所在路径的上级目录下。若放置不正确，可能出现找不到模型文件，没法进行人脸识别。

Q：工程激活过程中，提示segment fault
A：这是因为工程若没有激活，便直接执行脚本文件运行可执行文件，请先完成激活操作。

Q：激活后是否可以把激活文件license.ini和license.key拷贝到其他设备运行？
A：不能，离线sdk和设备绑定，每个设备对应一个key和一个license文件，换设备无法运行。