ZKLiveFace SDK For Java

native class

  com.zkteco.android.biometric.ZKLiveFaceService  

动态库加载

  static {      System.loadLibrary("zkdnnapi");      System.loadLibrary("zkdnnfd");      System.loadLibrary("zkipbase");      System.loadLibrary("msvcr100");      System.loadLibrary("msvcp100");      System.loadLibrary("opencv_highgui2410");      System.loadLibrary("opencv_core2410");      System.loadLibrary("zksface");      System.loadLibrary("ZKLiveFace");  }  

接口

getHardwareId

  [函数]      public native static int getHardwareId(byte[] hwid, int[] size);  [功能]      获取机器码  [参数]      hwId[out]          返回机器码（建议预分配256字节，足够使用）      size[in/out]          [in]:hwId内存大小(字节数)          [out]:实际返回hwId长度  [返回值]      错误码(见附录1)  [示例]      byte[] hwid = new byte[256];      int[] size = new int[1];      size[0] = 256;      if (0 == ZKLiveFaceService.getHardwareId(hwid, size))      {          String hwidStr = new String(hwid, 0, size[0]);      }  [备注]      暂不支持      

getLastError

  [函数]      public native static int getLastError(long context,byte[] lasterror, int[] size);  [功能]      返回最近一次的错误信息  [参数]     context[in]          算法实例指针(允许传NULL)，当传的不为NULL时为该实例的最近一次错误(错误码为11时可调用该接口获取错误描述)      lasterror[out]          错误信息（建议预分配512字节，足够使用）      size[in/out]          [in]:version内存大小(字节数)          [out]:实际返回lasterror长度  [返回值]      错误码(见附录1)(该接口返回失败，一般错误原因是分配的内存不足)        [备注]      暂不支持      

version

  [函数]      public native static int version(byte[] version, int[] size);  [功能]      获取版本号  [参数]      version[out]          返回版本号(建议预分配32字节以上)      size[in/out]          [in]:version内存大小(字节数)          [out]:实际返回version长度  [返回值]      错误码(见附录1)  [示例]      byte[] version = new byte[256];      int[] size = new int[1];      size[0] = 256;      if (0 == ZKLiveFaceService.version(version, size))      {          String verStr = new String(version, 0, size[0]);      }    

loadImage

  [函数]      public native static int loadImage(String fileName, byte[] rawImage, int[] width, int[] height, int[] size);  [功能]      加载图片文件并转换为BGR格式图像数据  [参数]      fileName[in]          文件全路径(支持的格式有:png, bmp, tif, jpg)      rawImage[out]           BGR格式图像数据，请参考备注1的说明，得到要预分配的内存长度。返回原始图数据      width[out]          返回图像宽      height[out]          返回图像高      size[in/out]          [in]:rawImage分配内存大小          [out]:实际返回rawImage数据长度  [返回值]      错误码(见附录1)  [示例]      byte[] rawImage = null;      int[] width = new int[1];      int[] height = new int[1];      int[] size = new int[1];      int ret = 0;      if (0 == (ret = ZKLiveFaceService.loadImage(fileName, rawImage, width, height, size)))      {          rawImage = new byte[size[0]];          ret = ZKLiveFaceService.loadImage(fileName, rawImage, width, height, size);          ...      }  [备注]      1、rawImage为NULL时，接口调用成功则width，height返回原始图像的宽和高，size即为图像大小(应分配的内存大小)      2、默认获取到的原始图像数据为：BGR图像位深度为24位的原始图像数据  

loadImageFromMemoryExt

  [函数]      public native static int loadImageFromMemoryExt(byte[] ImageFileData ,int cbImageFileData,byte[] rawImage, int[] width, int[] height, int[] size);  [功能]     加载图片文件数据转并转换为BGR格式图像数据  [参数]      ImageFileData[in]          图像的文件数据(支持的格式有:png, bmp, jpg)      cbImageFileData[in]          图像的文件数据的大小      rawImage[out]           BGR格式图像数据，请参考备注1的说明，得到要预分配的内存长度。      width[out]          返回图像宽      height[out]          返回图像高      size[in/out]          [in]:rawImage分配内存大小          [out]:实际返回rawImage数据长度  [返回值]      错误码(见附录1)  [备注]      1、rawImage为NULL时，接口调用成功则width，height返回原始图像的宽和高，size即为图像大小(应分配的内存大小)      2、默认获取到的原始图像数据为：BGR图像位深度为24位的原始图像数据  

