版本日志

目录

1、简介
   1.1 SDK基础信息
       1.1.1 产品概述
       1.1.2 规格信息
       1.1.3 兼容性
       1.1.4 授权方式
       1.1.5 产品定价
   1.2 功能介绍
       1.2.1 人脸检测与追踪
       1.2.2 质量控制
       1.2.3 人脸采集
       1.2.4 离线RGB可见光活体检测
       1.2.5 离线NIR近红外活体检测
       1.2.6 离线Depth深度图像活体检测（3D结构光）
       1.2.7 离线1：1对比
       1.2.8 离线1：N搜索
       1.2.9 离线人脸库管理
   1.3 业务逻辑
   	   1.3.1 通用流程概述
   	   1.3.2 活体检测
   	   1.3.3 人脸对比
   	   1.3.4 人脸搜索
   1.4 设备选型
       1.4.1 镜头模组选择
       1.4.2 机器选择
   1.5 方案选型
       1.5.1 使用离线SDK
       1.5.2 使用采集SDK+API
       1.5.3 使用离线SDK+API
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.2 人脸管理接口
       3.2.1 人脸注册接口
       3.2.2 人脸注册接口（传入二进制图片buffer）
       3.2.3 人脸更新接口
       3.2.4 人脸更新接口（传入二进制图片buffer）
       3.2.5 人脸删除接口
       3.2.6 用户删除接口
       3.2.7 创建用户组接口
       3.2.8 用户组删除 
       3.2.9 用户信息查询接口
       3.2.10 用户组列表查询接口
       3.2.11 组列表查询接口
   3.3 人脸对比及识别接口
       3.3.1 人脸对比接口
       3.3.2 人脸对比接口（传入二进制图片buffer）
       3.3.3 人脸对比接口（传入二进制图片buffer和特征值feature比对）
       3.3.4 人脸识别identify接口
       3.3.5 人脸识别identify接口（传入二进制图片buffer）
       3.3.6 特征值提取接口（通过传入图片）
       3.3.7 特征值提取接口（传入二进制图片buffer）
       3.3.8 特征值比较接口
   3.4 活体检测接口
       3.4.1 可见光(RGB)活体检测接口（通过传入图片）
       3.4.2 可见光(RGB)活体检测接口（通过传入二进制图片buffer）
       3.4.3 可见光(RGB)&近红外(NIR)活体检测接口（通过传入二进制图片buffer）
       3.4.4 可见光(RGB)&近红外(NIR)活体检测接口（通过sdk底层打开opencv视频帧）
       3.4.5 可见光(RGB)&深度(Depth)活体检测接口（通过传入二进制图片buffer）
       3.4.6 可见光(RGB)&深度(Depth)活体检测接口（通过sdk底层打开opencv视频帧）
   3.5 质量接口
   	   3.5.1 人脸质量接口（通过传入图片）
   	   3.5.2 人脸质量接口（通过传入图片二进制buffer）
4、适配的深度双目摄像头特别说明
5、错误码及错误信息
6、常见问题

1、简介

1.1 SDK基础信息

1.1.1 产品概述

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

适用场景特点

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

1.1.2 规格信息

• 包大小：~ 500M
• 最小人脸检测大小：50px * 50px
• 可识别人脸角度：yaw ≤ ±30°, pitch ≤ ±30°
• 检测速度：100ms 720p*
• 追踪速度：30ms 720p*
• 人脸检测耗时：< 100ms
• RGB图片特征抽取耗时：< 300ms
• RGB活体检测耗时：< 200ms
• 近红外活体检测耗时：< 50ms
• 1万本地人脸库检索速度：< 400ms

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

• SDK采用动态库dll方式提供
• 提供一个鉴权激活工具：LicenseTool.exe

1.1.3 兼容性

• x86、x64两个版本，支持Win7、Win10
• 推荐基于vs2015进行开发

1.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.1.5 定价方式

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

立即去购买

1.2 功能介绍

1.2.1 人脸检测与追踪

可在设备端，离线实时检测视频流中的人脸。同时支持处理静态图片或者视频流，并对当前检测到的人脸持续跟踪，动态定位人脸轮廓，稳定贴合人脸。

1.2.2 质量控制

在人脸检测及追踪过程中，实时校验人脸的姿态角度、遮挡、清晰度、光照条件，符合质量条件的人脸图片才会被采集。

