本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 成功獲取到人臉特征值 } } } } }