ArcSoft ArcFace SDK Windows 平台 API 文档 V2.2

1 数据结构与枚举

1.1 数据结构

1.1.1 ASF_VERSION

结构体描述：
SDK版本信息
定义：

typedef struct {
    MPChar Version;                    // 版本号
    MPChar BuildDate;                // 构建日期
    MPChar CopyRight;                // 版权说明
}ASF_VERSION;

1.1.2 ASF_ActiveFileInfo

结构体描述：
激活文件信息
定义：

typedef struct{
    MPChar startTime;            //SDK开始时间
    MPChar endTime;                //SDK截止时间
    MPChar platform;            //平台版本
    MPChar sdkType;                //SDK类型
    MPChar appId;                //APPID
    MPChar sdkKey;                //SDKKEY
    MPChar sdkVersion;            //SDK版本号
    MPChar fileVersion;            //激活文件版本号
}ASF_ActiveFileInfo, *LPASF_ActiveFileInfo;

1.1.3 ASF_SingleFaceInfo

结构体描述：
单人脸信息
定义：

typedef struct {
    MRECT        faceRect;        // 人脸框
    MInt32        faceOrient;        //人脸角度
} ASF_SingleFaceInfo, *LPASF_SingleFaceInfo;

1.1.4 ASF_MultiFaceInfo

结构体描述：
多人脸信息
定义：

typedef struct {
    MRECT*          faceRect;            // 人脸框数组
    MInt32*         faceOrient;        // 人脸角度数组
    MInt32         faceNum;            // 检测到的人脸个数
MInt32*      faceID;            //在VIDEO模式下有效，IMAGE模式下为空
}ASF_MultiFaceInfo, *LPASF_MultiFaceInfo;

1.1.5 ASF_FaceFeature

结构体描述：
人脸特征
定义：

typedef struct {
    MByte*        feature;        // 人脸特征
    MInt32        featureSize;    // 人脸特征长度    
}ASF_FaceFeature, *LPASF_FaceFeature;

1.1.6 ASF_AgeInfo

结构体描述：
年龄信息
定义：

typedef struct{
    MInt32*    ageArray;    // 0:未知; >0:年龄
    MInt32    num;        // 检测的人脸个数
}ASF_AgeInfo, *LPASF_AgeInfo;

1.1.7 ASF_GenderInfo

结构体描述：
性别信息
定义：

typedef struct{
    MInt32*    genderArray;    // 0:男性; 1:女性; -1:未知
    MInt32    num;            // 检测的人脸个数    
}ASF_GenderInfo, *LPASF_GenderInfo;

1.1.8 ASF_Face3DAngle

结构体描述：
3D角度信息
定义：

typedef struct{
    MFloat* roll;            //横滚角
    MFloat* yaw;             //偏航角
    MFloat* pitch;             //俯仰角
    MInt32* status;            //0:正常; 非0:异常
    MInt32 num;                //检测的人脸个数
}ASF_Face3DAngle, *LPASF_Face3DAngle;

1.1.9 ASF_LivenessThreshold

结构体描述：
活体置信度
定义：

typedef struct{
    MFloat        thresholdmodel_BGR;            //RGB活体置信度
    MFloat        thresholdmodel_IR;            //IR活体置信度
}ASF_LivenessThreshold, *LPASF_LivenessThreshold;

1.1.10 ASF_LivenessInfo

结构体描述：
活体信息
定义：

typedef struct{
        MInt32*    isLive;        //0:非真人； 1:真人； -1：不确定； -2:传入人脸数>1
        MInt32 num;            //检测的人脸个数
}ASF_LivenessInfo, *LPASF_LivenessInfo;

2 枚举

2.1 人脸检测方向

根据应用场景，推荐选择单一角度，检测效果更优；