init

  [函数]      public native static int init(long[] context);  [功能]      初始化算法库  [参数]      context[out]          返回算法实例指针(context[0])  [返回值]      错误码(见附录1)  [示例]      long context[] = new long[1];      int ret = ZKFaceService.init(context);      if (0 == ret)      {          System.out.print("Init succ, context=" + context[0]);      }      else      {          System.out.print("Init failed, error code=" + ret);      }  [返回值]      错误码  [示例]      long[] retContext = new long[1];      int ret = ZKLiveFaceService.init(retContext);      if (0 == ret)      {          context = retContext[0];      }      ...  [备注]          1、调用初始接口成功后可以调用setParameter来设置探测人脸数、、1：1比对阀值具体设置步骤及相关参数说明可以参考setParameter接口说明  

setParameter

  [函数]      public native static int setParameter(long context, int code, byte[] value, int size);  [功能]      设置参数  [参数]      context[in]          算法实例指针      code[in]          参数代码（见附录2）      value[in]          参数值      size[in]          数据长度(字节数)  [返回值]      错误码(见附录1)  [备注]      1、设置探测人脸数(默认为10)、1：1比对阀值、参数值为纯数字字符串。例如设置的参数值为："8"。      2、如果调用设置许可文件路径或者许可文件数据，在初始化前调用，此时算法句柄context传0。      3、相关的参数说明和参数代码可见附录2详细说明  [示例]      String maxFaceCnt = "8";      int ret = ZKLiveFaceService.setParameter(context, 1008, maxFaceCnt.getBytes(), maxFaceCnt.length());  

getParameter

  [函数]      public native static int getParameter(long context, int code, byte[] value, int[] size);  [功能]      获取参数  [参数]      context[in]          算法实例指针      code[in]          参数代码(见附录2)      value[out]          参数值      size[in/out]          [in]:value分配数据长度          [out]:实际返回参数数据长度  [返回值]      错误码(见附录1)  [备注]      1、获取探测人脸数、1：1比对阀值,获取到的参数值为纯数字字符串。例如获取探测人脸数，返回的参数值为："10"。  

detectFaces

  [函数]      public native static int detectFaces(long context, byte[] rawImage, int width, int height, int[] detectedFaces);  [功能]      探测人脸  [参数]      context[in]          算法实例指针      rawImage[in]          原始图像数据(见loadImage)      width[in]          图像宽      height[in]          图像高      detectedFaces[out]          探测到人脸数(<=探测人脸数(PARAM_CODE_MAX_FACE))  [返回]      错误码(见附录1)  [备注]      1、rawImage默认为：BGR图像位深度为24位的原始图像数据      2、该接口为非线程安全接口。  [示例]      int[] detectedFaces = new int[1];      int ret = ZKLiveFaceService.detectFaces(context, rawImage, width, height, detectedFaces);      ...  

detectFacesExt

  [函数]      public native static int detectFacesExt(long context, byte[] rawImage, int width, int height, int[] detectedFaces,int colortype);  [功能]      探测人脸  [参数]      context[in]          算法实例指针      rawImage[in]          原始图像数据(见loadImage)      width[in]          图像宽      height[in]          图像高      detectedFaces[out]          探测到人脸数(<=探测人脸数(PARAM_CODE_MAX_FACE))      colortype[in]          图片色彩类型(备注：0：表示灰度图像位深度为8位  1：表示BGR图像位深度为24位 )          建议使用BGR图像位深度为24位的图片  [返回]      错误码(见附录1)  [备注]      暂不支持      

terminate

  [函数]      public native static int terminate(long context);  [功能]      释放算法资源  [参数]      context[in]          算法实例指针  [返回值]      错误码(见附录1)  

getFaceContext

  [函数]      public native static int getFaceContext(long context, int faceIdx, long[] faceContext);  [功能]      获取人脸实例指针  [参数]      context[in]          算法实例指针      faceIdx[in]          人脸索引(见ZKFace_DetectFaces，0~[detectedFaces-1])      faceContext[out]          返回人脸实例指针  [返回值]      错误码(见附录1)  

setThumbnailParameter

  [函数]      public native static int setThumbnailParameter(long context, int thumbnailWidth, int thumbnailHeight, float thumbnailScale, float thumbnailQuality);  [功能]      设置小图像压缩参数  [参数]      context[in]          算法实例指针      thumbnailWidth[in]          缩略图图像宽度(（范围：32~1024）默认值为：192(建议使用该值))      thumbnailHeight[in]          缩略图图像高度((范围：32~1024) 默认值为：256(建议使用该值))      thumbnailScale[in]          要缩略的尺度(范围：0.1~1)默认值为：0.6(建议使用该值)      thumbnailScale[in]          缩略图的质量(范围：0~100)默认值为：32(建议使用该值)  [返回值]      错误码(见附录1)  [备注]      该函数应该在调用探测人脸数接口(detectFaces或者detectFacesExt)前调用方可生效  [备注]      暂不支持      

