商米人脸识别DemoAPP_v1.8.0（47.0M）：下载
商米人脸识别SDK包_v1.8.0（37.1M）：下载
1. 概述
商米人脸识别SDK是一种面向安卓设备的人脸技术开发包。此SDK开发包包含人脸检测、人脸识别和人证比对等功能，以aar包+models的形式发布。本文档介绍了SDK的使用说明以及数据结构和接口的定义，便于开发者在调用SDK接口时参考。
1.1.文档使用范围
该人脸识别接口文档主要适用于人脸识别开发的相关人员参考阅读。
1.2.功能清单
商米人脸识别SDK主要提供如下功能：
| 模块 | 功能 |
| 人脸检测 | 检测图片中出现人脸的位置，并标记出人脸的五个关键点位置 |
| 人脸识别 | 将当前人脸和数据库中的人脸进行匹配，确定当前人脸身份信息 |
| 人证比对 | 采集身份证上的照片，并且判断当前人脸是否和身份证上的人脸匹配 |
| 人脸属性预测 | 根据图片上出现的脸，预测人的性别及年龄 |
| 活体检测 | 判断图片上出现的脸是否来自于真人；当采用3D摄像头时预测结果更准确 |
1.3. 开发包SDK的说明
商米人脸识别SDK包含sunmi_facelib.aar文件和models文件夹。其中models文件夹包含一个配置文件和六个模型文件：
| 文件/文件夹名 | 说明 |
| sunmi_facelib.aar | SDK lib库相关代码的aar |
| models | 配置文件：config.json，模型文件：face.json、face.params、detect.json、detect.params、rgb_liveness.json、rgb_liveness.params、depth_detector.yml、attribute.json、attribute.params、nir_liveness.json、nir_liveness.params |
注： 商米人脸识别SDK 只有一个实例，是线程不可重入的。只能同时由一个线程调用，不能在多个线程里面同时调用。
2. 环境信息
| 系统环境 | 平台 | 编译环境 |
| Android7及以上 | arm32, arm64 | NDK |
3. JavaSDK使用说明
3.1. 获取授权文件
商米人脸识别SDK的授权需要绑定Android系统信息。在第一次使用前，开发者需要获取人脸识别SDK的license授权文件，请参考文档 授权&购买授权 。
3.2. 导入SDK包
在Android Studio项目中导入SDK aar包即可。
3.3. 存放模型文件
模型文件（.json和.params文件）可以存放在SD卡某个路径下，也可以存放在APP文件路径下。请务必保证模型所在路径可以被访问。
3.4. 配置config.json文件
使用模型包中config.json文件作为模板，或者自行创建一个config.json文件，拷贝如下代码。根据3.3中11个文件face.json、face.params、detect.json、detect.params、rgb_liveness.json、rgb_liveness.params、nir_liveness.json、nir_liveness.params、depth_detector.yml、attribute.json和attribute.params存放的实际路径进行修改。SDK需通过读取此config.json配置文件进行初始化。
{
// 人脸识别库文件，此文件在SDK Jnilibs里，一般不需要修改
"face_lib_path":"libface.so",
// 人脸识别库网络描述文件，需要绝对路径
"face_graph_path":"/storage/emulated/0/faceTest/face.json",
// 人脸识别库网络参数文件，需要绝对路径
"face_param_path":"/storage/emulated/0/faceTest/face.params",
// 人脸检测库文件，此文件在SDK Jnilibs里，一般不需要修改
"detect_lib_path":"libdetect.so",
// 人脸检测库网络描述文件，需要绝对路径
"detect_graph_path":"/storage/emulated/0/faceTest/detect.json",
// 人脸检测库网络参数文件，需要绝对路径
"detect_param_path":"/storage/emulated/0/faceTest/detect.params",
// rgb活体检测库文件，此文件在SDK Jnilibs里，一般不需要修改
"rgb_liveness_lib_path":"librgb_liveness.so",
// rgb活体检测库网络描述文件，需要绝对路径
"rgb_liveness_graph_path":"/storage/emulated/0/faceTest/rgb_liveness.json",
// rgb活体检测库网络参数文件，需要绝对路径
"rgb_liveness_param_path":"/storage/emulated/0/faceTest/rgb_liveness.params",
// nir活体检测库文件，此文件在SDK Jnilibs里，一般不需要修改
"nir_liveness_lib_path":"libnir_liveness.so"
// nir活体检测库网络描述文件，需要绝对路径
"nir_liveness_graph_path":"/storage/emulated/0/faceTest/nir_liveness.json",
// nir活体检测库网络参数文件，需要绝对路径
"nir_liveness_param_path":"/storage/emulated/0/faceTest/nir_liveness.params",
// 人脸库存放路径，需要绝对路径
"face_db_file":"/storage/emulated/0/faceTest/sunmi_face.db",
// 3D活体检测模型，需要绝对路径
"depth_detector":"/storage/emulated/0/faceTest/depth_detector.yml"
// 人脸属性预测库文件，此文件在SDK Jnilibs里，一般不需要修改
"attr_lib_path":"libattribute.so",
// 人脸属性预测网络描述文件，需要绝对路径
"attr_graph_path":"/storage/emulated/0/faceTest/attribute.json",
// 人脸属性预测库网络参数文件，需要绝对路径
"attr_param_path":"/storage/emulated/0/faceTest/attribute.params",
}3.5. 初始化SDK
以下为SDK调用init接口执行初始化的示例。init接口参数为3.4中的config.json文件的路径。
SunmiFaceSDK.createHandle();
String confPath = Environment.getExternalStorageDirectory() +
"/faceTest/config.json";
int code = SunmiFaceSDK.init(confPath);注：在调用其他接口之前，需调用接口createHandle创建SDK句柄。在安全性方面， SDK内部可以保证多次调用不会重复创建SDK句柄 。不需要使用SDK时，可调用releaseHandle接口释放SDK句柄。
3.6. 验证授权文件
使用类似如下代码读取授权文件内容到Java String中，再通过verifyLicense接口验证。若验证通过，可正常调用SDK其他接口。若验证失败，调用SDK其他接口将返回授权错误代码。错误代码为“10”，则表示授权文件无效；错误代码为“11”，则表示授权文件过期。如有授权问题，请联系商米解决。
注：需保证wifi开关为打开状态。
String license = readToString(Environment.getExternalStorageDirectory() +
"/faceTest/license_face.txt");
int code = SunmiFaceSDK.verifyLicense(context, license); // context为Android Context3.7. 配置SDK
商米人脸识别SDK参数都可动态配置，建议先通过getConfig得到当前参数，根据需要将参数修改完成后，再用setConfig接口进行设置。示例代码如下：
SunmiFaceConfigParam param = new SunmiFaceConfigParam();
SunmiFaceSDK.getConfig(param);
param.setDistanceThreshold(0.9f); //当SDK应用于支付场景，推荐值是0.9；当应用于人证比对场景时，推荐值为1.1；阈值越小，SDK对于相同人的判定越严格
param.setYawThreshold(50.0f);//人脸姿态阈值，设置较小的人脸姿态阈值，阈值越小，人脸姿态要求越严格，保证相对正面的人脸姿态做识别
param.setPitchThreshold(50.0f);
param.setRollThreshold(50.0f);
param.setMinFaceSize(60);//最小人脸检测尺寸，较大较清晰的人脸识别较准确
param.setImageQualityThreshold(10);//阈值越高，人脸清晰度越好，人脸识别越准确
param.setMinLuminance(10);//最小光照
param.setMaxLuminance(180);//最大光照
param.setThreadNum(1); //使用一个cpu核心执行人脸检测，人脸识别
int code = SunmiFaceSDK.setConfig(param);
int box_sort_mode; // 人脸框排序方式相似度阈值0.9、1.1的含义，以及如何设置调整？
相似度值代表的是两个特征码之间的欧式距离。人脸识别算法原理是智能识别人脸图片，提取人脸特征码，使用时计算注册的特征码和实时采集的特征码之间的距离。商米人脸识别算法相似度阈值设定范围为0-2，可调范围为0.8-1.3。
人脸识别场景相似度阈值默认0.9，识别时如相似度小于设定的阈值0.9，认定为同一个人；大于设定的阈值0.9，则不认为是同一个人。由此可见，设置阈值越低，人脸识别越严格，也越容易发生真人通不过算法的情况。0.9已经较为严格，一般使用默认0.9即可。如场景情况光照不佳，角度不佳等，也可调整为1.0或1.1；
人证比对场景一般建议阈值为1.1，1.1相对松一点，原因是实际情况中证件照通常和本人有一定区别，设置严格会导致大比例真人通不过。根据场景情况也可调整为1.2或1.3。
阈值的设置以建议阈值为主，可根据具体场景需要和测试识别情况进行参数的微调。
3.8 释放内存
在SDK调用过程中，通过调用SunmiFaceFeatureArrayGetItem和SunmiFaceLmkArrayGetItem方法得到的对象，可调用delete方法手动立即释放内存。如果未调用delete方法，java垃圾回收会自动释放内存 。示例代码如下：
SunmiFaceFeature faceFeature = SunmiFaceLib.SunmiFaceFeatureArrayGetItem(features.getFeatures(), 0);
feature.delete();3.9. 提取人脸特征
提取步骤：
- 获取的Bitmap图片：用户根据需求，从摄像头获取bitmap传给SDK。
- 传入图片的尺寸：人脸SDK检测最佳输入图的宽高比为1:1。若宽高比过大，可能导致检测性能略微下降。
- 图像格式处理：将获取的Bitmap图片转为BGR byte buffer格式。（可参考如下示例代码）
- 接口调用：传入BGR byte buffer，通过SunmiFaceImage构造函数创建SunmiFaceImage。再通过getImageFeatures接口传入SunmiFaceImage图片数据，得到SunmiFaceImageFeatures人脸结果。
- 多人脸识别逻辑：如果有多张人脸，SunmiFaceFeature在SunmiFaceImageFeatures中按照置信度score从高到低排列。
- 人脸库记录：faceFeature2FaceDBRecord把得到的人脸特征转换为人脸库的记录，设置相关ID，name。
- 资源释放：SunmiFaceImageFeatures在SDK中动态分配内存空间，使用完毕后需要调用接口释放资源。
示例代码如下：
public static byte[] getPixelsBGR(Bitmap image) {
// 计算图片有多少字节
int bytes = image.getByteCount();
ByteBuffer buffer = ByteBuffer.allocate(bytes); // 创建新的buffer
image.copyPixelsToBuffer(buffer); // 移动字节数据到buffer
byte[] temp = buffer.array(); // 获取包含数据的底层数组
byte[] pixels = new byte[(temp.length / 4) * 3]; // 分配空间给BGR
// 对像素重组
for (int i = 0; i < temp.length / 4; i++){
pixels[i * 3] = temp[i * 4 + 2]; //B
pixels[i * 3 + 1] = temp[i * 4 + 1]; //G
pixels[i * 3 + 2] = temp[i * 4]; //R
}
return pixels;
}private void addFeature(String name) {
if (bitmap == null) {
Toast.makeText(context, "请先拍照", Toast.LENGTH_SHORT).show();
return;
}
byte[] srcData = FileUtils.getPixelsBGR(bitmap);
SunmiFaceImage image = new SunmiFaceImage(srcData, bitmap.getHeight(), bitmap.getWidth(), 1);
SunmiFaceImageFeatures features = new SunmiFaceImageFeatures();
SunmiFaceSDK.getImageFeatures(image, features);
SunmiFaceFeature feature_ary = features.getFeatures();
Log.e("ma", "face info: " + features.getFeaturesCount());
if (features.getFeaturesCount() == 0) {
showId("没有检测到人脸，请重新拍照！");
return;
}
SunmiFaceFeature feature = SunmiFaceLib.SunmiFaceFeatureArrayGetItem(feature_ary, 0);
SunmiFaceDBRecord record = SunmiFaceSDK.faceFeature2FaceDBRecord(feature);
record.setId(name);
record.setName(name);
SunmiFaceSDK.addDBRecord(record);
SunmiFaceSDK.releaseImageFeatures(features);
Log.e("face", "采集成功 " + etName.getText().toString());
feature.delete();
}3.10. 人脸库添加人脸特征
注意：商米人脸识别SDK包产品中的离线人脸库只存不可逆的人脸特征值，并不存储原始照片，在每次识别过程中也不存储照片。
SunmiFaceDBRecord包含img_id_、id和name三个参数，其中img_id_无需设置，id和name需要调用者进行设置：
- img_id_无需设置。调用addDBRecord将记录成功加入到人脸库后，SunmiFaceDBRecord中img_id_会自动被设置为人脸库中代表此图片的唯一id。img_id_可以理解为录入图片的唯一名字，SDK保证返回的img_id不重复。用户可以以img_id为文件名来保存拍摄的人脸照片。根据此img_id可以调用deleteDBRecord来删除这条记录。
- id为被录入人脸的人员的唯一id。SDK考虑开发者调用的灵活性，没有对其唯一性进行限制。在通常情况下，建议调用者务必保证id的唯一性，id可理解为一般不会重号的身份证号，食堂卡号，会员号等。
- name可以不唯一，允许出现两个人名相同的情况，同时允许每个人录入多张人脸。
示例：
数据库中记录：
用户A，id为0001，姓名张三，图片1，图片2；
用户B, id为0002，姓名也是张三，图片3，图片4，图片5。
用户A和B同名，并且都有多张图片，存储每张图片提取的人脸特征。
注：通常在私域情形下，在被采集人知情情况下，建议将被识别的人脸底图存储于安全位置， 推荐采用addDBRecord接口返回的SunmiFaceDBRecord里面的getImgId()来命名图片，以绑定图片和人脸库中人脸特征，方便后期对人脸库进行相关操作和比对 。
3.11. 获取人脸关键点
通过getLandmark_得到人脸关键点数组，在获取数组中的每个关键点信息。示例代码如下：
SunmiFaceFeature feature = SunmiFaceLib.SunmiFaceFeatureArrayGetItem(feature_ary, 0);
SunmiFaceLmk lmk_ary = feature.getLandmark();
for(int i = 0; i < SunmiFaceLibConstants.SUNMI_FACE_LANDMARK_LEN; i++) {
SunmiFaceLmk lmk = SunmiFaceLib.SunmiFaceLmkArrayGetItem(lmk_ary, i);
lmk.delete();
}
feature.delete();3.12. 搜索人脸库
调用searchDB执行人脸库搜索寻找最相似的人脸。如果SDK判断人脸距离小于阈值，matched设为true，否则为false。示例代码如下：
SunmiFaceDBRecord record = SunmiFaceSDK.faceFeature2FaceDBRecord(feature);
SunmiFaceDBIdInfo info = new SunmiFaceDBIdInfo();
SunmiFaceSDK.searchDB(record, info);
if (info.getIsMatched()) {
Log.e("ma", “Found”);
}
else {
Log.e("ma", “Not Found”);
}3.13. 人脸1：1比对
分别对要比对的两张图片进行人脸特征的提取，得到类型为SunmiFaceFeature两个人脸特征feature1，feature2。在调用compare1v1接口得到比对结果。getIsMatched()得到比对结果，getDistance()得到两张人脸的距离度量。
SunmiFaceCompareResult result;
int code = SunmiFaceSDK.compare1v1(feature1, feature2, result)
boolean isMatched = result.getIsMatched()
float distance = result.getDistance();3.14. 获取人脸属性
人脸属性首先需要获取人脸特征faceFeature，再根据人脸特征获取年龄和性别属性，主要示例代码如下：
SunmiFaceFeature faceFeature = SunmiFaceLib.SunmiFaceFeatureArrayGetItem(features.getFeatures(), 0);
SunmiFaceAge ageInfo = faceFeature.getAge();
int age = ageInfo.getClassification();
float ageScore = ageInfo.getScore();
SunmiFaceGender genderInfo = faceFeature.getGender();
int gender = genderInfo.getClassification();
float genderScore = genderInfo.getScore();
feature.delete();3.15. 执行功能选择
功能选择是为了方便开发者在实际开发中只选择所需的SDK功能，减少计算资源和时间的浪费。该功能可通过SunmiFaceImage中定义的predict_mode_成员进行控制。
例如：在3.9和3.14中，分别介绍了商米人脸识别SDK提取人脸特征和人脸属性获取的功能。实际上，SDK在这两小节提供的代码中同时完成了人脸检测、人脸特征提取及人脸属性识别。若开发者只需使用其中一个，三个功能同时进行会极大地浪费计算资源和时间。因此，可以使用功能选择进行控制，主要示例代码如下：
image = new SunmiFaceImage(srcData, bitmap.getHeight(), bitmap.getWidth(), 1); //根据bitmap创建SunmiFaceImage对象
SunmiFaceImageFeatures features = new SunmiFaceImageFeatures(); //创建空的SunmiFaceImageFeatures对象
image.setPredictMode(SunmiFaceMode.PredictMode_Age); //只进行年龄预测
image.setPredictMode(SunmiFaceMode.PredictMode_Feature); //只进行特征提取
image.setPredictMode(SunmiFaceMode.PredictMode_Detect); //只进行人脸检测
image.setPredictMode(SunmiFaceMode.PredictMode_Age|SunmiFaceMode.PredictMode_Feature); //进行人脸特征提取和年龄预测
image.setPredictMode(SunmiFaceMode.PredictMode_Age|SunmiFaceMode.PredictMode_Feature|PredictMode_Gender); //进行人脸特征提取及年龄性别预测，即执行SDK的全部功能，此行代码可以不写，SDK默认模式为执行全部功能
ret = SunmiFaceSDK.getImageFeatures(image, features); //根据选择的模式提取相应特征3.16. 活体检测
SDK支持三种活体检测，分别是RGB彩色图活体检测、NIR近红外活体检测和3D结构光活体检测，目前SDK仅支持在同一时刻做一种活体检测。由于NIR近红外和3D结构光活体检测对摄像头设备及SDK配置有特定要求，因此本文主要介绍RGB彩色图活体检测，NIR近红外活体和3D结构光活体检测可通过以下链接参考文档 NIR近红外和3D结构光活体检测。
RGB彩色图活体使用普通摄像头图片判断，抵御能力普通，此外由于RGB彩色图活体检测需要考虑脸部的细节信息，因此要求适配的摄像头需支持720p以上的分辨率。如果场景对活体有较高要求，建议直接考虑NIR近红外活体和3D结构光活体。
如需要启用RGB彩色图活体检测功能，可依次添加以下三个步骤：
第一步： 在第3.7节的配置SDK时 ，添加对RGB彩色图活体检测阈值设定：
param.setRgbLivenessThreshold(0.5f); //阈值越高，活体检测越严格，人脸通过活体检测的难度越大第二步：检查第3.15节中提到的执行选择功能不是PredictMode_None ，并且在第3.9节中提到的用SunmiFaceImage构造函数创建SunmiFaceImage实例后，通过实例中的setLivenessMode方法指定需要进行的活体检测方法：
SunmiFaceImage image = new SunmiFaceImage(srcData, bitmap.getHeight(), bitmap.getWidth(), 1);
image.setPredictMode(SunmiFaceMode.PredictMode_Feature);//执行功能选择不能是PredictMode_None
image.setLivenessMode(SunmiFaceLivenessMode.LivenessMode_None);//不进行活体检测
image.setLivenessMode(SunmiFaceLivenessMode.LivenessMode_RGB);//只进行RGB活体检测第三步：获取活体检测分数及SDK返回的响应值：
SunmiFaceImageFeatures features = new SunmiFaceImageFeatures(); //构造空的人脸特征对象
ret = SunmiFaceSDK.getImageFeatures(image, features); //使用人脸识别SDK进行特征提取
SunmiFaceFeature faceFeature = SunmiFaceLib.SunmiFaceFeatureArrayGetItem(features.getFeatures(), 0); //提取置信度最高的人脸特征信息
float rgb_liveness_score = faceFeature.getRgbLivenessScore(); //获取置信度最高的人脸活体检测分数
feature.delete();开发者可根据自己的需求对rgb_liveness_score进行后续代码逻辑开发。当返回的ret为FACE_CODE_NOT_LIVENESS时，说明SDK根据当前设定的活体检测阈值认为当前人脸是假脸；而ret为FACE_CODE_OK时说明当前人脸通过了活体检测。
3.17. 释放 SDK句柄
调用完成后， 需要释放商米人脸识别SDK句柄，同时释放模型等资源。如需再次使用SDK，需要先调用createHandle接口， 主要示例代码如下：
SunmiFaceSDK.releaseHandle();4. 数据类型定义
4.1. 类型别名
| 别名 | 类型 | 说明 |
| SunmiFaceStatus | int | Typedef，定义在face_type.h 文件中 |
| SunmiFaceHandle | void* | Typedef，定义在face.h 文件中 |
4.2. 宏
接口使用的数据类型定义在face_type.h头文件中，主要数据如下：
| 成员 | 值 | 说明 |
| SUNMI_FACE_FEATURE_LEN | 256 | 人脸特征向量长度 |
| SUNMI_FACE_ID_LEN | 64 | id字符长度限制 |
| SUNMI_FACE_NAME_LEN | 64 | 人脸用户名长度 |
| SUNMI_FACE_IMG_ID_LEN | 64 | 人脸采集图片ID长度 |
| SUNMI_FACE_LANDMARK_LEN | 5 | 人脸关键点数量 |
4.3. 枚举类型
接口使用的数据结构定义在face_type.h头文件中。
4.3.1. SunmiFaceStatusCode 商米人脸识别状态码
| 枚举成员 | 状态码 | 说明 |
| FACE_CODE_OK | 0 | 正确 |
| FACE_CODE_UNINIT | 1 | SDK没有初始化 |
| FACE_CODE_EMPTY_IMAGE | 2 | 图片为空 |
| FACE_CODE_NO_MODEL | 3 | 无加载模型文件 |
| FACE_CODE_CONFIG_ERROR | 4 | 配置错误 |
| FACE_CODE_BAD_ILLUMINATION | 5 | 光线条件不好 |
| FACE_CODE_POSE_ERROR | 6 | 面部位置不符合要求 |
| FACE_CODE_SMALL_FACE_SIZE | 7 | 人脸尺寸太小 |
| FACE_CODE_LOW_IMAGE_QUALITY | 8 | 人脸图像模糊 |
| FACE_CODE_NOT_LIVENESS | 9 | 非活体人脸图像 |
| FACE_CODE_LICENSE_ERROR | 10 | 授权文件无效 |
| FACE_CODE_LICENSE_EXPIRED | 11 | 授权文件过期 |
| FACE_CODE_FACE_DB_ERROR | 12 | 人脸库加载失败 |
| FACE_CODE_IMAGE_ID_ERROR | 101 | 删除时图像id不存在 |
| FACE_CODE_OTHER_ERROR | 1000 | 其他错误 |
4.3.2. SunmiFaceGenderType 性别类型
| 枚举成员 | 值 | 说明 |
| FACE_ATTR_FEMALE | 0 | 性别女 |
| FACE_ATTR_MALE | 1 | 性别男 |
4.3.3 SunmiFaceMode 执行功能选择
| 枚举成员 | 值 | 说明 |
| PredictMode_None | 0 | 不执行任何功能 |
| PredictMode_Detect | 1 | 执行人脸检测 |
| PredictMode_Feature | 3 | 执行人脸特征提取 |
| PredictMode_Age | 5 | 执行年龄预测 |
| PredictMode_Gender | 5 | 执行性别预测 |
4.3.4 SunmiFaceLivenessMode 活体检测功能选择
| 枚举成员 | 值 | 说明 |
| LivenessMode_None | 0 | 不执行活体检测 |
| LivenessMode_RGB | 1 | 进行RGB活体检测 |
| LivenessMode_NIR | 2 | 进行NIR活体检测 |
| LivenessMode_Depth | 4 | 进行深度图活体检测 |
4.3.5 SunmiFaceBoxSortMode 人脸框排序方式选择
| 枚举类型 | 值 | 说明 |
| BoxSortMode_Score | 0 | 按 人脸框置信度进行排序 |
| BoxSortMode_Size | 1 | 按人脸框尺寸进行排序 |
| BoxSortMode_Position | 2 | 按人脸框位置进行排序（优先选择居中位置） |
4.4. 结构体类型
4.4.1. SunmiFaceRect人脸框位置
| 成员 | 类型 | 说明 |
| x1_ | float | 人脸框左上角横坐标 |
| y1_ | float | 人脸框左上角纵坐标 |
| x2_ | float | 人脸框右下角横坐标 |
| y2_ | float | 人脸框右小角纵坐标 |
| score_ | float | 置信度 |
4.4.2. SunmiFaceLmk人脸关键点坐标
| 成员 | 类型 | 说明 |
| x_ | float | 关键点横坐标 |
| y_ | float | 关键点纵坐标 |
4.4.3. SunmiFaceImage人脸识别输入图像
| 成员 | 类型 | 说明 |
| buf_ | unsigned char * | 图片像素字节地址 |
| buf_len_ | int | 字节缓冲区长度 |
| img_w_ | int | 图像宽度 |
| img_h_ | int | 图像高度 |
| max_face_count_ | int | 单图人脸数最大返回值 |
| depth_buf_ | unsigned char * | 深度图数据字节地址 |
| depth_buf_len_ | int | 深度图数据长度 |
| depth_img_w_ | int | 深度图宽度 |
| depth_img_h_ | int | 深度图高度 |
| nir_buf_ | unsigned char * | 红外图数据字节地址 |
| nir_buf_len_ | int | 红外图数据长度 |
| nir_img_w_ | int | 红外图宽度 |
| nir_img_h_ | int | 红外图高度 |
| liveness_mode_ | int | 需要执行的活体检测功能选择 |
| predict_mode_ | int | 需要执行的功能选择 |
4.4.4. SunmiFacePose人脸姿态
| 成员 | 类型 | 说明 |
| pitch_ | float | 俯仰角度 |
| yaw_ | float | 偏航角度 |
| roll_ | float | 翻滚角度 |
4.4.5. SunmiFaceAge 年龄
| 成员 | 类型 | 说明 |
| classification_ | int | 年龄范围（0-74岁） |
| score_ | float | 置信度 |
4.4.6. SunmiFaceGender 性别
| 成员 | 类型 | 说明 |
| classification_ | int | 性别分类(0: female ; 1: male) |
| score_ | float | 置信度 |
4.4.7. SunmiFaceFeature单个特征提取输出信息结构体
| 成员 | 类型 | 说明 |
| face_rect_ | SunmiFaceRect | 人脸矩形框位置 |
| rgb_liveness_score_ | float | RGB活体检测分数 |
| nir_liveness_score_ | float | NIR活体检测分数 |
| depth_liveness_score_ | float | 深度图活体检测分数 |
| feature_[SUNMI_FACE_FEATURE_LEN] | float | 人脸特征数组 |
| landmark_[SUNMI_FACE_LANDMARK_LEN] | SunmiFaceLmk | 关键点 |
| pose_ | SunmiFacePose | 人脸姿态 |
| age_ | SunmiFaceAge | 年龄 |
| gender_ | SunmiFaceGender | 性别 |
4.4.8. SunmiFaceImageFeatures多个特征提取输出信息结构体
| 成员 | 类型 | 说明 |
| features_ | SunmiFaceFeature * | 特征数组 |
| features_count_ | int | 特征数组长度 |
4.4.9. SunmiFaceConfigParam人脸配置参数
| 成员 | 类型 | 说明 |
| thread_num_ | int | SDK人脸检测人脸识别计算使用的线程数量（cpu核数），0代表使用所有的cpu核 |
| distance_threshold_ | float | 人脸距离阈值 |
| yaw_threshold_ | float | 偏航角度阈值 |
| pitch_threshold_ | float | 俯仰角度阈值 |
| roll_threshold_ | float | 翻滚角度阈值 |
| min_face_size | int | 人脸最小尺寸 |
| image_quality_threshold_ | float | 图像质量阈值 |
| min_luminance_ | int | 最低亮度 |
| max_luminance_ | int | 最高亮度 |
| rgb_liveness_threshold_ | float | RGB活体检测阈值 |
| depth_liveness_threshold_ | float | 3D活体检测阈值 |
| nir_liveness_threshold_ | float | NIR活体检测阈值 |
| depth_x_offset | int | 深度图相对于彩色图x方向偏移 |
| depth_y_offset | int | 深度图相对于彩色图y方向偏移 |
| nir_x_offset | int | 红外图相对于彩色图x方向偏移 |
| nir_y_offset | int | 红外图相对于彩色图y方向偏移 |
4.4.10. SunmiFaceCompareResult人脸匹配结果
| 成员 | 类型 | 说明 |
| is_matched_ | bool | 如果距离小于人脸间距阈值，则为真，否则为假 |
| distance_ | float | 人脸距离 |
4.4.11. SunmiFaceDBRecord人脸数据库记录
| 成员 | 类型 | 说明 |
| id_[SUNMI_FACE_ID_LEN] | char | 人脸唯一id |
| name_[SUNMI_FACE_NAME_LEN] | char | 用户名 |
| img_id_[SUNMI_FACE_IMG_ID_LEN] | char | 人脸采集图像唯一id |
| feature_[SUNMI_FACE_FEATURE_LEN] | float | 人脸特征 |
4.4.12. SunmiFaceDBIdInfo人脸数据库信息
| 成员 | 类型 | 说明 |
| id_[SUNMI_FACE_ID_LEN] | char | 人脸唯一id |
| name_[SUNMI_FACE_NAME_LEN] | char | 用户名 |
| is_matched_ | bool | 如果距离小于人脸间距阈值，则为真，否则为假 |
| distance_ | float | 人脸距离 |
5. Java函数接口定义
对外接口的定义在SunmiFaceSDK.java文件中。
5.1. 接口类定义
| 类名 | 说明 |
| SunmiFaceSDK | 人脸识别接口类名定义 |
5.2. 函数接口定义
5.2.1. getVersion
函数定义：public static String getVersion()
函数功能：获取Sunmi人脸识别SDK版本号
返回值：SDK版本字符串
5.2.2. createHandle
函数定义： public static int createHandle()
函数功能： 创建商米人脸识别SDK句柄，需要在其他接口被使用前调用。 在安全性方面，SDK内部可以保证多次调用不会重复创建SDK句柄
返回值： SunmiFaceStatusCode
5.2.3. Init
函数定义：public static int init(String configPath)
函数功能：初始化SDK
| 变量 | 类型 | 说明 |
| configPath | String | 配置文件路径 |
返回值：SunmiFaceStatusCode
5.2.4. verifyLicense
函数定义：public static int verifyLicense(Context context, String license)
函数功能：验证许可证
| 变量 | 类型 | 说明 |
| context | Context | Android context |
| license | String | 许可证字符串 |
返回值：SunmiFaceStatusCode
5.2.5. getDeviceFingerprint
函数定义：public static String getDeviceFingerprint(Context context)
函数功能：获取Android设备指纹
| 变量 | 类型 | 说明 |
| context | Context | android context |
返回值：设备指纹字符串
5.2.6. getErrorString
函数定义：public static String getErrorString(int code)
函数功能：获得错误字符串
| 变量 | 类型 | 说明 |
| code | int | 错误代码 |
返回值：错误描述字符串
5.2.7. setConfig
函数定义：public static int setConfig(SunmiFaceConfigParam config)
函数功能：设置配置
| 变量 | 类型 | 说明 |
| config | SunmiFaceConfigParam | SDK配置参数 |
返回值：SunmiFaceStatusCode
5.2.8. getConfig
函数定义：public static int getConfig(SunmiFaceConfigParam config)
函数功能：获取当前SDK配置
| 变量 | 类型 | 说明 |
| config | SunmiFaceConfigParam | SDK配置参数 |
返回值：SunmiFaceStatusCode
5.2.9. getImageFeatures
函数定义：public static int getImageFeatures(SunmiFaceImage image, SunmiFaceImageFeatures features)
函数功能：从图像中进行人脸检测和人脸特征提取
| 变量 | 类型 | 说明 |
| image | SunmiFaceImage | 输入图像 |
| features | SunmiFaceImageFeatures | 返回人脸特征 |
返回值：SunmiFaceStatusCode
5.2.10. compare1v1
函数定义：public int compare1v1(SunmiFaceFeature feature1, SunmiFaceFeature feature2, SunmiFaceCompareResult compare_result)
函数功能：人脸1:1比对
| 变量 | 类型 | 说明 |
| features1 | SunmiFaceFeature | 人脸特征1 |
| features2 | SunmiFaceFeature | 人脸特征2 |
| compare_result | SunmiFaceCompareResult | 比对结果 |
返回值：SunmiFaceStatusCode
5.2.11. releaseImageFeatures
函数定义：public static int releaseImageFeatures(SunmiFaceImageFeatures features)
函数功能：释放人脸特征
| 变量 | 类型 | 说明 |
| features | SunmiFaceImageFeatures | 人脸特征 |
返回值：SunmiFaceStatusCode
5.2.12. releaseHandle
函数定义： public static int releaseHandle()
函数功能： 释放商米人脸识别SDK句柄，同时释放模型等资源。如需再次使用SDK，需要先调用createHandle接口。
返回值： SunmiFaceStatusCode
5.2.13. initDB
函数定义：public static int initDB(String db_name)
函数功能：初始化新人脸数据库
| 变量 | 类型 | 说明 |
| db_name | String | 人脸数据库文件名 |
返回值：SunmiFaceStatusCode
5.2.14. faceFeature2FaceDBRecord
函数定义：public static SunmiFaceDBRecord faceFeature2FaceDBRecord(SunmiFaceFeature feature)
函数功能：将人脸特征结构体转换成人脸库记录结构体
| 变量 | 类型 | 说明 |
| feature | SunmiFaceFeature | 人脸特征 |
返回值：SunmiFaceDBRecord
5.2.15. addDBRecord
函数定义：public static int addDBRecord(SunmiFaceDBRecord record)
函数功能：添加一条记录到人脸数据库，添加成功后通过img_id_可以的到人脸库中图片的ID，后续可以用来删除操作
| 变量 | 类型 | 说明 |
| record | SunmiFaceDBRecord | 人脸库记录结构体 |
返回值：SunmiFaceStatusCode
5.2.16. searchDB
函数定义：public static int searchDB(SunmiFaceDBRecord record, SunmiFaceDBIdInfo idInfo)
函数功能：数据库中1:N人脸比对
| 变量 | 类型 | 说明 |
| record | SunmiFaceDBRecord | 要搜索的人脸记录 |
| idInfo | SunmiFaceDBIdInfo | 搜索结果 |
返回值：SunmiFaceStatusCode
5.2.17. deleteDBRecord
函数定义：public static int deleteDBRecord(String img_id)
函数功能：根据图像id删除人脸数据库中的一条记录
| 变量 | 类型 | 说明 |
| img_id | String | 人脸采集图像的ID |
返回值：SunmiFaceStatusCode
