# OpenCV

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

本指南系统介绍了如何在 **Android** 平台集成和使用 [**OpenCV**](<https://opencv.org/>)[（](<https://opencv.org/>)[**Open Source Computer Vision Library**](<https://opencv.org/>) 进行计算机视觉应用开发。旨在为开发者提供一条清晰的实践路径，帮助您快速、顺利地在 **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** 包。

1. 访问 [OpenCV官网发布页](<https://opencv.org/releases/>)。

2. 选择最新或特定版本的 **OpenCV**，下载 **"Android"** 压缩包并解压到本地。此处以 **4.8.0** 为例：

```{image} images/image_SRyMb1XcGobBdgxY2PIc4cIrnrf.webp
:width: 743px
:height: 262px
```

**SDK主要目录结构说明**：

```{image} images/image_KOkHbLefXowOKzxUdsicDn4jnAf.webp
:width: 358px
:height: 324px
```

| <div style="text-align: center"><br><strong>目录</strong><br></div> | <div style="text-align: center"><br><strong>说明</strong><br></div> |
| --- | --- |
| **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++开发  <br>本地原生库包含针对不同CPU架构（如armeabi-v7a, arm64-v8a, x86）编译好的库文件 |

## 安装步骤

以下是在 **Android Studio** 项目中集成 **OpenCV** 的两种主流方法。

### 导入本地SDK模块（传统方式）

这种方式将 **OpenCV** 库的源代码和本地库直接集成到你的项目中。

1. 导入模块：在 **Android Studio** 中，选择 **File** -> **New** -> **Import Module**...，浏览并选择解压后的 **OpenCV SDK** 中的 **sdk** 目录，此处指定 **Module Name** 为 **opencv_sdk**。

```{image} images/image_Y5TsbhQFXoAbhpxWE4HcBzYrnuf.webp
:width: 737px
:height: 272px
```

```{image} images/image_MnZBbnzjkoflW1xWiB9cG9wmndh.webp
:width: 605px
:height: 308px
```

1. 修改 **opencv_sdk** 的 **build.gradle** 文件：  
    - 修改 **build.gradle** 文件中 **sdk** 版本，与 **app** 的 **build.gradle** 中的 **sdk** 版本一致。  
    - 注释 **'kotlin-android'** 插件。  
    - 重新编译成功。

```{image} images/image_DrQrbcaDEozkpcxt1QjckqyWnQb.webp
:width: 867px
:height: 350px
```

1. 添加模块依赖：打开你的 **App** 模块的 **build.gradle** 文件，在 **dependencies** 块中添加对 **OpenCV** 模块的依赖：**implementation project(':opencv_sdk')**。

```{image} images/image_RfCFb4sagoJEEYxwUlLcNneqn6b.webp
:width: 811px
:height: 393px
```

1. 复制原生库：在你的 **App** 模块的 **main** 目录下创建 **jniLibs** 文件夹（如果不存在）。将 **OpenCV-android-sdk/sdk/native/libs** 下的所有子目录（如 **arm64-v8a**）复制到 **jniLibs** 目录中。

```{image} images/image_XFl9bLZ25o4bqUxgpr1cznYZnFh.webp
:width: 318px
:height: 368px
```

1. 同步配置：确保导入 **OpenCV** 模块的 **build.gradle** 文件中的 **compileSdkVersion、minSdkVersion** 等版本号与你的 **App** 模块保持一致。

### 通过Maven依赖（推荐，简便）

从 **OpenCV 4.5.1** 开始，官方提供了 **Maven** 仓库支持，这是最便捷的集成方式。

1. **添加依赖**：在你的 **app** 模块的 **build.gradle** 文件的 **dependencies** 块中添加：

```plaintext
// 将4.x.x换成最新版本号或指定的版本号
implementation 'org.opencv:opencv-android:4.x.x'
```

1. **同步项目**：**Gradle** 会自动从 **Maven** 仓库下载对应的 **OpenCV Java** 库和原生库。

## 功能使用

下面将以 **实时转换相机流灰度化图像** 功能为例介绍使用方式。

### 权限添加

在 **app** 模块中的 **AndroidManifest.xml** 文件中添加权限：

```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
<?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:**

```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**：

```{image} images/image_AkMHbjMI7omsAlx6O5IctZeZn9e.webp
:width: 718px
:height: 409px
```

```{image} images/image_NpP6bx1hToZ0waxACNKcFy24njh.webp
:width: 708px
:height: 411px
```

## 常见问题

| <div style="text-align: center"><br><strong>问题</strong><br></div> | <div style="text-align: center"><br><strong>可能原因</strong><br></div> |
| --- | --- |
| 报错：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返回错误） | <ol><li>检查jniLibs目录结构是否正确。</li><li>在build.gradle的ndk块中指定abiFilters。</li><li>确保测试设备已安装所需版本的OpenCV Manager，或改用静态初始化。</li></ol> |
| 找不到libopencv_java.so | 确认 .so 文件已正确复制到 app/src/main/jniLibs/ 下各子目录。 |
| 相机预览黑屏或崩溃 | <ol><li>动态申请并检查权限。</li><li>确保在onPause()中正确释放相机。</li><li>在surfaceChanged回调中设置合适的相机预览尺寸。</li></ol> |
| 使用imread等函数时报链接错误 | 某些桌面平台才有的GUI函数在移动端不被支持。在Android上避免使用imshow。读取图像可使用Bitmap与Utils.bitmapToMat转换；显示则通过Android的ImageView实现。 |
| 应用体积过大 | 集成了所有CPU架构的原生库。在build.gradle中使用ndk.abiFilters只打包目标设备架构（如 arm64-v8a）的库文件。 |
| 运行速度慢 | <ol><li>将图像处理逻辑移至后台线程（如AsyncTask或线程池）。对于复杂操作，考虑使用OpenCV的 C++ 原生代码实现以获得最佳性能。</li><li>结合板载NPU和GPU能力进行加速（若有）。</li></ol> |

## 进阶建议

- 从示例开始：**OpenCV Android SDK** 自带的 **samples** 目录是极佳的学习资源，涵盖了从基础相机操作到人脸检测、颜色跟踪等多种场景。

- 混合使用 **Java** 和 **C++**：对于性能要求高的核心算法，可以通过 **JNI** 调用 **C++** 代码。**OpenCV** 提供了完整的 **native/jni** 支持。

- 关注 **DNN** 模块：**OpenCV** 的 **DNN** 模块允许在移动端高效运行深度学习模型（如 **YOLO、MobileNet SSD**），是实现现代计算机视觉应用（如物体识别、活体检测）的关键。