1 SDK 简介

本SDK适用于麒麟Linux X86平台下的人脸识别系统，为支持C++语言开发的SDK，开发者可在麒麟Linux X86平台下面进行开发（该版本为麒麟X86平台）。SDK采用导出动态库so的方式提供接口，SDK附带一个示例工程face_offline_sdk，提供了SDK的各种能力及调用示例。

cpu芯片支持：支持主流国产cpu如、飞腾，海光，兆芯，鲲鹏等。

1.1 功能架构

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

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

1.2 版本及兼容性

本SDK支持麒麟Linux X86平台，推荐使用Linux X86平台上直接编译。

1.3 直接编译和运行

SDK支持在开发板上直接编译运行，步骤如下：

1. 安装gcc、g++，可自行百度参考，也可命令如下：

     - sudo apt update             #更新
     - sudo apt install cmake      #安装cmake
     - sudo apt install gcc        #安装gcc
     - sudo apt install g++        #安装g++

若安装正确，可：

   gcc --version
   g++ --version

能看见输出正确的gcc版本号表示安装正确。

2. SDK支持登录设备上命令行直接编译，可参考SDK中的编译txt文件，具体命令如下：

    - 在SDK工程目录：
    - mkdir build               #新建build目录
    - cd build                  #进入build目录
    - cd ..
    - cmake .. 
    - make -j4                  #或 make 编译、根据开发板是否支持多核
    - ./run.sh                  #回退到sdk工程目录、执行脚本运行

2 SDK 工程结构

3 授权激活

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

3.1 SDK 自动激活

1. 在SDK的目录中有license文件夹，里面存放了2个文件：license.key和license.ini，分别是授权key和授权文件。
2. 若在百度官网申请了授权系列号key（16位），可按SDK中的license文件夹中license.key原格式样子用申请的key覆盖填写旧的。
3. 在设备能联网的情况下，运行SDK会自动授权激活并拉取新的授权文件license.ini覆盖SDK中的旧文件。
4. 设备能联网的情况下，拉取了正确的授权文件后即可通过授权激活，若报错，可根据错误码定义进行激活失败的排查。

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

1. 运行SDK的示例代码face.cpp，可获取设备指纹device id。请查看代码get_device_id部分。
2. 通过百度官网填入指纹信息device id和申请到的系列号key，完成离线激活并下载license.zip文件解压后得到license.ini文件和license.key文件。
3. 把这2个文件拷贝到face_offline_sdk的license目录下，重新运行SDK即可通过授权激活。

4 SDK 集成及DEMO 示例工程

4.1 SDK 的集成

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

4.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();
    //初始化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的各种能力。

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

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

5.1 模型删减说明

SDK支持按需配置模型和加载能力，不需要的功能可删除对应模型，删除后模型不会加载也不会占用内存。SDK中models文件夹里的模型及是否可删减说明如下：

5.2 模型路径的定制化

1. SDK支持模型文件夹models的路径自定义，当SDK初始化api->sdk_init(nullptr)传null时，模型文件夹路径为默认路径（models在SDK现有位置）。
2. 也可通过sdk_init中传入绝对路径自定义，例如把models文件夹拷贝到/home/face文件夹下面，可定义：api->sdk_init("/home/face")。
3. 此时，授权文件夹license也需要随之放到/home/face文件夹下面，否则会出现授权不通过的问题。
4. 另外，若使用了能力自定义的config文件夹，也需要拷贝到/home/face文件夹下面，否则能力定制化不会生效，将使用系统默认配置。

5.3 SDK 的配置文件

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

5.3.1 修改配置文件输出日志

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

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

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

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

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

[IdentifyScore]
IdentifyScore = 101

5.3.3 修改配置文件启用多因子模式提高静默防攻击能力

在进行RGB静默活体的时候，可通过修改配置文件的字段，打开多因子模型能力，该能力打开后，可提高静默活体防攻击能力（但同时，单帧耗时会有所增加）。打开方法为去掉配置文件face.ini中的#字段（#为注释），使得字段如下：

