1 SDK 简介

本 SDK 适应于 Linux RV1126B 平台下的人脸识别系统,为支持 C++语言开发的 SDK, 开发者可在 Linux RV1126B 平台下面进行开发。SDK 采用导出动态库 DLL 的方式提供接 口，SDK 附带一个示例工程 face_offline_sdk，提供了 SDK 的各种能力及调用示例。 SDK 采用 npu 进行推理，速度和性能较传统的 cpu 方式更佳。

1.1 功能架构

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

• 业务层：1:1比对、1:N识别、活体&镜头模组、视频集成、人脸库
• SDK能力层：人脸检测、人脸追踪、人脸特征值、人脸属性、人脸质量（遮挡、光照、模糊）、人脸注意力、人脸关键点、静默活体
• 底层：鉴权、模型、算法、依赖库（paddle、opencv等）

1.2 版本及兼容性

本SDK支持 64 位 Linux arm aarch64 平台的版本。 支持在 x86 环境的 ubuntu 操作系统或 centos 等系统上进行交叉编译，把编译后的可 执行程序拷贝到 RV1126B 板子上进行运行。(其他 Linux arm 系统不保证能支持)。

1.3 交叉编译和运行(也可参考SDK zip包里的编译说明.md)

SDK 支持在 x86 宿主机 ubuntu18.04 及以上或 centos 系列上进行交叉编译。
交叉编译工具链: gcc-linaro-6.3.1-2017.05-x86_64_aarch64-linux-gnu.zip
可去 linaro 官网下载或百度网盘：
链接: https://pan.baidu.com/s/1bRfJhZREl-N3PNIxsjsU0A 提取码: xkuc
下载后按如下步骤操作：
1） 解压到指定路径 (请正确填写 zip 名称）

     - mkdir -p /opt/gcc           #创建文件夹
     - cp gcc-linaro-6.3.1-2017.05-x86_64_aarch64-linux-gnu.zip /opt/gcc       #拷贝zip
     - cd /opt/gcc                 #到gcc路径
     - unzip gcc-linaro-6.3.1-2017.05-x86_64_aarch64-linux-gnu.zip        #解压

2）加入环境变量

    - sudo vim /etc/profile
    export PATH=/opt/gcc/gcc-linaro-6.3.1-2017.05-x86_64_aarch64-linux-gnu
/bin:$PATH #这句加入profile的最后一行
    - source /etc/profile #保存环境变量生效

3)检查工具链是否正常：

  - aarch64-linux-gnu-gcc --version #若看见正确的版本输出，表示工具链部署成功。

4）进行交叉编译： SDK 自带 quick_build.sh 脚本，执行:

  - sh quick_build.sh    #编译SDK
  - sh run.sh            #运行SDK,需要把整个编译后的工程拷贝到开发板上执行脚本

2 SDK 工程结构

3 授权激活

SDK 需要授权激活后才能正常使用，在 SDK 初始化后，若报错误码-13（错误码参考 文档最后定义） ，一般为没有通过授权。通常，SDK 分按设备授权和按应用授权两种方 式，大部分采用按设备授权的方式，按应用授权可针对批量大规模客户使用（文档中 先只介绍按设备授权，按应用授权可工单或联系百度商务我们提供另外的文档或技术 支持）。按设备授权的方式中，SDK 自动激活和激活工具激活需要设备能联网，若设备 不能连外网，可采用官网离线激活的方式。

3.1 SDK 自动激活(设备需要能联网)

在 SDK 的目录中有 models 文件夹，里面存放了 2 个文件，license.key 和 license.ini，分别是授权 key 和授权文件，若在百度官网申请了授权系列号 key（16 位），可按 SDK 中的 models 文件夹中 license.key 原格式样子覆盖填写您申请的 key。 在设备能联网的情况下，运行 SDK 会自动授权激活并拉取新的授权文件 license.ini 覆盖SDK中的旧文件。

3.2 官网离线激活(适应于设备不能联网场景)

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

4 加载驱动

