一张拍歪的纸怎么找边、透视怎么用一次单应抹平、3.4 MB 像素怎么从 Kotlin/Native 递到 ArkTS 而不走 JSON——这篇文章用一个跑在鸿蒙上的 KMP 工程,把这三个问题一次讲透。

仓库地址:https://atomgit.com/oh-tpc/kmp-ohos-docscan
版本地址:https://atomgit.com/CPF-KMP-CMP/compose-multiplatform-core/tree/main-1.9.2-OH
三方库框架:https://atomgit.com/CPF-KMP-CMP

0. 环境与实测设备

项版本/型号
DevEco Studio26.0.0.821(HarmonyOS SDK 26.0.0 Release / API 26)
Kotlin / Kotlin/Native2.2.21-1.0.0(目标 ohosArm64)
Gradle / JDK8.14.3(wrapper)/ 21.0.12(Homebrew;DevEco 自带的 JBR 是 25.0.2,跑不了本工程的 Gradle)
鸿蒙 SDK7.0.0(API 26,SDK 版本 26.0.0.105 Release)
文档扫描模块1.0.0(本仓库,com.ohos.ocr:ocr,jvm + ohosArm64 两个变体)
原生产物libohos_ocr.so 1.11 MiB;entry-default-signed.hap 2.56 MB
测试26 项 JVM 用例(KMP 24,其中 6 项是上一版 OCR 模型的用例;示例门面 2),0 失败;端侧 6 项自检
实测设备HarmonyOS PC(MateBook Pro S,2in1,HarmonyOS 7.0.0.111)

1. 一张拍歪的纸,把 OCR 打回了原形

上一篇文章里,我把 Core Vision Kit 的端侧 OCR 接进了这个 KMP 库:Kotlin/Native 编出 libohos_ocr.so,ArkTS 经 N-API 调进来,识别结果按 Block/Line 回来。那一步证明的是"字认得出、且不出设备"。

拿它干活时,第一个卡住的环节是输入。小票、合同、会议讲义,没有一张是端端正正拍的:纸是斜的、四角是梯形的、上半页在灯下、下半页在阴影里。系统 OCR 会把字按行读出来,可用户要的是"一页纸"——一个矩形、摆正、能导出、能发出去。拿一个梯形去识别,行框跟着斜;把结果硬裁成矩形,边角又切掉两行字。

扫描类 App 的第一段流水线干的就是这件事:找纸边 → 透视矫正 → 增强输出。这三步没有一步需要模型,全是像素和几何:Otsu 阈值、连通域、单应矩阵、双线性采样、直方图拉伸。它恰好又是最该放进 KMP 的那类代码——纯函数、只接收 ByteArray 和尺寸、在 JVM 上能写像素级断言、在设备上编成 ohosArm64 后跑同一份逻辑。

所以这一版的边界很清楚:库负责把照片变成一张矩形,页面只负责选图、解码、显示和保存。具体拆成三件事,正好对应流水线上的三个难点:

  • 纸边怎么在几毫秒里找对(360 px 上的 Otsu + 四极值角点);
  • 透视怎么用一次单应抹平(8×8 消元 + 反向采样);
  • 3.4 MB 像素怎么过语言边界(C ABI + N-API,JSON 只带数字)。

2. 效果展示

先看效果。第一张是手机上的实拍:一页新闻稿被随手拍下来,纸是歪的,四边都不与画面平行,露出来的一圈深色桌面宽窄不一。

在这里插入图片描述

页面从上到下:文档扫描 标题旁一枚 端侧 徽章,副标题直说 自动找边 · 透视矫正 · 增强输出,全部在设备本地完成;两个按钮,选择图片 和 示例图。拍摄原图 卡片右上角标着 1080×1151,里面那张纸是斜的,纸面还带着拍摄时的光线不均。扫描结果 卡片右上角是 已定位纸张 · 置信度 100%,下面是同一页纸:英伟达那篇 CEO 交接新闻的标题、日期、三条要点、六段正文全部水平,梯形没了,纸面填满结果图。这张手机截图来自较早一版页面——结果卡片里只有图,还没有下面那排滤镜和统计行;第二张 2in1 的截图是当前版本,两版之间页面只补了几个组件,找边和矫正的代码没动。

第二张是同一页面在 2in1 窗口里的样子,用的是内置示例图——深色桌面上斜放的一页纸,右下角画了一个红圈:

窗口标题栏是 文档扫描,扫描结果 置信度 73%、结果 1056×797;下面一排滤镜 原图 / 增强 / 灰度 / 黑白,增强 选中;最后一行是这一页的全部统计:输出 1056×797 · 找边 2ms · 矫正 105ms · 141KB。

同一套代码,为什么一张 100%、一张 73%?因为 confidence 是版面占比的映射,不是"算法有多确定":0.45 + paperRatio × 0.85,封顶 1.0。手机上那张纸几乎占满画面(≥ 64.7%),按公式算出来正好 100%;示例图里纸约占 32.6%,算出来 0.7267,页面显示 73%。它的作用是在回退时给页面一句可读的提示——检测不到纸边时,页面显示的是 未找到明显纸张边缘,已按整图矫正,而不是一个好看的百分比。不要把这个数字当成模型置信度。

两张截图隔着一个维度:一张是真实拍摄,一张是内置样例。示例图里那个红圈不是装饰,它是给矫正质量留的参照物——圆如果被拉成椭圆,透视就没算对。第 5.3 节那张黑白图里它还在,只是从红圈变成了黑圈。

3. 从一张照片到一页矩形:四步,零模型

写代码之前先把原理理清。整条链是四步确定性运算,没有模型、没有网络:

1600×1200 RGBA
  │  ① 灰度 + 缩到长边 360                O(工作像素)
  │  ② Otsu 阈值                          O(N + 256)
  │  ③ 最大亮连通域 → 四极值角点           O(工作像素)
  ▼
