SmartOpenCV

前言

:fire: :fire: :fire: 随着人工智能的快速发展以及终端设备硬件水平的不断提升，在终端设备上直接运行智能系统成为可能，端侧智能具备低延时，隐私安全等特点。同时降低了云端智能存在的网络传输不可靠风险，使得端侧智能越来越得到重视。端侧智能比较成熟的领域就是NLP以及CV。在CV领域OpenCV作为开源且强大的跨平台计算机视觉库，在图像处理以及图像识别方向得到了广泛应用。但是在Android平台OpenCV官方SDK在图像预览方面存在诸多缺陷。

SmartOpenCV是什么

SmartOpenCV是一个OpenCV在Android端的增强库，解决了OpenCV Android SDK在图像预览方面存在的诸多问题，而且无需修改OpenCV SDK源码，与OpenCV的SDK解耦，只需替换xml中原OpenCV的JavaCameraView/JavaCamera2View即可达到具备OpenCV官方SDK的原功能以及SmartOpenCV的增强功能。

OpenCV官方SDK存在的问题

OpenCV Android端SDK虽然很容易上手和使用，但是预览存在很多问题，常见问题如下：

• 默认横屏显示，且无法通过接口修改预览方向

• 预览绘制存在黑边：OpenCV默认绘制算法在绘制预览帧图像到Canvas时存在一定的偏移，在视觉上表现就是预览帧只会占SurfaceView控件的一部分区域，偏移部分区域会显示为黑色

  if (mScale != 0) {
      canvas.drawBitmap(mCacheBitmap, new Rect(0, 0, mCacheBitmap.getWidth(), mCacheBitmap.getHeight()),
              new Rect((int) ((canvas.getWidth() - mScale * mCacheBitmap.getWidth()) / 2),
                      (int) ((canvas.getHeight() - mScale * mCacheBitmap.getHeight()) / 2),
                      (int) ((canvas.getWidth() - mScale * mCacheBitmap.getWidth()) / 2 + mScale * mCacheBitmap.getWidth()),
                      (int) ((canvas.getHeight() - mScale * mCacheBitmap.getHeight()) / 2 + mScale * mCacheBitmap.getHeight())), null);
  } else {
      canvas.drawBitmap(mCacheBitmap, new Rect(0, 0, mCacheBitmap.getWidth(), mCacheBitmap.getHeight()),
              new Rect((canvas.getWidth() - mCacheBitmap.getWidth()) / 2,
                      (canvas.getHeight() - mCacheBitmap.getHeight()) / 2,
                      (canvas.getWidth() - mCacheBitmap.getWidth()) / 2 + mCacheBitmap.getWidth(),
                      (canvas.getHeight() - mCacheBitmap.getHeight()) / 2 + mCacheBitmap.getHeight()), null);
  }
  

• 预览帧大小选择算法不符合实际场景要求：对于预览帧大小的选择，OpenCV默认算法是选择小于预览控件(或设置的最大帧大小)的最大预览，这将导致在很多情况下预览图像的显示不能铺满整个控件甚至远小于控件大小， 在绝大部分业务场景下，这种算法不能满足实际需求

  protected Size calculateCameraFrameSize(List<?> supportedSizes, ListItemAccessor accessor, int surfaceWidth, int surfaceHeight) {
          int calcWidth = 0;
          int calcHeight = 0;
  
          int maxAllowedWidth = (mMaxWidth != MAX_UNSPECIFIED && mMaxWidth < surfaceWidth)? mMaxWidth : surfaceWidth;
          int maxAllowedHeight = (mMaxHeight != MAX_UNSPECIFIED && mMaxHeight < surfaceHeight)? mMaxHeight : surfaceHeight;
  
          for (Object size : supportedSizes) {
              int width = accessor.getWidth(size);
              int height = accessor.getHeight(size);
              Log.d(TAG, "trying size: " + width + "x" + height);
  
              if (width <= maxAllowedWidth && height <= maxAllowedHeight) {
                  if (width >= calcWidth && height >= calcHeight) {
                      calcWidth = (int) width;
                      calcHeight = (int) height;
                  }
              }
          }
          if ((calcWidth == 0 || calcHeight == 0) && supportedSizes.size() > 0)
          {
              Log.i(TAG, "fallback to the first frame size");
              Object size = supportedSizes.get(0);
              calcWidth = accessor.getWidth(size);
              calcHeight = accessor.getHeight(size);
          }
  
          return new Size(calcWidth, calcHeight);
      }
  

