简介一份面向Android开发者的OpenCV运动目标检测项目工程包适合具备一定Android或NDK基础的开发者阅读与实战。包内含完整的Android Studio工程源码、JNI本地实现、OpenCV依赖库、构建脚本及可安装APK覆盖相机帧捕获、图像预处理、背景差分与高斯混合模型等运动目标检测核心流程。资源共99个文件以.so动态库、.java源码、.xml配置文件、.cpp原生代码及APK安装包为主整体体积14.08MB目录按照工程结构组织便于定位和对比学习。截至目前已有237人学习下载适合需要快速搭建OpenCV-Android检测环境并理解跨平台视觉应用开发思路的开发者。额外附带的Matlab实现Prim算法文档可作为图论与图像分割结合应用的拓展参考资料。1. 一个能跑的OpenCV-Android工程包运动目标检测的完整拼图拿到这个OpenCV-Android运动目标检测的压缩包解压后你会看到一整套工程可安装的APK、jni下的 C 源码、libs里预编译的 armeabi 和 armeabi-v7a 动态库还有一份《Matlab实现无约束条件下普列姆(Prim)算法.docx》。这不只是演示代码而是一次从摄像头取帧、JNI 交叉编译、目标检测到 APK 打包的完整链路。它适合两种人想在 Android Studio 里复现 OpenCV 原生接口调用的开发者以及做智能监控、移动端巡检、需要把运动目标检测移植到手机上的工程师。核心思路很朴素在算力有限的设备上用背景差分加形态学处理把运动物体稳定地捞出来。下面我按算法选型、JNI 实现、构建流程、进阶优化四层往下拆。2. 运动目标检测算法选型帧差、GMM背景建模与光流的移动端取舍2.1 三种经典算法的原理对比运动目标检测的核心是区分“背景”和“前景”。在连续视频流中背景通常是静态或缓慢变化的而运动物体在相邻帧之间会产生明显的像素差异。最常见的三种方法是帧间差分法Frame Difference、高斯混合模型背景建模GMM/MOG2和光流法Optical Flow。帧间差分法的思路最直接取当前帧I_t与上一帧I_{t-1}做差得到差分图像D_t |I_t - I_{t-1}|再设置阈值T将大于T的像素标记为前景。它的计算量很小适合低功耗设备但问题是检测出的目标边缘不完整容易产生空洞而且当物体静止时会立刻消失。GMM 背景建模则是为每个像素建立多个高斯分布用历史帧统计出背景模型。OpenCV 中的BackgroundSubtractorMOG2就是这个原理的典型实现。新帧到来时计算当前像素与背景模型的匹配度匹配不上的像素被判为前景。相比帧差法GMM 能更好地处理光照缓慢变化和周期性背景扰动比如晃动的树叶但内存占用和计算量也更高。在 Android 手机上如果分辨率控制在 640x480 左右MOG2 在普通 ARM 处理器上可以达到实时的帧率。光流法通过计算相邻帧中特征点的运动向量来检测目标能够提供更丰富的运动信息甚至能估计运动速度。但光流法对光照突变和噪声非常敏感而且计算密集移动端要跑到实时往往需要 GPU 或 NPU 加速。因此在这个工程包里作者在原生层使用的是MOG2背景分割这正是移动端性能与效果之间的折中。算法计算开销抗光照干扰输出信息适用场景帧间差分极低弱二值前景区域固定摄像头、低功耗提醒GMM/MOG2中中前景掩码室内监控、智能门铃光流法高弱运动向量场运动分析、视频拼接2.2 参数与实现步骤先用一段代码跑通检测在 OpenCV 的 C 接口中运动目标检测的实现可以浓缩成下面这段核心代码。它也是这个工程包jni_part.cpp里的主干逻辑#include opencv2/core/core.hpp #include opencv2/video/background_segm.hpp #include opencv2/imgproc/imgproc.hpp cv::Ptrcv::BackgroundSubtractorMOG2 bg_model; cv::Mat frame_gray, fg_mask, fg_thresh; void init_background_model() { // history500用过去500帧建立背景varThreshold36像素差异超过36判为前景 bg_model cv::createBackgroundSubtractorMOG2(500, 36, false); } void process_frame(cv::Mat input_frame) { cv::cvtColor(input_frame, frame_gray, cv::COLOR_BGR2GRAY); // 用当前灰度图更新背景模型输出前景掩码 bg_model-apply(frame_gray, fg_mask); // 前景掩码再二值化把灰度差异转换成明确的0/1 cv::threshold(fg_mask, fg_thresh, 200, 255, cv::THRESH_BINARY); // 开运算去除噪声闭运算填补目标内部空洞 cv::morphologyEx(fg_thresh, fg_thresh, cv::MORPH_OPEN, cv::getStructuringElement(cv::MORPH_ELLIPSE, cv::Size(3, 3))); cv::morphologyEx(fg_thresh, fg_thresh, cv::MORPH_CLOSE, cv::getStructuringElement(cv::MORPH_ELLIPSE, cv::Size(5, 5))); }这里history参数决定背景模型对场景变化的适应速度。history越大背景更新越慢当前景物体长时间停顿时它会被逐渐吸收为背景history越小背景更新越快但运动缓慢的物体会被漏检。varThreshold则是像素值差别的敏感度值越小越容易把噪声当作运动目标。在室内监控场景下history300、varThreshold36通常能获得比较干净的掩码如果是在户外风吹草动带来的高频扰动建议把varThreshold提升到 48 以上。这个参数组合也是我拆包后第一件事要测试的内容因为不同摄像头传感器的噪声水平差异很大。2.3 为什么移动端更喜欢MOG2而非Deep Learning方案工程包里没有出现任何深度学习推理框架如 TensorFlow Lite、NCNN原因很实际纯 C 的 OpenCV 背景建模在移动端 CPU 上的延迟可以控制在 20ms 以内而 YOLO 等目标检测器虽然能输出语义类别但往往需要数秒的初始化时间和几十毫秒的推理时间且多数时候手机端算力扛不住实时摄像头流。如果你的应用目标只是“发现有人进入区域”而不是“识别出这是一个穿红衣服的人”MOG2 加形态学处理就是性价比最高的方案。注意这里不是否定深度学习而是要区分“运动检测”motion detection和“目标识别”object recognition前者只回答“有没有变化”后者回答“是什么”两者可以串联使用。3. JNI层实现从摄像头帧到检测结果的C流水线3.1 解包后的工程结构jni、libs、src各司其职解压后首先要看jni目录它是整个工程的引擎。jni/Android.mk是 Makefile 描述文件jni/jni_part.cpp是核心 C 源码jni/Application.mk控制平台特性和 STL。src/org下是 Java 包里面通过System.loadLibrary(jni_part)加载本地库。libs/armeabi-v7a和libs/armeabi里是编译好的.so文件Android 系统会按设备架构自动加载对应目录下的库。assets目录存放 OpenCV 级联分类器或其他配置文件而tutorial-3-native3.apk是已经打包好的演示安装包。从名称看“tutorial-3-native3”对应 OpenCV 官方 Android 原生示例的第三个工程示例重点就是演示JNI Camera的最小实现。目录/文件作用jni/Android.mkNDK 构建脚本定义模块名和源码jni/jni_part.cpp运动检测 C 实现jni/Application.mkABI、平台版本、STL 配置libs/armeabi-v7a编译好的 ARMv7.sosrc/org/...Java 层 Activity 与 JNI 调用tutorial-3-native3.apk可直接安装的演示 APK3.2 Android.mk 配置与 JNI 函数签名jni_part.cpp的典型结构可以分为三块JNI 接口、图像处理函数、以及把 Java 层传递的 Bitmap 或字节数组转换为cv::Mat的辅助函数。下面摘取工程中常见的 Android.mk 内容LOCAL_PATH : $(call my-dir) include $(CLEAR_VARS) OPENCV_CAMERA_MODULES : off OPENCV_INSTALL_MODULES : on OPENCV_LIB_TYPE : SHARED include ../../sdk/native/jni/OpenCV.mk LOCAL_MODULE : jni_part LOCAL_SRC_FILES : jni_part.cpp LOCAL_LDLIBS -llog -ldl include $(BUILD_SHARED_LIBRARY)注意include ../../sdk/native/jni/OpenCV.mk这一行依赖 OpenCV SDK 的目录结构编译前要确认OPENCV_ANDROID_SDK路径正确否则会报OpenCV.mk not found。LOCAL_LDLIBS中的-llog用于输出 logcat-ldl用于动态加载 OpenCV Manager 中的库。在Application.mk中通常会指定APP_ABI : armeabi-v7a APP_PLATFORM : android-14 APP_STL : gnustl_staticAPP_ABI : armeabi-v7a意味着只打一种架构生成的 APK 体积更小如果你的设备是 ARMv8绝大多数现代手机还需要增加arm64-v8a。APP_STL : gnustl_static指定静态 STL避免运行时找不到 libstdc 的问题。这个设置对 C 项目几乎是必须的否则std::vector、std::string的符号会链接失败。3.3 Java 层如何把摄像头帧丢给 JNI标准流程是Camera或Camera2的预览回调拿到YUV420数据先转成Mat再调用 native 方法。在jni_part.cpp中JNI 函数签名形如下方。这个函数接收一个 byte 数组和宽高在本地构造灰度图处理完后将检测框坐标写回两个 int 数组避免频繁创建 Java 对象extern C JNIEXPORT jint JNICALL Java_org_opencv_samples_tutorial3_Tutorial3Activity_processFrame( JNIEnv* env, jobject, jbyteArray yuv_data, jint width, jint height, jintArray out_rects) { jbyte* yuv env-GetByteArrayElements(yuv_data, 0); cv::Mat yuv_mat(height height / 2, width, CV_8UC1, yuv); cv::Mat bgr_mat; cv::cvtColor(yuv_mat, bgr_mat, cv::COLOR_YUV420sp2BGR); process_frame(bgr_mat); // 上一章的检测逻辑 // 用findContours获取运动目标外接矩形写回out_rects std::vectorstd::vectorcv::Point contours; cv::findContours(fg_thresh, contours, cv::RETR_EXTERNAL, cv::CHAIN_APPROX_SIMPLE); // ... 将满足面积阈值的矩形坐标写入 int 数组 env-ReleaseByteArrayElements(yuv_data, yuv, 0); return contours.size(); }注意GetByteArrayElements返回的指针在Release之前是固定锁定的。处理大分辨率帧时要尽快释放否则 GC 压力增大会导致掉帧。这里有个容易踩的坑cvtColor的转换码YUV420sp2BGR对应 Android 摄像头预览默认的NV21格式。如果预览回调使用YUV_420_888或RGBA_8888转换码要相应改为YUV420p2BGR或直接RGBA2BGR否则图像颜色会整体偏色进而影响前景掩码的准确性。3.4 目标后处理连通域和面积过滤单纯的掩码图会包含很多小噪点所以工程里一般会调用findContours找出所有白色区域然后按面积阈值过滤。面积太大可能是场景突变面积太小是噪点。过滤后还要做矩形合并把同一目标分裂出的多个小块合并成一个外接框。这个环节可以用 OpenCV 的groupRectangles或者自己写 IoU 合并。我会在最后一章再展开一个稳定化技巧因为findContours的结果直接决定最终预览框的平滑度。4. 从源码到APK构建流程、权限与ABI适配实践4.1 在Eclipse或Android Studio中导入工程这个工程包带有.project、.classpath和project.properties说明它最初是 Eclipse ADT 项目。现在推荐的做法是导入 Android Studio直接选 “Import project (Eclipse ADT, Gradle, etc.)”让 IDE 自动转换。但要注意project.properties中targetandroid-19之类的旧配置导入后应改为当前 SDK 版本否则过高的 compileSdk 和低版本 target 会触发兼容性警告。如果你的 Android Studio 版本较新Eclipse 项目转换后会自动生成build.gradle但src目录的包结构可能需要手动调整。4.2 用 convert-dependencies.sh 处理 OpenCV 依赖包里的convert-dependencies.sh是 OpenCV SDK 提供的一个脚本它会把 OpenCV 库与第三方依赖复制到工程中的libs目录。运行方式通常是在 SDK 的sdk/native下执行并传入工程路径cd OpenCV-2.4.x-android-sdk/sdk/native ./convert-dependencies.sh 你的工程路径/libs脚本执行后libs里会出现libopencv_java3.so或libopencv_core.so等文件。这一步的目的是让 APK 自带 OpenCV 动态库而不是依赖用户额外安装 OpenCV Manager。如果你希望 APK 体积更小可以依赖 OpenCV Manager在 Java 加载库之前先调用OpenCVLoader.initAsync()但代价是用户首次运行会跳转安装提示。工程包中AndroidManifest.xml里如果包含 OpenCV Manager 的声明那就说明它走的是后一种方式。手动跑ndk-build时我一般这样执行export PATH$PATH:/opt/android-ndk ndk-build NDK_PROJECT_PATH. APP_BUILD_SCRIPTjni/Android.mkNDK_PROJECT_PATH指向工程根目录APP_BUILD_SCRIPT显式指定构建脚本路径这样即使 IDE 环境变量混乱命令行也能保证产物正确输出到libs。4.3 回调配置与实时帧率控制摄像头采集的实时性直接影响检测效果。AndroidManifest.xml中必须声明两个权限否则预览画面全黑uses-permission android:nameandroid.permission.CAMERA / uses-feature android:nameandroid.hardware.camera android:requiredtrue /Android 6.0 之后摄像头属于运行时权限除了 manifest 声明还要在 Activity 中动态申请。工程包里的示例如果没加动态申请在 Android 9 以上会直接崩溃。建议在onResume()中封装权限检查通过后再打开相机。在帧率控制上我不推荐在预览回调里做阻塞式处理。常见做法是先用TextureView的onPreviewFrame拿帧然后把byte[]丢进一个HandlerThread在子线程做检测主线程只负责刷新 UI。这样即使单帧处理耗时 50ms也不会阻塞 UI 的 16ms 刷新周期。4.4 常见的链接和崩溃问题排查在 NDK 编译时经常会遇到undefined reference to cv::createBackgroundSubtractorMOG2()。这个函数在 OpenCV 3.0 以后才有如果你的 SDK 是 2.4.x应改用cv::BackgroundSubtractorMOG2类的构造函数。相反如果你在旧代码里看到new BackgroundSubtractorMOG2(500, 36)而链接的是 OpenCV 4.x也会报找不到符号。解决方案是统一头文件和 so 版本最好在 mk 文件里显式指定 OpenCV 的 include 路径和链接库顺序。错误现象常见原因解决方式OpenCV.mk not foundOPENCV_ANDROID_SDK 路径错误mk 中 include 真实路径UnsatisfiedLinkErrorABI 不匹配统一 APP_ABI 和 libs 架构相机预览黑屏缺少 CAMERA 权限manifest 声明 动态申请画面颜色偏绿YUV 格式转换错误确认 NV21 或 YUV_420_888另外java.lang.UnsatisfiedLinkError多半是 ABI 不匹配。现在手机大多是 arm64-v8a但Application.mk只写了armeabi-v7a系统仍能加载兼容的 32 位库前提是libs/armeabi-v7a下的.so完整。如果你自己引入其他 ABI 的.so需要把APP_ABI同步修改否则会出现找到多个.so但架构不一致的问题。我通常会在Application.mk里写成APP_ABI : armeabi-v7a arm64-v8a让 64 位设备跑原生 64 位库性能释放更充分。5. 工程包里的隐藏技能Prim算法辅助分割与检测框稳定化5.1 Matlab的Prim算法文档在什么场景下用得上压缩包里的《Matlab实现无约束条件下普列姆(Prim)算法.docx》看起来和运动检测不搭界但实际上它解决的是目标分割中的一个痛点。无约束条件的 Prim 算法可以在给定一组像素种子点的情况下找到连接这些点所需的最小代价路径代价可以定义为像素灰度差或梯度值。在运动目标被分裂成多个碎片时先对每个碎片取质心再用 Prim 算法生成最小生成树最后用树的最短路径把这些碎片连接起来可以恢复出完整目标的轮廓。Matlab 实现通常长这样% 输入points为Nx2的坐标矩阵 D pdist2(points, points); % 计算两两欧氏距离矩阵 G graph(D); T minspantree(G, Method, prim); plot(T, XData, points(:,1), YData, points(:,2));在 Android 工程中你不必真的去跑 Matlab只需要把同样的逻辑改成 C用cv::partition或自定义的并查集做连通分组合并。Prim 算法在这里的价值是给出一条“连接所有碎片的最短路径”据此可以推断哪些碎片应该被合并成同一个目标。5.2 让检测框更稳的一个实用技巧运动检测最常见的体验问题是检测框抖动。抖动来源有两个掩码边缘的像素起伏和连通域面积阈值临界值。我常用的稳定化手法是引入一个简单的时间滤波对每个跟踪目标的中心坐标做滑动平均。cv::Point2f smooth_center(cv::Point2f raw, cv::Point2f prev, float alpha) { prev alpha * raw (1.0f - alpha) * prev; return prev; }配合面积阈值处理时不要取固定阈值而是取前一帧目标面积的 ±30% 作为动态范围能有效抑制“时有时无”的闪烁。另外别忘了在每一帧处理前清空上一帧的轮廓缓存否则findContours返回的 vector 会越长越大拖慢帧率。这个技巧可以直接嵌入jni_part.cpp中在findContours之后、绘制矩形之前对每个候选框做一次平滑。这样最终在 UI 上看到的红色矩形框会稳定很多不会随着目标轻微姿势变化而剧烈跳动。本文还有配套的精品资源点击获取