getCropImageData

  [函数]      public native static int getCropImageData(long faceContext, int[] cropWidth, int[] cropHeight, int[] cropLength, byte[] rawCroppedImage);  [功能]       获取小图像数据（RGB图像位深度为24位图像数据）  [参数]      faceContext[in]          人脸实例指针      cropWidth[out]          缩略图图像宽度      cropHeight[out]          缩略图图像高度      cropLength[in/out]          [in]:rawCroppedImage内存大小          [out]:实际返回图像数据大小      rawCroppedImage          返回图像数据(RGB图像位深度为24位图像数据)  [返回值]      错误码(见附录1)  

getFaceFeature

  [函数]      public native static int getFaceFeature(long faceContext, int featureID, int[] pX, int[] pY, int[] score);  [功能]      获取特征  [参数]      faceContext[in]          人脸实例指针      featureID[in]          特征ID（见附录4）      pX[out]          返回X坐标      pY[out]          返回Y坐标      score[out]          返回分数(预留参数)   [返回值]      错误码(见附录1)  

getFaceICaoFeature

  [函数]      public native static int getFaceICaoFeature(long faceContext, int featureID, int[] score);  [功能]      获取ICao特征  [参数]      faceContext[in]          人脸实例指针      featureID[in]          特征ID（见附录3）      score[out]          返回对应的特征值  [返回值]      错误码(见附录1)  [备注]      该接口仅供参考，有可能存在误差  

extractTemplate

  [函数]      public native static int extractTemplate(long faceContext, byte[] template, int[] size, int[] resverd);  [功能]      提取人脸模板  [参数]      faceContext[in]          人脸实例指针      temlpate[out] （建议预分配2048个字节，足够使用）          人脸模板      size[in/out]          [in]:template内存分配大小          [out]:实际返回template数据长度      resverd[out]          该参数为预留参数  [返回值]      错误码(见附录1)  [示例]      int ret = 0;      byte[] template = new byte[2048];      int[] size = new int[1];      int[] resverd = new int[1];      size[0] = 2048;      ret = ZKLiveFaceService.extractTemplate(faceContext, template, size, resverd);      ...  

getFaceRect

  [函数]      public native static int getFaceRect(long faceContext, int[] points, int cntPx);  [功能]      获取探测到人脸的矩形框  [参数]      faceContext[in]          人脸实例指针      points[out]          矩形框四个坐标点p0.x p0.y p1.x p1.y p2.x p2.y p3.x p3.y顺序排列（顺时针方向）      cntPx[in]           points数组大小(8)  [返回值]      错误码(见附录1)  

closeFaceContext

  [函数]      public native static int closeFaceContext(long faceContext);  [功能]      释放人脸实例对象  [参数]      faceContext[in]          人脸实例指针  [返回值]      错误码(见附录1)  

verify

  [函数]      public native static int verify(long context, byte[] regTemplate, byte[] verTemplate, int[] score)  [功能]      人脸1:1比对  [参数]      context[in]          算法实例指针      regTemplate[in]          登记模板      verTemplate[in]          比对模板      score[out]          返回分数  [返回值]          错误码(见附录1)  [备注]      1、默认1:1的比对阀值为60。超过即为比对成功。      2、比对分数范围：0~120      3、人证合一时阀值可以设置为：55~60 。普通照片时：1：1人脸阀值可以设置为：80  [示例]      int ret = 0;      int[] score = new int[1];      ret = ZKLiveFaceService.verify(context, regTemplate, verTemplate, score);  

dbAdd

  [函数]      public native static int dbAdd(long context, String faceID, byte[] regTemplate)  [功能]      添加人脸模板到默认的1:N高速缓冲区  [参数]      context[in]          算法实例指针      faceID[in]          人脸ID      regTemplate[in]          登记模板  [返回值]      错误码(见附录1)  

dbDel

  [函数]      public native static int dbDel(long context, String faceID)  [功能]      从默认的1:N高速缓冲区删除一个人脸模板  [参数]      context[in]          算法实例指针      faceID[in]          人脸ID  [返回值]      错误码(见附录1)  [备注]      暂不支持      

dbClear

  [函数]      public native static int dbClear(long context)  [功能]      清空默认的1:N高速缓冲区  [参数]      context[in]          算法实例指针  [返回值]      错误码(见附录1)  

dbCount

  [函数]      public native static int dbCount(long context, int[] count)  [功能]      获取默认的1:N高速缓冲区的模板数  [参数]      context[in]          算法实例指针      count[out]          返回的模板个数  [返回值]      错误码(见附录1)  