SmartOpenCV的特点

• 易使用：如果你项目中之前使用的是OpenCV的官方SDK，那么引入SmartOpenCV后只需将xml文件中的JavaCameraView/JavaCamera2View替换为SmartOpenCV的CamerPreview/Camera2Preview即可达到与使用官方SDK相同的效果

• 功能增强：

  1. 预览自适应：自动根据前后摄像头，横竖屏以及不同摄像头参数来调整与适配预览方向以及大小，开发者无需写任何额外代码
  2. 可扩展预览绘制算法：SmartOpenCV内置了一种默认的预览帧绘制算法，同时提供策略接口让开发者根据自己的业务场景自定义预览绘制算法
  3. 可扩展预览帧大小选择算法：SmartOpenCV内置了一种默认的预览帧大小计算算法，同时提供策略接口让开发者根据自己的业务自定义预览帧大小计算算法
  4. 支持USB摄像头：USB摄像头作为外设接入设备，和手机/平板等移动设备内置摄像头存在差异，SDK内部在处理移动设备摄像头的逻辑时也兼容了对闸机等的USB摄像头的处理

• 提供更友好的API接口：在继承OpenCV官方接口的同时，SmartOpenCV将众多繁杂操作统一通过CameraConfiguration来配置，提供更友好的Fluent API接口，让开发者能够更灵活的控制预览显示相关参数与配置

• 不直接依赖官方SDK，方便升级官方SDK：与OpenCV官方SDK解耦，只要官方SDK内部核心逻辑未做修改，那么SmartOpenCV可以兼容所有版本的官方SDK，使用SmartOpenCV后如果以后打算升级依赖的OpenCV为更新版本，只需将OpenCV的依赖更新为新版本即可，代码无需做任何改动

效果对比

以人脸识别为例

	横屏	竖屏
OpenCV	即使宽与高都设置为match_parent也无法全屏，存在黑边	存在黑边，且默认不支持竖屏
SmartOpenCV

Demo对比体验

smartopencv-app-debug.apk
opencv-app-debug.apk

Integration

Step1：在项目根目录的build.gradle中添加对jitpack仓库的配置

allprojects {
    repositories {
        ...
        maven { url 'https://jitpack.io' }
    }
}

Step2：在需要使用SmartOpenCV库的模块中添加依赖

dependencies {
	implementation('com.github.HuTianQi:SmartOpenCV:1.0.1') { // 版本号建议使用已release的最新版本
        exclude module: 'openCVLibrary411' // 由于目前多模块依赖时jitpack打包存在bug，排除打包时依赖的该模块
    }
}

使用方法

基础用法

在项目中需要使用预览的XML文件中，将OpenCV的JavaCameraView/JavaCamera2View替换为SmartOpenCV的CameraPreview/Camera2Preview即可，非常简单，无需进行其他任何操作。

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <!--<org.opencv.android.JavaCameraView-->
    <!--android:id="@+id/fd_activity_surface_view"-->
    <!--android:layout_width="match_parent"-->
    <!--android:layout_height="match_parent" />-->

    <tech.huqi.smartopencv.core.preview.CameraPreview
        android:id="@+id/fd_activity_surface_view"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
</LinearLayout>

高级用法

如果希望通过SmartOpenCV提供的接口更灵活地控制预览显示的相关参数与配置，只需调用SmartOpenCV.getInstance().init()并传入之前获取的预览控件对象即可，用法如下：

SmartOpenCV.getInstance().init(mOpenCvCameraView, new CameraConfiguration.Builder()
    .debug(true)
    .cameraIndex(0)      // 设置摄像头索引,主要用于多摄像头设备，优先级低于frontCamera
    .keepScreenOn(false) // 是否保持屏幕常亮
    .frontCamera(true)   // 是否使用前置摄像头
    .openCvDefaultDrawStrategy(false)      // 是否使用OpenCV默认的预览图像绘制策略
    .openCvDefaultPreviewCalculator(false) // 是否使用OpenCV默认的预览帧大小计算策略
    .landscape(false)     // 是否横屏显示
    .enableFpsMeter(true) // 开启预览帧率的显示
    .usbCamera(false)     // 是否使用USB摄像头，当设备接入的是USB摄像头时将其设置为true
    .maxFrameSize(400, 300)     // 设置预览帧的最大大小
    .cvCameraViewListener(this) // 设置OpenCV回调监听器
    .previewSizeCalculator(new IPreviewSizeCalculator() { // 自定义预览帧大小计算策略
        @Override
        public Size calculateCameraFrameSize(List<Size> supportedSizes, int surfaceWidth, int surfaceHeight) {
            // 若需要根据自己的具体业务场景改写览帧大小，覆写该方法逻辑
            return new Size(1080,1920); 
        }
    })
    .drawStrategy(new IDrawStrategy() { // 自定义绘制策略
        @Override
        public void drawBitmap(Canvas canvas, Bitmap frameBitmap, int surfaceWidth, int surfaceHeight) {
            // 若需根据自己的具体业务场景绘制预览帧图像，覆写该方法逻辑
        }
    })
    .build());

