Linux-ARM-SDK

概述

• 百度人脸离线识别SDK Linux arm 版本，主要支持RK3288、3399芯片ubuntu平台，可登陆百度智能云控制台console后台获取SDK部署包
  
• 针对海思3516DV300、RV1109/1126、晶视CV1825等Linux芯片平台，有单独的专版SDK，请线下联系商务咨询获取专版SDK
  -海思3516DV300 官网地址：https://ai.baidu.com/tech/face/offline-sdk/hisilicon
  -RV1109/RV1126 官网地址：https://ai.baidu.com/tech/face/offline-sdk/rv1109
  

版本日志

目录

1 设计背景	
2 名词解释	
3 SDK简介	
    3.1 功能架构	
    3.2 版本及兼容性	
    3.3 直接编译和运行	
    3.4 交叉编译	
4 SDK工程结构	
5 授权激活	
    5.1 SDK自动激活	
    5.2 激活工具激活(LICENSE_TOOL)	
    5.3 官网离线激活(LICENSE_TOOL)	
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 人脸更新接口	
        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 获取设备指纹接口	
    8.17 安全驾驶接口	
        8.17.1 驾驶行为检测接口	
        8.17.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 静默活体置信度结构体	
    9.16 驾驶行为结构体	
    9.17 安全带佩戴结构体	
10 多端特征值对齐	
11 错误码及错误信息
12 常见问题	

1. 设计背景

• 场景特点:
  

-- 网络:对于无网、局域网等情况，无法连接公网，API 方式无法运作。如政府单 位、金融保险、教育机构等，其中内网情况最为常见，私有化部署是项目开展的前提条件。
-- 安全:即使可以连接外网，因为人脸数据的敏感性，许多客户不希望将人脸数据传入百度服务器，如大学学生照片、部分企业员工数据等，API 形式也往往不被接受。
-- 速度:由于各地网络线路、机房部署、图片采集方式等诸多原因，API 形式往往耗时较高，容易存在部分请求耗时过长的情况，容易影响业务正常运转。
-- 稳定:API 形式容易受网络抖动、机房故障、线上连带 bug 等影响，存在一定的不稳定因素，可用性保障，往往成为在线调用最容易出现问题的地方。

• 客户特点:
  

-- 1:N-小型人脸库检索:多为通道通行、固定区域人群验证等需求，如写字楼闸机 门禁、企业考勤打卡等，人脸库范围较小，且不易经常变动。
-- 1:1-自有数据源对比:将当前采集的人脸，与其他数据源中的人脸进行对比，如 身份证芯片照、教务系统图片、档案图片等，进行快速的 1:1 对比验证。

• 核心需求:
  

-- 基础的人脸采集:包含人脸检测、跟踪、捕获、质量校验等基础功能，获取符合识 别条件的人脸。为之前的客户端 SDK 的标准功能，离线版本 SDK 保留以上所有能力。
-- 本地特征抽取:所有在 SDK 中运行的人脸图片，都可以完成本地特征抽取，以便进行对比或识别操作。
-- 1:1 对比:支持两张图片的相似度对比，可直接传入图片，也可调用本地某个人脸特征;
-- 1:N 搜索:支持一定库大小的人脸查找，在指定的人脸集合中查找最相似的人脸，并返回相似度分值;

2. 名词解释

3. sdk 简介

本 sdk 适应于 linux arm 平台下的人脸识别系统,为支持 c++语言开发的 sdk,开发 者可在 linux arm 平台下面进行开发(支持 armv7hf、armv8 平台)。sdk 采用导出动 态库 dll 的方式提供接口，sdk 附带一个示例工程 face_offline_sdk，提供了 sdk 的各种能力及调用示例。

3.1 功能架构

sdk 具有人脸检测、追踪、特征值、静默活体、人脸库、镜头模组集成等诸多功能。架构如下图所示:

3.2 版本及兼容性

本 sdk 支持 armv7hf、armv8 两种 liunx arm 平台。各平台推荐代表如: armv7hf 架构的如 rk3288 系列。
armv8 架构的如 rk3399 系列。
推荐使用 linux arm 平台上直接编译。

3.3 直接编译和运行

sdk 支持 ssh 网络登录开发板直接命令行编译。可参考 sdk 中的编译 txt 文件进行 编译运行。
在 sdk 工程目录:

mkdir build             #新建 build 目录
cd build                #进入 build 目录 
cmake-DARCH_ABI=armv8.. #根据平台分别用命令armv7hf或armv8
make -j4                #或 make 编译、根据开发板是否支持多核 
cd ..                   #回退到 sdk 工程目录 
./run.sh armv8          #不同平台请分别修改为如 armv7hf 或 armv8。

4. 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 官网离线激活

若设备不能连外网、通过授权还有另外一种方法，即通过运行SDK中的get_device_id来获取硬件指纹信息，获取到设备硬件指纹信息，通过百度官网填入指纹信息和申请到的系列号 key，可完成激活并下载获取到 license.ini 文件和 license.key 文件，把这 2 个文件拷贝到 face_offline_sdk 的 license 目录下，重新运行 sdk 亦可通过授权激活。