1.2.3 人脸采集

针对视频流实时完成人脸图片采集，并输出满足质量过滤条件的人脸图片，可自定义采集人脸大小，采集频率，采集质量等设置。

1.2.4 离线RGB可见光活体检测

针对视频流/图片，通过采集人像的破绽（摩尔纹、成像畸形等）来判断目标对象是否为活体，可有效防止屏幕二次翻拍等作弊攻击，可使用单张或多张判断逻辑。

1.2.5 离线NIR近红外活体检测

针对视频流/图片，利用近红外成像原理，实现夜间或无自然光条件下的活体判断。其成像特点（如屏幕无法成像，不同材质反射率不同等）可以实现高鲁棒性的活体判断。

1.2.6 离线Depth深度图像活体检测（3D结构光）

通过3D建模判断目标对象是否为活体，基于3D结构光成像原理，可强效防御图片、视频、屏幕、模具等攻击。

1.2.7 离线1：1对比

提供本地化的1：1人脸对比功能，高鲁棒性算法，可对应各种姿态、肤色、光照等场景，可有效应用于人证比对、身份核验等场景。

示例工程中包含：

• 图片与图片的比对：两张人脸图片的1：1对比，并返回相似度分值。
• 图片与视频流比对：一张预设的人脸图片，和摄像头实时采集的符合条件的人脸图片进行对比。

1.2.8 离线1：N搜索

本地数据库中保留所有人脸特征值（如需要保留原图，可根据业务需要自行修改工程）。

• 视频流采集的人脸在人脸库中搜索：视频流中实时采集人脸，并与人脸库中预设的人脸库进行一一对比，返回相似度最高的user及对应分值。

1.2.9 离线人脸库管理

人脸数量不做上限，可根据业务需要适当调整，支持人脸库、人脸组、用户、Face几个维度的增删改查设置。

1.3 业务流程

1.3.1 通用流程概述

如上图所示，人脸识别的核心业务流程可以分为三个步骤。

1. 检测采集：通过视频流实时检测跟踪，并采集到符合质量要求的人脸图片，用于后续的识别。
2. 活体判断：为可选步骤，主要保障业务操作者为真人，避免业务作弊。加上这步的校验，即只有满足活体判断通过，人脸图片才会被采集。
3. 对比识别：1：1对比主要是判断「你是你」，用于核实身份的真实性；1：N搜索主要判断「你是谁」，用于明确身份的具体所属。

1.3.2 活体检测

提示：此版本仅支持RGB可见光活体、NIR近红外活体。Depth深度活体将会尽快推出

1.3.2.1 基础原理

• RGB可见光活体：主要基于图片破绽，判断目标对象是否为活体。例如图像中的屏幕反光、成像畸形等，最主要的应用情形为屏幕的二次翻拍等攻击防御。此种活体对于待检测图片的要求，主要需要满足画面中除了人脸以外，要尽可能保留一些背景内容，用于查找破绽，通常建议人脸与屏幕的长宽比为1：3。为控制达到此比例，建议通过调整最小检测人脸参数，控制采集的人脸不可过大，避免人脸面积占比过高，而导致图片中没有多少背景信息。同时RGB活体受光线影响较大，所以在强光、暗光等场景，容易数值波动较大，主要影响的是「通过率」，产品策略上需要通过适当的补光、使用宽动态镜头抵消逆光等方式缓解。
• NIR近红外活体：主要基于近红外光线反射成像原理，通过人脸呈现来判断是否为活体。即使是夜间或者没有自然光的情况下，依然可以判断活体。因为其成像特点，对于屏幕、图片等攻击形式，基本可以达到近似于100%的活体防御。同时近红外设备的成本，相对性价比更高。
• Depth深度活体（3D结构光）：结构光原理是通过主动光发射，在物体上形成光栅，并接受此信息进行活体分析。同样可以不需要自然光。3D结构光的成像更为稳定，抗攻击能力更强，对图像噪声的抗干扰能力也更强，是相对更加安全和稳定的方案，但相应的硬件设备造价也较高，需要根据实际业务成本预算，进行综合考虑。

以上，无论活体是否可以通过，我们业务的最终目的，还是要进行「对比识别」，所以拿到合适的RGB图像还是最为关键，保障符合条件的RGB图像获取也是需要在活体判断同时，最为需要关注的事情。

