ArcSoft IdCardVeri SDK Windows平台

API 接口说明

1.1数据结构

1.1.1 AFIC_FSDK_VERSION

功能描述：
版本信息；
定义：

typedef struct {
        MPChar Version;                        // Version in string form
        MPChar BuildDate;                    // Latest build Date
        MPChar CopyRight;                    // Copyright
}AFIC_FSDK_VERSION;

1.1.2 AFIC_FSDK_FACERES

类描述：
人脸信息；
定义：

typedef struct {
        MInt32 nFace;                        // number of faces detected
        MRECT rcFace;                        // The bounding box of face
} AFIC_FSDK_FACERES, *LPAFIC_FSDK_FACERES;

2. 接口

2.1 接口说明

2.1.1 ArcSoft_FIC_Activate

原型

    MRESULT ArcSoft_FIC_Activate(
        MPChar APPID,                                        
        MPChar SDKKEY                             
        );

功能描述

激活SDK

参数

名称	IN/OUT	说明
APPID	[in]	官网获取的APPID
SDKKEY	[in]	官网获取的SDKKEY

返回值

成功返回MOK，否则返回失败code。失败codes如下所列:

返回值	说明
MERR_FSDK_INVALID_APP_ID	无效的AppId
MERR_FSDK_INVALID_SDK_ID	无效的SDKkey
MERR_FSDK_INVALID_ID_PAIR	AppId和SDKKey不匹配
MERR_FSDK_MISMATCH_ID_AND_SDK	SDKKey 和使用的SDK 不匹配
MERR_FSDK_SYSTEM_VERSION_UNSUPPORTED	系统版本不被当前SDK所支持
MERR_FSDK_LICENCE_EXPIRED	SDK有效期过期，需要重新下载更新

2.1.2 ArcSoft_FIC_InitialEngine

原型

MRESULT ArcSoft_FIC_InitialEngine(
    MHandle *     phFICEngine
);

功能描述

初始化引擎

参数

名称	IN/OUT	说明
phFICEngine	[out]	引擎Handle

返回值

成功返回MOK，否则返回失败code。失败codes如下所列:

返回值	说明
MERR_INVALID_PARAM	参数输入非法

2.1.3 ArcSoft_FIC_FaceDataFeatureExtraction

原型

MRESULT ArcSoft_FIC_FaceDataFeatureExtraction(
MHandle     hFICEngine,    
MBool         isVideo, 
LPASVLOFFSCREEN         pInputFaceData,    
LPAFIC_FSDK_FACERES     pFaceRes
    );

功能描述

提取视频帧或者图片中人脸特征

参数

名称	IN/OUT	说明
hFICEngine	[in]	FIC 引擎Handle
isVideo	[in]	人脸数据类型 1-视频 0-静态图片
pInputFaceData	[in]	人脸图像原始数据
pFaceRes	[out]	人脸属性人脸数/人脸框

返回值

成功返回MOK，否则返回失败code。失败codes如下所列:

返回值	说明
MERR_INVALID_PARAM	参数输入非法
MERR_FSDK_FIC_UNDETECTED_FACE	未检测到人脸
MERR_FSDK_FIC_FEATURE_EXTRACTION_FAIL	特征提取失败

2.1.4 ArcSoft_FIC_IdCardDataFeatureExtraction

原型

MRESULT ArcSoft_FIC_IdCardDataFeatureExtraction(
    MHandle         hFICEngine,
    LPASVLOFFSCREEN     pInputIdcardData
    );

功能描述

提取证件照人脸特征

参数

名称	IN/OUT	说明
hFICEngine	[in]	FIC 引擎Handle
pInputIdcardData	[in]	图像原始数据

返回值

成功返回MOK，否则返回失败code。失败codes如下所列:

返回值	说明
MERR_INVALID_PARAM	参数输入非法
MERR_FSDK_FIC_UNDETECTED_FACE	未检测到人脸
MERR_FSDK_FIC_FEATURE_EXTRACTION_FAIL	特征提取失败

2.1.5 ArcSoft_FIC_FaceIdCardCompare