6. SDK 集成及 demo 示例工程

6.1 SDK 的集成

sdk 集成的 include 需包含 sdk 的接口头文件:baidu_face_api.h、以及 struct_info.h(定义 sdk 的结构体类)两个文件。(若需要使用 face_scene 文件夹里 面的原子方法，则需要引入整个 sdk 文件夹的 include 目录)。动态库文件在 lib 文件 夹下，根据平台区分 armv7hf 或 armv8 文件夹里面，动态库需要集成时候全部引入。 各动态库文件说明如下

6.2 sdk 的使用示例

sdk 工程 face_offline_sdk 包含了 sdk 接口及 demo 示例工程。其中:sdk 接口头 文件为前述 include 目录的 baidu_face_api.h，提供了 sdk 的各接口方法。sdk 接口 的 lib 库文件为前述 lib 目录。根据平台分别放置在 armv7hf/armv8 目录。其 中:baidu_face_api.so 和 face_sdk.so 为人脸 sdk 的 lib 库文件。其他为 curl、 opencv 库文件等。
demo 示例工程 face_offline_sdk 展示了如何集成百度人脸识别离线 sdk，并调用 sdk 的方法及使用场景化示例等。
在 face_offline_sdk 中的 face.cpp 的 main()方法中，有使用 sdk 的各个接口方法 示例。接入 sdk 及其简单，如下图及解释:

// 入口函数 
int main()
{
//api 实例指针
BaiduFaceApi *api = new BaiduFaceApi();
//初始化 sdk
std::cout << "before sdk_init" << std::endl; int res = api->sdk_init(nullptr);
std::cout << "after sdk_init" << std::endl; if (res != 0)
{
std::cout << "sdk init result is:" << res << std::endl; getchar();
return 0;
}
std::time_t time_begin = get_timestamp();
FaceDemo *demo = new FaceDemo(api);
demo->face_demo();
delete demo;
std::time_t time_end = get_timestamp();
std::cout << "time cost is :" << time_end - time_begin << "ms" << std::en dl;
std::cout << "before delete api" << std::endl; // 释放 sdk 实例指针，防止内存泄漏
delete api;
getchar();
std::cout << "end main" << std::endl;
return 0;
}

sdk 使用主要三步:
1)初始化实例指针
2)初始化 sdk
第 3 步即可调用示例 demo，实现需要的功能。末尾需要释放 sdk 实例化指针 api。 另外，可通过 is_auth()方法查看是否通过了授权，通常，需要通过授权，才可以使用 sdk 的各种能力。
示例工程中:分别有以下几个文件夹放置文件对应几个常用 sdk 的调用 demo。
解析如下:

7. 模型能力加载及模型说明

7.1 模型删减说明

sdk 支持按需配置模型和加载能力，若 sdk 有某部分功能不需要使用，可尝试删除 一些模型，删除后模型即不会加载也不会占用内存。sdk 中 models 文件夹里的模型及 是否可删减说明如下表:

7.2 模型路径的定制化

sdk 支持模型文件夹 models 的路径自定义，当 sdk 初始化 api->sdk_init(nullptr)传 null 时候，为 sdk 支持模型文件夹路径在默认路径，即 models 在 sdk 现有位置。同时也支持 models 通过 sdk_init 中传入绝对路径。若把 models 文件夹拷贝到如/home/face 文件夹下面，则可定义:
api->sdk_init(“/home/face”);
此时，授权文件夹 license 也需要随之变为/home/face 文件夹下面。否则会出现授权 不通过的问题。
另外，若使用了能力自定义的 config 文件夹，也需要拷贝到/home/face 文件夹下面。 否则能力定制化也不会生效而是使用的系统默认。

7.3 能力定制化说明

sdk 支持能力自定义、通过读取配置文件的方式进行能力定制化。sdk 默认能力加 载无需定制化，若需要定制化，请把 sdk 根目录里面的 conf 文件夹重命名为 config 文件夹。并且在 sdk 中，把里面的 json 配置按如下说明做修改，可起到定制化能力加 载的效果，配置文件简要说明如下(若需定制化修改，请参考示例 json，修改 json 字段的值来达到定制化的目的)

7.3.1 detect.json (人脸检测能力定制配置文件)

7.3.2 track.json (人脸追踪能力定制配置文件)

7.3.3 action_live.json (动作活体能力定制配置文件)

7.3.4 crop.json (人脸抠图能力定制配置文件)

8. 功能接口

