人脸识别SDK¶
本SDK开发指南指导您如何安装和配置开发环境,如何通过调用 SDK 提供的接口函数(API)进行二次开发与系统集成。 用户按照要求调用SDK提供的API即可实现使用 人脸检测/跟踪、活体识别、人脸识别等服务的目的。
1. 主要返回参数¶
public static final int SUCCESS = 0; //执行接口返回成功
public static final int ERROR_INVALID_PARAM = -1; //非法参数
public static final int ERROR_TOO_MANY_REQUESTS = -2; //太多请求
public static final int ERROR_NOT_EXIST = -3; //不存在
public static final int ERROR_FAILURE = -4; // 执行接口返回失败
2. FaceInfo 人脸信息¶
public class FaceInfo {
public Rect mRect;//人脸方框
public FaceAttribute mAttr;//人脸属性
public FaceQuality mQuality;//人脸质量
public Landmark mLandmark;//用于存储5个关键点坐标值，依次是左眼、右眼、鼻子、左侧嘴唇、右侧嘴唇。
}
3. FaceAttribute 人脸属性¶
public class FaceAttribute {
public int mGender;//性别 0：男性；1：女性
public int mEmotion;//表情 0：平静；1：高兴
public int mAge;//年龄
}
4. FaceQuality 人脸质量¶
public class FaceQuality {
public float mScore;//人脸质量的置信度
public float mLeftRight;//左右角度
public float mUpDown;//上下角度
public float mHorizontal;//水平角度
public float mClarity;//图片清晰度
public float mBright;//亮度
}
5. 构造函数¶
static FaceAPP GetInstance()
功能 获取单例的对象,人脸识别类采用单例模式,一个类Class只有一个实例存在
参数 无
返回值 FaceAPP类型的对象
实例代码 ：
private FaceAPP face = FaceAPP.GetInstance();
6. 识别人脸特征¶
int Recognize( Image image, float featureArray [][512], int size, List
faceinfos, int[] res ) 功能 识别提交的Image中的人脸特征,然后和featureArray里这些特征数组进行比较,找出其中相似度
最高的返回特征数组的二维数组的索引值参数 image : 人脸图片
featureArray : 特征数组的二维数组,特征值数组是存储人脸特征信息的数组,由512个float组成。
size : 特征数组的二维数组大小
faceinfos : FaceInfo 清单。<用于保存返回人脸在图片中的信息>
res: 执行结果,未发现人脸返回 ERROR_INVALID_PARAM,
image中人脸不在feature数组中返回 ERROR_NOT_EXIST, >=0特征数组的索引返回值 执行成功 SUCCESS
执行失败 ERROR_FAILURE
实例代码 ：
float[][] featurelist = new float[][]; //存储特征值的数组
int size = featurelist.lenth;
int[] ret = new int[1];
byte[] tmpPos = new byte[1024];
FaceAPP.Image image = FaceAPP.GetInstance().new Image();
image.matAddrframe = mRgbaFrame.getNativeObjAddr();
face.Recognize( image, featurelist, size, tmpPos, res );
7. 识别人脸特征(根据特征值)¶
int Recognize( float[] feature, float featureArray [][512], int size, float[] high, int[] res )
功能 根据已经存在的人脸特征,然后和featureArray里这些特征数组进行比较,找出其中相似度
最高的返回特征数组的二维数组的索引值,返回相似度得分值。参数 feature : 特征数组
featureArray : 特征数组的二维数组,特征值数组是存储人脸特征信息的数组,
由512个float组成。
size : 特征数组的二维数组大小
high : float[]型,返回最大得分值
res : 执行结果,未发现人脸返回 ERROR_INVALID_PARAM,
image中人脸不在feature数组中返回 ERROR_NOT_EXIST,
>=0特征数组的索引号返回值
执行成功 SUCCESS 执行失败 ERROR_FAILURE
实例代码 ：
float[][] featurelist = new float[][]; //存储特征值的数组
int size = featurelist.lenth;
int[] ret = new int[1];
byte[] tmpPos = new byte[1024];
float[] feature;
float[] high = float[1];
FaceAPP.Image image = FaceAPP.GetInstance().new Image();
image.matAddrframe = mRgbaFrame.getNativeObjAddr();
face.Recognize( feature, featurelist, size, high, tmpPos, res );
8. 检测人脸¶
int Detect( Image image, List
faceinfos, int[] res ) 功能 检测提交的图片中的是否有人脸
参数 image : 人脸图片,用于检测的图片
faceinfos : FaceInfo 清单。<用于保存返回人脸在图片中的信息>
res : 执行结果,未发现人脸返回 ERROR_INVALID_PARAM返回值
执行成功 SUCCESS
执行失败 ERROR_FAILURE
实例代码 ：
int[] ret = new int[1];
byte[] tmpPos = new byte[1024];//byte数组用于存位置信息
FaceAPP.Image image = FaceAPP.GetInstance().new Image(); //初始化
image.matAddrframe = mRgbaFrame.getNativeObjAddr(); //image赋值
if( success = face.Detect( image, tmpPos, res ) ){
//to do
};
9. 比较特征数据¶
int Compare( float[] origin, float[] chose, float score )
功能 用于比较两个feature值相似度
参数 origin : 待比较feature数组
chose : 用于比较的feature数组
score : origin和chose比较的相似度返回值
执行成功 SUCCESS
执行失败 ERROR_FAILURE
实例代码 ：
float score;
float[] origin = new float[512];
Float[] chose = new float[512];
face.Compare( origin, chose, score );
10. 双目带有活体的提取人脸特征¶
int GetFeature( Image image, Image grayImage, float[] feature, List
faceinfos, int[] res ) 功能 获取image中的人脸特征值数组,特征值数组是存储人脸特征信息的数组,
由512个float型数字组成,只获取图片中一个人的特征,多于一人会返回错误信息。参数 image : 人脸图片,用于检测的图片
grayImage : 红外摄像头获取的图片
feature : 存储image中检测到的人脸特征信息,无人脸返回空数组
faceinfos : FaceInfo 清单。<用于保存返回人脸在图片中的信息>
res : 执行结果,未发现人脸返回 ERROR_INVALID_PARAM返回值
SUCCESS : 正确获取人脸信息
ERROR_FAILURE : 未获取到人脸信息
实例代码 ：
float[] feature = new float[512];
int[] ret = new int[1];
byte[] tmpPos = new byte[1024]; //byte数组用于存位置信息
ret = face.GetFeature( image, grayImage, feature, tmpPos, res);
if( ret == SUCCESS ){
//to do 成功获取到活体人脸特征值
}
11. 活体检测¶
int DetectLiveness(Image image, List
faceinfos, int[] res) 功能 检测识别活体和非活体。
参数 image : 彩色人脸图片,用于检测和识别的图片。
faceinfos : FaceInfo 清单。<用于保存返回人脸在图片中的信息>
res : 执行结果,未发现人脸返回 ERROR_INVALID_PARAM返回值
SUCCESS : 是活体
ERROR_FAILURE : 非活体
实例代码 ：
int[] ret=new int[1];
ret= face.DetectLiveness(image,grayImage ,tmpPos,res);
if(ret== SUCCESS){
//to do 活体检测成功
}
12. 双目活体检测¶
int GetDetectLiveness(Image image, Image grayImage, List
faceinfos, int[] res) 功能 检测识别活体和非活体。
参数 image : 彩色人脸图片,用于检测和识别的图片。
grayImage :红外摄像头获取的图片。
faceinfos : FaceInfo 清单。<用于保存返回人脸在图片中的信息>
res : 执行结果,未发现人脸返回 ERROR_INVALID_PARAM返回值
SUCCESS : 是活体
ERROR_FAILURE : 非活体
实例代码 ：
int[] ret=new int[1];
ret= face.GetDetectLiveness(image,grayImage ,tmpPos,res);
if(ret== SUCCESS){
//to do 活体检测成功
}
13. 双目校准¶
int Calibration( Image image, Image grayImage, float[] scale, int[] Rect, int[] res );
功能 对红外和普通光组成的双摄像头识别进行校准,要求1个人在最佳位置(0.8-1米)站定,
大约需要校验20次,得到人脸框修正参数用于人脸画框,
返回红外摄像头相对普通光的显示区域坐标,该区域是有效识别和活体检测区域参数 image : 输入红外图像
grayImage : 输入彩色图像
scale : 输出 人脸框修正参数
rect : 输出红外图像与彩色图像重叠区域(红外图像在彩色图像的对应区域/推荐的检测区域)
res : 执行结果,未发现人脸返回 ERROR_INVALID_PARAM返回值
SUCCESS : 正确校准
ERROR_FAILURE : 校准失败
实例代码 ：
int[] ret = new int[1];
float[] scale = new float[1];
int[] rect = new int[4];
ret = face.Calibration( image, grayimage, scale, rect, res );
if( ret == SUCCESS ){
//to do 校准成功
}
14. 设备激活一¶
int AuthorizedDevice( String uidStr, String password, Context activity )
功能 设备激活
参数 uidStr : OEMID号+合同号
password : 用户密码返回值
0 : 鉴权成功
实例代码 ：
String oem_id = "1000000000000001";//OEMID
String contract_id = "0001";//合同号
String password = "0123456789abcdef0123456789abcdef"; //初始授权密码
String uidStr = oem_id + contract_id;
int res = face.AuthorizedDevice( uidStr, password, LoginActivity.this );
15. 设备激活二¶
int fireflyInit(Context context, String uidStr, String password)
功能 设备激活，这个接口是firefly一个临时接口，可以永久激活设备，该接口到后面可能会被移除，
如果后续开发文档中没有该接口说明，则已被移除。开发文档以开源Demo中的文档为准。参数 uidStr : OEMID号+合同号
password : 用户密码返回值
0 : 鉴权成功
实例代码 ：
String oem_id = "1000000000000001";//OEMID
String contract_id = "0001";//合同号
String password = "0123456789abcdef0123456789abcdef"; //初始授权密码
String uidStr = oem_id + contract_id;
int res =face.fireflyInit(LoginActivity.this, uidStr, password);
16. 设备激活三¶
int AuthorizedDeviceUserPassword(String uidStr, String password, Context context, String userPassword)
功能 设备激活，这个接口主要用于带有用户密码的激活方式。
参数 uidStr : OEMID号+合同号
password : 授权密码
userPassword:用户密码返回值
0 : 鉴权成功
实例代码 ：
String oem_id ="1000000000000001";//OEMID
String contract_id ="0001";//合同号
String password = "0123456789abcdef0123456789abcdef";//初始授权密码
String userPassword ="012345678912";//授权密码;
String uidStr = oem_id+contract_id;
int res =face. AuthorizedDeviceUserPassword(uidStr,password,
LoginActivity.this,userPassword);
17. 获取鉴权激活状态值¶
int getAuthStatus()
功能 获取鉴权激活状态值
参数 无
返回值
0 : 鉴权成功
实例代码 ：
int res = face.getAuthStatus();
18. 提取人脸特征¶
int GetFeature( Image image, float[] feature, List
faceinfos, int[] res ) 功能 获取image中的人脸特征值数组,特征值数组是存储人脸特征信息的数组,
由512个float型数字组成,只获取图片中一个人的特征。参数 image : 人脸图片,用于检测的图片
feature : 存储image中检测到的人脸特征信息,无人脸返回空数组
faceinfos : FaceInfo 清单。<用于保存返回人脸在图片中的信息>
res : 执行结果,未发现人脸返回 ERROR_INVALID_PARAM返回值
SUCCESS : 正确获取人脸信息
ERROR_FAILURE : 未获取到人脸信息
实例代码 ：
float[] feature = new float[512];
int[] ret = new int[1];
byte[] tmpPos = new byte[1024]; //byte数组用于存位置信息
ret = face.GetFeature( image, feature, tmpPos, res );
if( ret == SUCCESS ){
//to do 成功获取到人脸特征值
}
19. 提取人脸特征(根据人脸坐标信息)¶
int GetFeature( Image image, FaceInfo detectInfo, float[] feature, int[] res )
功能 根据传入的人脸和关键点坐标信息,获取image中的人脸特征值数组,
特征值数组是存储人脸特征信息的数组,由512个float型数字组成,
只获取图片中一个人的特征。参数 image : 人脸图片,用于检测的图片
detectInfo : 检测到的人脸信息,用于人脸特征提取
feature : 存储image中检测到的人脸特征信息,无人脸返回空数组
res : 执行结果,未发现人脸返回 ERROR_INVALID_PARAM返回值
SUCCESS : 正确获取人脸信息
ERROR_FAILURE : 未获取到人脸信息
实例代码 ：
float[] feature = new float[512];
int[] ret = new int[1];
float[] detectinfo = new float[]{ x0, y0, x1, y1, landmarkx0, landmarky0,
landmarkx1, landmarky1, landmarkx2, landmarky2,
landmarkx3, landmarky3, landmarkx4, landmarky4 }
byte[] tmpPos = new byte[1024]; //byte数组用于存位置信息
ret = face.GetFeature( image, detectinfo, feature, res );
if( ret == SUCCESS ){
//to do 成功获取到人脸特征值
}
20. 提取人脸特征(根据图片文件)¶
float[] GetFeature(String path, List
faceinfos) 功能 根据传入的图片文件路径,获取image中的人脸特征值数据。
参数 path :人脸图片文件的绝对路径
faceinfos : FaceInfo 清单。<用于保存返回人脸在图片中的信息>返回值
Float[] : 人脸特征值数组
实例代码 ：
int ret = this.FaceGetFeatureFromAddr(addr, feature, mFaceInfos, policy);
if (ret == -1) {
return null;
} else {
faceInfos.addAll(Arrays.asList(this.mFaceInfos).subList(0,ret));
return this.feature;
}
21. 提取人脸关键点¶
int GetLandmark ( Image image, float[] landmark, int[] res )
功能 获取人脸关键点坐标信息
参数 Image : 人脸图片,用于提取人脸关键点信息的图片,只提取一个人的关键点信息
Landmark : 用于存储5个关键点坐标值,依次是左眼,右眼,鼻子,左侧嘴唇,右侧嘴唇
res : 执行结果,未发现人脸返回 ERROR_INVALID_PARAM返回值
SUCCESS : 正确获取人脸关键点坐标信息
ERROR_FAILURE : 未获取到人脸关键点信息
实例代码 ：
float[] landmark = new float[10];
int[] ret = new int[1];
ret = face.GetLandmark( image, landmark, res);
if( ret == SUCCESS ){
}
22. 人脸质量提取¶
FaceInfo getQuality(long matAddrframe)
功能 传入图像,返回图像中人脸位置和最大一张人脸的质量信息。
参数 matAddrframe : 保存在Mat中图像地址
返回值
FaceInfo : 用于保存返回人脸在图片中的信息
实例代码 ：
Faceinfo faceinfo=new Faceinfo();
faceinfo=face.getQuality(matAddrframe);
if(faceinfo!=null){
}
23. 参数设置¶
bool SetParameter( const String[] name, float value[] )
功能 设置输入的参数名和对应数值
参数 char[] name : 参数的名字
a : a参数值 内部参数,按示例设置,请不要随意修改
b : b参数值 内部参数,按示例设置,请不要随意修改
c : c参数值 内部参数,按示例设置,请不要随意修改
d : d参数值 内部参数,按示例设置,请不要随意修改
factor : 检测人脸放大比例 内部参数,按示例设置,请不要随意修改
min_size : 最小人脸框大小 范围 32-80
faceclarity : 照片清晰度阈值 范围 建议200-400
perfoptimize : 是否优化效果 范围 0或1
livenessdetect : 是否活体检测 范围0-1
gray2colorscale : 双目活体检测比值 范围 0.1-0.5
frame_num : 优化的帧数,范围20-40
quality_thresh : 图片质量阀值,建议范围0.7-0.8
mode : 工作模式 0 闸机 1 门禁
facenum : 检测最大人脸数,最多支持检测3张人脸识别1张脸,范围1-3
value[] : 参数的数值(可能多个)返回值 参数设置是否成功
实例代码 ：
String[] name = { "a", "b","c", "d", "factor", "min_size", "clarity", "perfoptimize",
"livenessdetect", "gray2colorscale", "frame_num", "qualit_thresh",
"mode", "facenum" };
double[] value = {0.9, 0.9, 0.9, 0.715, 0.6, 64, 400, 1, 0, 0.5, 20, 0.8, 1, 1 };
face.SetParameter( name, value );
24. 参数设置(参数可变长度)¶
bool SetParameters( String[] name, float value[] )
功能 可变长度的设置输入的参数名和对应数值
参数 char[] name : 参数的名字(>=1),详情见14,
value[] : 参数的数值(>=1个)返回值 参数设置是否成功
实例代码 ：
String[] name = { "perfoptimize", "livenessdetect", "frame_num", "quality_thresh",
"mode", "facenum" };
double[] value = { 1, 0, 20, 0.8, 1, 1 };
face.SetParameter( name, value );
25. 获取版本信息¶
public String GetVersion()
功能 获取当前SDK版本的信息
参数 无
返回值 返回当前版本信息的字符串
实例代码 ：
Face.GetVersion();
26. 获取底层库信息¶
public String GetFacelibVersion()
功能 获取当前SDK底层库的信息
参数 无
返回值 返回当前版本底层库的字符串
实例代码 ：
Face.GetFacelibVersion();
27. 打开人脸数据库¶
int OpenDB()
功能 使用人脸数据库,内部人脸数据库可实现1:N高效快速查询
参数 无
返回值
执行成功 SUCCESS
执行失败 ERROR_FAILURE
实例代码 ：
if(face.OpenDB() == SUCCESS){
// TODO
}
28. 注册人脸¶
int AddDB( float[] feature, string name )
功能 注册人脸
参数 feature : 人脸特征
name : 登记名字返回值
执行成功 SUCCESS
执行失败 ERROR_FAILURE
实例代码 ：
String name= "test";
int[] res=new int[];
if( Face.GetFeature( image, feature, tmpPos, res ) == SUCCESS ){
Face.AddDB ( feature, name );
}
29. 保存人脸¶
int SaveDB()
功能 将AddDB()写入的数据保存到文件；如果在reboot或者断电重启设备之前，没有调用SaveDB()，
则AddDB()添加的人脸将丢失。参数 无
返回值
执行成功 SUCCESS
执行失败 ERROR_FAILURE
实例代码 ：
Face.AddDB(feature,name);
...
//在添加人脸之后，要确保重启设备之前执行Face.SaveDB()；
Face.SaveDB();
30. 删除人脸¶
int DelDB(string name)
功能 删除人脸
参数 name : 要删除的名字
返回值
执行成功 SUCCESS
执行失败 ERROR_FAILURE
实例代码 ：
String name= "test";
Face.DelDB (name);
31. 删除所有已注册人脸¶
int DelAllDB()
功能 删除所有已注册人脸
参数 无
返回值
执行成功 SUCCESS
执行失败 ERROR_FAILURE
实例代码 ：
Face.DelAllDB ();
32. 查询人脸特征对应名字¶
String QueryDB( float[] feature, float [] score )
功能 给定人脸特征最接近的数据库所登记的人脸,并给出相似度
参数 feature : 人脸特征
score : 相似度分值返回值
执行成功 返回登记名字
执行失败 返回为unknown
实例代码 ：
float[] score = new float[1];
String name = Face.QueryDB( feature, score );
if( score > thresh_hold ){
// TODO
}
33. 关闭人脸数据库¶
int CloseDB()
功能 关闭人脸数据库
参数 无
返回值
执行成功 SUCCESS
执行失败 ERROR_FAILURE
实例代码 ：
if( Face.CloseDB() == SUCCESS ){
// TODO
}
34. 加载快速比对功能¶
int FastQueryInit()
功能 加载快速比对功能
参数 无
返回值
执行成功 SUCCESS
执行失败 ERROR_FAILURE
实例代码 ：
if(Face.FastQueryInit () == SUCCESS){
// TODO
}
35. 刷新快速比对缓存区¶
int FastQueryFlush(float [] data, int num)
功能 刷新快速比对缓存区
参数 Data : 外部特征缓存区
Num : 特征数量返回值
执行成功 SUCCESS
执行失败 ERROR_FAILURE
实例代码 ：
if(Face.FastQueryFlush(data,num) == SUCCESS){
// TODO
}
36. 快速查询¶
int FastQuery(float[] data, float[] feature, float[] scores, int num)
功能 快速查询
参数 Data : 外部特征缓存区
Feature : 要查询的特征
Scores:获得的相似度
Num : 特征数量返回值
执行成功 SUCCESS
执行失败 ERROR_FAILURE
实例代码 ：
if(Face.FastQuery(data,feature,num) == SUCCESS){
// TODO
}
37. 获取人脸属性¶
int GetFaceAttr( Image image, FaceInfo data, FaceAttribute face_attr, int *res )
功能 Detect后执行,通过检测获取的人脸位置和关键点信息,获取人脸属性包括年龄、性别和表情 。
参数 image : 人脸图片,用于检测的图片
data : 检测得到的人脸位置和人脸关键点信息
face_attr : 存储计算得到的人脸属性
res : 执行结果,未发现人脸返回 ERROR_INVALID_PARAM返回值
SUCCESS : 正确获取人脸属性
ERROR_FAILURE : 未获取到人脸属性
实例代码 ：
if( face.GetFaceAttr( Image, data, attr, res ) == SUCCESS ){
// TODO
}
39. 示例代码¶
初始化双目摄像头人脸识别Demo。
public class MainActivity extends Activity implements CvCameraViewListener2 {
private FaceAPP face= FaceAPP.GetInstance(); //face 作为成员变量
.........
@Override
protected void onCreate(Bundle savedInstanceState) {
.........
String[] name={"a","b","c","d","factor","min_size","clarity","perf-optimize","liveness-detect","gray2color-scale"};
double[] value={0.9,0.9,0.9,0.715,0.6,64,400,1,0,0.5};
face.SetParameter(name,value);
mainLoop = new Thread() { //人脸检测不要放在 Android 主线程
public void run() {
.........
float[] feature=new float[512];
byte[] tmpPos = new byte[1024];// byte 数组用于存位置信息
switch (mixController.curState){
......
case mixController. STATE_IDLE :
FaceAPP.Image image= FaceAPP. GetInstance ().new Image();
image.matAddrframe=mRgbaFrame.getNativeObjAddr();
int[] res=new int[1];
int ret;
ret= face.GetFeature(image,feature,tmpPos,res);
if(ret== SUCCESS){
//to do 成功获取到人脸特征值
}
}
}
}
}