fireflyFace-RK3399人脸识别SDK介绍

人脸识别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 }

38. 释放人脸识别资源

public void Destroy（）

功能   释放初始化和设置参数时分配的资源

参数   无

返回值  无

实例代码 ：

Face.Destroy（）;

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 成功获取到人脸特征值 } } } } }