若运行 SDK 后无法正确运行，报如下错误： 则可能是开发板没用加载驱动导致，执行如下命令加载后再运行 SDK 即可。

  - sudo chmod 0777 /dev/rk*    #加载驱动

5 SDK 集成及DEMO 示例工程

5.1 SDK 的集成

1. 需包含sdk的接口头文件：baidu_face_api.h、struct_info.h（定义sdk的结构体类）。
2. 动态库文件在lib文件夹下，各动态库文件说明如下：

5.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示例工程展示了如何集成百度人脸识别离线SDK，并调用SDK的方法及使用场景化示例等。

在face_offline_sdk中的face.cpp的main()方法中，有使用SDK的各个接口方法示例，接入SDK步骤如下：

// 入口函数
int main() {
    //api 实例指针
    BaiduFaceApi *api = new BaiduFaceApi();
    // 获取指纹设备
    std::string dev_id;
    get_device_id(api,dev_id);
    //初始化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::endl;
    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的各种能力。

示例工程中各文件夹/文件说明如下：

6 模型能力加载及模型说明

SDK 中的 models 文件夹是模型文件夹，SDK 的所有能力模型文件在这里，切勿删除。 模型文件会在 SDK 初始化时候自动加载。

6.1 模型路径的定制化

SDK 支持模型文件夹 models 的路径自定义，当 SDK 初始化 api->sdk_init(nullptr)传 null 时候，为 SDK 支持模型文件夹路径在默认路径，即 models 在 SDK 现有位置。同时 也支持 models 通过 sdk_init 中传入绝对路径。若把 models 文件夹拷贝到如 /home/face 文件夹下面，则可定义： api->sdk_init(“/home/face”);

6.2 SDK 的配置文件

SDK提供配置文件face.ini，通过修改配置文件，可输出文件日志、定制化数据库文件db路径等，可通过#注释字段，具体可参见face.ini示例。当sdk_init传nullptr的时候，face.ini默认在SDK的run.sh同目录夹中；若sdk_init传入了绝对路径，则face.ini文件需要放置在传入的绝对路径上层目录中。

6.2.1 修改配置文件输出日志

人脸库路径db文件夹也可定制化，通过修改face.ini文件实现：

• 若face.ini定义字段：DbDir = /home/face，则表示人脸库路径会生成在/home/face路径的face文件夹中。
• 若无需定制，则在face.ini中删除DbDir字段即可，#号为注释或不启用该字段。

6.2.2 修改配置文件变更人脸识别输出结果数量

通常，进行1:N人脸识别的时候，只返回最高分的识别结果。若需要返回更多结果，可通过修改face.ini文件的IdentifyScore字段：

• 如设为80，则返回识别分值大于80的结果（可能多个）。
• 若只想返回1个结果，把字段的值设置为101，则返回1个最高分的识别结果。
• 字段配置如下：

[IdentifyScore]
IdentifyScore = 101

7 功能接口

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

7.1 人脸检测detect接口

7.2 人脸跟踪track接口

7.3 人脸关键点接口

7.4 人脸扣图接口

7.5 口罩佩戴检测接口

7.6 人脸质量

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

7.6.1 人脸姿态角接口

7.6.2 人脸光照检测接口

7.6.3 人脸遮挡检测接口

7.6.4 人脸模糊度检测接口

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

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

人脸1:1比对流程如下，实现如人证比对功能。 （人的照片和实时视频比对，可根 据使用情况选择是否启用质量检测）：

7.7.1 人脸特征值接口

7.7.2 Pipline 全流程特征值提取接口 （采用该接口提取的特征值更符合质量要求，识别时候更准确）

7.7.3 特征值比对接口

7.7.4 人脸1:1 比对接口

7.8 静默活体

7.8.1 rgb 静默活体接口

7.8.2 nir 静默活体接口

7.9 人脸库管理

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识别流程图如下：

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

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

7.9.3 人脸更新接口

7.9.4 用户删除接口

7.9.5 创建用户组接口

7.9.6 用户组删除接口

7.9.7 用户信息查询接口

7.9.8 用户人脸图片查询接口

7.9.9 用户组列表查询接口

7.9.10 人脸库人脸数量查询

7.9.11 群组列表查询接口

7.9.12 人脸识别接口

人脸识别（1:N）结果，通过传入人脸特征值或图片进行人脸的1:N识别，即传入的1和人脸库的N进行识别（人脸库自动创建，需要通过user_add等接口把人脸注册入库），人脸识别的返回默认大于80分的识别结果。可通过配置文件face.ini中的字段IdentifyScore的分值控制识别返回的结果，若该字段分值设为101，则默认返回1个识别结果（1:N的识别最高分结果）。

7.9.12.1 人脸识别接口(1:N) (传入opencv图片帧)

7.9.12.2 人脸识别接口(1:N)(传入特征值)

7.9.12.3 人脸识别接口(1:N) (传入opencv图片帧)

7.9.12.4 人脸识别接口(1:N) (传入特征值)

7.10 SDK 系统信息接口

7.10.1 获取SDK 版本号接口

7.10.2 获取设备指纹接口

8 结构体描述

8.1 人脸跟踪信息结构体

struct TrackFaceInfo {
    long face_id;
    FaceBox box;
    Landmarks facelandmarks; 
    }

8.2 人脸框信息结构体

struct FaceBox 
{ 
    int index; 
    float center_x; 
    float center_y; 
    float width; 
    float height; 
    float score;
}

8.3 人脸关键点信息结构体

struct Landmarks { 
    int index;
    int size;
    float data[144];
    float score; 
}

8.4 人脸特征值结构体

struct Feature { 
    int size; 
    float data[256]; 
} 

8.5 人脸姿态角结构体

struct HeadPose { 
    float yaw; 
    float roll; 
    float pitch;
} 

8.6 人脸质量信息结构体

struct Quality { 
    HeadPose head_pose;
    Occlusion occlusion;
    Illumination illum;
    Blur blur;
    float score; 
} 

8.7 Pipline 配置信息

struct PiplineConf { 
    bool check_headpose;
    bool check_blur;
    bool check_illum;
    bool check_occlu;
    bool check_liveness; 
} 

8.8 Pipline 返回信息

struct PiplineRes { 
    FaceBox box;
    Quality quality;
    float rgb_score;
    float nir_score;
} 

8.9 口罩佩戴结构体

struct MouthMask { 
    float mask_score;
} 

8.10 人脸模糊度置信度结构体

struct Blur { 
    float score; 
}

8.11 人脸光照置信度结构体

struct Illumination { 
    int score[2]; 
} 

8.12 人脸遮挡置信度结构体

struct Illumination { 
    float left_eye; 
    float right_eye; 
    float nose; 
    float mouth;
    float left_cheek; 
    float right_cheek; 
    float chin; 
} 

8.13 静默活体置信度结构体

struct LivenessScore { 
    float score; 
} 

9 错误码及错误信息

10 常见问题

10.1 工程运行异常时，可在face.ini中设置LogType=1，开启SDK日志模式，通过输出的错误码日志定位问题。

10.2 模型文件可定制化：在main方法入口的sdk_init中传入模型文件夹绝对路径；不定制则传入NULL，默认使用SDK的models文件夹。

10.3 激活文件不可跨设备使用：离线SDK与设备绑定，每个设备对应唯一key和license文件；同一设备下可将Release目录的license.ini和license.key拷贝到其他SDK使用。

10.4 仅支持RELEASE模式，不支持DEBUG模式。

10.5 SDK 支持 rv1126b 开发板，请根据对应平台运行。

10.6 人脸库参数限制：用户信息user_info支持中文，其他管理参数仅支持英文、数字、下划线组合；工程路径建议避免中文，否则可能影响人脸库创建。

10.7 特征值多端是否对齐？该 SDK 为专版 SDK，只对应这个版本的特征值。

10.8 SDK 是否支持多线程运行？SDK 采用 npu 推理，不支持多线程运行。