原型

MRESULT ArcSoft_FIC_FaceIdCardCompare(
    MHandle     hFICEngine,      
    MFloat     threshold,        
    MFloat *     pSimilarScore,    
    MInt32 *     pResult        
    );

功能描述

人证比对，视频模式下调用compare接口之前图像数据被释放可能导致比对接口失败或carsh;

参数

名称	IN/OUT	说明
hFICEngine	[in]	FIC 引擎Handle
threshold	[in]	比对阈值
pSimilarScore	[out]	比对结果相似度
pResult	[out]	比对结果

返回值

成功返回MOK，否则返回失败code。失败codes如下所列:

返回值	说明
MERR_INVALID_PARAM	参数输入非法
MERR_FSDK_FIC_UNDETECTED_FACE	未检测到人脸
MERR_FSDK_FIC_FEATURE_EXTRACTION_FAIL	特征提取失败

2.1.6 ArcSoft_FIC_UninitialEngine

原型

MRESULT ArcSoft_FIC_UninitialEngine(
    MHandle     hFICEngine
    );

功能描述

释放引擎

参数

名称	IN/OUT	说明
hFICEngine	[in]	FIC 引擎Handle

返回值

成功返回MOK，否则返回失败code。失败codes如下所列:

返回值	说明
MERR_INVALID_PARAM	参数输入非法

2.1.7 ArcSoft_FIC_GetVersion

原型

const AFIC_FSDK_VERSION *ArcSoft_FIC_GetVersion(MHandle hFICEngine);

参数

名称	IN/OUT	说明
hFICEngine	[in]	FIC 引擎Handle

功能描述

获取引擎版本信息

返回值

成功返回版本信息，失败返回NULL

2.2部分错误码概览