许可证

许可证

公众号

SmartOpenCV 快速上手指南

SmartOpenCV 是一个针对 Android 平台的 OpenCV 增强库，旨在解决官方 SDK 在图像预览方向、黑边问题及帧大小选择算法上的缺陷。它无需修改 OpenCV 源码，通过替换 XML 组件即可实现自适应横竖屏、全屏无黑边预览，并支持 USB 摄像头。

环境准备

• 开发系统：Windows, macOS 或 Linux
• 开发工具：Android Studio (推荐最新稳定版)
• 语言环境：Java 或 Kotlin
• 前置依赖：
  • 项目需配置 JitPack 仓库（SmartOpenCV 托管于此）。
  • 无需预先集成特定版本的 OpenCV SDK，SmartOpenCV 与官方 SDK 解耦，兼容性强。

安装步骤

1. 配置仓库

在项目根目录的 build.gradle (Project 级别) 文件中，添加 JitPack 仓库地址：

allprojects {
    repositories {
        // ... 其他仓库
        maven { url 'https://jitpack.io' }
    }
}

2. 添加依赖

在需要使用 SmartOpenCV 的模块 build.gradle (Module 级别) 中添加依赖。

注意：由于 JitPack 多模块打包机制，建议排除内部传递的 openCV 模块以避免冲突。

dependencies {
    implementation('com.github.HuTianQi:SmartOpenCV:1.0.1') { 
        exclude module: 'openCVLibrary411' 
    }
}

(注：请将 1.0.1 替换为最新的 Release 版本号)

基本使用

SmartOpenCV 的核心优势在于“零代码侵入”，仅需替换布局文件中的视图组件即可生效。

1. 替换 XML 布局

在您的布局文件（如 activity_main.xml）中，将原生的 JavaCameraView 或 JavaCamera2View 替换为 SmartOpenCV 提供的 CameraPreview 或 Camera2Preview。

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <!-- 原生 OpenCV 写法 (注释掉) -->
    <!--<org.opencv.android.JavaCameraView-->
    <!--android:id="@+id/fd_activity_surface_view"-->
    <!--android:layout_width="match_parent"-->
    <!--android:layout_height="match_parent" />-->

    <!-- SmartOpenCV 写法 (直接替换) -->
    <tech.huqi.smartopencv.core.preview.CameraPreview
        android:id="@+id/fd_activity_surface_view"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
</LinearLayout>

2. Java/Kotlin 代码逻辑

在 Activity 或 Fragment 中，原有的 OpenCV 初始化逻辑（如 findViewById 和设置监听器）无需任何改动即可正常运行。SmartOpenCV 会自动处理以下增强功能：

• 自动适配横竖屏旋转。
• 自动计算最佳预览尺寸，消除黑边，实现全屏显示。
• 自动识别前后摄像头及 USB 摄像头。

3. (可选) 高级配置

如果您需要自定义预览策略（如强制横屏、自定义帧大小算法、开启 FPS 显示等），可通过 Fluent API 进行配置：

SmartOpenCV.getInstance().init(mOpenCvCameraView, new CameraConfiguration.Builder()
    .debug(true)                // 开启调试日志
    .frontCamera(true)          // 使用前置摄像头
    .landscape(false)           // 强制竖屏 (false) 或横屏 (true)
    .enableFpsMeter(true)       // 显示 FPS
    .usbCamera(false)           // 若连接 USB 摄像头设为 true
    .maxFrameSize(400, 300)     // 限制最大预览分辨率
    .cvCameraViewListener(this) // 绑定 OpenCV 回调监听器
    // .previewSizeCalculator(...) // 可选：自定义尺寸计算策略
    // .drawStrategy(...)          // 可选：自定义绘制策略
    .build());

完成上述步骤后，运行项目即可体验无黑边、自适应方向的增强版 OpenCV 预览效果。