ArcSoft IdCardVeri SDK

开发说明文档

1. 简介

1.1 产品概述

人证核验SDK，包含人脸采集、人脸检测、人证核验等能力，主要实现人证的1:1比对。该SDK完全在无网环境下工作，全部离线化、本地化，所有数据在设备本地运行处理，可根据业务需要进行灵活的上层业务开发。
该SDK仅限于采集照与二代身份证件比对，不推荐使用于其他应场景。

1.2 环境要求

1.2.1 运行环境

Android armeabi-v7a

1.2.2 系统要求

支持Android 4.4 (API Level 19)及以上系统。

1.2.3 权限申明

获取设备唯一标识，用于SDK激活授权

<uses-permission android:name="android.permission.READ_PHONE_STATE" />

允许应用联网，用于SDK联网激活授权

<uses-permission android:name="android.permission.INTERNET" />

1.2.4 支持的颜色空间格式

NV21

常量名	常量值	常量说明
CP_PAF_NV21	2050	8-bit Y层，之后是8-bit的2x2 采样的U，V交织层

1.3 产品功能简介

1.3.1 人脸检测

对传入图像数据进行人脸检测，返回人脸位置信息和人脸在图像中的朝向信息，可用于后续的人脸分析、人脸比对操作，支持图像模式和视频流模式。

1.3.2 人脸跟踪

捕捉并检测视频流中的人脸，对人脸进行跟踪。

1.3.3 人证核验

基于二代身份证证件照和采集照实现人证1:1比对，返回比对结果。

1.4 SDK授权说明

SDK授权按设备进行授权，每台硬件设备需要一个独立的授权，此授权的校验基于设备的唯一标识，被授权的设备，初次授权时需要联网进行授权，授权成功后可以离线运行SDK。
激活一台设备后，遇以下情况，需要重新联网激活：

删除基于SDK开发的应用或删除应用数据
刷新安卓系统
激活一台设备后，硬件信息发生变更

2. 接入指南

2.1 SDK获取

2.1.1 注册为开发者

访问ArcSoft 视觉开放平台门户：https://ai.arcsoft.com.cn，注册开发者账号并登录。

2.1.2 SDK下载

创建对应的应用，并选择需要下载的SDK、对应平台及版本，确认后即可下载SDK和查看激活码。

点击【下载SDK】即可下载SDK开发包；
点击【查看激活码】即可查看所需要APPID、SDKKEY；

2.1.3 SDK包结构

 |---doc
 |   |---ARCSOFT_IDCARDVERI_DEVELOPER'S_GUIDE.pdf        开发说明文档
 |   |---IdCardVeriAPI-Android.zip                    		API说明
 |---libs
 |   |---armeabi-v7a
 |   |   |---libarcsoft_face.so                              引擎库
 |   |   |---libarcsoft_idcardveri.so                     	 引擎库
 |   |---libIdCardVeri.jar                                   引擎库
 |---samplecode
 |   |---IdCardVeriDemo                                     示例工程
 |---releasenotes.txt                                    	更新说明

2.1.4 工程配置

新建一个Android Project，切换到Project视图；
将libarcsoft_face.so和libarcsoft_idcardveri.so添加到src->main->jniLibs->armeabi-v7a路径下；
将libIdCardVeri.jar放入，并依赖进工程；
方法1：

方法2：

2.1.5 调用流程

Step1：调用IdCardVerifyManager的active方法激活设备，一个设备安装后仅需激活一次，卸载重新安装或者清除应用数据后需要重新激活。

Step2：调用IdCardVerifyManager的init方法初始化SDK，初始化成功后才能进一步使用SDK的功能。

Step3：调用IdCardVerifyManager的inputIdCardData方法传入身份证图片数据进行人脸检测，若检测成功，则可得到一个最大人脸框。

Step4：通过IdCardVerifyListener接口中onIdCardResult回调获取身份证数据特征提取结果，若成功，且现场采集数据同样也提取成功，则可进行人证比对。

Step5：调用IdCardVerifyManager的onPreviewData方法传入视频或图片数据进行人脸检测，若检测成功，则可得到一个最大人脸框。

Step6：通过IdCardVerifyListener接口中onPreviewResult回调获取身份证数据特征提取结果，若成功，且身份证图片数据同样也提取成功，则可进行人证比对。

Step7：调用IdCardVerifyManager的compareFeature方法进行人证比对，若成功，则可获取比对结果。

Step8：调用IdCardVerifyManager的unInit方法销毁引擎。在init成功后如不unInit会导致内存泄漏。

2.2 核心类介绍

2.2.1 Class IdCardVerifyManager

类描述：
人证比对引擎类，其中定义了人证比对相关的函数，包含SDK的授权激活、引擎初始化以及人证处理相关方法。
具体说明见 JavaDoc 。

2.2.2 Class IdCardVerifyListener