在实际业务场景中，需要根据场景特点，灵活组合使用以上几种活体方案。当然，实际业务中，没有绝对100%的安全，在应用过程中，还需要根据业务流程特点，指定一系列的辅助措施，如证件信息读取、密码、其他生物特征识别等，达到刚安全的核验。

1.3.2.2 产品应用策略

活体判断逻辑简单理解为：满足活体条件才可以采集图片，否则一直反复判断，直到满足活体条件为止。因为我们最终送去识别的图片是RGB图片，所以需要保证活体通过时，在同一时间采集RGB图片，才可真正防止作弊攻击。当多种活体叠加使用时，需要满足所有活体都通过，才能出发此操作，如果有任一活体没有通过，都不可进入识别步骤。

1.3.2.3 场景及应用方案

• 通行场景：此场景通常保障通行速度为主，确保不影响通行秩序和效率。所以建议无需使用三重活体检测，可仅用NIR活体或Depth活体，保障效率同时仍可保证安全性。
• 身份核验场景：此场景通常保障业务安全性为主，可尽可能提供更加安全的活体方案。如RGB+NIR，或者RGB+Depth，乃至RGB+NIR+Depth，最大程度确保对攻击的拒绝率较高。
• 强光/暗光场景：光线较强的场景，RGB活体会受影响比较严重，建议使用NIR或者Depth活体，同时尽量通过产品策略避免这两种情况的光线，例如添加补光灯、配备遮光板等。

1.3.2.4 应用方案及模组选择

• 无需活体：如有人值守的场景下，活体检测并无太大的必要（活体检测也会增加额外的业务耗时），现有设备的单目USB摄像头即可。
• 仅用RGB可见光活体：如果您的设备已经配备了USB单目摄像头，则无需更换，输出的RGB图像可直接用于RGB可见光活体算法识别。
• RGB可见光+NIR近红外活体：需要配备能够同时获取RGB、NIR近红外数据的镜头使用。
• RGB可见光+Depth深度活体：需要配备能够同时获取RGB、Depth深度图像数据的镜头使用。
• RGB可见光+NIR近红外+Depth深度活体：此种方式安全度最高，目前SDK正在模组适配中，后续会陆续推出已适配的模组方案，敬请期待。

1.3.2.4 指标

活体检测存在几个标准的指标，如下所示：

• 拒绝率（TRR）：如99%，代表100次作弊假体攻击，会有99次被拒绝。
• 误拒率（FRR）：如0.5%，指1000次真人请求，会有5次因为活体分数低于阈值被错误拒绝。
• 通过率（TAR）：如99%，指100次真人请求，会有99次因为活体分数高于阈值而通过。
• 阈值（Threshold）：高于此数值，则可判断为活体。

温馨提示：此SDK涉及多种离线活体检测模型，加上镜头模组效果各异，使用环境也较为复杂，以下给出综合测试值，仅供参考：

• 拒绝率：> 99.5%
• 误拒率：< 1%
• 通过率：> 99%

1.3.2.4 阈值选择推荐

活体分值区间为[0~1]，大部分情况的活体攻击，活体分值近似于接近0.0，建议阈值如下，高于此阈值的即可判断为活体。

• RGB可见光活体：0.8
• NIR近红外活体：0.8
• Depth深度活体（3D结构光）：0.8（后续版本即将支持）

1.3.3 人脸1：1对比

人脸对比分为两种常见形态，具体如下：

1.3.3.1 对比类型：图片vs图片

如果有两张待对比的图片（如证件图片、以事先获取到的人脸生活照等），则可以直接通过离线SDK进行对比，业务流程如下图所示：

1.3.3.2 对比类型：实时视频流vs图片

这是最为常见的1：1对比类型，一张事先获取的图片（通常为身份证芯片照、证件照片等），与现场人脸采集的图片进行对比。如果需要为无人看守，则需要配备活体检测保障业务真实性和安全性。

1.3.4 人脸1：N搜索

将需要识别的人脸图片集注册到本地人脸库中，当有用户需要识别身份时，从视频流中实时采集人脸图片，与人脸库中的人脸集合对比，得到搜索结果。如果需要为无人看守，则需要配备活体检测保障业务真实性和安全性。

