libfacedetection 移动端移植指南:在 iOS 与 Android 上集成 CNN 人脸检测
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 集成实战
按照 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 示例形成完整对照:
- 颜色空间转换:Android 端通过
Utils.bitmapToMat得到的通常是 RGBA 四通道图,JNI 中先cvtColor(img, bgr, COLOR_RGBA2BGR)转成facedetect_cnn要求的 BGR 三通道输入; - 调用检测:
pResults = facedetect_cnn(pBuffer, (unsigned char*)(bgr.ptr(0)), bgr.cols, bgr.rows, (int)bgr.step);,并用FACEDETECTION_RESULT_STRIDE_SHORTS按 stride 遍历每人脸; - 反射填充 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 两条移植路径,以下约束来自源码或示例代码,移植到自己的工程时必须遵守:
- 输入必须是三通道 BGR:
facedetect_cnn的形参名虽是rgb_image_data,但 src/facedetectcnn.h 注释明确要求输入为 BGR。iOS 端imread默认读入 BGR 可直接使用;Android 端 RGBA 位图必须先COLOR_RGBA2BGR; - 结果缓冲区大小固定:
DETECT_BUFFER_SIZE必须等于FACEDETECTION_RESULT_BUFFER_SIZE(0x9000),勿自行修改; - 多线程调用需独立 buffer:检测函数内部会复用传入的缓冲区,多线程并发时必须为每个线程单独分配;
- 不要释放
pResults:它指向缓冲区内部,释放整个pBuffer即可; - SIMD 宏互斥:
_ENABLE_AVX512、_ENABLE_AVX2、_ENABLE_NEON同时只能开启一个,否则编译报错; - iOS 头文件顺序:必须先
#import <opencv2/opencv.hpp>再导入其他头文件;涉及 C++ API 的源文件须为.mm扩展名; - 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 检测能力无缝嵌入自己的移动应用。