enum ArcSoftFace_OrientPriority {
    ASF_OP_0_ONLY = 0x1,        // 仅检测0度
    ASF_OP_90_ONLY = 0x2,        // 仅检测90度
    ASF_OP_270_ONLY = 0x3,        // 仅检测270度
    ASF_OP_180_ONLY = 0x4,        // 仅检测180度
    ASF_OP_0_HIGHER_EXT = 0x5,    // 全角度检测
};

注：IMAGE模式下为了提高检测识别率，不支持ASF_OP_0_HIGHER_EXT检测

2.2 检测到的人脸角度（按逆时针方向）

enum ArcSoftFace_OrientCode {
    ASF_OC_0 = 0x1,            // 0度
    ASF_OC_90 = 0x2,        // 90度 
    ASF_OC_270 = 0x3,        // 270度 
    ASF_OC_180 = 0x4,       // 180度 
    ASF_OC_30 = 0x5,        // 30度
    ASF_OC_60 = 0x6,        // 60度
    ASF_OC_120 = 0x7,        // 120度
    ASF_OC_150 = 0x8,        // 150度
    ASF_OC_210 = 0x9,        // 210度
    ASF_OC_240 = 0xa,        // 240度
    ASF_OC_300 = 0xb,        // 300度
    ASF_OC_330 = 0xc        // 330度
};

3. 接口

3.1 接口说明

3.1.1 ASFGetActiveFileInfo

接口

MRESULT ASFGetActiveFileInfo(
    LPASF_ActiveFileInfo  activeFileInfo
);

功能描述
获取激活文件信息
参数

返回值
成功返回MOK，失败详见 3.2错误码列表

3.1.2 ASFOnlineActivation

接口

MRESULT ASFOnlineActivation(
    MPChar        AppId,
    MPChar        SDKKey
);

功能描述
用于在线激活SDK
注：
1) 初次使用SDK时需要对SDK先进行激活，激活后无需重复调用；
2) 调用此接口时必须为联网状态，激活成功后即可离线使用；

参数

返回值

成功返回MOK或MERR_ASF_ALREADY_ACTIVATED，失败详见 3.2错误码列表

3.1.3 ASFActivation

接口

MRESULT ASFActivation(
    MPChar        AppId,
    MPChar        SDKKey
);

功能描述

在线激活SDK，与ASFOnlineActivation接口功能相同，首次需要联网激活，生成激活文件之后即可进行本地校验。（ASFOnlineActivation接口做了激活方案的优化，推荐使用ASFOnlineActivation接口）
参数

返回值

成功返回MOK或MERR_ASF_ALREADY_ACTIVATED，失败详见 3.2错误码列表

3.1.4 ASFInitEngine

接口

MRESULT ASFInitEngine(
MUInt32                    detectMode,    
ASF_OrientPriority        detectFaceOrientPriority,
MInt32                        detectFaceScaleVal,
    MInt32                        detectFaceMaxNum,
    MInt32                        combinedMask,
    MHandle*                    hEngine
);

功能描述

初始化引擎

参数

返回值

成功返回MOK，失败详见 3.2错误码列表

3.1.5 ASFDetectFaces

接口

MRESULT ASFDetectFaces(
    MHandle                    hEngine,
    MInt32                        width,
    MInt32                        height,
    MInt32                        format,
    MUInt8*                    imgData,
    LPASF_MultiFaceInfo        detectedFaces 
);

功能描述
人脸检测
参数

返回值

成功返回MOK，失败详见 3.2错误码列表

3.1.6 ASFFaceFeatureExtract

接口

MRESULT ASFFaceFeatureExtract(
    MHandle                    hEngine,
    MInt32                        width,
    MInt32                        height,
    MInt32                        format,
    MUInt8*                    imgData,
    LPASF_SingleFaceInfo    faceInfo,
    LPASF_FaceFeature        feature
);

功能描述
单人脸特征提取
参数

返回值

成功返回MOK，失败详见 3.2错误码列表

3.1.7 ASFFaceFeatureCompare

接口