1.4 设备选型

1.4.1 镜头模组选择

1.4.1.1 无活体或仅用RGB单目活体

uvc免驱单目USB摄像头，推荐视派尔单目摄像头，默认为3mm焦距镜头，可以选择6mm镜头，可以检测识别更远的人脸。

• 视派尔C-EP28WD400，[产品规格书]

1.4.1.2 RGB可见光+NIR近红外活体

推荐使用如下品牌的近红外摄像头，可根据场景举例选择合适焦距摄像头。

• 视派尔C-EP35WDLDIR，[产品规格书] | [去AI市场购买]
• 迪威泰DV-BD4044S305AD，[产品规格书]；联系人：杨先生；联系电话：18643209187
• 迪威泰DV-BD4053S305AD，[产品规格书]；联系人：杨先生；联系电话：18643209187

NIR近红外实际检测效果回显示例：

1.4.1.3 RGB可见光+Depth深度活体（3D结构光）

推荐使用如下品牌的深度摄像头，可根据场景举例选择合适焦距摄像头。

• 奥比中光Astra Mini / Mini S，[产品规格书]；[AI市场购买链接]

1.4.1.4 是否可以使用其他品牌镜头？

如果您需要使用NIR近红外或者Depth活体，则一定要配备支持对应图像格式类型的镜头模组。目前百度离线SDK适配的镜头类型有限，难以覆盖市面上所有双目模组。您可以查看下方的图像适配指标文档，只需满足文档中的图像/数据要求，即可自行进行模组适配。

[镜头模组图像适配指标]

我们也诚挚欢迎各镜头模组厂商参与到SDK的合作中来，我们会积极与您进行产品、技术、商务等多方面对接。测评效果较佳的模组，将会作为SDK官方适配模组，并在所有技术资料中优先推荐用户使用。您可以将合作申请发送到下方咨询邮箱，我们接到您的申请后会尽快与您取得联系，感谢您的信任。

合作邮件：ai#baidu.com（ #替换成@符号 ）

1.4.2 机器选择

• 系统：Windows 7、Windows 10系统的设备
• 处理器：推荐Intel i3及以上
• 内存：4.00 GB及以上
• 系统类型：32位、64位
• 具备2个及以上的USB插口
• 安装vs2015环境（不保证其他vs版本的兼容性）

1.5 方案选型

离线SDK具备离线人脸检测、跟踪、质量校验、图像采集、RGB/NIR/3D结构光活体、离线对比识别、离线人脸库管理。可基本cover人脸识别所需要的全部能力，仅需一个SDK即可完成业务能力覆盖。但相对来说仍然具备一定的场景及业务使用限制。

目前AI开放平台也同时开放采集SDK和API能力，建议您根据实际的业务需要，选择合适的产品应用方案，以达到最佳的应用效果。

1.5.1 使用离线SDK

以下特点及场景，适合仅适用人脸离线SDK

适用的场景特点

• 网络条件不稳定
• 无网络
• 数据安全性高，不允许联网
• 人脸库较小，且变更不频繁，如1w人以下
• 单台设备、单人脸检测与识别

注意：此版本离线SDK暂不支持多线程处理，主要适用于单人脸核验场景，不建议用于多人脸抓拍识别。

典型场景及设备类型

• 人脸门禁
• 人脸闸机
• 人证核验机
• 自助柜机
• 人脸考勤机
• 会场签到

提示：对于离线1：N场景，需要您基于SDK构造上层的人脸库数据更新业务逻辑，例如小区门口的闸机为纯离线，但是住户的变更信息，如何同步到每一个大门的闸机中。

1.5.2 使用采集SDK+API接口

以下特点及场景，适合使用采集SDK+API接口

适用的场景特点

• 网络条件良好
• 人脸库量级庞大
• 需要跨地域同步人脸库
• 人脸库更新频繁
• 用户APP产品形态

提示：采集SDK具备本地化的人脸检测跟踪、质量校验、人脸采集等功能，与离线SDK相比，活体和识别操作使用云端服务完成。

典型场景及设备类型

• 零售会员识别
• 人脸支付
• 手机APP
• 移动考勤
• 远程开户

1.5.3 使用离线SDK+API接口

以下特点及场景，适合使用离线SDK+API接口

适用的场景特点