quad(四个角,原图坐标)
  │  ④ 8×8 高斯消元求单应                  O(1)
  │  ⑤ 逐像素反向采样 + 双线性             O(输出像素)
  ▼
1056×797 RGB
  │  ⑥ 滤镜:拉伸 / 灰度 / 自适应二值       O(输出像素)
  ▼
JPEG 141 KB

第一步,找边(①②③)。 缩到长边 360、Otsu 把纸和桌面分开、取最大亮连通域、用四个极值点当角。先缩到 360 是因为找边只需要知道"纸在哪儿",不需要"纸上写了什么":1600×1200 缩到 360×270 只剩 97,200 个像素,直方图、阈值、连通域都在这个尺度上跑,四个角点最后按比例映射回原图。检测耗时因此基本不受原图分辨率影响——12 MP 的照片和 1600×1200 都在 2 ms 这一档。缩放用的是最近邻、不做面积平均:找边只关心"哪里亮",最近邻不会改变亮暗分布的大势,还省掉一次逐像素浮点加权。角点定下来,输出尺寸也就跟着定了:宽高取四边形对边的最大长度(上/下宽取大、左/右高取大),再按 1800 px 长边封顶——不强制 A4,纸可能是小票、名片、书页,硬拉成 A4 会把内容压扁。

找边里还有两处选择值得单独说。用 Otsu 而不是固定阈值:白纸在照片里到底有多白,取决于环境光,暖光下 200 上下、冷光下 245,桌面可能是 40 也可能是 120;固定阈值(比如 128)在暖光下会把桌面判成纸。Otsu 在 256 桶直方图上找"类间方差最大"的切分点,不假设纸有多白;它的前提是双峰,纸占画面太小时直方图只有一个峰,阈值会漂,所以后面还有 paperRatio ≥ 0.08 和面积比 0.06 ~ 1.05 两道闸。用四极值而不是凸包:纸在照片里是一个凸四边形,对任意凸多边形,沿 (1,1)、(1,−1)、(−1,1)、(−1,−1) 四个方向取支撑点,拿到的正好是四个角——x+y 最小的是左上、最大的是右下,x−y 最大的是右上、最小的是左下。不需要凸包、不需要 Douglas-Peucker 简化,而且可以在 flood fill 的同一次遍历里顺手记下来,每个像素只多两次加法。边界也很清楚:纸转到 45° 附近,两个方向会命中同一个角,代码里 corners.distinct().size < 4 直接判失败、回退整图(第 6 节坑六细说)。

第二步,单应(④)。 四个角对四个角,8 个未知数、8 个方程,一次高斯消元解完。方向刻意定成输出 → 源:给采样器反查用的,不是给投影用的。

第三步,采样(⑤)。 对输出的每个像素,用单应反查它在原图里的坐标,再做双线性插值。为什么必须反向:正向投影会在输出上留下空洞和裂缝(源像素被拉稀、有的输出像素根本没被写到),反向采样保证每个输出像素恰好被赋值一次。这也是为什么 Perspective.fromQuad() 的第一个参数是输出矩形的四角。

第四步,滤镜(⑥)。 重采样出来的是"摆正的彩色照片",还没到"扫描件"。增强做 2%–98% 分位拉伸,灰度去色偏,黑白用局部均值做自适应阈值。四种滤镜共用同一个 quad,所以来回切换时纸边不会跳。

性能数据如下。1600×1200 的示例图:找边 2 ms,矫正 105 ms(1056×797,约 0.84 M 像素,合每像素 125 ns)。矫正的主要成本不是算术,是源图的随机访问——输出是顺序写,读源像素是散的,cache miss 决定了下限。黑白滤镜多一次可分离 box blur(横向、纵向各一遍前缀和,O(W·H),与半径无关),实测 125 ms、输出 77 KB。整条链没有一步需要每帧跑:找边只在新图进来时跑一次,矫正只在切滤镜时跑一次;它不占帧率,但那一次同步调用会占住 UI 线程一百毫秒(5.5 里说)。

还有一个容易误判的数字:同一份代码在 debug 版 so 上是 820 ms。那不是算法慢,是构建类型不对,第 6 节坑四细说。

4. 工程怎么搭:一个 KMP 模块,两层原生,一层页面

先看整体结构。算法在公共 KMP 模块里,原生桥和鸿蒙宿主退到 example/:

kmp-ohos-ocr/                                  # 仓库根:Gradle 工程 A
├─ ocr/                                        # 公共 KMP 模块(jvm + ohosArm64,运行时零三方依赖)
│  └─ src/commonMain/kotlin/com/ohos/docscan/
│     ├─ DocScanModels.kt                      # DocumentQuad / ScanFilter / Detection
│     ├─ DocScanDetector.kt                    # Otsu + 连通域 + 四极值角点
│     ├─ Perspective.kt                        # 8×8 单应求解与反向映射
│     ├─ DocScanRenderer.kt                    # 双线性重采样 + 四种滤镜
│     ├─ DocScanJson.kt                        # JSON 边界
│     └─ DocScanChecks.kt                      # 6 项端侧自检
├─ example/                                    # Gradle 工程 B(把 ocr 的 projectDir 指到 ../ocr)
│  ├─ shared/                                  # 门面 DocScanExamples + JVM 验收测试
│  ├─ nativeApp/                               # ohosArm64 动态库与 C ABI
│  │  └─ src/ohosArm64Main/kotlin/…/NativeBridge.kt    # @CName 导出
│  └─ ohosApp/                                 # DevEco Stage 工程(不参与 Gradle)
│     ├─ entry/src/main/cpp/                   # N-API 壳:napi_init.cpp + CMakeLists.txt
│     ├─ entry/src/main/ets/scan/              # DocScanBridge.ets / ImageCodec.ets
│     ├─ entry/src/main/ets/pages/Index.ets    # 扫描页面
│     └─ entry/src/main/resources/rawfile/     # sample_document.jpg(内置示例图)
├─ docs/screenshot-scan.png
└─ README.OpenHarmony_CN.md

