libfacedetection 移动端移植指南:在 iOS 与 Android 上集成 CNN 人脸检测

原创2026-09-21 18:25:241,936 阅读
文章标签:计算机视觉人工智能深度学习图像处理

libfacedetection 移动端移植指南:在 iOS 与 Android 上集成 CNN 人脸检测

libfacedetection 是一款开源的人脸检测库,其核心 API facedetect_cnn 基于轻量 CNN 网络实现,可在普通 CPU 上达到接近实时的检测速度。本指南以仓库 mobile/README.md 为主线,完整梳理该库移植到 iOS(Objective-C++ + OpenCV)与 Android(Kotlin + JNI + OpenCV)两条集成路径:从工程搭建、facedetectcnn.h 的 SIMD 宏配置,到 facedetect_cnn 的结果解析与界面绘制,再到 JNI 层的数据转换。读完本文,你将能够在自己的移动端 App 中直接复用本仓库的示例代码完成人脸检测功能的落地。

移动端支持概览

仓库的 mobile 目录下同时维护了两套可直接编译运行的移动端示例工程:

平台 工程位置 技术栈
iOS mobile/iOS/FaceDetection Objective-C++(.mm)+ OpenCV iOS framework
Android mobile/Android/FaceDetection Kotlin + JNI(C++)+ OpenCV Android SDK + CMake/NDK

两者的核心思路完全一致:复用 src/ 目录下同一套 C++ 源码,通过 OpenCV 完成图像读取与显示,并针对 ARM 平台开启 NEON 指令集加速。下面的截图分别是两个平台示例工程的真实运行效果(来自本仓库 mobile/iOS/screenshot1.png 与 mobile/Android/screenshot1.jpg)。

iOS 平台 libfacedetection 人脸检测运行结果

Android 平台 libfacedetection 人脸检测运行结果

iOS 集成实战

按照 mobile/README.md 的描述,iOS 端集成共分 6 步:下载/克隆仓库 → 新建 Xcode 工程 → 将 src 加入工程 → 链接系统库 → 导入 opencv2.framework → 参照示例编写代码。下面是每一步的关键细节。

1. 将源码加入工程并链接系统库

  • 在 Xcode 中新建工程后,将本仓库 src 目录下的源码文件(facedetectcnn.cpp、facedetectcnn-model.cpp、facedetectcnn-data.cpp 以及头文件)直接拖入工程;
  • 在 Build Phases → Link Binary With Libraries 中添加系统库 libc++.tbd,以及工程实际用到的其他系统 framework(如 ACFoundation.framework 等,按工程模板默认即可);
  • 下载 opencv2.framework 并加入工程。示例工程 mobile/iOS/FaceDetection/ViewController.mm 中就是通过 OpenCV 的 imread 读取图片、rectangle/circle/putText 绘制结果,最后用 MatToUIImage 转回 UIImage 展示。

2. 修改 facedetectcnn.h:按 CPU 架构启用 SIMD 宏

这是移动端移植最关键的配置。打开 src/facedetectcnn.h,按设备 CPU 类型打开对应的指令集宏:

//#define _ENABLE_AVX2 //Please enable it if X64 CPU
#define _ENABLE_NEON //Please enable it if ARM CPU
//#include "facedetection_export.h"
#define FACEDETECTION_EXPORT