错误码名	十六进制	十进制	错误码说明
MOK	0	0	成功
MERR_UNKNOWN	1	1	错误原因不明
MERR_INVALID_PARAM	2	2	无效的参数
MERR_UNSUPPORTED	3	3	引擎不支持
MERR_NO_MEMORY	4	4	内存不足
MERR_BAD_STATE	5	5	状态错误
MERR_USER_CANCEL	6	6	用户取消相关操作
MERR_EXPIRED	7	7	操作时间过期
MERR_USER_PAUSE	8	8	用户暂停操作
MERR_BUFFER_OVERFLOW	9	9	缓冲上溢
MERR_BUFFER_UNDERFLOW	A	10	缓冲下溢
MERR_NO_DISKSPACE	B	11	存贮空间不足
MERR_COMPONENT_NOT_EXIST	C	12	组件不存在
MERR_GLOBAL_DATA_NOT_EXIST	D	13	全局数据不存在
MERR_FSDK_INVALID_APP_ID	7001	28673	无效的App Id
MERR_FSDK_INVALID_SDK_ID	7002	28674	无效的SDK key
MERR_FSDK_INVALID_ID_PAIR	7003	28675	AppId和SDKKey不匹配
MERR_FSDK_MISMATCH_ID_AND_SDK	7004	28676	SDKKey和使用的SDK不匹配
MERR_FSDK_SYSTEM_VERSION_UNSUPPORTED	7005	28677	系统版本不被当前SDK所支持
MERR_FSDK_LICENCE_EXPIRED	7006	28678	SDK有效期过期，需要重新下载更新
MERR_FSDK_FR_INVALID_MEMORY_INFO	12001	73729	无效的输入内存
MERR_FSDK_FR_INVALID_IMAGE_INFO	12002	73730	无效的输入图像参数
MERR_FSDK_FR_INVALID_FACE_INFO	12003	73731	无效的脸部信息
MERR_FSDK_FR_NO_GPU_AVAILABLE	12004	73732	当前设备无GPU可用
MERR_FSDK_FR_MISMATCHED_FEATURE_LEVEL	12005	73733	待比较的两个人脸特征的版本不一致
MERR_FSDK_FACEFEATURE_UNKNOWN	14001	81921	人脸特征检测错误未知
MERR_FSDK_FACEFEATURE_MEMORY	14002	81922	人脸特征检测内存错误
MERR_FSDK_FACEFEATURE_INVALID_FORMAT	14003	81923	人脸特征检测格式错误
MERR_FSDK_FACEFEATURE_INVALID_PARAM	14004	81924	人脸特征检测参数错误
MERR_FSDK_FACEFEATURE_LOW_CONFIDENCE_LEVEL	14005	81925	人脸特征检测结果置信度低
MERR_ASF_EX_FEATURE_UNSUPPORTED_ON_INIT	15001	86017	Engine不支持的检测属性
MERR_ASF_EX_FEATURE_UNINITED	15002	86018	需要检测的属性未初始化
MERR_ASF_EX_FEATURE_UNPROCESSED	15003	86019	待获取的属性未在process中处理过
MERR_ASF_EX_FEATURE_UNSUPPORTED_ON_PROCESS	15004	86020	PROCESS不支持的检测属性，例如FR，有自己独立的处理函数
MERR_ASF_EX_INVALID_IMAGE_INFO	15005	86021	无效的输入图像
MERR_ASF_EX_INVALID_FACE_INFO	15006	86022	无效的脸部信息
MERR_ASF_ACTIVATION_FAIL	16001	90113	SDK激活失败,请打开读写权限
MERR_ASF_ALREADY_ACTIVATED	16002	90114	SDK已激活
MERR_ASF_NOT_ACTIVATED	16003	90115	SDK未激活
MERR_ASF_SCALE_NOT_SUPPORT	16004	90116	detectFaceScaleVal不支持
MERR_ASF_VERION_MISMATCH	16005	90117	SDK版本不匹配
MERR_ASF_DEVICE_MISMATCH	16006	90118	设备不匹配
MERR_ASF_UNIQUE_IDENTIFIER_MISMATCH	16007	90119	唯一标识不匹配
MERR_ASF_PARAM_NULL	16008	90120	参数为空
MERR_ASF_LIVENESS_EXPIRED	16009	90121	活体检测功能已过期
MERR_ASF_VERSION_NOT_SUPPORT	1600A	90122	版本不支持
MERR_ASF_SIGN_ERROR	1600B	90123	签名错误
MERR_ASF_DATABASE_ERROR	1600C	90124	数据库插入错误
MERR_ASF_UNIQUE_CHECKOUT_FAIL	1600D	90125	唯一标识符校验失败
MERR_ASF_COLOR_SPACE_NOT_SUPPORT	1600E	90126	颜色空间不支持
MERR_ASF_IMAGE_WIDTH_HEIGHT_NOT_SUPPORT	1600F	90127	图片宽度或高度不支持
MERR_ASF_READ_PHONE_STATE_DENIED	16010	90128	android.permission.READ_PHONE_STATE权限被拒绝
MERR_ASF_ACTIVATION_DATA_DESTROYED	16011	90129	激活数据被破坏,请删除激活文件，重新进行激活
MERR_ASF_SERVER_UNKNOWN_ERROR	16012	90130	服务端未知错误
MERR_ASF_NETWORK_COULDNT_RESOLVE_HOST	17001	94209	无法解析主机地址
MERR_ASF_NETWORK_COULDNT_CONNECT_SERVER	17002	94210	无法连接服务器
MERR_ASF_NETWORK_CONNECT_TIMEOUT	17003	94211	网络连接超时
MERR_ASF_NETWORK_UNKNOWN_ERROR	17004	94212	网络未知错误

2.3 示例代码

调用方法一：读取BGR RAW数据文件