在这里插入图片描述

这次设计最关键的决定有四个:

算法只在 commonMain。 explicitApi() 打开,所有公共类型显式可见;模块不依赖任何三方运行时,输入输出都是 ByteArray + Int。24 项 JVM 用例之所以能代表设备,是因为设备上跑的就是这同一个模块编出来的 KLIB,不是"参考实现"。

两个 Gradle 工程,而不是一个。 DevEco 的 ohosApp 不参与 Gradle;example 用 include("ocr") 再把 projectDir 指到 ../ocr,直接依赖公共模块。Gradle 和 hvigor 各跑各的,HAP 那边只需要一个 .so 和一个头文件,不需要把 Kotlin 塞进 DevEco 的构建图。

像素不走 JSON。 详见 5.4:3.37 MB 的 RGBA 如果 base64 是 4.5 MB 字符串,JSON.parse 一次就要几十毫秒,白白占用渲染预算。JSON 只过 8 个角点、两个尺寸、一个滤镜索引和几个统计量。

旧导出保留。 version script 里 8 个符号并列:4 个 Ocr*(上一版的识别接口)加 4 个 DocScan*。老的调用方不用改,新的扫描页也不需要另起一个 so。

桥的协议没有花活:C ABI 进 JSON、出 JSON,像素走缓冲区。下面这份是示例图(1600×1200)的检测载荷,四角、比例、置信度都是引擎的真实输出,elapsedMs 取设备上的 2 ms:

// DocScanDetect(rgba, length, width, height) → 找边
{ "ok": true, "quad": [251, 277, 1300, 157, 1393, 948, 344, 1068],
  "outWidth": 1056, "outHeight": 797, "paperRatio": 0.3255,
  "confidence": 0.7267, "fallback": false, "elapsedMs": 2,
  "sourceWidth": 1600, "sourceHeight": 1200 }

// DocScanRender(… 15 个 JS 参数 …) → 矫正,只回统计,像素写进调用方缓冲
{ "ok": true, "width": 1056, "height": 797, "filter": "增强", "elapsedMs": 105 }

对使用方来说,一次"扫描"就是一次 detect 加一次 render:

// example/ohosApp/entry/src/main/ets/pages/Index.ets(节选)
const detection: DetectionJson = detectDocument(this.pixels, this.imageWidth, this.imageHeight);
this.quad = detection.quad;
this.outWidth = detection.outWidth;
this.outHeight = detection.outHeight;
this.resultAspect = detection.outWidth / detection.outHeight;
this.status = detection.fallback
  ? '未找到明显纸张边缘,已按整图矫正'
  : `已定位纸张 · 置信度 ${(detection.confidence * 100).toFixed(0)}%`;

页面上那个 73% 是 toFixed(0) 的结果,JSON 里是完整的 0.7267…。精度留给展示层决定,桥上不做四舍五入——不然调用方想显示一位小数时就没数据了。

5. 把代码讲透

5.1 找边:360 像素上的 Otsu 与四个极值点

DocScanDetector.detect() 是个三十来行的入口,四件事按顺序做完:

// ocr/src/commonMain/kotlin/com/ohos/docscan/DocScanDetector.kt - detect()(节选)
val scale = min(1.0, WORK_LONG_SIDE / max(width, height))            // 360 / 1600
val workWidth  = max(MIN_WORK_SIDE, (width  * scale).roundToInt())   // 360
val workHeight = max(MIN_WORK_SIDE, (height * scale).roundToInt())   // 270
val gray = downsampleGray(rgba, width, height, workWidth, workHeight)
val threshold = otsuThreshold(gray)
val corner = largestBrightComponent(gray, workWidth, workHeight, threshold)

val paperRatio = if (corner == null) 0.0 else corner.area.toDouble() / (workWidth * workHeight)
val fallbackQuad = DocumentQuad.fullFrame(width, height)
if (corner == null || paperRatio < MIN_PAPER_RATIO) {                // 0.08
  return detection(fallbackQuad, width, height, paperRatio,
                   confidence = 0.0, fallback = true, started = started)
}

连通域那段有两个细节值得单独说明:显式栈,以及把四个极值顺手记在遍历里。

// 同文件 - largestBrightComponent()(节选,省略了变量声明与面积统计)
val visited = BooleanArray(gray.size)
val stack = IntArray(gray.size)                 // 显式栈:不依赖递归深度
for (start in gray.indices) {
  if (visited[start] || gray[start] <= threshold) continue
  var top = 0
  fun push(index: Int) {
    if (!visited[index] && gray[index] > threshold) {
      visited[index] = true
      stack[top++] = index
    }
  }
  push(start)
  while (top > 0) {
    val current = stack[--top]
    val x = current % width
    val y = current / width
    val sum = x.toLong() + y
    val diff = x.toLong() - y
    if (sum < minSum) { minSum = sum; minSumX = x; minSumY = y }
    if (sum > maxSum) { maxSum = sum; maxSumX = x; maxSumY = y }
    if (diff < minDiff) { minDiff = diff; minDiffX = x; minDiffY = y }
    if (diff > maxDiff) { maxDiff = diff; maxDiffX = x; maxDiffY = y }
    if (x > 0) push(current - 1)
    if (x + 1 < width) push(current + 1)
    if (y > 0) push(current - width)
    if (y + 1 < height) push(current + width)
  }
}

几个我调试时才意识到的点,写出来给后来人省时间:

用显式栈,不用递归。 stack = IntArray(gray.size) 看着浪费(360×270 时约 388 KB),但它一次性覆盖了最坏情况。一张占满画面的纸,亮连通域可能有十几万像素,递归深度就等于像素数——十万级的递归,不管在哪个运行时上都有栈溢出的风险。

