商米开发者文档

活体检测包括3种类型：RGB彩色图活体、NIR近红外活体和3D结构光活体。RGB彩色图活体使用普通摄像头图片判断，抵御能力普通，如果对活体有较高要求，建议直接考虑NIR近红外活体和3D结构光活体。

NIR近红外活体需要配备红外双目摄像头，主要通过红外反射形成的红外图像进行判断。3D结构光活体需要配备3D结构光摄像头，通过两个摄像头图片的微小区别形成深度图像，判断虚假平面类的攻击。两种活体判断都需要人脸离摄像头较近且完整的场景。此外，由于红外图像和深度图像与彩色图像之间可能会有位置偏移，因此SDK要求在进行NIR近红外活体和3D结构光活体时，彩色图像的分辨率务必为640×480。

商米不同型号设备摄像头配置选择可能有区别，请咨询商米销售。另外在选择设备和方案阶段，我们很乐于提供一些实际场景应用的经验。

1.1 NIR近红外活体检测简介

NIR近红外活体检测利用近红外成像原理，比如屏幕无法成像，不同材质反射率不同等，可以抵御手机和照片等多种攻击。

红外成像有多种类型，比较常见的有两种：第一种是inutive模组采集的pattern红外图，这种红外图是带斑点的；与此相对应的是用Boteye模组采集的clean红外图，这种红外图不带斑点是干净的。商米人脸识别SDK使用clean红外图，商米设备配备的红外摄像头都满足红外活体检测要求。

此外，商米人脸识别演示APP中已经预设了商米配置的双目红外摄像头的偏差值，以下三点设置细节可帮助使用其他途径获得的双目摄像头的情况：

1. RGB和NIR图像分辨率均为640×480。
2. NIR近红外活体检测需保证RGB图像和IR图像在时间上是对应的。
3. RGB图和IR图存在一定的位置偏差，以RGB图检测到的人脸位置为参考，IR图在x方向和y方向的偏差如表1.1.1所示。

表1.1.1 IR摄像头偏移情况

IR摄像头型号	IR图相比RGB图在x方向的偏移量	IR图相比RGB图在y方向的偏移量
1	-40	0
2	10	-10

1.2 NIR活体使用步骤

NIR近红外活体检测是人脸识别基础上的附加功能，在使用 人脸识别Andriod_SDK_1.4 调用人脸识别功能的过程中（特别注意第3.7、3.9和3.15），如需要NIR近红外活体检测功能，依次添加以下四个步骤：

第一步：在第3.7节的配置SDK时，添加对NIR活体检测阈值设定：

param.setNirLivenessThreshold(0.5f); //阈值越高，活体检测越严格，人脸通过活体检测的难度越大
param.setNirXOffset(-40); //根据设备型号设置红外图相对彩色图x方向偏移量
param.setNirYOffset(0); //根据设备型号设置红外图相对彩色图y方向偏移量

第二步：将RGB图的全部通道从Bitmap类型转成字节数组；将IR图的一个通道从Bitmap类型转成字节数组，两组示例代码如下。

RGB图全部通道从Bitmap类型转成字节数组：

public static byte[] getPixelsBGR(Bitmap image) {
    // 计算图片有多少字节
    int bytes = image.getByteCount();

    ByteBuffer buffer = ByteBuffer.allocate(bytes); // 创建新的buffer
    image.copyPixelsToBuffer(buffer); // 移动字节数据到buffer

    byte[] temp = buffer.array(); // 获取包含数据的底层数组
    byte[] pixels = new byte[(temp.length / 4) * 3]; // 分配空间给BGR

    // 对像素重组
    for (int i = 0; i ‹ temp.length / 4; i++) {
        pixels[i * 3] = temp[i * 4 + 2];        //B
        pixels[i * 3 + 1] = temp[i * 4 + 1];    //G
        pixels[i * 3 + 2] = temp[i * 4];        //R
    }
    return pixels;
}

IR图的一个通道从Bitmap类型转成字节数组：

public static byte[] getSingleChannelPixels(Bitmap image){
    if(image == null){return null;}
    int bytes = image.getByteCount();

    ByteBuffer buffer = ByteBuffer.allocate(bytes); // Create a new buffer
    image.copyPixelsToBuffer(buffer); // Move the byte data to the buffer

    byte [] temp = buffer.array();
    byte[] pixels = new byte[(temp.length / 4)];
    for (int i = 0; i ‹ temp.length / 4; i++) {
        pixels[i] = temp[i * 4];
    } 
    return pixels;

}