#include "arcsoft_idcardveri.h"
#include "merror.h"
#include "asvloffscreen.h"
#include "amcomdef.h"
#include <stdio.h>
#include <stdlib.h>
#pragma comment(lib,"libarcsoft_idcardveri.lib")
#define APPID    ""            //APPID
#define SDKKey    ""            //SDKKey
int main()
{
    MRESULT res = ArcSoft_FIC_Activate(APPID, SDKKey);
    if (res != MOK && res != MERR_ASF_ALREADY_ACTIVATED)
    {
        printf("Activate failed, error code: %d\n", res);
        return -1;
    }
    /* 初始化人证比对引擎*/
    MHandle hEngine = { 0 };
    res = ArcSoft_FIC_InitialEngine(&hEngine);
    if (res != MOK)
    {
        printf("Initial Engine failed, error code: %d\n", res);
        return -1;
    }
    /* 读取预览静态图片信息，并保存到ASVLOFFSCREEN结构体 （以ASVL_PAF_RGB24_B8G8R8格式为例） 图片数据为BGR原始数据 */
    ASVLOFFSCREEN imgInfo0 = { 0 };
    imgInfo0.i32Width = IMAGE_WIDTH;
    imgInfo0.i32Height = IMAGE_HEIGHT;
    imgInfo0.u32PixelArrayFormat = ASVL_PAF_RGB24_B8G8R8;
    imgInfo0.pi32Pitch[0] = imgInfo0.i32Width * 3;
    imgInfo0.ppu8Plane[0] = (MUInt8*)malloc(imgInfo0.i32Height*imgInfo0.pi32Pitch[0]);
    FILE* fp1 = fopen("IMAGE_PATH", "rb");
    if (fp1)
    {
        fread(imgInfo0.ppu8Plane[0], imgInfo0.i32Height*imgInfo0.pi32Pitch[0], 1, fp1);
        fclose(fp1);
    }
    /* 人脸特征提取 0-静态图片 1-视频 */
    LPAFIC_FSDK_FACERES pFaceRes=(LPAFIC_FSDK_FACERES)malloc(sizeof(AFIC_FSDK_FACERES));
    MRESULT res = ArcSoft_FIC_FaceDataFeatureExtraction(hEngine, 0, &imgInfo0, pFaceRes);
    if (res != MOK)
    {
        printf("Face Feature Extraction failed, error code: %d\n", res);
        return -1;
    }
    /* 读取证件照静态图片信息，并保存到ASVLOFFSCREEN结构体 （以ASVL_PAF_RGB24_B8G8R8格式为例） 图片数据为BGR原始数据 */
    ASVLOFFSCREEN imgInfo1 = { 0 };
    imgInfo1.i32Width = IMAGE_WIDTH;
    imgInfo1.i32Height = IMAGE_HEIGHT;
    imgInfo1.u32PixelArrayFormat = ASVL_PAF_RGB24_B8G8R8;
    imgInfo1.pi32Pitch[0] = imgInfo1.i32Width * 3;//
    imgInfo1.ppu8Plane[0] = (MUInt8*)malloc(imgInfo1.i32Height*imgInfo1.pi32Pitch[0]);
    FILE* fp2 = fopen("IMAGE_PATH", "rb");
    if (fp2)
    {
        fread(imgInfo1.ppu8Plane[0], imgInfo1.i32Height*imgInfo1.pi32Pitch[0], 1, fp1);
        fclose(fp2);
    }
    /* 证件照特征提取 */
    MRESULT res = ArcSoft_FIC_IdCardDataFeatureExtraction(hEngine, &imgInfo1);
    if (res != MOK)
    {
        printf("IdCard Feature Extraction failed, error code: %d\n", res);
        return -1;
    }
    /* 人证比对 */
    MFloat pSimilarScore = 0.0f;
    MInt32 pResult = 0;
    MFloat g_threshold = 0.82;
    MRESULT res = ArcSoft_FIC_FaceIdCardCompare(hEngine, g_threshold, &pSimilarScore, &pResult);
    if (res != MOK)
    {
        printf("Face IdCard Compare failed, error code: %d\n", res);
        return -1;
    }
    /* 反初始化引擎 */
    MRESULT res = ArcSoft_FIC_UninitialEngine(hEngine);
    if (res != MOK)
    {
        printf("Uninitial Engine failed, error code: %d\n", res);
        return -1;
    }
    free(pFaceRes);
    free(imgInfo0.ppu8Plane[0]);    //video模式下如果在compare接口之前图像数据被
                        //释放可能会导致比对失败或carsh；
    free(imgInfo1.ppu8Plane[0]);
    return 0;
}

