更新记录

1.1.0（2026-08-28）

新增 8 个图像处理 API（四端统一，句柄模型不变，失败返回 -1）：

  • 形态学：morphErode（腐蚀）/ morphDilate（膨胀）/ morphologyEx（开、闭、梯度、顶帽、黑帽）
  • 滤波与阈值：adaptiveThreshold（自适应二值化，光照不均场景）、medianBlur（中值去椒盐噪声）、bilateralFilter（双边保边平滑）
  • 增强：equalizeHist（直方图均衡化）
  • 几何：flipRotate（水平/垂直翻转，逆时针旋转 90/180/270）

全部支持非灰度输入自动转灰度（bilateralFilter 除外，其按原色彩空间处理）；ksize 自动修正为奇数。

1.0.0（2026-08-27）

首个公开版本。

核心能力（15 个 API，四端统一）

  • 图像基础处理：loadImage / releaseImage / resize / cvtGray / cvtHsv / threshold / gaussianBlur / drawRect / toBase64
  • 颜色检测：detectColorRange（HSV 范围过滤，返回命中像素数/占比/外接矩形）
  • 边缘检测：canny
  • 轮廓与形状识别：findContours（面积/外接矩形/顶点数/形状分类 circle·rectangle·triangle·quad·other）
  • 模板匹配：matchTemplate（TM_CCOEFF_NORMED + NMS，Top N 位置与分数）
  • 特征点匹配：orbMatch（ORB + BFMatcher(HAMMING) + 0.75 比率测试）

平台支持

平台 引擎 说明
App-Android OpenCV 4.8.0 官方 classes.jar + 原生 so 重打包 aar 内置（4 ABI），兼容 Android 14+（bionic __sfp_handle_exceptions 移除问题已规避）
App-iOS OpenCV 4.8.0 pod OpenCV 4.8.0 + 预编译 ObjC++ 桥接库（内置模拟器版，真机需 device 模式重编，见 docs/IOS.md）
鸿蒙 HarmonyOS OpenCV 4.8.0 OHOS 交叉编译 libopencv_bridge.so（NAPI 桥，句柄制零拷贝架构），arm64-v8a + x86_64 双 ABI
H5 (web) opencv-wasm 4.3.0 wasm 内联 + 异步编译改造

工程质量

  • 四端算法完全一致（同一 OpenCV 4.8.0），跨端契约统一（错误码/空值结构/参数语义）
  • 句柄制架构：像素常驻 native/wasm 内存，跨语言调用零像素拷贝（Android/iOS/鸿蒙/H5 同构）
  • 健壮性：非法输入全兜底（彩色自动转灰/尺寸校验/颜色回退）、异常不穿透边界、无已知内存泄漏
  • 经 7 轮代码审查，累计修复 35+ 项（功能/内存/跨端一致性/边界条件）
  • 所有图像处理均在本地完成，不上传任何数据、不新增权限

平台兼容性

uni-app(3.8.2)

Vue2 Vue3 Chrome Chrome插件版本 Safari Safari插件版本 app-vue app-vue插件版本 app-nvue app-nvue插件版本 Android Android插件版本 iOS iOS插件版本 鸿蒙 鸿蒙插件版本
- √ √ 1.0.0 √ 1.0.0 √ 1.0.0 √ 1.0.0 5.0 1.0.0 12 1.0.0 12 1.0.0
微信小程序 支付宝小程序 抖音小程序 百度小程序 快手小程序 京东小程序 鸿蒙元服务 QQ小程序 飞书小程序 小红书小程序 快应用-华为 快应用-联盟
× × × × × × - × × × × ×

uni-app x(4.61)

Chrome Chrome插件版本 Safari Safari插件版本 Android Android插件版本 iOS iOS插件版本 鸿蒙 鸿蒙插件版本 微信小程序
√ 1.0.0 √ 1.0.0 5.0 1.0.0 12 1.0.0 12 1.0.0 ×

OpenCV 图像识别 - uni-app 跨端图像处理插件

基于 OpenCV 4.8.0（H5 为 opencv-wasm 4.3.0）的 uni-app UTS 插件，句柄式图像处理管线。同一套 API 覆盖 H5 / App-Android / App-iOS / 鸿蒙，全端结果一致。

