OpenCV¶
Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.
本指南系统介绍了如何在 Android 平台集成和使用 OpenCV（Open Source Computer Vision Library 进行计算机视觉应用开发。旨在为开发者提供一条清晰的实践路径，帮助您快速、顺利地在 Android 项目中部署并应用 OpenCV 的强大视觉功能。
简介¶
Android OpenCV 是针对 Android 平台的移植版本，专为移动设备上的计算机视觉（CV）和机器学习（ML）开发提供支持。它支持包括 Java、C++、Python 在内的多种编程语言接口。在 Android 平台上，OpenCV 提供了丰富的图像处理和计算机视觉功能，使开发者能够轻松实现人脸检测、物体识别、图像跟踪、活体检测等复杂任务。
核心特性¶
跨平台：OpenCV 支持 Windows、Linux、macOS、iOS 和 Android。
功能全：涵盖从基础的图像处理到先进的机器学习和深度学习算法。
高性能：底层由高效的 C/C++ 实现，并通过 JNI（Java Native Interface）技术为 Android 提供 Java 接口，保证了在移动设备上的运行效率。
主要应用领域包括 智能安全、医学图像处理、工业质检、自动驾驶 以及移动端的 身份认证 和 智能交互 等。
准备工作¶
在开始集成 OpenCV 之前，请确保你的开发环境已满足以下要求。
系统与环境要求¶
操作系统：Windows、macOS 或 Linux。
开发工具：Android Studio（推荐最新稳定版本）。早期的 OpenCV 示例可能基于 Eclipse，但当前开发主要使用 Android Studio。
Android SDK 与 NDK：在 Android Studio 中下载并配置。部分高级 功能（如原生 C++ 开发）需要用到 NDK。
Java 开发工具包 (JDK)：Android Studio 通常内置或会自动配置。
OpenCV库获取¶
你需要从 OpenCV 官方网站下载适用于 Android 的 SDK 包。
访问 OpenCV官网发布页。
选择最新或特定版本的 OpenCV，下载 “Android” 压缩包并解压到本地。此处以 4.8.0 为例：
SDK主要目录结构说明：
目录 |
说明 |
|---|---|
README.android |
OpenCV Android 文档 |
samples/ |
示例应用程序代码，是学习的绝佳资源 |
sdk/build.gradle |
Android项目（基于Gradle构建系统）的核心构建配置文件 |
sdk/etc/ |
预置数据和模型文件的资源目录 |
sdk/java/ |
核心Java库。包含Android Studio模块文件，将作为库模块导入项目 |
sdk/libcxx_helper/ |
C++头文件。用于JNI和原生C++ 开发 |
sdk/native/ |
包含C++头文件，用于JNI和原生C++开发 |
安装步骤¶
以下是在 Android Studio 项目中集成 OpenCV 的两种主流方法。
导入本地SDK模块（传统方式）¶
这种方式将 OpenCV 库的源代码和本地库直接集成到你的项目中。
导入模块：在 Android Studio 中，选择 File -> New -> Import Module…，浏览并选择解压后的 OpenCV SDK 中的 sdk 目录，此处指定 Module Name 为 opencv_sdk。
修改 opencv_sdk 的 build.gradle 文件：
修改 build.gradle 文件中 sdk 版本，与 app 的 build.gradle 中的 sdk 版本一致。
注释 ‘kotlin-android’ 插件。
重新编译成功。
添加模块依赖：打开你的 App 模块的 build.gradle 文件，在 dependencies 块中添加对 OpenCV 模块的依赖：implementation project(‘:opencv_sdk’)。
复制原生库：在你的 App 模块的 main 目录下创建 jniLibs 文件夹（如果不存在）。将 OpenCV-android-sdk/sdk/native/libs 下的所有子目录（如 arm64-v8a）复制到 jniLibs 目录中。
同步配置：确保导入 OpenCV 模块的 build.gradle 文件中的 compileSdkVersion、minSdkVersion 等版本号与你的 App 模块保持一致。
通过Maven依赖（推荐，简便）¶
从 OpenCV 4.5.1 开始，官方提供了 Maven 仓库支持，这是最便捷的集成方式。
添加依赖：在你的 app 模块的 build.gradle 文件的 dependencies 块中添加：
// 将4.x.x换成最新版本号或指定的版本号
implementation 'org.opencv:opencv-android:4.x.x'
同步项目：Gradle 会自动从 Maven 仓库下载对应的 OpenCV Java 库和原生库。
功能使用¶
下面将以 实时转换相机流灰度化图像 功能为例介绍使用方式。
权限添加¶
在 app 模块中的 AndroidManifest.xml 文件中添加权限：
<uses-permission android:name="android.permission.CAMERA" /><uses-featureandroid:name="android.hardware.camera"android:required="true" /><uses-featureandroid:name="android.hardware.camera.autofocus"android:required="false" /><uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
新建一个 DemoActivity, 并实现实时相机流灰度化功能：
activity_demo.xml:
<?xml version="1.0" encoding="utf-8"?><androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"xmlns:app="http://schemas.android.com/apk/res-auto"xmlns:tools="http://schemas.android.com/tools"android:id="@+id/main"android:layout_width="match_parent"android:layout_height="match_parent"tools:context=".DemoActivity"><org.opencv.android.JavaCameraViewandroid:id="@+id/javaCameraView"android:layout_width="match_parent"android:layout_height="match_parent"app:camera_id="back"app:show_fps="true" /></androidx.constraintlayout.widget.ConstraintLayout>
DemoActivity.java:
public class DemoActivity extends CameraActivity implements CameraBridgeViewBase.CvCameraViewListener2 {private static final String TAG = "opencvDemo";private JavaCameraView javaCameraView;@Overrideprotected void onCreate(Bundle savedInstanceState) {super.onCreate(savedInstanceState);setContentView(R.layout.activity_demo);ViewCompat.setOnApplyWindowInsetsListener(findViewById(R.id.main), (v, insets) -> {Insets systemBars = insets.getInsets(WindowInsetsCompat.Type.systemBars());
v.setPadding(systemBars.left, systemBars.top, systemBars.right, systemBars.bottom);return insets;});
javaCameraView = findViewById(R.id.javaCameraView);
javaCameraView.setVisibility(SurfaceView.VISIBLE);
javaCameraView.setCvCameraViewListener(this);}@Overridepublic void onPause() {super.onPause();if (javaCameraView != null) {
javaCameraView.disableView();}}@Overridepublic void onResume() {super.onResume();if (!OpenCVLoader.initDebug()) {OpenCVLoader.initAsync(OpenCVLoader.OPENCV_VERSION, this, baseLoaderCallback);} else {
baseLoaderCallback.onManagerConnected(LoaderCallbackInterface.SUCCESS);}}private final BaseLoaderCallback baseLoaderCallback = new BaseLoaderCallback(this) {@Overridepublic void onManagerConnected(int status) {switch (status) {case LoaderCallbackInterface.SUCCESS: {
javaCameraView.enableView();}break;default:super.onManagerConnected(status);break;}}};@Overrideprotected List<? extends CameraBridgeViewBase> getCameraViewList() {List<CameraBridgeViewBase> list = new ArrayList<>();
list.add(javaCameraView);return list;}@Overridepublic void onCameraViewStarted(int width, int height) {}@Overridepublic void onCameraViewStopped() {}@Overridepublic Mat onCameraFrame(CameraBridgeViewBase.CvCameraViewFrame inputFrame) {return inputFrame.gray();}}
在 MainActivity 中，允许权限后会自动跳转到 DemoActivity：
常见问题¶
问题 |
可能原因 |
|---|---|
报错：Your build is currently configured to use incompatible Java 21.0.7 and Gradle 5.6.4. Cannot sync the project |
在File > Settings > Build, Execution, Deployment > Build Tools > Gradle, 修改Gradle JDK为Java11。 |
初始化失败（onManagerConnected返回错误） |
|
找不到libopencv_java.so |
确认 .so 文件已正确复制到 app/src/main/jniLibs/ 下各子目录。 |
相机预览黑屏或崩溃 |
|
使用imread等函数时报链接错误 |
某些桌面平台才有的GUI函数在移动端不被支持。在Android上避免使用imshow。读取图像可使用Bitmap与Utils.bitmapToMat转换；显示则通过Android的ImageView实现。 |
应用体积过大 |
集成了所有CPU架构的原生库。在build.gradle中使用ndk.abiFilters只打包目标设备架构（如 arm64-v8a）的库文件。 |
运行速度慢 |
|
进阶建议¶
从示例开始：OpenCV Android SDK 自带的 samples 目录是极佳的学习资源，涵盖了从基础相机操作到人脸检测、颜色跟踪等多种场景。
混合使用 Java 和 C++：对于性能要求高的核心算法，可以通过 JNI 调用 C++ 代码。OpenCV 提供了完整的 native/jni 支持。
关注 DNN 模块：OpenCV 的 DNN 模块允许在移动端高效运行深度学习模型（如 YOLO、MobileNet SSD），是实现现代计算机视觉应用（如物体识别、活体检测）的关键。