像素中心对齐的那半个像素。 角点映射回原图用的是 (x + 0.5) * width / workWidth - 0.5,不是 x * width / workWidth。缩图时每个工作像素代表原图的一块,中心对齐后角点回代没有系统性偏移;直接乘比例会整体偏半个工作像素,1600/360 ≈ 4.4,就是 2.2 个原图像素的系统误差。视觉上看不出来,但四角会整体偏一两个像素,输出尺寸也跟着偏。

四极值给出的顺序看着对,仍然要再排一次。 四个方向按 minSum → maxDiff → maxSum → minDiff 取出来,本来就是顺时针的左上、右上、右下、左下;但这个类型也由 NAPI 传进来的 8 个整数构造、由测试里的乱序点构造,角点顺序不能依赖调用方保证。DocumentQuad.ordered() 用 atan2 按质心排序(保证不自交),再旋转到 x+y 最小的那个角当起点(保证左上角是第一个),最后看 signedArea:屏幕坐标 Y 向下,顺时针的四边形的鞋带面积为正,为负就翻转一次。

// DocScanModels.kt - ordered()(节选)
val sorted = points.sortedBy { atan2(it.y - centreY, it.x - centreX) }
val start = sorted.indices.minByOrNull { sorted[it].x + sorted[it].y } ?: 0
val rotated = List(4) { sorted[(start + it) % 4] }
val quad = DocumentQuad(rotated[0], rotated[1], rotated[2], rotated[3])
return if (quad.signedArea >= 0.0) {
  quad
} else {
  DocumentQuad(rotated[0], rotated[3], rotated[2], rotated[1])
}

置信度是个映射,不是概率。 (0.45 + paperRatio * 0.85).coerceAtMost(1.0),所以一张占满画面的纸必然是 100%,一张只占 32.6% 画面的纸约是 73%。它不做质量判断,只做"版面占比"的换算。真要靠它做取舍,得先接受这个定义。

自检里那条 12 px 的断言比"看起来对"可靠。 合成图 160×120、纸边 inset 20,检测出的左上角必须落在 12 px 以内,回退必须为 false,黑白输出必须只有 0 和 255。这些断言在页面上也跑一遍(DocScanChecks.run() 经 NAPI 调回 ArkTS),所以"装上去自检失败"和"装上去能跑"是两回事,一眼就能分开。

5.2 单应:8 个未知数、一次消元、方向反过来

四个点对给出 8 个方程,未知数是单应矩阵的 8 个自由系数(h8 固定为 1)。构造增广矩阵的代码只有 8 行:

// Perspective.kt - fromQuad()(节选)
val system = Array(8) { DoubleArray(9) }
for (index in 0 until 4) {
  val x = destination[index].x
  val y = destination[index].y
  val u = source[index].x
  val v = source[index].y
  system[index * 2]     = doubleArrayOf(x, y, 1.0, 0.0, 0.0, 0.0, -x * u, -y * u, u)
  system[index * 2 + 1] = doubleArrayOf(0.0, 0.0, 0.0, x, y, 1.0, -x * v, -y * v, v)
}
val solution = solve(system)     // 8×8 高斯-约当,部分选主元
return Perspective(doubleArrayOf(
  solution[0], solution[1], solution[2],
  solution[3], solution[4], solution[5],
  solution[6], solution[7], 1.0,
))

消元是"约当"而不是"回代":每个主元行归一化之后,把所有行(不只是下方)都消一遍,最后一列就是解:

// 同文件 - solve()(节选)
require(kotlin.math.abs(system[pivot][column]) > 1e-12) { "Document quad is degenerate" }
val divisor = system[column][column]
for (entry in column..size) system[column][entry] /= divisor
for (row in 0 until size) {
  if (row == column) continue
  val factor = system[row][column]
  for (entry in column..size) system[row][entry] -= factor * system[column][entry]
}

五个设计点:

方向:输出 → 源。 mapToSource 的名字已经把用途写死了。单应矩阵本身可逆,两个方向都能算;但采样器需要的是反查,所以构造时就把"输出矩形的四角"当 destination、“检测到的四角"当 source。方向写反不会崩,只会得到一张位置全错的图——这是最难靠肉眼发现的一类错误,因为"看起来像一张扫描件”。

// 同文件 - mapToSource()
public fun mapToSource(x: Double, y: Double): ImagePoint {
  val denominator = matrix[6] * x + matrix[7] * y + matrix[8]
  if (denominator == 0.0) return ImagePoint(0.0, 0.0)
  return ImagePoint(
    x = (matrix[0] * x + matrix[1] * y + matrix[2]) / denominator,
    y = (matrix[3] * x + matrix[4] * y + matrix[5]) / denominator,
  )
}

h8 固定为 1 是对的。 单应矩阵齐次,9 个系数差一个常数是同一个变换;固定一个系数后剩 8 个未知数,四个点对正好 8 个方程,直接解,不需要最小二乘。这也是为什么 coefficients() 返回的数组最后一位恒为 1。

部分选主元是必需的。 纸被拍成一条、四个角近似共线时,主元会趋近 0。1e-12 的闸把它变成一句明确的 Document quad is degenerate,而不是让后面每个像素都除以一个接近 0 的数、输出一屏 NaN——那种失败在设备上看起来是"花屏",最难查。

为什么不是 4×4 透视矩阵。 2D 平面到平面就是 3×3 单应;4×4 是 3D 投影,多出来的自由度对一张纸没有意义,方程组还更大。3D 图形管线里那套矩阵在这里用不上。

精度有断言。 mapsOutputCornersToSourceCorners 把四个输出角映射回源,与检测出的四角逐一比较,误差要求 < 1e-6 px;straightQuadBehavesLikeAUnitScale 再钉一条"矩形进、矩形出"的退化情形——200×100 的全画布四边形,输出中心必须映射回原点中心。