sdk 功能接口的调用可参考各示例 cpp 文件，接口定义在 baidu_face_api.h。 sdk 实现的主要功能有人脸实时跟踪检测、人脸特征值提取、动作活体、RGB&IR 静默 活体检测、RGB&DEPTH 静默活体检测、人脸注册、人脸更新、组管理、用户管理以及 1:1 人脸对比,1:N 人脸识别、特征值的比对和通过 usb 或笔记本自带摄像头检测视频 帧，返回识别出的人脸信息、人脸属性等，另外支持对人脸检测进行能力加载设置， 达到根据设置进行识别的目的。
各接口功能及传入参数和返回结果等定义如下:

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 人脸质量

人脸质量判断可由以下几个因素自由组合综合判断，如姿态角、光照、遮挡、模 糊以及最佳人脸。人脸质量判断的推荐阈值:人脸检测置信度>0.63、遮挡度 <0.75、 人脸姿态角 <20 、人脸模糊度 <0.8、最优人脸 >50。

8.12.1 人脸姿态角接口

8.12.2 人脸光照检测接口

8.12.3 人脸遮挡检测接口

8.12.4 人脸模糊度检测接口

8.12.5 最优人脸检测接口

8.13 特征值及人脸比对(1:1)

人脸比对的原理实际是特征值比对，通过提取图片中的人脸特征值，根据特征值 调用 compare_feature 接口进行比对，推荐比对分值超过 80 分为同一人，可根据实际 检测比对情况动态调整。
人脸 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 人脸库管理

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识别返回识别的最高分和用户信息，推荐分值超过80为识别成功。
人脸库1：N识别可如如下图所示流程：

8.15.1 人脸注册接口(通过传入图片帧)

8.15.2 人脸注册接口(通过传入特征值)

8.15.3 人脸更新接口

8.15.4 用户删除接口

8.15.5 创建用户组接口

8.15.6 用户组删除接口

8.15.7 用户信息查询接口

8.15.8 用户人脸图片查询接口

返回字段描述：返回int，0为成功，其他为错误码

8.15.9 用户组列表查询接口

8.15.10 人脸库人脸数量查询

返回示例：int >=0 (返回的数量)

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 获取设备指纹接口

8.17 安全驾驶接口

8.17.1 驾驶行为检测接口

返回字段描述: int，>=0返回人脸个数，<0时候为错误码

8.17.2 安全带佩戴检测接口

返回字段描述：int，>=0返回人脸个数，<0时候为错误码

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 静默活体置信度结构体

9.16 驾驶行为结构体

9.17 安全带佩戴结构体

10. 多端特征值对齐

对于linux arm sdk来说，支持和安卓特征值对齐，linux arm sdk7.x系列，特征值对齐安卓7.x系列，但和如安卓6.x系列或5.x系列，则不对齐，且只支持rgb可见光特征值对齐。
在linux arm sdk中，可通过提取的特征值128个float数组，保存成二进制数据，即和安卓中的512个byte保存成字节流的数据对齐。
sdk中提供了float数组转换为二进制buffer的示例代码以及二进制buffer数据转换为特征值float数组的示例代码。可参考util文件夹中的FeatureAlign类。

11. 错误码及错误信息

各接口返回结果error_code及msg信息如下：

12. 常见问题：

12.1 sdk推荐使用交叉编译或在开发板如rk3288上直接编译。
12.2 工程运行过程中，若不能正常运行功能，可在build目录下，生成face_conf.json文件，内容为{"log_open":true}，通过这个json配置文件，可打开sdk的日志模式，运行后会输出及各接口返回的错误码日志等判断问题所在。
12.3 模型文件可定制化：在main方法入口，可在sdk_init方法中传入模型文件夹的绝对路径，达到模型文件定制化的目的。若不定制化路径，sdk_init中传入null即可，默认模型文件在sdk的models文件夹里面，无需更改。
12.4 激活后是否可以把激活文件license.ini和license.key拷贝到其他设备运行？
不能，离线sdk和设备绑定，每个设备对应一个key和一个license文件，换设备无法运行。但对同一台设备，可把Release下的license.ini和license.key拷贝到本电脑的另外sdk，该设备也等同于激活，可以使用。
12.5 是否支持debug模式？只支持Release模式，不支持debug模式。
12.6 sdk支持armv7hf、armv8等平台，请根据对应平台运行。
12.7 人脸库不支持中文参数？用户信息user_info支持中文，其他人脸管理参数目前暂只支持英文、数字下划线组合模式，工程所在的路径也建议不用放入中文路径中，可能影响人脸库创建。
12.8 特征值多端是否对齐？在人脸7.0系列sdk中，安卓和linux端生活照模式下的特征值都是对齐的。linux中请把提取出来的128个float数据保存成二进制数据（float数组转二进制保存）即可和安卓的512个byte二进制数据对齐。linux中人脸库保存的数据是进行了base64编码保存的。
12.9 sdk是否支持多线程运行？sdk不推荐采用多线程运行。
12.10 海思等其他开发板是否支持？sdk推荐用在rk3288开发板上，其他开发板是armv7hf或armv8平台，也可支持运行、部分第三库如opencv等，若报错，可推荐在对应开发板上编译产出库文件，opencv推荐使用4.1版本。