第三步：检查第3.15节中提到的执行选择功能不是PredictMode_None；再使用SunmiFaceImage构造函数及上一步得到的彩色图字节流和红外图字节流创建SunmiFaceImage实例；最后通过实例中的setLivenessMode方法指定需要进行的活体检测方法：

SunmiFaceImage image = new SunmiFaceImage(RGBData, RGBbitmap.getHeight(), RGBbitmap.getWidth(), IRData, IRHeight, IRWidth, null, null, null, 1);
image.setPredictMode(SunmiFaceMode.PredictMode_Feature);//执行功能选择不能是PredictMode_None
image.setLivenessMode(SunmiFaceLivenessMode.LivenessMode_None);//不进行活体检测
image.setLivenessMode(SunmiFaceLivenessMode.LivenessMode_NIR);//只进行NIR活体检测
image.setLivenessMode(SunmiFaceLivenessMode.LivenessMode_NIR|SunmiFaceLivenessMode.LivenessMode_RGB)//同时进行NIR和RGB活体检测

第四步：获取活体检测分数及SDK返回的响应值：

SunmiFaceImageFeatures features = new SunmiFaceImageFeatures(); //构造空的人脸特征对象
ret = SunmiFaceSDK.getImageFeatures(image, features); //使用人脸识别SDK进行特征提取
SunmiFaceFeature faceFeature = SunmiFaceLib.SunmiFaceFeatureArrayGetItem(features.getFeatures(), 0);  //提取置信度最高的人脸特征信息
float rgb_liveness_score = faceFeature.getRgbLivenessScore(); //获取置信度最高的人脸RGB活体检测分数
float nir_liveness_score = faceFeature.getNirLivenessScore();//获取置信度最高的人脸NIR活体检测分数

开发者可根据不同的需求对rgb_liveness_score和nir_liveness_score进行后续代码逻辑开发。当返回的ret为FACE_CODE_NOT_LIVENESS时，说明SDK根据当前设定的RGB和NIR活体检测阈值认为当前人脸是假脸；而ret为FACE_CODE_OK时说明当前人脸通过了RGB彩色图和NIR近红外活体检测。

2. 3D结构光活体检测

2.1 3D结构光活体检测简介

商米人脸识别SDK使用奥比中光3D结构光摄像头实现3D结构光活体检测功能。3D摄像头采集到的深度图以字节流的形式输出，其中每个像素点占据2个字节，其物理意义为在图像上该点物体到摄像头的距离（距离单位为毫米）。3D结构光活体检测反欺诈能力相对较强，建议安全性要求较高场景选用。

此外，商米人脸识别演示APP中已经预设了商米配置的3D结构光摄像头的偏差值，一般可以直接使用，两种摄像头的参数略有不同，以下三点设置细节可帮助您了解更多：

1. RGB图像分辨率为 640×480，3D结构光活体检测深度图分辨率如表2.1.1所示。
2. 3D结构光活体检测需保证RGB图像和深度图像在时间上是对应的。
3. 彩色图和深度图存在一定的位置偏差，以彩色图检测到的人脸位置为参考，深度图在x方向和y方向的偏差如表2.1.1所示。

表2.1.1 配置3D摄像头的商米设备情况

设备型号	3D摄像头型号	深度图分辨率	深度图相比彩色图在x方向偏移量	深度图相比彩色图在y方向偏移量	是否旋转
K1	Pro A	640*480	28	-20	否
K2	D2plus	400*640	75	-15	是

2.2 3D结构光活体检测使用步骤

3D结构光活体检测是人脸识别基础上的附加功能，在使用 人脸识别Andriod_SDK_1.6 调用人脸识别功能的过程中（特别注意第3.7、3.9和3.15），如需要3D结构光活体检测功能，依次添加以下四个步骤：

第一步：在第3.7节的配置SDK时，添加对3D结构光活体检测阈值设定：

param.setDepthLivenessThreshold(0.5f); //阈值越高，活体检测越严格，人脸通过活体检测的难度越大
param.setDepthXOffset(75); //根据设备型号设置深度图相对彩色图x方向偏移量
param.setDepthYOffset(-15); //根据设备型号设置深度图相对彩色图y方向偏移量

3D活体阈值0.5f的含义，以及如何设置调整？
3D活体识别算法的输出是真人的置信度，商米3D活体阈值设定范围为0-1，可调范围为0.4-0.7，活体识别一般建议阈值为0.5，一般能很好满足需要。

假如场景环境较好、对活体识别要求较高，也可以考虑调高阈值，阈值设定越高，活体检测越严格，但阈值调高的过程中不可避免在光线和角度不佳的情况下真人会通不过活体检测，可以根据场景实测结果调整。