底部那行表格为什么是半截的?源图里那页纸的表格本来就画到了纸边之外——矫正只是把它照实搬过来,不是丢内容。这也正好说明示例图为什么用程序生成:每个像素的来历都能对上,出问题时分得清是"源图如此"还是"算法错了"。

5.3 重采样与滤镜:两次除法,四次加权

内层循环是全篇最热的一段代码。一个输出像素的成本是:两次除法拿到源坐标,一次夹取,四次加权求和,四次写入(RGB + A)。

// DocScanRenderer.kt - render() 内层循环(节选)
val denominator = h[6] * sx + h[7] * sy + h[8]
var u = 0.0
var v = 0.0
if (denominator != 0.0) {
  u = (h[0] * sx + h[1] * sy + h[2]) / denominator
  v = (h[3] * sx + h[4] * sy + h[5]) / denominator
}
if (u < 0.0) u = 0.0 else if (u > maxX) u = maxX    // 纸边映射到图外时夹住
if (v < 0.0) v = 0.0 else if (v > maxY) v = maxY

val x0 = u.toInt(); val y0 = v.toInt()
val x1 = if (x0 < width - 1) x0 + 1 else x0
val y1 = if (y0 < height - 1) y0 + 1 else y0
val fx = u - x0; val fy = v - y0
val w00 = (1 - fx) * (1 - fy); val w10 = fx * (1 - fy)
val w01 = (1 - fx) * fy;       val w11 = fx * fy
output[index] = ((rgba[i00].toInt() and 0xFF) * w00 + (rgba[i10].toInt() and 0xFF) * w10 +
  (rgba[i01].toInt() and 0xFF) * w01 + (rgba[i11].toInt() and 0xFF) * w11
  ).toInt().coerceIn(0, 255).toByte()

四个点:

顺序写、散乱读。 输出 index 是递增的,写是顺序的;源像素 i00..i11 由单应决定,跳着读。105 ms 里相当一部分是 cache miss。要再快,得把源图按 32×32 分块、按块遍历(牺牲输出顺序换源局部性),我没做——105 ms 已经够用,分块会把代码复杂度翻倍。

边缘 clamp 不能省。 单应把输出最外一列映射到源图 x=1600.3 时,不 clamp 的话 u.toInt() 就是 1600,越界;Kotlin 的 ByteArray 会直接抛 IndexOutOfBounds。clamp 到 1599 后取的是边缘像素,纸边不会出现黑边或异常色。

alpha 一律写 255。 后面 JPEG 编码和 PixelMap 都不需要 alpha 通道;固定成不透明,省掉一次分支,也避免"重采样把 alpha 也插值了"这种伪影。

每次 render 都新建输出数组。 render() 返回一个新 ByteArray,不接收调用方的缓冲。好处是签名干净、测试一行断言就能比大小;代价是最后多一次 memcpy(5.4 里说,亚毫秒级)。

滤镜是四种,都作用在重采样之后:

滤镜做法典型输出
原图只做重采样保留颜色、阴影和纸面的光
增强2%–98% 分位直方图拉伸纸更白、字更黑,阴影被压平
灰度0.299R + 0.587G + 0.114B去掉色偏,体积小
黑白box blur 局部均值 + 阈值纯 0/255,适合打印或再 OCR

增强的关键是那两个分位点,不是"乘以 1.2":取 2% 和 98% 的亮度做上下界,把这一段映射到 0…255,span.coerceAtLeast(8) 兜住纯色图(high − low ≈ 0 时按 8 算,避免除以 0 或放大噪点)。黑白的关键是阈值不是全局的:

// 同文件 - blackAndWhite()(节选)
val radius = max(6, min(width, height) / 24)        // 1056×797 → 33
val local = boxBlur(luma, width, height, radius)    // 前缀和,O(W·H)
for (pixel in luma.indices) {
  val paper = luma[pixel] > local[pixel] - 8        // 给纸面留 8 级容差
  val value = if (paper) 255.toByte() else 0.toByte()
  val index = pixel * 4
  rgba[index] = value
  rgba[index + 1] = value
  rgba[index + 2] = value
}

全局 Otsu 在"上半页亮、下半页阴影"的图上会失效:阴影里的白纸会被判成黑。box blur 给出每个像素的局部均值,luma > local − 8 判白。那个 −8 是容差:纸面比局部均值略暗一点(阴影、脏点)仍然算白,只有明显更暗的笔画才判黑;去掉它,阴影边缘会碎成一片黑点。

boxBlur 用前缀和实现:横一遍、竖一遍,每行/每列先累加,再两点相减除以窗口长度,O(W·H) 且与半径无关。朴素实现每个像素要 33²=1089 次乘加,在 0.84 M 像素上是 9 亿次,根本跑不进 100 ms。

这张 PNG 只有 12 KB,因为像素只有 0 和 255。自检里那条 rendered.all { it.toInt() == 0 || (it.toInt() and 0xFF) == 255 } 钉的就是这个性质。

5.4 桥:JSON 只带数字,像素走缓冲区

C ABI 的 DocScanRender 有 16 个参数:源缓冲 + 长度 + 宽高 + 8 个角点坐标 + 输出宽高 + 滤镜索引 + 目标缓冲。JS 这一侧只传 15 个——长度由 Uint8Array 自带,不用另传。看着长,但没有一个是对象、没有一个是字符串,跨语言边界上没有对象生命周期问题。