• 网络条件较好
• 人脸库较小，但变更频繁
• 业务常为集中时段的高并发（如考勤）

典型场景及设备类型

• 上下班刷脸考勤
• 社区闸机
• 楼宇门禁

离线人脸库处理固定人员的识别请求，将在本地抵消掉很多API请求量；同时API处理变动人员的请求，方便及时同步更新，从而总体节省QPS资源的成本消耗。

2、SDK详细介绍

2.1 名词解释

2.2 SDK简介

本sdk适应于windows平台下的人脸识别系统，为在c++版本基础上进行c#接口支持的sdk，开发者可在vs2015下面进行开发（推荐使用，不保证vs其他版本都兼容）

SDK采用C#调用C++的动态库dll的方式，另外随SDK附带一个鉴权激活工具（LicenseTool.exe），此激活工具为采用微软MFC开发，通过该激活工具可生成正常接入SDK的激活license文件（生成两个文件license.ini和license.key）达到通过鉴权，正常使用sdk的目的。

2.3 SDK文件结构

SDK提供C++的动态库BaiduFaceApi.dll，C#调用方法如TestFace工程各demo示例。另外有附带的鉴权激活工具LicenseTool.exe。在此之外，还附带支撑SDK使用的人脸识别模型文件等在文件夹face-resource中，该文件夹在TestFace例子工程里面（该文件夹存放路径请参考TestFace工程，默认存放路径为您要开发的exe(如demo工程TestFace.exe)所在路径的上级目录下。若存放不对，可能会影响sdk正常使用,另外请勿删除该文件夹）。为运行exe，需要用到一些底层的库文件(dll)，相关库文件在TestFace的bin\Release文件夹中已提供。

2.4 激活工具（LicenseTool.exe）

在百度官网申请或购买序列号后，在TestFace的bin\Release目录夹下，双击运行LicenseTool.exe激活工具，可见如下所示界面。在输入框中输入16位的系列号后，点击激活按钮，稍等片刻，即可见弹出的激活成功对话框，若激活失败，请参考对话框中弹出的message信息查找原因。激活成功后会在激活目录生成license.ini以及license.key文件，这2个文件是作为SDK通过鉴权使用的配置文件，请勿删除。

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

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

2.5 Demo示例工程

Demo示例工程TestFace展示了如何集成百度人脸识别离线sdk。即通过DllImport c++的库文件BaiduFaceApi.dll，引入sdk的方法。

在TestFace中的Face.cs的Main()方法中，有使用SDK的各个接口方法示例。接入SDK及其简单，分2步2行代码。如下：

sdk_init(false); 
// 第一步：实例化人脸SDK

test_get_device_id();                     
// 第二步：调用sdk的功能，本句示例：获取设备指纹的示例代码

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

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

2.6 特征抽取模型选择

模型介绍

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

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

使用方法

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

注意事项

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

3、功能接口

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

3.1 人脸检测及设置

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

方法名

track

方法说明

人脸检测，返回人脸信息

请求信息

返回信息

返回结果为json，示例如下:

{
	”count”: 1,
	data: {
		“width”: 200,
		”angle”: 5,
		”center_x”: 20.3,
		”center_y”: 30.2,
		”face_id”: 0,
		”score”: 0.80,
		”headpos”: [5, 3, 2],
		”landmarks”: […]
	}
}, 

依次为

count: 检测的人脸数量
width: 人脸宽度， angle： 角度
center_x, center_y： 人脸中心位置坐标
face_id: 人脸id
score：人脸得分
headpos: 人脸三个角度（ x， y， z方向） landmark： 人脸轮廓关键点坐标

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

方法名

track_by_buf

方法说明

人脸检测，返回人脸信息

请求信息

返回信息

返回结果为json，示例如下:

{
	”count”: 1,
	data: {
		“width”: 200,
		”angle”: 5,
		”center_x”: 20.3,
		”center_y”: 30.2,
		”face_id”: 0,
		”score”: 0.80,
		”headpos”: [5, 3, 2],
		”landmarks”: […]
	}
}, 

依次为

count: 检测的人脸数量
width: 人脸宽度， angle： 角度
center_x, center_y： 人脸中心位置坐标
face_id: 人脸id
score：人脸得分
headpos: 人脸三个角度（ x， y， z方向） landmark： 人脸轮廓关键点坐标