MRESULT ASFFaceFeatureCompare(
    MHandle                    hEngine,
    LPASF_FaceFeature        feature1,
    LPASF_FaceFeature        feature2,
    MFloat*                    confidenceLevel
);

功能描述
人脸特征比对
参数

返回值

成功返回MOK，失败详见 3.2错误码列表

3.1.8 ASFSetLivenessParam

接口

MRESULT ASFSetLivenessParam(
    MHandle                        hEngine,
    LPASF_LivenessThreshold     threshold
);

功能描述
修改RGB/IR活体阈值，SDK默认RGB：0.75,IR：0.7
参数

返回值

成功返回MOK，失败详见 3.2错误码列表

3.1.9 ASFProcess

接口

MRESULT ASFProcess(
    MHandle                    hEngine,
    MInt32                        width,
    MInt32                        height,
    MInt32                        format,
    MUInt8*                    imgData,
    LPASF_MultiFaceInfo        detectedFaces, 
    MInt32                        combinedMask
);

功能描述

人脸信息检测（年龄/性别/人脸3D角度），最多支持4张人脸信息检测，超过部分返回未知（活体仅支持单张人脸检测，超出返回未知）,接口不支持IR图像检测。

参数

注：检测的属性须在引擎初始化接口的combinedMask参数中启用

返回值

成功返回MOK，失败详见 3.2错误码列表

3.1.10 ASFProcess_IR

接口

MRESULT ASFProcess_IR(
    MHandle                    hEngine,
    MInt32                        width,
    MInt32                        height,    
    MInt32                        format,    
    MUInt8*                    imgData,
    LPASF_MultiFaceInfo        detectedFaces,
    MInt32                        combinedMask 
);

功能描述
IR活体单人脸检测
参数

注：检测的属性须在引擎初始化接口的combinedMask参数中启用

返回值

成功返回MOK，失败详见 3.2错误码列表

3.1.11 ASFGetAge

接口

MRESULT ASFGetAge(
    MHandle                 hEngine,
    LPASF_AgeInfo         ageInfo
);

功能描述
获取年龄信息
参数

返回值
成功返回MOK，失败详见 3.2错误码列表

3.1.12 ASFGetGender

接口

MRESULT ASFGetGender(
    MHandle                     hEngine,
    LPASF_GenderInfo         genderInfo
);

功能描述
获取性别信息
参数

返回值

成功返回MOK，失败详见 3.2错误码列表

3.1.13 ASFGetFace3DAngle

接口

MRESULT ASFGetFace3DAngle(
    MHandle                     hEngine,
    LPASF_Face3DAngle         p3DAngleInfo
);

功能描述
获取3D角度信息
参数

返回值
成功返回MOK，失败详见 3.2错误码列表

3.1.14 ASFGetLivenessScore

接口

MRESULT ASFGetLivenessScore(
    MHandle                 hEngine,
    LPASF_LivenessInfo     livenessInfo    
);

功能描述
获取RGB活体信息
参数

返回值

成功返回MOK，失败详见 3.2错误码列表

3.1.15 ASFGetLivenessScore_IR

接口

MRESULT ASFGetLivenessScore_IR(
    MHandle                 hEngine,
    LPASF_LivenessInfo     livenessInfo    
);

功能描述
获取IR活体信息
参数

返回值

成功返回MOK，失败详见 3.2错误码列表

3.1.16 ASFGetVersion

接口

const ASF_VERSION* ASFGetVersion(
    MHandle     hEngine
);

功能描述
获取版本信息
参数

返回值

成功返回版本信息，失败返回MNull。

3.1.17 ASFUninitEngine

接口

MRESULT ASFUninitEngine(
    MHandle hEngine
);

功能描述
销毁引擎

参数

返回值
成功返回MOK，失败详见 3.2错误码列表

3.2 错误码列表

3.3 示例代码