dbIdentify

  [函数]      public native static int dbIdentify(long context, byte[] verTemplate, byte[] faceIDs, int[] score, int[] maxRetCount, int minScore, int maxScore)  [功能]      1:N识别  [参数]      context[in]          算法实例指针      verTemplate[in]          比对模板      faceID[out]          返回人脸ID数组      score[out]          返回比对分数      maxRetCount[in/out]          [in]:返回多少个          [out]:实际返回多少个      minScore[in]          匹配分数。只有要识别的人脸与数据库中 的某一人脸模板的相似度达到该值时，才能识别 成功      maxScore[in]          当要识别人脸与数据库中的某一人脸模板的相似 度达到该值时，识别成功立即返回  [返回值]      错误码(见附录1)  [示例]      int ret = 0;      int[] score = new int[1];      byte[] faceIDS = new byte[256];      int[] maxRetCount = new int[1];      maxRetCount[0] = 1; //只返回1个人脸      ret = ZKLiveFaceService.dbIdentify(context, verTemplate, faceIDS, score, maxRetCount, 80, 110);      ...    [备注]          1、比对分数范围：0~160      2、匹配分数一般设置为：80  

bayerToBGR24

  [函数]      public native static int bayerToBGR24(byte[] bayer, int width, int height, byte[] imgData)  [参数]      bayer          bayer数据      width          图像宽      height          图像高      imgData          图像数据  [返回值]      错误码(见附录1)  [备注]      暂不支持      

dbVerifyByID

  [函数]      public native static int dbVerifyByID(long context,String faceID,byte[]verTemplate,int[] score);  [功能]      在默认的1:N高速缓冲区中通过人脸ID号进行1:1比对  [参数]      context[in]          算法实例指针      faceID[in]          人脸ID      verTemplate[in]          比对的模板      score[out]          返回比对分数  [返回值]      错误码(见附录1)  [备注]      暂不支持      

dbInitExt

  [函数]      public native static int dbInitExt(long context,long[] dbcontext);  [功能]      初始化并创建1:N高速缓冲区 (可以创建多个高速缓冲区)  [参数]       context[in]          算法实例指针       dbcontext[out]          返回1:N高速缓冲区实例指针  [返回值]      错误码(见附录1)  [备注]      暂不支持      

dbAddExt

  [函数]       public native static int dbAddExt(long dbcontext,String faceID,byte[] regTemplate);  [功能]       添加人脸模板到1:N高速缓冲区  [参数]       dbcontext[in]          1:N高速缓冲区实例指针       faceID[in]          人脸ID       regTemplate[in]          登记模板  [返回值]      错误码(见附录1)  [备注]      暂不支持      

dbDelExt

  [函数]      public native static int dbDelExt(long dbcontext,String faceID);  [功能]      从1:N高速缓冲区中删除一个人脸模板  [参数]      dbcontext[in]          1:N高速缓冲区实例指针      faceID[in]          要删除的人脸ID  [返回值]      错误码(见附录1)  [备注]      暂不支持      

dbCountExt

  [函数]       public native static int dbCountExt(long dbcontext,int[] count);  [功能]       获取1:N高速缓冲区的模板数  [参数]       dbcontext[in]          1:N高速缓冲区实例指针       count[out]          返回模板个数  [返回值]      错误码(见附录1)。  [备注]      暂不支持      

dbIdentifyExt

  [函数]      public native static int dbIdentifyExt(long dbcontext, byte[] verTemplate, byte[] faceIDs, int[] score, int[] maxRetCount, int minScore, int maxScore);  [功能]      在1:N高速缓冲区中进行1:N识别  [参数]      dbcontext[in]          1:N高速缓冲区实例指针      verTemplate[in]          比对模板      faceID[out]          返回人脸ID数组      score[out]          返回比对分数      maxRetCount[in/out]          [in]:返回多少个          [out]:实际返回多少个      minScore[in]          匹配分数。只有要识别的人脸与数据库中 的某一人脸模板的相似度达到该值时，才能识别 成功      maxScore[in]          当要识别人脸与数据库中的某一人脸模板的相似 度达到该值时，识别成功立即返回  [返回值]      错误码(见附录1)  [备注]      暂不支持      

dbVerifyByIDExt

  [函数]      public native static int dbVerifyByIDExt(long dbcontext,String faceID,byte[] verTemplate,int[] score);  [功能]       在1:N高速缓冲区中通过人脸ID号进行1:1比对  [参数]       dbcontext[in]          1:N高速缓冲区实例指针       faceID[in]          人脸ID       verTemplate[in]          比对模板       cbVerTemplate[in]          比对模板长度       score[out]          返回分数  [返回值]      错误码(见附录1)  [备注]      暂不支持      

dbFreeExt

  [函数]       public native static int dbFreeExt(long dbcontext);  [功能]       释放1:N高速缓冲区资源  [参数]       dbcontext[in]          1:N高速缓冲区实例指针  [返回值]      错误码(见附录1)  [备注]      暂不支持      

附录

附录1

错误码如下表所示