第二步：根据使用的摄像头型号，Pro A（常见于K1，T2）或D2plus（常见于K2），具体见表2.1.1，确定图像是否需要旋转，需要旋转的进行彩色图和深度图的旋转，最后再把彩色图从Bitmap类型转换成字节数组，示例代码分别如下：

旋转彩色图：

public static Bitmap rotateBitmap(Bitmap origin, float alpha) {
        if (origin == null) {
            return null;
        }
        int width = origin.getWidth();
        int height = origin.getHeight();
        Matrix matrix = new Matrix();
        matrix.setRotate(alpha);
        // 围绕原地进行旋转
        Bitmap newBM = Bitmap.createBitmap(origin, 0, 0, width, height, matrix, false);
        if (newBM.equals(origin)) {
            return newBM;
        }

        return newBM;
    }

旋转深度图：

public static byte [] rotateDepthImage(byte[] depthByte, int height, int width){
        if(depthByte == null){return null;}

        int depthLen = height * width * 2;
        byte [] newDepth = new byte [depthLen];
        for (int i = 0; i‹=width-1; i++){
            for(int j = 0; j‹=height-1; j++){
                newDepth[2*(i*height+j)] = depthByte[2*((height-1-j)*width+i)];
                newDepth[2*(i*height+j)+1] = depthByte[2*((height-1-j)*width+i)+1];
            }
        }
        return newDepth;
    }

将彩色图从Bitmap类型转成字节数组：

public static byte[] getPixelsBGR(Bitmap image) {
    // 计算图片有多少字节
    int bytes = image.getByteCount();

    ByteBuffer buffer = ByteBuffer.allocate(bytes); // 创建新的buffer
    image.copyPixelsToBuffer(buffer); // 移动字节数据到buffer

    byte[] temp = buffer.array(); // 获取包含数据的底层数组
    byte[] pixels = new byte[(temp.length / 4) * 3]; // 分配空间给BGR

    // 对像素重组
    for (int i = 0; i ‹ temp.length / 4; i++) {
        pixels[i * 3] = temp[i * 4 + 2];        //B
        pixels[i * 3 + 1] = temp[i * 4 + 1];    //G
        pixels[i * 3 + 2] = temp[i * 4];        //R
    }
    return pixels;
}

第三步：检查第3.15节中提到的执行选择功能不是PredictMode_None；再使用SunmiFaceImage构造函数及上一步得到的彩色图字节流和红外图字节流创建SunmiFaceImage实例；最后通过实例中的setLivenessMode方法指定需要进行的活体检测方法：

SunmiFaceImage image = new SunmiFaceImage(RGBData, RGBbitmap.getHeight(), RGBbitmap.getWidth(), null, null, null, DepthData, DepthHeight, DepthWidth, 1);
image.setPredictMode(SunmiFaceMode.PredictMode_Feature);//执行功能选择不能是PredictMode_None
image.setLivenessMode(SunmiFaceLivenessMode.LivenessMode_None);//不进行活体检测
image.setLivenessMode(SunmiFaceLivenessMode.LivenessMode_Depth);//只进行3d活体检测
image.setLivenessMode(SunmiFaceLivenessMode.LivenessMode_Depth|SunmiFaceLivenessMode.LivenessMode_RGB)//同时进行3d和RGB活体检测

注：在使用3D活体检测时，为保证正确调用3D摄像头并且获取深度图，需要导入奥比中光SDK（demo代码commonlib/libs目录下的arm64-v8a、armeabi-v7a和openni2.3.jar）和3D摄像头的配置文件（demo代码app/src/main/assets/目录下的openni）。

第四步：获取活体检测分数及SDK返回的响应值：

SunmiFaceImageFeatures features = new SunmiFaceImageFeatures(); //构造空的人脸特征对象
ret = SunmiFaceSDK.getImageFeatures(image, features); //使用人脸识别SDK进行特征提取
SunmiFaceFeature faceFeature = SunmiFaceLib.SunmiFaceFeatureArrayGetItem(features.getFeatures(), 0);  //提取置信度最高的人脸特征信息
float rgb_liveness_score = faceFeature.getRgbLivenessScore(); //获取置信度最高的人脸RGB活体检测分数
float depth_liveness_score = faceFeature.getDepthLivenessScore();//获取置信度最高的人脸3D活体检测分数

开发者可根据不同的需求对rgb_liveness_score和depth_liveness_score进行后续代码逻辑开发。当返回的ret为FACE_CODE_NOT_LIVENESS时，说明SDK根据当前设定的RGB和3D结构光活体检测阈值认为当前人脸是假脸；而ret为FACE_CODE_OK时说明当前人脸通过了RGB彩色图和3D结构光活体检测。