3.1.3 人脸检测track_max_face接口

方法名

track_max_face

方法说明

检测最大人脸。

请求信息

返回信息

返回结果为json，示例如下:

{
	”count”: 1,
	data: {
		“width”: 200,
		”angle”: 5,
		”center_x”: 20.3,
		”center_y”: 30.2,
		”face_id”: 0,
		”score”: 0.80,
		”headpos”: [5, 3, 2],
		”landmarks”: […]
	}
}, 

依次为

count: 检测的人脸数量
width: 人脸宽度， angle： 角度
center_x, center_y： 人脸中心位置坐标
face_id: 人脸id
score：人脸得分
headpos: 人脸三个角度（ x， y， z方向） landmark： 人脸轮廓关键点坐标

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

方法名

track_max_face_by_buf

方法说明

检测最大人脸。

请求信息

返回信息

返回结果为json，示例如下:

{
	”count”: 1,
	data: {
		“width”: 200,
		”angle”: 5,
		”center_x”: 20.3,
		”center_y”: 30.2,
		”face_id”: 0,
		”score”: 0.80,
		”headpos”: [5, 3, 2],
		”landmarks”: […]
	}
}, 

依次为

count: 检测的人脸数量
width: 人脸宽度， angle： 角度
center_x, center_y： 人脸中心位置坐标
face_id: 人脸id
score：人脸得分
headpos: 人脸三个角度（ x， y， z方向） landmark： 人脸轮廓关键点坐标

3.1.5 人脸检测设置接口

请参考TestFace工程中的代码示例及FaceSetting.cs的代码注释。

3.1.6 USB摄像头检测

方法名

usb_track_face_info

方法说明

人脸检测，返回人脸信息（sdk内部使用opencv打开摄像头检测）

请求信息

3.2 人脸管理接口

3.2.1 人脸注册接口

方法名

user_add

方法说明

用户注册，该接口支持传入本地图片文件地址。

请求信息

返回信息

errno信息：

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

data信息:

3.2.2 人脸注册接口（传入二进制图片buffer）

方法名

user_add_by_buf

方法说明

用户注册，该接口支持传入二进制的图片buffer。

请求信息

返回信息

errno信息：

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

data信息:

3.2.3 人脸更新接口

方法名

user_update

方法说明

人脸图片及信息更新

请求信息

返回信息

errno信息：

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

data信息:

3.2.4 人脸更新接口（传入二进制图片buffer）

方法名

user_update_by_buf

方法说明

人脸更新，该接口支持传入二进制的图片buffer。

请求信息

返回信息

errno信息：

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

data信息:

3.2.5 人脸删除接口

方法名

user_face_delete

方法说明

人脸删除

请求信息

返回信息

errno信息：

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

data信息:

3.2.6 用户删除接口

方法名

user_delete

方法说明

用户删除

请求信息

返回信息

errno信息：

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

data信息:

3.2.7 创建用户组接口

方法名

group_add

方法说明

创建用户组

请求信息

返回信息

errno信息：

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

data信息:

3.2.8 用户组删除

方法名

group_delete

方法说明

用户组删除

请求信息

返回信息

errno信息：

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

data信息:

3.2.9 用户信息查询接口

方法名

get_user_info

方法说明

用户信息查询

请求信息

返回信息

errno信息：

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

data信息:

3.2.10 用户组列表查询接口

方法名

get_user_list

方法说明

用户组列表查询

请求信息

返回信息

errno信息：

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

data信息:

3.2.11 组列表查询接口

方法名

get_group_list

方法说明

组列表查询

请求信息

返回信息

errno信息：

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

data信息:

3.3 人脸对比及识别接口

3.3.1 人脸对比接口

方法名

match

方法说明

人脸对比接口（传入图片文件路径）

请求信息

返回信息

errno信息：

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

data信息:

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

方法名

match_by_buf

方法说明

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

请求信息

返回信息

errno信息：

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

data信息:

3.3.3 人脸对比接口（传入二进制图片buffer和特征值feature比对）

方法名

match_by_feature

方法说明

人脸对比接口(传入二进制图片buffer)

请求信息

返回信息

errno信息：

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

data信息:

3.3.4 人脸识别identify接口

方法名

identify

方法说明

人脸识别，提供1：N查找 (传入图片文件路径)

