ArcSoft ArcFace SDK Linux 平台 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 "arcsoft_face_sdk.h"
#include "amcomdef.h"
#include "asvloffscreen.h"
#include "merror.h"
#include <iostream>  
#include <string>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#define APPID "官网获取APPID"
#define SDKKey "官网获取SDKKEY"
#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; } 
#define NSCALE "取值范围[2,32]，VIDEO模式推荐值16，IMAGE模式内部设置固定值为30" 
#define FACENUM    "检测的人脸数"
int main()
{
    //激活SDK
    MRESULT res = ASFOnlineActivation(APPID, SDKKEY);
    if (MOK != res && MERR_ASF_ALREADY_ACTIVATED != res)
        printf("ASFOnlineActivation fail: %d\n", res);
    else
        printf("ASFOnlineActivation sucess: %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, NSCALE, FACENUM, mask, &handle);
    if (res != MOK)
        printf("ALInitEngine fail: %d\n", res);
    else
        printf("ALInitEngine sucess: %d\n", res);
    char* picPath1 = "图片路径，该demo只支持裸数据（NV21/BGR24/BMP等）格式";
    int Width1 = 图片宽度;
    int Height1 = 图片高度;
    int Format1 = ASVL_PAF_RGB24_B8G8R8;    //图像数据为RGB24颜色格式
    MUInt8* imageData1 = (MUInt8*)malloc(Height1*Width1*3);
    FILE* fp1 = fopen(picPath1, "rb");
    char* picPath2 = "图片路径，该demo只支持裸数据（NV21/BGR24/BMP等）格式";
    int Width2 = 图片宽度;
    int Height2 = 图片高度;
    int Format2 = ASVL_PAF_RGB24_B8G8R8;    //图像数据为RGB24颜色格式
    MUInt8* imageData2 = (MUInt8*)malloc(Height2*Width2*3);
    FILE* fp2 = fopen(picPath2, "rb");
    char* picPath3 = "图片路径，这里用的NV21为例";
    int Width3 = 图片宽度;
    int Height3 = 图片高度;
    int Format3 = ASVL_PAF_GRAY;    //用于红外活体检测
//只读NV21前2/3的数据为灰度数据
    MUInt8* imageData3 = (MUInt8*)malloc(Height2*Width2);    
    FILE* fp3 = fopen(picPath3, "rb");
    if (fp1 && fp2 && fp3)
    {
        fread(imageData1, 1, Height1*Width1*3, fp1);        //读BGR裸数据
        fclose(fp1);
        fread(imageData2, 1, Height2*Width2*3, fp2);        //读BGR裸数据
        fclose(fp2);
        fread(imageData3, 1, Height3*Width3, fp3);//读NV21前2/3的数据,用于红外活体检测
        fclose(fp3);
        // 人脸检测
        ASF_MultiFaceInfo detectedFaces1 = { 0 };
        ASF_SingleFaceInfo SingleDetectedFaces = { 0 };
        ASF_FaceFeature feature1 = { 0 };
        ASF_FaceFeature copyfeature1 = { 0 };
        res = ASFDetectFaces(handle, Width1, Height1, Format1, imageData1, &detectedFaces1);
        if (res != MOK)
            printf("%s ASFDetectFaces fail: %d\n", picPath1, res);
        else
        {
            printf("%s ASFDetectFaces sucess: %d\n", picPath1, res);
            SingleDetectedFaces.faceRect.left = detectedFaces1.faceRect[0].left;
            SingleDetectedFaces.faceRect.top = detectedFaces1.faceRect[0].top;
            SingleDetectedFaces.faceRect.right = detectedFaces1.faceRect[0].right;
            SingleDetectedFaces.faceRect.bottom = detectedFaces1.faceRect[0].bottom;
            SingleDetectedFaces.faceOrient = detectedFaces1.faceOrient[0];
        }
        // 单人脸特征提取
        res = ASFFaceFeatureExtract(handle, Width1, Height1, Format1, imageData1, &SingleDetectedFaces, &feature1);
        if (res != MOK)
            printf("%s ASFFaceFeatureExtract fail: %d\n", picPath1, res);
        else
        {
            printf("%s ASFFaceFeatureExtract sucess: %d\n", picPath1, res);
            //拷贝feature，否则第二次进行特征提取，会覆盖第一次特征提取的数据，导致比对的结果为1
            copyfeature1.featureSize = feature1.featureSize;
            copyfeature1.feature = (MByte *)malloc(feature1.featureSize);
            memset(copyfeature1.feature, 0, feature1.featureSize);
            memcpy(copyfeature1.feature, feature1.feature, feature1.featureSize);
        }
        ASF_MultiFaceInfo detectedFaces2 = { 0 };
        ASF_FaceFeature feature2 = { 0 };
        res = ASFDetectFaces(handle, Width2, Height2, Format2, imageData2, &detectedFaces2);
        if (res != MOK)
            printf("%s ASFDetectFaces fail: %d\n", picPath2, res);
        else
        {
            printf("%s ASFDetectFaces sucess: %d\n", picPath2, res);
            SingleDetectedFaces.faceRect.left = detectedFaces2.faceRect[0].left;
            SingleDetectedFaces.faceRect.top = detectedFaces2.faceRect[0].top;
            SingleDetectedFaces.faceRect.right = detectedFaces2.faceRect[0].right;
            SingleDetectedFaces.faceRect.bottom = detectedFaces2.faceRect[0].bottom;
            SingleDetectedFaces.faceOrient = detectedFaces2.faceOrient[0];
        }
        res = ASFFaceFeatureExtract(handle, Width2, Height2, Format2, imageData2, &SingleDetectedFaces, &feature2);
        if (res != MOK)
            printf("%s ASFFaceFeatureExtract fail: %d\n", picPath2, res);
        else
            printf("%s ASFFaceFeatureExtract sucess: %d\n", picPath2, 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("ASFSetLivenessParam sucess: %d\n", res);
        // 人脸信息检测
        MInt32 lastMask = ASF_AGE | ASF_GENDER | ASF_FACE3DANGLE | ASF_LIVENESS;
        res = ASFProcess(handle, Width2, Height2, Format2, imageData2, &detectedFaces2, lastMask);
        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("%s ASFGetAge fail: %d\n", picPath2, res);
        else
            printf("%s ASFGetAge sucess: %d First face age: %d\n", picPath2, res, ageInfo.ageArray[0]);
        // 获取性别
        ASF_GenderInfo genderInfo = { 0 };
        res = ASFGetGender(handle, &genderInfo);
        if (res != MOK)
            printf("%s ASFGetGender fail: %d\n", picPath2, res);
        else
            printf("%s ASFGetGender sucess: %d First face gender: %d\n", picPath2, res, genderInfo.genderArray[0]);
        // 获取3D角度
        ASF_Face3DAngle angleInfo = { 0 };
        res = ASFGetFace3DAngle(handle, &angleInfo);
        if (res != MOK)
            printf("%s ASFGetFace3DAngle fail: %d\n", picPath2, res);
        else
            printf("%s ASFGetFace3DAngle sucess: %d First face 3dAngle: roll: %lf yaw: %lf pitch: %lf\n", picPath2, res, angleInfo.roll[0], angleInfo.yaw[0], angleInfo.pitch[0]);
        //获取活体信息
        ASF_LivenessInfo rgbLivenessInfo = { 0 };
        res = ASFGetLivenessScore(handle, &rgbLivenessInfo);
        if (res != MOK)
            printf("ASFGetLivenessScore fail: %d\n", res);
        else
            printf("ASFGetLivenessScore sucess: %d\n", rgbLivenessInfo.isLive[0]);
        //**************进行IR活体检测********************
        printf("\n**********IR LIVENESS*************\n");
        ASF_MultiFaceInfo    detectedFaces3 = { 0 };
        //以GRAY图像为例进行红外活体检测
        res = ASFDetectFaces(handle, Width3, Height3, Format3, imageData3, &detectedFaces3);
        if (res != MOK)
            printf("ASFDetectFaces fail: %d\n", res);
        else
            printf("Face num: %d\n", detectedFaces3.faceNum);
        //IR图像活体检测
        MInt32 processIRMask = ASF_IR_LIVENESS;
        res = ASFProcess_IR(handle, Width3, Height3, ASVL_PAF_GRAY, imageData3, &detectedFaces3, processIRMask);
        if (res != MOK)
            printf("ASFProcess_IR fail: %d\n", res);
        else
            printf("ASFProcess_IR sucess: %d\n", res);
        //获取IR活体信息
        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);        //释放内存
        SafeArrayDelete(imageData1);
        SafeArrayDelete(imageData2);
        SafeArrayDelete(imageData3);
        //获取版本信息
        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);
    }
    else{
        printf("No pictures found.\n");
    }
    getchar();
    return 0;
}