调用方法二：使用OpenCV解码

	#include "cv.h"
#include "highgui.h"
#include "arcsoft_idcardveri.h"
#include "asvloffscreen.h"
#include "amcomdef.h"
#include "merror.h"
#pragma comment(lib,"libarcsoft_idcardveri.lib")
#define APPID    ""            //APPID
#define SDKKey    ""            //SDKKey
int main()
{
    IplImage* img0 = cvLoadImage("");
    IplImage* img1 = cvLoadImage("");
    if (img0 && img1)
    {
        MRESULT res = ArcSoft_FIC_Activate(APPID, SDKKey);
    if (res != MOK && res != MERR_ASF_ALREADY_ACTIVATED)
    {
        printf("Activate failed, error code: %d\n", res);
        return -1;
    }
    /* 初始化人证比对引擎*/
    MHandle hEngine = { 0 };
    res = ArcSoft_FIC_InitialEngine(&hEngine);
    if (res != MOK)
    {
        printf("Initial Engine failed, error code: %d\n", res);
        return -1;
    }        
        /* 读取预览静态图片信息，并保存到ASVLOFFSCREEN结构体 （以ASVL_PAF_RGB24_B8G8R8格式为例） 图片数据为BGR原始数据 */
        ASVLOFFSCREEN imgInfo0 = { 0 };
        imgInfo0.i32Width = img0->width;
        imgInfo0.i32Height = img0->height;
        imgInfo0.u32PixelArrayFormat = ASVL_PAF_RGB24_B8G8R8;
        imgInfo0.pi32Pitch[0] = imgInfo0.i32Width * 3;
        imgInfo0.ppu8Plane[0] = (MUInt8*)img0->imageData;
        /* 人脸特征提取 0-静态图片 1-视频 */
        LPAFIC_FSDK_FACERES pFaceRes=(LPAFIC_FSDK_FACERES)malloc(sizeof(AFIC_FSDK_FACERES));
        MRESULT res = ArcSoft_FIC_FaceDataFeatureExtraction(hEngine, 0, &imgInfo0, pFaceRes);
        if (res != MOK)
        {
            printf("Face Feature Extraction failed, error code: %d\n", res);
            return -1;
        }
        /* 读取证件照静态图片信息，并保存到ASVLOFFSCREEN结构体 （以ASVL_PAF_RGB24_B8G8R8格式为例） 图片数据为BGR原始数据 */
        ASVLOFFSCREEN imgInfo1 = { 0 };
        imgInfo1.i32Width = img1->width;
        imgInfo1.i32Height = img1->height;
        imgInfo1.u32PixelArrayFormat = ASVL_PAF_RGB24_B8G8R8;
        imgInfo1.pi32Pitch[0] = imgInfo1.i32Width * 3;
        imgInfo1.ppu8Plane[0] = (MUInt8*)img1->imageData;
/* 证件照特征提取 */
        MRESULT res = ArcSoft_FIC_IdCardDataFeatureExtraction(hEngine, &imgInfo1);
        if (res != MOK)
        {
            printf("IdCard Feature Extraction failed, error code: %d\n", res);
            return -1;
        }
        /* 人证比对 */
        MFloat pSimilarScore = 0.0f;
        MInt32 pResult = 0;
        MFloat g_threshold = 0.82;
        MRESULT res = ArcSoft_FIC_FaceIdCardCompare(hEngine, g_threshold, &pSimilarScore, &pResult);
        if (res != MOK)
        {
            printf("Face IdCard Compare failed, error code: %d\n", res);
            return -1;
        }
        /* 反初始化引擎 */
        MRESULT res = ArcSoft_FIC_UninitialEngine(hEngine);
        if (res != MOK)
        {
            printf("Uninitial Engine failed, error code: %d\n", res);
            return -1;
        }
    }
    cvReleaseImage(&img0);        //video模式下如果在compare接口之前图像数据被
                        //释放可能会导致比对失败或carsh；
    cvReleaseImage(&img1);
    return 0;
}