3.3 ZK人脸识别算法

    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

    错误码如下表所示