✨ 特性

  • 🖼️ 基础处理：灰度、HSV 转换、二值化、高斯模糊、缩放、Canny 边缘
  • 🎨 颜色检测：HSV 范围过滤，返回命中像素数、占比、外接矩形
  • 🔷 轮廓与形状识别：面积、外接矩形、顶点数、形状分类（circle/rectangle/triangle/quad/other）
  • 🔍 模板匹配：TM_CCOEFF_NORMED + NMS，返回 Top N 位置与分数
  • 🧩 特征点匹配：ORB 提取 + BFMatcher(HAMMING) + 0.75 比率测试
  • 📱 原生引擎：Android / iOS / 鸿蒙均基于 OpenCV 4.8.0 原生实现（H5 走 opencv.js WASM）
  • 🏗️ 句柄模型：loadImage 返回句柄，链式处理不拷贝原图，用完必须 releaseImage
  • 🔒 本地计算：所有图像处理均在设备本地完成，不上传任何数据

📦 安装

插件市场搜索「OpenCV 图像识别」或直接导入 uni_modules/axen-opencv-image。

本插件已在 Android 模拟器（API 37）/ iOS 模拟器（iPhone）/ 鸿蒙模拟器（arm64）完成接入验证与全功能自测；如有复杂接入场景，可通过插件市场作者联系方式咨询。

🚀 快速开始

import {
  initEngine, loadImage, releaseImage,
  cvtGray, threshold, cvtHsv, gaussianBlur, resize, canny,
  detectColorRange, findContours, matchTemplate, orbMatch,
  drawRect, toBase64
} from '@/uni_modules/axen-opencv-image'

// 1. 初始化（App 端加载 OpenCV 原生库；H5 端等待 wasm 异步编译完成）
await initEngine()

// 2. 加载图片，得到句柄
const img = await loadImage('/storage/emulated/0/xxx.png')   // App: 本地文件绝对路径
// const img = await loadImage('https://xxx/1.png')          // H5: URL / blob / data URL

// 3. 基础处理：灰度 -> 二值化
const gray = cvtGray(img)
const binary = threshold(gray, 127, 255)

// 4. 颜色检测（输入 HSV 图，范围为 OpenCV 约定 H:0-180, S:0-255, V:0-255）
const hsv = cvtHsv(img)
const red = detectColorRange(hsv, 0, 100, 100, 10, 255, 255)

// 5. 轮廓/形状识别（输入二值图）
const contours = JSON.parse(findContours(binary))   // [{ area, x, y, width, height, shape, points }]

// 6. 模板匹配（templateId 为模板图句柄，需先 loadImage 模板图）
const templateId = await loadImage('/path/to/template.png')
const matches = JSON.parse(matchTemplate(img, templateId, 3))   // [{ x, y, width, height, score }]

// 7. 特征点匹配（imgB 为另一张图的句柄）
const imgB = await loadImage('/path/to/another.png')
const orb = orbMatch(img, imgB)   // { keypoints1, keypoints2, matches, goodMatches }

// 8. 绘制结果并导出 base64 展示
drawRect(img, matches[0].x, matches[0].y, matches[0].width, matches[0].height, '#00ff00', 3)
const b64 = await toBase64(img)

// 9. 释放句柄（所有中间结果都要释放）
releaseImage(img); releaseImage(gray); releaseImage(binary); releaseImage(hsv); releaseImage(templateId); releaseImage(imgB)

句柄模型：每个处理函数返回新句柄，原句柄不受影响；用完必须 releaseImage 释放，否则内存泄漏（H5 端是 WASM 线性内存，泄漏会导致可分配内存耗尽）。

📖 API 文档

函数 返回 说明
initEngine() Promise<OcvInitResult> 初始化，返回 OpenCV 版本
loadImage(source) Promise<number> 加载图片返回句柄；失败返回 -1
releaseImage(id) void 释放句柄
resize(id, w, h) number 缩放（w/h 须为正数，否则返回 -1）
cvtGray(id) / cvtHsv(id) number 通道转换
threshold(id, thresh, maxval) number 二值化（THRESH_BINARY）；非灰度输入自动转灰度
gaussianBlur(id, ksize) number 高斯模糊（ksize 自动取奇数）
canny(id, low, high) number Canny 边缘；非灰度输入自动转灰度
detectColorRange(id, hMin, sMin, vMin, hMax, sMax, vMax) OcvColorRangeResult HSV 范围检测（H:0-180, S/V:0-255）
findContours(id) string 轮廓与形状（JSON 字符串，JSON.parse 后为 OcvContour[]）
matchTemplate(id, templateId, topN) string 模板匹配 TopN（JSON 字符串，OcvMatch[]）
orbMatch(id1, id2) OcvFeatureMatchResult ORB 特征匹配
drawRect(id, x, y, w, h, color, thickness) number 在原句柄上画框（颜色 #rrggbb）
toBase64(id) Promise<string> PNG base64（无 data: 前缀）
morphErode(id, kernelSize) / morphDilate(id, shapeSize) number 腐蚀 / 膨胀
morphologyEx(id, morphType, ksize) number 形态学：open / close / gradient / tophat / blackhat
adaptiveThreshold(id, method, blockSize, c) number 自适应二值化（mean / gaussian）
medianBlur(id, ksize) number 中值滤波
bilateralFilter(id, d, sigmaColor, sigmaSpace) number 双边滤波（保边平滑；RGBA 输入自动转 RGB 处理）
equalizeHist(id) number 直方图均衡化
flipRotate(id, mode) number flipH / flipV / rotate90 / rotate180 / rotate270