// example/nativeApp/src/ohosArm64Main/kotlin/com/ohos/ocr/example/NativeBridge.kt(节选)
@CName("DocScanRender")
public fun docScanRenderNative(
  rgba: CPointer<ByteVar>?, length: Int, width: Int, height: Int,
  x0: Int, y0: Int, x1: Int, y1: Int, x2: Int, y2: Int, x3: Int, y3: Int,
  outWidth: Int, outHeight: Int, filterIndex: Int,
  destination: CPointer<ByteVar>?,
): CPointer<ByteVar> = response {
  val source = rgba ?: error("Missing image buffer")
  val target = destination ?: error("Missing output buffer")
  val started = TimeSource.Monotonic.markNow()
  val quad = DocumentQuad.ordered(listOf(          // 再排一次序:不信任调用方
    ImagePoint(x0.toDouble(), y0.toDouble()), ImagePoint(x1.toDouble(), y1.toDouble()),
    ImagePoint(x2.toDouble(), y2.toDouble()), ImagePoint(x3.toDouble(), y3.toDouble()),
  ))
  val filter = ScanFilter.byIndex(filterIndex)
  val output = DocScanExamples.render(
    rgba = source.readBytes(length), width = width, height = height,
    quad = quad, outWidth = outWidth, outHeight = outHeight, filter = filter,
  )
  output.usePinned { pinned ->
    memcpy(target, pinned.addressOf(0), output.size.convert())
  }
  renderJson(outWidth, outHeight, filter, started.elapsedNow().inWholeMilliseconds)
}

NAPI 壳负责把 JS 的 Uint8Array 变成 uint8_t*,并在调用之前把能查的都查掉:

// example/ohosApp/entry/src/main/cpp/napi_init.cpp(节选)
uint8_t* destination = nullptr;
size_t destinationLength = 0;
if (!ReadBytes(env, args[14], destination, destinationLength)) {
  napi_throw_type_error(env, nullptr,
                        "docScanRender expects a non-empty Uint8Array destination");
  return nullptr;
}
const auto expected = static_cast<size_t>(numbers[10]) * static_cast<size_t>(numbers[11]) * 4;
if (destinationLength < expected) {
  napi_throw_range_error(env, nullptr,
                         "destination buffer is smaller than outWidth * outHeight * 4");
  return nullptr;
}

七个取舍:

JSON 里没有像素。 3.37 MB 的 RGBA 如果 base64,是 4.5 MB 的字符串;JS 侧要 decode 一次、JSON.parse 一次,光这两下耗时比 105 ms 的渲染还长。桥的协议只走 8 个角点、两个尺寸、一个滤镜索引和几个统计量。

返回的 char* 谁释放。 Kotlin 侧 nativeHeap.allocArray 分配、DocScanFree 释放;NAPI 壳 napi_create_string_utf8 复制成 JS 字符串后立刻 DocScanFree。ArkTS 拿到的永远是一份独立的字符串,不是指针——这条如果反过来,GC 一跑就是野指针。

出参缓冲由调用方分配。 destination 是 ArkTS 侧 new 出来的 Uint8Array,Native 只写。NAPI 先校验 destinationLength >= outWidth * outHeight * 4,不够就 napi_throw_range_error;页面每次 render 前 new 一块同尺寸的缓冲,尺寸固定,分配开销和 GC 压力都可预期。

"零拷贝"是相对的,这里不做夸大。 渲染内部还是会新建一个 ByteArray,最后 memcpy 一次 3.37 MB,亚毫秒级。真要省,就得把 destination 传进 Kotlin、用 usePinned 直接写;我没做——这点拷贝在 105 ms 里是噪声,而"返回新数组"让 JVM 测试可以一行断言输出尺寸。

参数校验全在壳里。 ReadNumber 拒绝负数和非有限值(NaN/Inf),ReadBytes 要求非空 Uint8Array,argc 不能少于 15,destination 不够大直接抛。任何一条不满足都是可捕获的 JS 异常,而不是 native crash。

导出面用 version script 收敛。 shared-library.map 里只列 8 个符号、local: * 兜底,链接参数带 --entry=0(这个 so 不是可执行文件)。产物 1.11 MiB,进 HAP 时还会被 DoNativeStrip 处理一遍。

耗时包含拷贝。 renderJson() 的 elapsedMs 是在 memcpy 之后取的,所以那 105 ms 里已经算进了这次拷贝。

5.5 ArkTS 侧:1600 px 解码、一帧重渲染、JPEG 落盘

页面状态极简:一份 pixels、一个 quad、一个滤镜索引。解码是最容易出事的一步:

// example/ohosApp/entry/src/main/ets/scan/ImageCodec.ets(节选)
const info = await source.getImageInfo();
const longest = Math.max(info.size.width, info.size.height);
const ratio = longest > MAX_DECODE_SIDE ? MAX_DECODE_SIDE / longest : 1;   // 1600
const options: image.DecodingOptions = {
  desiredSize: { width: Math.round(info.size.width * ratio),
                 height: Math.round(info.size.height * ratio) },
  desiredPixelFormat: image.PixelMapFormat.RGBA_8888,
  editable: true,
};
const pixelMap = await source.createPixelMap(options);
const pixelInfo = await pixelMap.getImageInfo();
const byteCount = pixelMap.getPixelBytesNumber();
const buffer = new ArrayBuffer(byteCount);
await pixelMap.readPixelsToBuffer(buffer);
if (byteCount !== pixelInfo.size.width * pixelInfo.size.height * 4) {
  throw new Error('不支持的像素跨距');
}

拿到紧凑 RGBA 之后,渲染是一段同步调用,编码是异步的:

// example/ohosApp/entry/src/main/ets/pages/Index.ets(节选)
const destination = new Uint8Array(this.outWidth * this.outHeight * 4);
const stats: RenderJson = renderDocument(
  this.pixels, this.imageWidth, this.imageHeight,
  this.quad, this.outWidth, this.outHeight, this.filter, destination,
);
const bytes = await writeJpeg(destination, this.outWidth, this.outHeight, path, 92);
this.info =
  `输出 ${this.outWidth}×${this.outHeight} · 找边 ${this.detectMs}ms · ` +
  `矫正 ${stats.elapsedMs}ms · ${(bytes / 1024).toFixed(0)}KB`;

几个不能省的细节:

为什么解码限 1600。 一张 12 MP 的照片直接解成 RGBA 是 48 MB;Kotlin/Native 侧再读一份、渲染再出 3.4 MB,峰值轻易上 100 MB。1600 长边 → 1600×1200×4 = 7.7 MB;找边只在 360 工作分辨率上跑,精度不受影响,输出又有 1800 封顶,不会因为输入变小而损失精度。