[MultiFactor] 
MultiFactor = 1

说明：其中值设为1为启用，设为0不启用，参数前加#为注释该参数，亦不启用。

5.4 能力定制化说明

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

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

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

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

6 功能接口

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

6.1 人脸检测detect接口

6.2 人脸跟踪track接口

6.3 清除人脸跟踪历史接口

6.4 人脸关键点接口

6.5 人脸扣图接口

6.12 人脸质量

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

6.12.1 人脸姿态角接口

6.12.2 人脸光照检测接口

6.12.3 人脸遮挡检测接口

6.12.4 人脸模糊度检测接口

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

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

人脸1:1比对流程如下：

6.13.1 人脸特征值接口

6.13.2 人脸活体特征值接口

6.13.3 特征值比对接口

6.13.4 人脸1:1 比对接口

6.14 静默活体

6.14.1 rgb 静默活体接口

6.14.2 nir 静默活体接口

6.14.3 rgb+depth 双目静默活体接口

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

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

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

6.15.3 人脸更新接口

6.15.4 用户删除接口

6.15.5 创建用户组接口

6.15.6 用户组删除接口

6.15.7 用户信息查询接口

6.15.8 用户人脸图片查询接口

6.15.9 用户组列表查询接口

6.15.10 人脸库人脸数量查询

6.15.11 群组列表查询接口

6.15.12 人脸识别接口

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

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

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

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

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

6.16 SDK 系统信息接口

6.16.1 获取SDK 版本号接口

6.16.2 获取设备指纹接口

7 结构体描述

7.1 人脸跟踪信息结构体

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

7.2 人脸框信息结构体

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

7.3 人脸关键点信息结构体

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

7.4 人脸特征值结构体

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

7.5 人脸姿态角结构体

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

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

struct Blur { 
    float score; 
}

7.7 人脸光照置信度结构体

struct Illumination { 
    int score; 
} 

7.8 人脸遮挡置信度结构体

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

7.9 静默活体置信度结构体

struct LivenessScore { 
    float score; 
} 

8 多端特征值对齐

• 麒麟X86 SDK支持与安卓特征值对齐，仅对齐V8.X系列，如安卓V8.X， Linux Arm V8.x，Windows V8.X，且仅支持RGB可见光特征值对齐。
• 跟云端提取的特征值同步，可参考https://ai.baidu.com/ai-doc/FACE/Okg7edktq ，对齐V8.X系列即可。
• 在麒麟 X86 SDK中，提取的128个float特征值数组需保存为二进制数据，即可与安卓的512个byte字节流数据对齐。
• SDK提供float数组与二进制buffer互转的示例代码，可参考util文件夹中的FeatureAlign类。

9 多线程运行

• SDK支持多实例的多线程使用，具体示例可参考multi_thread文件夹。
• 单个实例不支持多线程同时调用人脸检测（detect）和特征值提取（face_feature）等接口。
• 多个实例可多线程调用不同接口，例如一个实例调用detect，另一个实例调用face_feature。
• 使用多个实例时，需new不同的BaiduFaceApi实例，调用多次sdk_init方法，销毁时需销毁所有实例，避免内存泄漏。

10 错误码及错误信息

11 常见问题

11.1 SDK推荐在麒麟X86设备上直接编译运行，需安装GCC/G++/CMAKE，也支持在Ubuntu等X86机器上交叉编译。

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

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

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

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

11.6 支持X86平台，需根据对应平台运行。

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

11.8 特征值多端对齐：人脸8.0系列SDK中，安卓和Linux端生活照模式特征值对齐；Linux端需将128个float数据转为二进制保存，即可与安卓512个byte二进制数据对齐；Linux人脸库数据采用BASE64编码保存。

11.9 多线程支持：支持多实例的多线程运行，具体参考multi_thread示例。

11.10 多人脸检测设置：SDK默认检测1个人脸，需修改detect.json配置文件实现多人脸检测。