注:最新版本人脸识别离线SDK已更新至1.9版本,请参考最新版本:人脸识别Andriod_SDK_1.9
商米人脸识别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 Context
3.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