需要理解的三点:

  • _ENABLE_NEON:iOS 设备均为 ARM CPU,必须打开该宏才能使用 ARM NEON 向量指令,否则将回退到标量实现,性能损失明显。facedetectcnn.h 在定义 NEON 时还会把输入数据映射到 <a href="https://link.gitcode.com/i/107c842731a5d7060af49c03c677865a" target="_blank">0, 127] 区间以使用 INT8×INT8 点积(见 [src/facedetectcnn.h);
  • _ENABLE_AVX2 / _ENABLE_AVX512:仅用于 x86/x64 CPU,移动端保持注释状态;
  • 互斥约束:头文件中通过 #error 强制规定 AVX512、AVX2、NEON 三者不可同时开启(见 src/facedetectcnn.h),因为同一次编译只能针对一种 SIMD 体系生成内核。

此外,移动端工程不依赖导出头文件,因此示例将 #include "facedetection_export.h" 注释掉,并直接 #define FACEDETECTION_EXPORT(空定义)让 API 以默认可见性导出。

3. 将 .m 重命名为 .mm

由于检测代码使用了 C++ 的头文件与 OpenCV 的 C++ API,所有需要调用 facedetect_cnn 的源文件必须把扩展名从 .m 改为 .mm,交由 Xcode 的 Objective-C++ 编译器处理。示例工程中即使用了 mobile/iOS/FaceDetection/ViewController.mm。

4. 头文件导入顺序

在 .mm 文件中导入头文件时,必须将 OpenCV 头放在最前面:

#import <opencv2/opencv.hpp>
#import <opencv2/imgcodecs/ios.h>
#import "ViewController.h"
#import "facedetectcnn.h"

先导入 opencv2/opencv.hpp 是为了保证 OpenCV 的命名空间与类型声明先于 facedetectcnn.h 生效,避免头文件解析顺序导致的编译错误。

5. 完整检测代码与结果解析

下面是示例工程 mobile/iOS/FaceDetection/ViewController.mm 中经过实际运行验证的完整实现(相较 README 中的旧版代码,该文件额外做了 BGR→RGB 转换以便正确显示):

- (UIImage *)loadImageAndDectect:(const char *)image_file{
    Mat img = imread(image_file);
    if (img.empty()) {
        fprintf(stderr, "Can not load the image file %s.\n", image_file);
        return nil;
    }

    int *pResults = NULL;
    unsigned char * pBuffer = (unsigned char *)malloc(DETECT_BUFFER_SIZE);
    if (!pBuffer) {
        fprintf(stderr, "Can not alloc buffer.\n");
        return nil;
    }
    pResults = facedetect_cnn(pBuffer, (unsigned char *)(img.ptr(0)), img.cols, img.rows, (int)img.step);
    printf("%d faces detected.\n", (pResults ? *pResults : 0));
    Mat result_cnn = img.clone();
    cvtColor(img, result_cnn, cv::COLOR_BGR2RGB);
    //print the detection results
    for(int i = 0; i < (pResults ? *pResults : 0); i++)
    {
        short * p = ((short*)(pResults+1)) + FACEDETECTION_RESULT_STRIDE_SHORTS * i;
        int confidence = p[0];
        int x = p[1];
        int y = p[2];
        int w = p[3];
        int h = p[4];

        printf("face%drect=[%d, %d, %d, %d], confidence=%d\n",i,x,y,w,h,confidence);
        rectangle(result_cnn, cv::Rect(x, y, w, h), Scalar(0, 255, 0), 2);
        string str = to_string(confidence);
        putText(result_cnn, str, cv::Point(x-2,y-2), cv::FONT_HERSHEY_SIMPLEX, 1.0, Scalar(0, 255, 0));
        for (int j = 5; j < 14; j += 2) {
            int p_x = p[j];
            int p_y = p[j+1];
            printf("landmark%d=[%d, %d]\n",(j-5)/2,p_x,p_y);
            circle(result_cnn, cv::Point(p_x,p_y), 2, Scalar(255, 0, 0), -1, cv::LINE_AA);
        }
    }

    free(pBuffer);

    return MatToUIImage(result_cnn);
}

- (void)viewDidLoad {
    [super viewDidLoad];

    UIImageView *imageView = [[UIImageView alloc] initWithFrame:[UIScreen mainScreen].bounds];
    imageView.contentMode = UIViewContentModeScaleAspectFit;
    [self.view addSubview:imageView];

    NSString *path = [[NSBundle mainBundle] pathForResource:@"test" ofType:@".jpg"];
    imageView.image = [self loadImageAndDectect:[path UTF8String]];
}

在 viewDidLoad 中,示例从 App 的 Bundle 中读取测试图片 test.jpg(位于 mobile/iOS/FaceDetection/test.jpg),调用检测方法后把带标注的结果图显示在 UIImageView 上。

6. 检测结果的内存布局

facedetect_cnn 的函数签名定义在 src/facedetectcnn.h:

#define FACEDETECTION_RESULT_BUFFER_SIZE 0x9000
#define FACEDETECTION_RESULT_MAX_FACES 1024
#define FACEDETECTION_RESULT_STRIDE_SHORTS 16

FACEDETECTION_EXPORT int * facedetect_cnn(unsigned char * result_buffer,
                    unsigned char * rgb_image_data, int width, int height, int step);

解析结果时需遵守以下约定(示例代码中已完整体现):

  • pResults[0] 为检测到的人脸数量,因此 *pResults 直接可用作循环上限;
  • 从 pResults+1 开始是每人脸固定 FACEDETECTION_RESULT_STRIDE_SHORTS(16)个 short 的记录,依次为:confidence(置信度)、x、y、w、h(人脸矩形框),随后是 5 个关键点(左右眼、鼻尖、左右嘴角)的坐标,每点 x、y 两个 short,共 10 个;
  • 输入图像必须是三通道 BGR 格式,step 传图像的行字节步长 img.step;
  • result_buffer 大小必须严格等于 FACEDETECTION_RESULT_BUFFER_SIZE(0x9000 = 36864 字节),不可更改,示例用 #define DETECT_BUFFER_SIZE FACEDETECTION_RESULT_BUFFER_SIZE 直接引用宏来保证一致;
  • 结果指针 pResults 指向 result_buffer 内部,不要释放 pResults,只需在最后 free(pBuffer);
  • 若在多线程中调用检测函数,每个线程需要独立的 buffer(该提示同时出现在 src/facedetectcnn.h 的注释与 JNI 代码中)。

Android 集成实战

Android 端在 libfacedetection 的基础 C++ 源码之上,额外提供了一层 JNI 封装(mobile/Android/FaceDetection/app/src/main/cpp/facedetectcnn-jni.cpp),把 facedetect_cnn 的裸指针结果转换成 Java/Kotlin 可用的 Face 对象。仓库还在 mobile/Android/FaceDetection/release/facedetection.apk 直接提供了一份编译好的 APK,可直接安装到 Android 设备上体验。

1. 环境准备

按 README 的要求准备环境:

  • 克隆本仓库,并确保 Android Studio 已下载 CMake、NDK(如需调试 C++ 代码还可安装 LLDB);
  • 从 OpenCV 官方 Releases 页面下载 OpenCV Android SDK,解压后将 OpenCV-android-sdk 目录放到仓库根目录下(README 原文即要求 unzip 到 project root dir)。

工程通过 mobile/Android/FaceDetection/settings.gradle 将 OpenCV 作为 Gradle 子模块引入:

include ':app'

def opencv_sdk='./OpenCV-android-sdk/sdk'
include ':opencv4'
project(':opencv4').projectDir = new File(opencv_sdk)

2. CMake 构建配置:三行看懂 OpenCV 集成

app/src/main/cpp/CMakeLists.txt 是 Android 端构建的核心。它通过相对路径把上层 src/ 的源码与 JNI 文件一起编成 libfacedetection.so:

SET(fdt_base_dir   ${PROJECT_SOURCE_DIR})
SET(fdt_src_dir    ${fdt_base_dir}/../../../../../../../src/)
SET(fdt_inc_dir    ${fdt_base_dir}/../../../../../../../src/)

FILE(GLOB_RECURSE fdt_source_files ${fdt_src_dir}/*.cpp)
FILE(GLOB_RECURSE jni_source_files ${fdt_base_dir}/facedetectcnn-jni.cpp)

ADD_LIBRARY(${fdt_lib_static} STATIC  ${fdt_source_files} ${jni_source_files})
ADD_LIBRARY(${fdt_lib_shared} SHARED ${fdt_source_files} ${jni_source_files})

该文件顶部提供了一组与移动端强相关的编译选项:

选项 默认值 说明
ENABLE_OPENCV ON 启用 OpenCV 支持并链接 libopencv_java4.so
ENABLE_OPENMP ON 启用 OpenMP 多线程并行
ENABLE_INT8 ON 启用 INT8 量化加速(对应 -D_ENABLE_INT8)
ENABLE_NEON ON ARM 平台启用 NEON 指令集(对应 -D_ENABLE_NEON)
ENABLE_AVX2 / ENABLE_AVX512 OFF x64 专用,移动端关闭
DEMO OFF 是否构建桌面 Demo

同时所有源文件统一使用 -O3 优化(CMake 中通过 add_definitions("-O3") 与 GCC/Clang 分支下的 -O3 双重保证)。OpenCV 头文件与 libopencv_java4.so 的路径则直接指向仓库根目录下的 OpenCV-android-sdk:

SET(OpenCV_INCLUDE_DIRS ${PROJECT_SOURCE_DIR}/../../../../OpenCV-android-sdk/sdk/native/jni/include)
SET(OpenCV_SHARED_LIBS  ${PROJECT_SOURCE_DIR}/../../../../OpenCV-android-sdk/sdk/native/libs/${ANDROID_ABI})

add_library(libopencv_java4 SHARED IMPORTED)
set_target_properties(libopencv_java4 PROPERTIES
        IMPORTED_LOCATION "${OpenCV_SHARED_LIBS}/libopencv_java4.so")

因此,正如 README 所说:“all you need to do is to add opencv for android to it and RUN IT”——把 OpenCV SDK 放到指定位置后即可直接编译运行。

3. 修改 facedetectcnn.h

与 iOS 端完全相同,Android 端同样需要按 ARM CPU 打开 NEON 并定义导出宏:

//#define _ENABLE_AVX2 //Please enable it if X64 CPU
#define _ENABLE_NEON //Please enable it if ARM CPU
//#include "facedetection_export.h"
#define FACEDETECTION_EXPORT

仓库根目录的 build_android.sh 展示了用 NDK 交叉编译本库时的等效 CMake 参数,可作为对照参考:-DANDROID_ABI="arm64-v8a" -DANDROID_ARM_NEON=ON -DENABLE_NEON=ON -DENABLE_AVX2=OFF。

4. JNI 封装:C++ 结果到 Java 对象的桥接

JNI 层 facedetectcnn-jni.cpp 做了三件事,与 iOS 示例形成完整对照:

  1. 颜色空间转换:Android 端通过 Utils.bitmapToMat 得到的通常是 RGBA 四通道图,JNI 中先 cvtColor(img, bgr, COLOR_RGBA2BGR) 转成 facedetect_cnn 要求的 BGR 三通道输入;
  2. 调用检测:pResults = facedetect_cnn(pBuffer, (unsigned char*)(bgr.ptr(0)), bgr.cols, bgr.rows, (int)bgr.step);,并用 FACEDETECTION_RESULT_STRIDE_SHORTS 按 stride 遍历每人脸;
  3. 反射填充 Java 对象:通过 JNI 反射创建 org.dp.facedetection.Face、org.opencv.core.Rect、org.opencv.core.Point,把 confidence / x / y / w / h 与 5 个关键点逐字段填入,最终以 jobjectArray 返回。

对应的 Java/Kotlin 侧定义非常精简。数据载体 Face.java 只有三个公开字段:

public class Face {
    public Rect faceRect;
    public int faceConfidence;
    public Point[] faceLandmarks;
}

调用方 MainActivity.kt 中声明 external fun facedetect(matAddr: Long): Array<Face>,在 init 块里 System.loadLibrary("facedetection") 加载 so,然后对 assets 中的 test2.jpg 执行检测并统计耗时:

val startTime = System.currentTimeMillis()
val facesArray = facedetect(mat.nativeObjAddr)
str = str + "detectTime = ${System.currentTimeMillis() - startTime}ms\n"
for (face in facesArray) {
    Imgproc.rectangle(mat, face.faceRect, FACE_RECT_COLOR, FACE_RECT_THICKNESS)
    for (landmark in face.faceLandmarks){
        Imgproc.circle(mat, landmark, FACE_RECT_THICKNESS, FACE_RECT_COLOR, -1, Imgproc.LINE_AA)
    }
}

注意 JNI 函数签名 Java_org_dp_facedetection_MainActivity_facedetect 必须与 Kotlin 包名 org.dp.facedetection 及方法名 facedetect 严格一致,这是 JNI 命名规范决定的。

移动端集成的关键注意点

综合 iOS 与 Android 两条移植路径,以下约束来自源码或示例代码,移植到自己的工程时必须遵守:

  1. 输入必须是三通道 BGR:facedetect_cnn 的形参名虽是 rgb_image_data,但 src/facedetectcnn.h 注释明确要求输入为 BGR。iOS 端 imread 默认读入 BGR 可直接使用;Android 端 RGBA 位图必须先 COLOR_RGBA2BGR;
  2. 结果缓冲区大小固定:DETECT_BUFFER_SIZE 必须等于 FACEDETECTION_RESULT_BUFFER_SIZE(0x9000),勿自行修改;
  3. 多线程调用需独立 buffer:检测函数内部会复用传入的缓冲区,多线程并发时必须为每个线程单独分配;
  4. 不要释放 pResults:它指向缓冲区内部,释放整个 pBuffer 即可;
  5. SIMD 宏互斥:_ENABLE_AVX512、_ENABLE_AVX2、_ENABLE_NEON 同时只能开启一个,否则编译报错;
  6. iOS 头文件顺序:必须先 #import <opencv2/opencv.hpp> 再导入其他头文件;涉及 C++ API 的源文件须为 .mm 扩展名;
  7. Android 工程路径约定:OpenCV-android-sdk 必须解压到仓库根目录,settings.gradle 与 CMakeLists.txt 中的相对路径均依赖这一约定。

结语

通过本仓库的 mobile 示例,libfacedetection 在 iOS 与 Android 上的集成路径已经非常成熟:iOS 端只需“源码 + OpenCV framework + NEON 宏 + .mm”,Android 端只需“源码 + OpenCV SDK + JNI 封装 + CMake”。两张运行截图(iOS、Android)与现成 APK(facedetection.apk)均可作为验收基准。开发者按照本文步骤完成工程搭建后,即可把 src/facedetectcnn.cpp 中的轻量 CNN 检测能力无缝嵌入自己的移动应用。

登录后查看全文
libfacedetection