媒体库 URI 不能直接传给 ImageSource。 相册返回的是 file://media/Photo/...,要先用 fileIo.open(uri) 拿 fd,再 image.createImageSource(fd);ImageSource 和 PixelMap 都在 finally 里 release(),少一个就是一张图一份泄漏。

像素格式要显式要,收到还要验。 不少解码器的默认输出不是 RGBA(常见 NV12/YUV),即便传了 desiredPixelFormat 也可能被忽略;readPixelsToBuffer 拿到的布局和 Kotlin 侧的 RGBA 假设不一致,画面会花。解码后还校验 byteCount === w*h*4,对不上就抛"不支持的像素跨距",不拿一个"看起来能跑"的缓冲去冒险。

切滤镜只重渲染,不重新找边。 找边结果对同一张图是常量;selectFilter() 只改索引、重建 destination、再编码一次。四张滤镜图共用同一个 quad,来回切换不会看到纸边跳动。

那一百毫秒是同步的。 renderDocument() 是同步 NAPI 调用,UI 线程会被阻塞;切滤镜是低频动作,这点顿挫可以接受,所以没有为它引入 TaskPool/Worker。但如果要做"实时取景框选",这条必须先改——真到那一天,这也是整个页面唯一需要重构的地方。

自检在页面加载时跑一次。 aboutToAppear() 里 runSelfChecks() 过 NAPI 跑那 6 项(角点排序、单应回代、合成图找边、黑白纯 0/255、角点误差 < 12 px、无纸回退),底部一行 KMP 自检 6 项通过 · 检测与矫正均在端侧完成。它证明的是"so 真的加载了、跑的是对的代码",不是 UI 好看。

保存走两步。 JPEG 先写 cacheDir(每次切滤镜都是一个新文件名),点"保存 JPG"再 fileIo.copyFileSync 到 filesDir,页面下方显示完整路径。缓存不主动清理,因为它本来就可以被系统回收。

6. 踩坑与经验

以下是这次开发中实际遇到的坑,全部来自报错、构建日志和代码注释。

坑一:DevEco 的 JBR 25 让 Gradle 只回一个版本号。

FAILURE: Build failed with an exception.
* What went wrong:
25.0.2

整个错误正文就一个版本号。DevEco Studio 自带的 JBR 是 25.0.2,Kotlin 2.2.21 的 JavaVersion.parse 不认它,构建在解析工具链时就只回了这一个版本号。解决:JAVA_HOME 指到 JDK 21(我用 Homebrew 的 21.0.12)。看到错误信息"就一个版本号",先怀疑工具链,别去翻代码。

坑二:命令行工具链的 hvigor 不认 API 26。

00303168 Configuration Error
Error Message: SDK component missing.

* Try the following:
  > Please verify the integrity of your SDK.

一开始用的是 命令行工具里的 hvigor,它在加载 SDK 组件时直接退出,连"哪个组件缺"都不说。换成 DevEco 自带的 hvigor 之后,又撞了一次路径没对齐:

Warning: Cannot find the file under the specified path
旧 SDK 的 hmos.toolchain.cmake

DEVECO_SDK_HOME 还指着旧 SDK,CMake 工具链找不到。改成 <DevEco SDK 路径> 后,同一条 assembleHap 才干净通过。同一个工程、同一条命令,工具链换了就过——这种时候别改工程,先改 PATH 和 SDK 环境变量。

坑三:从 OCR 页换成扫描页,ArkTS 先给了两处报错。

1 ERROR: 10605008 ArkTS Compiler Error
Error Message: Use explicit types instead of "any", "unknown" (arkts-no-any-unknown)
  At File: .../entry/src/main/ets/pages/Index.ets:85:20

2 ERROR: 10505001 ArkTS Compiler Error
Error Message: Cannot find module '@hms.ai.ocr.textRecognition' or its
corresponding type declarations.
  At File: .../entry/src/main/ets/pages/Index.ets:4:33

扫描页根本不需要 Core Vision Kit——@hms.ai.ocr.textRecognition 是上一版 OCR 页面留下的 import,没删;同一个文件里还有一处类型被推成了 any。清掉旧 import、给那一处补上显式类型后编译通过。换示例页的第一件事是清 import;ArkTS 的严格模式对"上一版的残留"零容忍。

坑四:debug 版 so 慢 8 倍,差点去优化 box blur。

第一次在设备上量到的是 820 ms 矫正。我当时正对着 boxBlur 的复杂度发呆,怀疑 33 px 半径的局部均值太贵。实际原因是 prepareOhos 挂的还是 linkDebugSharedOhosArm64——Kotlin/Native 的 debug 构建没有优化,同样的输入 820 ms;换成 linkReleaseSharedOhosArm64(现在 prepareOhos 的默认依赖)就是 105 ms。Kotlin/Native 的性能数字只能来自 release so;debug 的数字连趋势都不可信。

坑五:解码器可能不给你 RGBA,也不给你紧凑缓冲。

代码里有两句错误文本是有实际作用的:

不支持的像素格式 ${pixelInfo.pixelFormat}
不支持的像素跨距

第一句在解码结果的 pixelFormat 不是 RGBA_8888 时抛;第二句在 getPixelBytesNumber() !== width * height * 4 时抛。两者都来自"声明了 desiredPixelFormat 但解码器没照做"的现实——个别机型、个别相册图片会忽略 desiredSize,或者返回带行对齐的 stride。少了这两道检查,等于假设系统会给出正确的缓冲区形状。跨语言边界上的缓冲区,尺寸必须自己校验;宁可抛一个带原因的错,也不要让 Kotlin 按紧凑布局去读一块带 padding 的内存。

坑六:纸转到 45°,四个极值点会撞在一起。