类描述：
特征提取结果回调接口，用于人脸特征提取成功后回调提取结果及人脸相关信息。
具体说明见 JavaDoc 。

2.2.3 Class DetectFaceResult

类描述：
检测结果类，用于存储检测到的人脸信息。
具体说明见 JavaDoc 。

2.2.4 Class CompareResult

类描述：
比对结果类，用于存储人证比对结果。
具体说明见 JavaDoc 。

2.2.5 Class IdCardVerifyError

类描述：
错误信息类，其中定义了引擎调用的错误码。
具体说明见 JavaDoc 。

2.3 错误代码

错误码名	十六进制	十进制	错误码说明
OK	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有效期过期，需要重新下载更新
ERR_NULL_PARAMETER	10001	65537	参数不能为空
ERR_INVALID_DATA	10002	65538	视频数据宽高不匹配
ERR_NO_FACE	10003	65539	未检测到人脸
ERR_NO_PICORVIDEO_DATA	10004	65540	无图像或视频数据
ERR_NO_IDCARD_DATA	10005	65541	无身份证数据
ERR_COMPARE_NOT_READY	10006	65542	身份证数据未上传或预览数据重复上传
ERR_ENGINE_INIT_ERROR	10007	65543	引擎初始化失败
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_ACTIVEFILE_SDKTYPE_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	READ_PHONE_STATE权限被拒绝
MERR_ASF_ACTIVATION_DATA_DESTROYED	16011	90129	激活数据被破坏,请清除应用数据或卸载应用后，重新进行激活
MERR_ASF_SERVER_UNKNOWN_ERROR	16012	90130	服务端未知错误
MERR_ASF_INTERNET_DENIED	16013	90131	INTERNET权限被拒绝
MERR_ASF_ACTIVEFILE_SDK_MISMATCH	16014	90132	激活文件与SDK版本不匹配,请重新激活
MERR_ASF_DEVICEINFO_LESS	16015	90133	设备信息太少，不足以生成设备指纹
MERR_ASF_REQUEST_TIMEOUT	16016	90134	客户端时间与服务器时间（即北京时间）前后相差在30分钟之内
MERR_ASF_APPID_DATA_DECRYPT	16017	90135	服务端解密失败
MERR_ASF_APPID_APPKEY_SDK_MISMATCH	16018	90136	传入的AppId和AppKey与使用的SDK版本不一致
MERR_ASF_NO_REQUEST	16019	90137	短时间大量请求会被禁止请求,30分钟之后会解封
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.4 通用方法

2.4.1 Bitmap转换成NV21数据

/**
 * Bitmap转化为ARGB数据，再转化为NV21数据
 *
 * @param src    传入的Bitmap，格式为Bitmap.Config.ARGB_8888
 * @param width  NV21图像的宽度
 * @param height NV21图像的高度
 * @return nv21数据
 */
public static byte[] bitmapToNv21(Bitmap src, int width, int height) {
    if (src != null && src.getWidth() >= width && src.getHeight() >= height) {
        int[] argb = new int[width * height];
        src.getPixels(argb, 0, width, 0, 0, width, height);
        return argbToNv21(argb, width, height);
    } else {
        return null;
    }
}
/**
 * ARGB数据转化为NV21数据
 *
 * @param argb   argb数据
 * @param width  宽度
 * @param height 高度
 * @return nv21数据
 */
private static byte[] argbToNv21(int[] argb, int width, int height) {
    int frameSize = width * height;
    int yIndex = 0;
    int uvIndex = frameSize;
    int index = 0;
    byte[] nv21 = new byte[width * height * 3 / 2];
    for (int j = 0; j < height; ++j) {
        for (int i = 0; i < width; ++i) {
            int R = (argb[index] & 0xFF0000) >> 16;
            int G = (argb[index] & 0x00FF00) >> 8;
            int B = argb[index] & 0x0000FF;
            int Y = (66 * R + 129 * G + 25 * B + 128 >> 8) + 16;
            int U = (-38 * R - 74 * G + 112 * B + 128 >> 8) + 128;
            int V = (112 * R - 94 * G - 18 * B + 128 >> 8) + 128;
            nv21[yIndex++] = (byte) (Y < 0 ? 0 : (Y > 255 ? 255 : Y));
            if (j % 2 == 0 && index % 2 == 0 && uvIndex < nv21.length - 2) {
                nv21[uvIndex++] = (byte) (V < 0 ? 0 : (V > 255 ? 255 : V));
                nv21[uvIndex++] = (byte) (U < 0 ? 0 : (U > 255 ? 255 : U));
            }
            ++index;
        }
    }
    return nv21;
}

2.5 阈值推荐

阈值区间为[0~1]，建议阈值设置为0.82，可根据实际场景需求进行调整。

3 其他帮助

虹助手微信：Hongzhushou88；

QQ交流群：659920696；

SDK交流论坛：https://ai.arcsoft.com.cn/bbs/