请求信息

返回信息

errno信息：

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

data信息:

3.3.5 人脸识别identify接口（传入二进制图片buffer）

方法名

identify_by_buf

方法说明

人脸识别，提供1：N查找 (传入二进制图片buffer）

请求信息

返回信息

errno信息：

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

data信息:

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

方法名

get_face_feature

方法说明

提取人脸特征值，为512个浮点值，已加密

请求信息

返回信息

byte[]， 若为空，表示提取特征值失败，不为空，则为长度为2048的byte[]。

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

方法名

get_face_feature_by_buf

方法说明

提取人脸特征值，为2048个byte (传入二进制图片buffer)

请求信息

返回信息

byte[]， 若为空，表示提取特征值失败，不为空，则为长度为2048的byte[]。

3.3.8 特征值比较接口

方法名

compare_feature

方法说明

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

请求信息

返回信息

3.4 活体检测接口

3.4.1 可见光(RGB)活体检测接口（通过传入图片）

方法名

rgb_liveness_check

方法说明

人脸可见光活体检测接口（image_type 为1表示base64图片编码 为2表示文件路径）

请求信息

返回信息

errno信息：

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

data信息:

3.4.2 可见光(RGB)活体检测接口（通过传入二进制图片buffer）

方法名

rgb_liveness_check_by_buf

方法说明

人脸可见光活体检测接口（image_type 为1表示base64图片编码 为2表示文件路径）

请求信息

返回信息

errno信息：

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

data信息:

3.4.3 可见光(RGB)&近红外(NIR)活体检测接口（通过传入二进制图片buffer）

方法名

rgb_ir_liveness_check_by_buf

方法说明

可见光和近红外（RGB & NIR）同时活体检测

请求信息

返回信息

errno信息：

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

data信息:

3.4.4 可见光(RGB)&近红外(NIR)活体检测接口（通过sdk底层打开opencv视频帧）

方法名

rgb_ir_liveness_check_by_opencv

方法说明

可见光和近红外（RGB & NIR）同时活体检测

请求信息

3.4.5 可见光(RGB)&深度(Depth)活体检测接口（通过传入二进制图片buffer）

方法名

rgb_depth_liveness_check_by_buf

方法说明

可见光和深度图（RGB & Depth）同时活体检测

请求信息

返回信息

errno信息：

• errno=0 : Success
• errno>0 : 错误码对应的详细msghttp://news.family.baidu.com/specialTopicDetail?subjectId=186429&subjectPathNodeId=2103

data信息:

3.4.6 可见光(RGB)&深度(Depth)活体检测接口（通过sdk底层打开opencv视频帧）

方法名

rgb_ir_liveness_check

方法说明

可见光和近红外（RGB & NIR）同时活体检测

请求信息

3.5 质量接口

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

方法名

face_quality

方法说明

人脸质量检测接口

请求信息

返回信息

errno信息：

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

data信息:

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

方法名

face_quality_by_buf

方法说明

人脸质量检测接口

请求信息

返回信息

errno信息：

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

data信息:

4、适配的深度双目摄像头特别说明

本SDK目前适配了奥比中光的双目深度摄像头。

在SDK中分别以动态库的形式接入，如orbe_camera.dll，是为了用户使用方便以及快速接入或不需要则可以移除。另外若要适配奥比中光的摄像头，在bin\Release下有个orbe_install目录，该目录有个sensorDriver.exe文件需要双击安装后重启电脑，才能保证适配奥比中光摄像头成功。

5、错误码及错误信息

6、常见问题

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

Q：激活后是否可以把激活文件license.ini和license.key拷贝到其他设备运行？
A：不能，离线sdk和设备绑定，每个设备对应一个key和一个license文件，换设备无法运行。但对同一台设备，可把win32下的license.ini和license.key拷贝到x64下，则x64环境，该设备也等同于激活，可以使用。

Q：证件照等图片检测不到人脸，但实际是有人脸的？
A：默认可检测最小人脸大小是100，若检测不到，可通过设置最小人脸大小调整，例如调整最小检测人脸为30px，可使用api->set_min_face_size(30)，达到调整最小人脸检测大小的目的，然后再调用检测，这样能检测到比较小得图片如证件照等。v1.1版本中已经集成了证件照模型，推荐您升级SDK版本解决此问题。·