返回类型定义见 utssdk/interface.uts；App 端 findContours / matchTemplate 返回 JSON 字符串（原生数组桥接字段丢失问题，跨端统一字符串传递 + JSON.parse）。

🌐 平台支持

平台 引擎 支持度
H5 (web) opencv.js（opencv-wasm，wasm 内联 base64 + 异步编译改造） 全部能力（发行包将增加约 9.7MB）
App-Android OpenCV 4.8.0（官方 classes.jar + 原生 so 重打包 aar，内置 4 ABI） 全部能力
App-iOS OpenCV 4.8.0（pod 合并静态库 + 预编译 ObjC++ 桥接库，见 docs/IOS.md） 全部能力（需先编译桥接库）
鸿蒙 OpenCV 4.8.0（OHOS 交叉编译，NAPI 桥 libopencv_bridge.so，全部处理原生实现） 全部能力
小程序 不支持——opencv wasm 9.2MB 远超小程序主包 2MB 限制；逻辑层无标准 Web API，emscripten 运行时需深度改造。如有刚需可基于裁剪版 wasm 定制基础处理子集 -

🗓️ 路线图（待支持能力）

当前 23 个 API（15 基础 + 8 个 1.1.0 新增）覆盖了经典图像处理与特征匹配的常用子集。以下按规划优先级列出待支持能力，全部基于 OpenCV 4.8.0 原生实现（各端引擎已就位，扩展只需新增原生函数 + API 薄层）：

近期规划（原生 API 现成，扩展成本低）

  • 阈值全家桶：Otsu 自动阈值 / 三角法
  • 霍夫变换：直线检测 / 圆检测
  • 轮廓进阶：凸包 / 多边形逼近点集 / 最小外接圆 / 旋转矩形 / 层级树
  • 颜色空间扩展：LAB / XYZ / YCrCb / 灰度反变换
  • 几何变换：仿射 / 透视变换（getPerspectiveTransform / warpPerspective）
  • 直方图：反向投影（均衡化已支持）
  • 连通域分析 / 距离变换
  • 图像金字塔：上采样 / 下采样
  • 导向滤波

中期规划（需引入模型/级联资源，注意包体）

  • 人脸检测（Haar 级联或 YuNet ONNX）
  • SIFT / AKAZE 特征 + FLANN 匹配 + 单应矩阵（findHomography）+ 透视校正与拼接
  • 二维码 / 条码检测（QRCodeDetector）
  • DNN 推理模块（ONNX：分类 / 检测 / 分割，模型由宿主下发）

远期规划

  • 光流（稀疏 / 稠密）与背景建模（MOG2/KNN）
  • 视频流处理管线（各端相机帧回调接入）
  • GPU 加速（OpenCL / Metal / 鸿蒙 NAPI 侧加速）

需求优先级欢迎通过插件市场联系方式反馈，将按热度排期。