四极值找角有一个几何边界:x+y 与 x−y 两组支撑方向,在纸转到 45° 附近时会各自命中同一个角,四个极值退化成两个(甚至更少)。代码的处理是显式判失败:

if (corners.distinct().size < 4) return null
val quad = DocumentQuad.ordered(corners)
val smallestSide = quad.points.indices.minOf { index ->
  quad.points[index].distanceTo(quad.points[(index + 1) % 4])
}
return if (smallestSide > CORNER_EPSILON) quad else null   // 6 px

返回 null 之后,detect() 走 fallback:整图 inset 2% 当四边形,页面文案变成"未找到明显纸张边缘,已按整图矫正"。这是一次取舍:一个错的四边形会让矫正结果缺一个角,用户看到的是一张残图;回退整图至少内容是全的,只是没摆正。白桌面 + 强反光也是同一套闸:Otsu 分不开纸和桌面时,亮连通域要么是一块反光斑(被 paperRatio 和面积比闸挡下),要么干脆是整张图(本身就是一个"整图四边形",结果等于没裁)——两种情况都不会给出一个错的四角。

找边还有一个更常见的偏差:纸边阴影被算成背景,亮区比纸面小一圈,扫描件边缘会少几个像素。仓库说明的 FAQ 给的修法是把 quad 沿质心外扩 0.3%–0.5%;这一版没有默认打开,因为"多切一点"和"多留一圈桌面"是两个不同的错误,该由调用方决定。

7. 现在怎么用:从 Maven 坐标到一次 105 ms 的矫正

经过上面的整理,这个工程是三层交付(Apache-2.0):

  • KMP 模块(com.ohos.ocr:ocr):找边、单应、重采样、滤镜,jvm 与 ohosArm64 两个变体,运行时零三方依赖;
  • 原生桥(example/nativeApp):8 个 @CName 导出 + version script,编成 libohos_ocr.so;
  • ArkTS 页面(example/ohosApp):选图、解码、滤镜、导出,可以整包复制进别的 DevEco 工程。

接入 KMP 工程,先发布到本地 Maven 再引用:

JAVA_HOME=/path/to/jdk21 ./gradlew :ocr:publishToMavenLocal
// commonMain
implementation("com.ohos.ocr:ocr:1.0.0")

产物是 ocr(KMP 元数据)+ ocr-jvm + ocr-ohosarm64 三个坐标,Gradle 按目标自动选变体;消费端记得把 mavenLocal() 加进 repositories。这一版没有往公共仓库发——本机 本地 Maven 仓库 里能查到这三个变体,上面的坐标直接可用。

要接原生桥,把 example/nativeApp 的 DocScan* 四个导出和 napi_init.cpp 里那段 15 参数壳抄过去即可;嫌麻烦就把 example/ohosApp 整个复制走,签名换成本机的。纯 ArkTS 宿主的原生产物只需要两个文件:entry/libs/arm64-v8a/libohos_ocr.so 和 entry/src/main/cpp/include/libohos_ocr_api.h,prepareOhos 会一起递过去。

# 1) 24 项 KMP 用例 + 2 项示例门面用例(在仓库根执行)
JAVA_HOME=/path/to/jdk21 ./gradlew :ocr:jvmTest
(cd example && JAVA_HOME=/path/to/jdk21 ../gradlew :shared:jvmTest)

# 2) release so + 头文件 → example/ohosApp/entry(在仓库根执行)
(cd example && JAVA_HOME=/path/to/jdk21 ../gradlew :nativeApp:prepareOhos)

# 3) HAP(必须用 DevEco 自带 hvigor,见坑二)
cd example/ohosApp
export PATH="<DevEco Node 目录>:<DevEco ohpm 目录>:$PATH"
export DEVECO_SDK_HOME="<DevEco SDK 路径>"
ohpm install --all
hvigorw \
  --mode module -p module=entry@default -p product=default -p buildMode=debug \
  assembleHap --no-daemon

hdc install -r entry/build/default/outputs/default/entry-default-signed.hap
hdc shell aa start -a EntryAbility -b com.ohos.ocr.sample

宿主检查清单就四条:

  1. 送进 detectDocument 的必须是紧凑 RGBA(byteCount === w*h*4),尺寸与缓冲长度一致;
  2. 先 detect 再 render,quad 的 8 个整数别自己重排——Native 侧会再 ordered() 一次;
  3. destination 用 Uint8Array(outWidth * outHeight * 4) 预分配,切滤镜时尺寸不变;
  4. detection.fallback 为 true 时显示"已按整图矫正",不要显示置信度。

能力边界、构建步骤和 FAQ 都写在OpenHarmony 接入说明里,本文只挑了与这版扫描链路直接相关的部分。

当前版本在 DevEco Studio 26.0.0.821 / HarmonyOS API 26 上验证:26 项 JVM 用例全绿(含真实感示例图的找边回归与四种滤镜的像素断言),assembleHap 产出 2.56 MB 签名 HAP,启动后页面自检 6 项通过;手机实拍 1080×1151 的新闻页,置信度 100%,四边拉直;内置示例图 1600×1200 输出 1056×797,找边 2 ms、矫正 105 ms、JPG 141 KB,黑白滤镜 125 ms、77 KB;debug so 的 820 ms 已经不在交付路径上。

下一步的计划也记在这里:一是手动拖角——现在只有自动找边,四个角应该能拖、拖完实时重渲染,这会把 105 ms 的同步渲染移进 TaskPool,5.5 里那条同步调用的限制也必须处理;二是多页扫描 + PDF 导出,现在一次只处理一张;三是把纸张外扩比例做成参数(仓库说明里那个 0.3%–0.5%),让"怕切到字"和"怕留桌面"的用户各取所需。如果你想看哪一个,在仓库 issue 里提出来即可。

Logo

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念,把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起,为开发者提供从开发、训练到部署的一站式体验。

更多推荐