#include "stdafx.h"
#include <stdio.h>
#include <stdlib.h>
#include "arcsoft_face_sdk.h"
#include "amcomdef.h"
#include "asvloffscreen.h"
#include "merror.h"
#include <direct.h>
#include <iostream>  
#include <stdarg.h>
#include <string>
#include <opencv2\opencv.hpp>
using namespace std;
#pragma comment(lib, "libarcsoft_face_engine.lib")
#define APPID "官网获取APPID"
#define SDKKey "官网获取ADKKey"
#define SafeFree(p) { if ((p)) free(p); (p) = NULL; }
#define SafeArrayDelete(p) { if ((p)) delete [] (p); (p) = NULL; } 
#define SafeDelete(p) { if ((p)) delete (p); (p) = NULL; } 
//裁剪图片,做四字节对齐
void CutIplImage(IplImage* src, IplImage* dst, int x, int y)
{
    CvSize size = cvSize(dst->width, dst->height);//区域大小
    cvSetImageROI(src, cvRect(x, y, size.width, size.height));//设置源图像ROI
    cvCopy(src, dst); //复制图像
    cvResetImageROI(src);//源图像用完后，清空ROI
}
int main()
{
    //激活接口,首次需联网激活
    MRESULT res = ASFOnlineActivation(APPID, SDKKey);
    //MRESULT res = ASFActivation(APPID, SDKKey);
    if (MOK != res && MERR_ASF_ALREADY_ACTIVATED != res)
        printf("ASFActivation fail: %d\n", res);
    else
        printf("ASFActivation sucess: %d\n", res);
    //获取激活文件信息
    ASF_ActiveFileInfo  activeFileInfo;
    res = ASFGetActiveFileInfo(&activeFileInfo);
    if (res != MOK)
        printf("ASFGetActiveFileInfo fail: %d\n", res);
    //初始化接口
    MHandle handle = NULL;
    MInt32 mask = ASF_FACE_DETECT | ASF_FACERECOGNITION | ASF_AGE | ASF_GENDER | ASF_FACE3DANGLE | ASF_LIVENESS | ASF_IR_LIVENESS;
    res = ASFInitEngine(ASF_DETECT_MODE_IMAGE, ASF_OP_0_ONLY, 30, 10, mask, &handle);
    if (res != MOK)
        printf("ASFInitEngine fail: %d\n", res);
    else
        printf("ASFInitEngine sucess: %d\n", res);
    // 人脸检测
    IplImage* img1 = cvLoadImage("RGB图像路径");
    IplImage* img2 = cvLoadImage("RGB图像路径");
    IplImage* img3 = cvLoadImage("IR图像路径");
    if (img1 && img2 && img3)
    {
        ASF_MultiFaceInfo detectedFaces1 = { 0 };
        ASF_SingleFaceInfo SingleDetectedFaces1 = { 0 };
        ASF_FaceFeature feature1 = { 0 };
        ASF_FaceFeature copyfeature1 = { 0 };
        IplImage* cutImg1 = cvCreateImage(cvSize(img1->width - img1->width % 4, img1->height), IPL_DEPTH_8U, img1->nChannels);
        CutIplImage(img1, cutImg1, 0, 0);
        res = ASFDetectFaces(handle, cutImg1->width, cutImg1->height, ASVL_PAF_RGB24_B8G8R8, (MUInt8*)cutImg1->imageData, &detectedFaces1);
        if (MOK == res)
        {
            SingleDetectedFaces1.faceRect.left = detectedFaces1.faceRect[0].left;
            SingleDetectedFaces1.faceRect.top = detectedFaces1.faceRect[0].top;
            SingleDetectedFaces1.faceRect.right = detectedFaces1.faceRect[0].right;
            SingleDetectedFaces1.faceRect.bottom = detectedFaces1.faceRect[0].bottom;
            SingleDetectedFaces1.faceOrient = detectedFaces1.faceOrient[0];
            res = ASFFaceFeatureExtract(handle, cutImg1->width, cutImg1->height, ASVL_PAF_RGB24_B8G8R8, (MUInt8*)cutImg1->imageData, &SingleDetectedFaces1, &feature1);
            if (res == MOK)
            {
                //拷贝feature
                copyfeature1.featureSize = feature1.featureSize;
                copyfeature1.feature = (MByte *)malloc(feature1.featureSize);
                memset(copyfeature1.feature, 0, feature1.featureSize);
                memcpy(copyfeature1.feature, feature1.feature, feature1.featureSize);
            }
            else
                printf("ASFFaceFeatureExtract 1 fail: %d\n", res);
        }
        else
            printf("ASFDetectFaces 1 fail: %d\n", res);
        //第二张人脸处理
        ASF_MultiFaceInfo    detectedFaces2 = { 0 };
        ASF_SingleFaceInfo SingleDetectedFaces2 = { 0 };
        ASF_FaceFeature feature2 = { 0 };
        IplImage* cutImg2 = cvCreateImage(cvSize(img2->width - img2->width % 4, img2->height), IPL_DEPTH_8U, img2->nChannels);
        CutIplImage(img2, cutImg2, 0, 0);
        res = ASFDetectFaces(handle, cutImg2->width, cutImg2->height, ASVL_PAF_RGB24_B8G8R8, (MUInt8*)cutImg2->imageData, &detectedFaces2);
        if (MOK == res)
        {
            SingleDetectedFaces2.faceRect.left = detectedFaces2.faceRect[0].left;
            SingleDetectedFaces2.faceRect.top = detectedFaces2.faceRect[0].top;
            SingleDetectedFaces2.faceRect.right = detectedFaces2.faceRect[0].right;
            SingleDetectedFaces2.faceRect.bottom = detectedFaces2.faceRect[0].bottom;
            SingleDetectedFaces2.faceOrient = detectedFaces2.faceOrient[0];
            res = ASFFaceFeatureExtract(handle, cutImg2->width, cutImg2->height, ASVL_PAF_RGB24_B8G8R8, (MUInt8*)cutImg2->imageData, &SingleDetectedFaces2, &feature2);
            if (MOK != res)
                printf("ASFFaceFeatureExtract 2 fail: %d\n", res);
        }
        else
            printf("ASFDetectFaces 2 fail: %d\n", res);
        // 单人脸特征比对
        MFloat confidenceLevel;
        res = ASFFaceFeatureCompare(handle, ©feature1, &feature2, &confidenceLevel);
        if (res != MOK)
            printf("ASFFaceFeatureCompare fail: %d\n", res);
        else
            printf("ASFFaceFeatureCompare sucess: %lf\n", confidenceLevel);
        //设置活体置信度 SDK内部默认值为 IR：0.7  RGB：0.75（无特殊需要，可以不设置）
        ASF_LivenessThreshold threshold = { 0 };
        threshold.thresholdmodel_BGR = 0.75;
        threshold.thresholdmodel_IR = 0.7;
        res = ASFSetLivenessParam(handle, &threshold);
        if (res != MOK)
            printf("ASFSetLivenessParam fail: %d\n", res);
        else
            printf("RGB Threshold: %f  IR Threshold: %f\n", threshold.thresholdmodel_BGR, threshold.thresholdmodel_IR);
        // RGB图像属性检测
        MInt32 processMask = ASF_AGE | ASF_GENDER | ASF_FACE3DANGLE | ASF_LIVENESS;
        res = ASFProcess(handle, cutImg2->width, cutImg2->height, ASVL_PAF_RGB24_B8G8R8, (MUInt8*)cutImg2->imageData, &detectedFaces2, processMask);
        if (res != MOK)
            printf("ASFProcess fail: %d\n", res);
        else
            printf("ASFProcess sucess: %d\n", res);
        // 获取年龄
        ASF_AgeInfo ageInfo = { 0 };
        res = ASFGetAge(handle, &ageInfo);
        if (res != MOK)
            printf("ASFGetAge fail: %d\n", res);
        else
            printf("Age: %d\n", ageInfo.ageArray[0]);
        // 获取性别
        ASF_GenderInfo genderInfo = { 0 };
        res = ASFGetGender(handle, &genderInfo);
        if (res != MOK)
            printf("ASFGetGender fail: %d\n", res);
        else
            printf("Gender: %d\n", genderInfo.genderArray[0]);
        // 获取3D角度
        ASF_Face3DAngle angleInfo = { 0 };
        res = ASFGetFace3DAngle(handle, &angleInfo);
        if (res != MOK)
            printf("ASFGetFace3DAngle fail: %d\n", res);
        else
            printf("3DAngle roll: %f   yaw: %f   pitch: %f\n", angleInfo.roll[0], angleInfo.yaw[0], angleInfo.pitch[0]);
        //获取RGB活体信息
        ASF_LivenessInfo rgbLivenessInfo = { 0 };
        res = ASFGetLivenessScore(handle, &rgbLivenessInfo);
        if (res != MOK)
            printf("ASFGetLivenessScore fail: %d\n", res);
        else
            printf("RGB Liveness: %d\n", rgbLivenessInfo.isLive[0]);
        //**************进行IR活体检测********************
        printf("\n**********IR LIVENESS*************\n");
        ASF_MultiFaceInfo    detectedFaces3 = { 0 };
        IplImage* cutImg3 = cvCreateImage(cvSize(img3->width - img3->width % 4, img3->height), IPL_DEPTH_8U, img3->nChannels);
        CutIplImage(img3, cutImg3, 0, 0);
        //opencv读图时会将灰度图读成RGB图，需要转换成GRAY图进行IR活体检测
        cv::Mat grayMat;
        cv::Mat copyCutImg3(cutImg3, false);    //IplImage转Mat 设为ture为深拷贝
        cv::cvtColor(copyCutImg3, grayMat, CV_BGR2GRAY);
        res = ASFDetectFaces(handle, cutImg3->width, cutImg3->height, ASVL_PAF_RGB24_B8G8R8, (MUInt8*)cutImg3->imageData, &detectedFaces3);
        if (res != MOK)
            printf("ASFGetLivenessScore fail: %d\n", res);
        else
            printf("Face num: %d\n", detectedFaces3.faceNum);
        //IR图像活体检测
        MInt32 processIRMask = ASF_IR_LIVENESS;
        res = ASFProcess_IR(handle, grayMat.cols, grayMat.rows, ASVL_PAF_GRAY, (MUInt8*)grayMat.data, &detectedFaces3, processIRMask);
        if (res != MOK)
            printf("ASFProcess_IR fail: %d\n", res);
        else
            printf("ASFProcess_IR sucess: %d\n", res);
        //获取RGB活体信息
        ASF_LivenessInfo irLivenessInfo = { 0 };
        res = ASFGetLivenessScore_IR(handle, &irLivenessInfo);
        if (res != MOK)
            printf("ASFGetLivenessScore_IR fail: %d\n", res);
        else
            printf("IR Liveness: %d\n", irLivenessInfo.isLive[0]);
        SafeFree(copyfeature1.feature);        //释放内存
        cvReleaseImage(&cutImg1);
        cvReleaseImage(&cutImg2);
        cvReleaseImage(&cutImg3);
    }
    cvReleaseImage(&img1);
    cvReleaseImage(&img2);
    cvReleaseImage(&img3);
    //获取版本信息
    const ASF_VERSION* pVersionInfo = ASFGetVersion(handle);
    //反初始化
    res = ASFUninitEngine(handle);
    if (res != MOK)
        printf("ALUninitEngine fail: %d\n", res);
    else
        printf("ALUninitEngine sucess: %d\n", res);
    getchar();
    return 0;