⚠️ 鸿蒙 HarmonyOS 说明

  • 鸿蒙实现位于 utssdk/app-harmony/：index.uts（UTS 入口）+ OpenCVBridge.ets（混编 ArkTS，通过 NAPI import opencvNative from 'libopencv_bridge.so' 调用原生）+ 内置原生库。
  • 全原生实现：基础处理（灰度/HSV/二值化/模糊/缩放/颜色检测/绘制）与高级能力（Canny/轮廓/模板/ORB）均走 NAPI 原生 OpenCV（Uint8Array 通道），与 Android/iOS 算法结果一致；仅图片解码（@ohos.multimedia.image）与 PNG 编码（ImagePacker）走系统 API。
  • .so 打包方式：HAR 不支持携带 .so，需同步将 libopencv_bridge.so / libc++_shared.so 放入项目 harmony-configs/entry/libs/<abi>/（HBuilderX 会覆盖到生成的鸿蒙工程，打包进对应 libs/<abi>/）。插件目录 utssdk/app-harmony/libs/ 内已附带两个 ABI 的库，直接拷贝即可。
  • 双 ABI：arm64-v8a 用于真机/模拟器，x86_64 用于 x86 模拟器；HarmonyOS NEXT 仅 64 位，无需 32 位 ABI。

  • 原生库重建（仅插件维护者）：源码与脚本在仓库 native/harmony/：

    cd native/harmony
./build-so.sh            # arm64-v8a（默认）
./build-so.sh x86_64     # x86_64

    前置：OpenCV 4.8 源码 /tmp/opencv-4.8.0/，交叉编译静态库于 /tmp/opencv-ohos-build（arm64）与 /tmp/opencv-ohos-x64-build（x86_64），OpenCV cmake 参数：

    cmake -DCMAKE_TOOLCHAIN_FILE=$OHOS_SDK/native/build/cmake/ohos.toolchain.cmake \
    -DOHOS_ARCH=<arm64-v8a|x86_64> -DBUILD_SHARED_LIBS=OFF \
    -DBUILD_LIST=core,imgproc,flann,features2d,calib3d /tmp/opencv-4.8.0

    链接使用 -lace_napi（libace_napi.z.so，NAPI 运行时符号）；产物同步到插件 utssdk/app-harmony/libs/<abi>/ 与项目 harmony-configs/entry/libs/<abi>/。

  • 鸿蒙运行需 uni-app x 工程（HBuilderX 4.61+），并处理运行时 EntryAbility（不依赖 HBuilderX 调试会话），参考仓库 harmony-configs/entry/src/main/ets/entryability/EntryAbility.ets。

⚠️ iOS 说明

  • iOS 原生实现位于 utssdk/app-ios/，依赖 Libs/OpenCVBridge/libOpenCVBridge.a（OpenCV 4.8.0 合并静态库 + ObjC++ 桥）与 ios-bridge/ 头文件。
  • 内置桥接库为模拟器版（arm64 + x86_64 双 slice，约 200MB，OpenCV 已静态合并）：可直接用于 iOS 模拟器联调；真机打包前需用 build-bridge.sh（默认 device 模式）重新编译 arm64 版并替换，否则真机链接失败。
  • 首次编译前需执行 build-bridge.sh 生成桥接库（详见 docs/IOS.md）。OpenCV 4.8.0 已静态合并进桥接库，无需 pod。
  • 桥接采用 NSNumber + NS_SWIFT_NAME 无标签签名；findContours/matchTemplate 返回 JSON 字符串（iOS 类型化对象数组桥接字段丢失问题）。

⚠️ Android 说明

  • 原生实现位于 utssdk/app-android/：OpenCVNative.kt（Kotlin 混编）+ config.json + index.uts。
  • 依赖原生三方库，真机运行需自定义调试基座（HBuilderX: 运行 → 运行到手机或模拟器 → 制作自定义调试基座）。
  • OpenCV 4.8.0 官方 jar/so 重打包为 aar 随插件内置，无需额外配置（旧版 QuickBird 4.5.3 aar 在 Android 14+ bionic 存在 __sfp_handle_exceptions 兼容问题，已升级规避）。

🔐 隐私与安全

本插件所有图像处理均在设备本地完成，不主动采集 IDFA、定位、相机、麦克风、相册、通讯录信息，也不上传任何数据。处理图片由宿主业务方选择传入；读取相册/拍照需宿主自行调用 uni.chooseImage 申请用户授权，插件不新增权限。

📄 许可证

插件引擎基于 OpenCV（Apache License 2.0，含原始 OpenCV 与 opencv.js 组件），许可见 THIRD_PARTY_LICENSES.md；插件本体授权以插件市场页面/购买协议为准。

隐私、权限声明

1. 本插件需要申请的系统权限列表：

插件不新增权限；读取图片由宿主应用通过 uni.chooseImage 授权完成。

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明：

本插件所有图像处理均在本地设备完成，不上传任何数据。

3. 本插件是否包含广告，如包含需详细说明广告表达方式、展示频率：

无

评论列表 撰写评论 向官方投诉

暂无用户评论。