KMP 鸿蒙端侧图像超分实战:让 600×369 的图长出叶脉
一个只有 ArkTS 入口的系统 AI 能力、一条把 4× 变成 16× 的内存预算、三个并不总是一致指向的指标——这篇文章用一个跑在鸿蒙 2in1 上的 KMP 工程,把这三件事一次讲透。
仓库地址:https://atomgit.com/oh-tpc/kmp-ohos-ai-vision
版本地址:https://atomgit.com/CPF-KMP-CMP/compose-multiplatform-core/tree/main-1.9.2-OH
三方库框架:https://atomgit.com/CPF-KMP-CMP
0. 环境与实测设备
| 项 | 版本/型号 |
|---|---|
| DevEco Studio | 26.0.0.821(HarmonyOS SDK 26.0.0 Release / API 26) |
| Kotlin / Kotlin/Native | 2.2.21-1.0.0(目标 ohosArm64) |
| Gradle / JDK | 8.14.3(wrapper)/ 21.0.12(Homebrew;DevEco 自带的 JBR 是 25.0.2,跑不了本工程的 Gradle) |
| 鸿蒙 SDK | 7.0.0(API 26,SDK 版本 26.0.0.105 Release) |
| 超分模块 | 1.0.0(本仓库,com.ohos.vision:vision,jvm + ohosArm64 两个变体) |
| 系统能力 | Core Vision Kit imageSuperResolution(@since 26.0.0,Phone / 2in1 / Tablet,仅 Stage 模型) |
| 原生产物 | libohos_vision.so 1.05 MiB;entry-default-signed.hap 3.92 MB |
| 测试 | 27 项 JVM 用例(KMP 25:23 项 common + 2 项真实图回归;示例门面 2),0 失败;端侧 8 项自检 |
| 实测设备 | HUAWEI MateBook Pro S(MOR-M1),HarmonyOS 7.0.0.111(SP15C00E101R9P2),API 26 |
1. AI 说它更清楚,得先有个对照组
上一篇文章里,我用 KMP 把文档扫描的"找边 → 透视矫正 → 滤镜"跑通了。那一版里的每一步都是自己写的像素算法;这一版换了个方向:不再自己写重建,改用系统开放的 AI 能力。HarmonyOS 26 在 Core Vision Kit 里开了 imageSuperResolution:输入一张低清图,每条边放大 4 倍(像素数 16 倍),模型随系统提供,推理在设备本地完成,图片不出设备。
第一反应当然是"接上它"。但动手前有两个问题绕不过去。
第一个是位置。这个能力只有 ArkTS 接口——没有 NDK 绑定,没有 C++ 头文件。KMP 没法把推理搬进 commonMain,也没必要:模型在系统里,K/N 自己实现推理只会更慢。那 KMP 库的价值在哪?
第二个是证据。"AI 超分更清楚"是一句观感,不是结论。只把 AI 输出和低清输入并排放在一起,任何人都会说 AI 赢——因为低清输入本来就是糊的。要回答的问题是:它和"把丢掉的 15/16 像素尽量算回来"这个目标比,到底赢在哪、输在哪?
这两个问题决定了这一版的形态:推理走系统,可测试的部分留在 KMP。具体拆成三件事:
- 用 4×4 面积均值把原图打成低清输入(确定、可复现的降质模型);
- 用双线性 / 双三次 / Lanczos3 在 KMP 里做一条纯 CPU 基线,和 AI 用同一张低清图、重建到同一个尺寸;
- 用 PSNR / SSIM / 锐度三项指标,把两条路径都对着原图量一遍,数字全部上屏。
结果并不全是好消息:AI 的锐度是双三次的 6.4 倍,但 PSNR 低 0.66 dB、SSIM 也略低。这一页没有把不占优的项藏起来。
2. 效果展示
先看效果。窗口标题是 图像超分,页面往下滚着截的:标题和两个按钮已经滚出视口,第一张从引擎状态条开始。

第一行是引擎状态:绿色圆点 + HMS 图像超分引擎已就绪 · 4× 端侧重建,说明系统分析器创建成功;再往下是 原图 · 真值参考 卡片,右上角标着 2400×1476,里面是那张 CC0 的蕨类叶子照片;重建结果 卡片右上角写着 600×369 → 2400×1476,两颗按钮 双三次 · KMP 基线 和 AI 超分 · HMS,右侧那颗是蓝底、当前选中。选中项下面就是 AI 重建的大图。
第二张是同一页的下半部分,这一屏才是整件事的指标汇总:

结果图下沿一行小字:降采样 149ms · 双三次 742ms · AI 234ms。与真值对比 卡片右上角是一句结论:AI:锐度 ×6.4 · PSNR -0.66 dB;表格三行分别是 PSNR 28.18 dB / 27.52 dB、SSIM 0.914 / 0.891、锐度 7 / 45。脚注说明 PSNR / SSIM 以原图为基准、衡量重建结果和原图的保真度,锐度为拉普拉斯方差。再往下是 细节放大:三张中心 320×240 的裁切,低清输入 / 双三次 / AI 超分;底部一行 保存 AI 超分 JPG,最下面那行小字是 KMP 自检 8 项通过 · 降采样 / 重建 / PSNR / SSIM 全部在端侧完成。
把中间那三张裁切单独放大,差别就具体了:

低清输入一块一块,像素边界比叶脉还粗;双三次把块抹平了,代价是叶脉发虚;AI 的边缘更硬,小叶脉的走向能连着看下去。这也解释了页面那句"低清一侧按最近邻显示"——不是偷懒,是为了让"丢了多少"这件事肉眼可见。
但指标上,AI 的 PSNR 比双三次低 0.66 dB,SSIM 低 0.023。几个指标在量不同的东西,第 3 节和 5.3 会把这件事讲清楚。
还有一组容易看漏的数字:降采样 149 ms、双三次 742 ms、AI 234 ms。系统 AI 比 KMP 的双三次快 3 倍多。这和 Kotlin 代码质量无关,两条路径的执行位置根本不同:AI 在系统服务里跑模型,双三次是纯 CPU 的 Kotlin/Native 循环;计时口径也不完全一样(AI 的 234 ms 只包住 process()),第 3 节会交代。另一次运行的三个数是 148 / 743 / 195 ms——CPU 两段基本不动,AI 推理在 195–234 ms 之间浮动。
3. 4× 超分:把"更清楚"拆成四个可测量的环节
写代码之前先把四个环节定清楚。这一页从头到尾是四环,环环都能落到数字上:
2400×1476 原图(真值)
│ ① 规划:同一条像素网格(长边 2400、4 对齐)
│ ② 4×4 面积均值降采样 → 600×369 低清输入
▼
600×369 RGBA
├─ ③a 双线性 / 双三次 / Lanczos3(KMP,CPU)
├─ ③b imageSuperResolution(系统,4×) → 2400×1476
▼
两份重建结果
│ ④ PSNR / SSIM / 锐度,都以原图为基准
▼
三行数字 + 三张裁切
第一环,规划同一条像素网格。 ground 2400×1476,low = ground / 4 = 600×369,output = low × 4 = 2400×1476,恰好和 ground 同尺寸、同相位。这是 PSNR / SSIM 能直接算的前提:不用缩放、不用配准。两条规则:长边压到 2400;ground 的每条边除以 4 向下取整,所以 output 可能比 ground 小 0–3 px(1477 → 369 → 1476),小掉的几个像素由"只比重叠区"兜住。
2400 不是审美,是内存。 2400×1476 的 RGBA 一帧是 13.5 MiB;页面同时持有原图、低清、双三次、AI 四份,再加 AI 输入 / 输出两块 PixelMap 和 JPEG 编码缓冲。不压上限,一张 12 MP 的照片(4000×3000)一帧就是 48 MB,四份就是 192 MB,峰值很容易上两百兆——2in1 也承受不了这个峰值。
第二环,把原图打回低清。 用 4×4 面积均值,把 2400×1476 压成 600×369。为什么是面积均值,不是最近邻或双线性:面积均值是确定的低通——每个 4×4 块的 16 个像素权重相同、各用一次,丢掉的就是高频,重建算法要把它"猜"回来;最近邻会产生混叠,而且"猜"的难度和采样相位有关;双线性会引入和基线同族的低通,对照组从一开始就偏了。它还有一个好性质:平坦色块在降采样后仍然平坦,重建后也该保持平坦——自检里那条 drift <= 1 钉的就是这个。顺带纠一句自己写的文案:页面脚注目前写的是"丢掉 3/4 像素",那是 2× 的说法;4× 保住的是 1/16,丢掉的是 15/16,这句文案会随下一次提交改掉。
第三环,两条重建路径。 双三次走的是可分离卷积(横向一遍、纵向一遍),纯 Kotlin 在 ohosArm64 上跑;AI 走系统分析器,输入 600×369 的 PixelMap,输出 2400×1476。两条路用同一张低清图、重建到同一个尺寸,所以结果可以逐像素比较。基线故意传 sharpen = 0:纯插值才是"把丢掉的像素算回来"的对照组,给它加锐化就变成另一个只针对指标优化的对照组——锐度上去了,PSNR 多半更难看。
第四环,三项指标。 PSNR 量全局保真(RGB 逐像素误差),SSIM 量局部结构(亮度 8×8 块),锐度量高频能量(拉普拉斯方差)。三者衡量的东西不一样:PSNR 偏爱护住均值的模糊,锐度偏爱高频的过冲。一个为"看起来清楚"训练的模型,天然会在锐度上更高、在 PSNR 上更低——这正是页面上那组数字的由来。
性能数据。 三个数的计时口径不完全一样:降采样和双三次的耗时是在 native 侧量的,含最后那次 memcpy;AI 的 234 ms 是从 process() 开始到返回的墙钟,不含输入 PixelMap 的创建,也不含输出像素的拷出。即便把口径补齐,AI 仍然更快——另一条路径是 CPU 上跑两遍浮点卷积,而模型跑在系统侧。双三次这 742 ms 里,很大一块不是算术,是内存:横向中间层是 outWidth × inHeight × 3 个 float,2400×369×3×4 B ≈ 10.1 MiB,纵向再读一遍;再加上每像素两个轴的 4 个 Double 权重、Kotlin/Native 没有 JIT,这个数就不奇怪了。
4. 工程怎么搭:一个 KMP 模块,一条 C ABI,一层 ArkTS 封装
先看整体结构。可测试的像素与指标在公共 KMP 模块,原生桥和鸿蒙宿主退到 example/:
kmp-ohos-ai-vision/ # 仓库根:Gradle 工程 A
├─ vision/ # 公共 KMP 模块(jvm + ohosArm64,运行时零三方依赖)
│ └─ src/commonMain/kotlin/com/ohos/vision/
│ ├─ VisionModels.kt # SR_FACTOR / ResampleKernel / SrPlan / QualityReport
│ ├─ ImageOps.kt # 面积均值降采样 + 可分离重采样 + unsharp
│ ├─ QualityMetrics.kt # PSNR / SSIM / 锐度 / 边缘能量
│ ├─ VisionChecks.kt # 8 项端侧自检
│ └─ VisionJson.kt # C ABI 的 JSON 边界
├─ example/ # Gradle 工程 B(把 vision 的 projectDir 指到 ../vision)
│ ├─ shared/ # 门面 VisionExamples + JVM 验收测试
│ ├─ nativeApp/ # ohosArm64 动态库与 C ABI
│ │ └─ src/ohosArm64Main/kotlin/…/NativeBridge.kt # @CName 导出 6 个符号
│ └─ ohosApp/ # DevEco Stage 工程(不参与 Gradle)
│ ├─ entry/src/main/cpp/ # N-API 壳:napi_init.cpp + CMakeLists.txt
│ ├─ entry/src/main/ets/sr/ # VisionBridge / SuperResolution / ImageCodec
│ ├─ entry/src/main/ets/pages/Index.ets # 超分页面
│ └─ entry/src/main/resources/rawfile/ # sample_photo.jpg(CC0 示例图)
├─ tools/make_sample.py # 生成单测用的分辨率测试卡
└─ docs/screenshot-sr.png

这次设计最关键的决定有四个:
推理归系统,可测试的部分归 KMP。 imageSuperResolution 只有 ArkTS 入口,就不硬包一层"伪 C++ 推理";KMP 承担可测试的前处理(降采样、规划)、后处理(经典重建、回退)和评估(三项指标)。设备上实际运行的算法,就是 25 项 JVM 用例盯着的那份代码。
两个 Gradle 工程,而不是一个。 DevEco 的 ohosApp 不参与 Gradle;example 用 include("vision") 再把 projectDir 指到 ../vision。Gradle 和 hvigor 各跑各的,HAP 那边只需要一个 .so 和一个头文件。
统计走 JSON,像素走缓冲区。 一帧 2400×1476 的 RGBA 是 13.5 MiB,base64 之后是 18 MiB 字符串;JSON 只过尺寸、耗时、指标这些标量。像素由 ArkTS 侧分配 Uint8Array,Native 只负责往里写。
同一套门面给两边用。 VisionExamples 把 plan / downsample / upsample / compare / runChecks 包成五个方法,JVM 测试和 C ABI 都调它,设备上不会出现"测试里是一套、桥上另一套"的情况。
桥的协议没有花活:C ABI 进数字、出 JSON,像素走缓冲区。下面这两份是示例图(2400×1476)的真实载荷:
// VisionPlan(2400, 1476) → 尺寸规划
{ "ok": true, "groundWidth": 2400, "groundHeight": 1476,
"lowWidth": 600, "lowHeight": 369,
"outputWidth": 2400, "outputHeight": 1476, "factor": 4 }
// VisionUpscale(low, 600, 369, 2400, 1476, 双三次, 0.0, dst) → 只回统计,像素写进 dst
{ "ok": true, "width": 2400, "height": 1476,
"kernel": "双三次", "sharpen": 0.00, "elapsedMs": 742 }
对使用方来说,一次"超分"就是按规划走一遍:
// example/ohosApp/entry/src/main/ets/pages/Index.ets(节选)
const plan: PlanJson = planFrame(this.sourceWidth, this.sourceHeight);
const low = new Uint8Array(plan.lowWidth * plan.lowHeight * 4);
const down = downscalePixels(ground, this.sourceWidth, this.sourceHeight, plan.factor, low);
const classic = new Uint8Array(plan.outputWidth * plan.outputHeight * 4);
const klass = upscalePixels(low, plan.lowWidth, plan.lowHeight,
plan.outputWidth, plan.outputHeight, KERNEL_BICUBIC, 0, classic);
const frame: SrFrame = await this.engine.upscale(low, plan.lowWidth, plan.lowHeight);
const report = compareFrames(ground, this.sourceWidth, this.sourceHeight,
frame.pixels, frame.width, frame.height);
注意这里没有"把 AI 结果缩放到原图"的步骤:两条路径本来就落在同一条网格上,所以指标可以直接算。
5. 把代码讲透
5.1 规划:4× 放大对应 16× 内存
SrPlan.forGroundTruth() 只有十几行,但它决定了后面所有的尺寸和内存:
// vision/src/commonMain/kotlin/com/ohos/vision/VisionModels.kt - forGroundTruth()(节选)
val longest = max(width, height)
val scale = if (longest > maxSide) maxSide.toDouble() / longest else 1.0
val groundWidth = max(SR_FACTOR, (width * scale).roundToInt())
val groundHeight = max(SR_FACTOR, (height * scale).roundToInt())
val lowWidth = groundWidth / SR_FACTOR
val lowHeight = groundHeight / SR_FACTOR
return SrPlan(
groundWidth = groundWidth,
groundHeight = groundHeight,
lowWidth = lowWidth,
lowHeight = lowHeight,
outputWidth = lowWidth * SR_FACTOR,
outputHeight = lowHeight * SR_FACTOR,
)
三个不变量写在 init 里,任何一条不满足都直接抛:
// 同文件 - SrPlan.init(节选)
require(outputWidth == lowWidth * SR_FACTOR && outputHeight == lowHeight * SR_FACTOR) {
"Output size must be exactly ${SR_FACTOR}x the low resolution input"
}
require(outputWidth <= groundWidth && outputHeight <= groundHeight) {
"Reconstruction cannot exceed the ground truth frame"
}
几个当时想清楚的点:
向下取整,所以 output 可以比 ground 小几个像素。 low = ground / 4 是整数除法,1477 的边会变成 ground 1477 → low 369 → output 1476。这不是 bug,是"宁可少比一行,也不做半像素对不齐的比较";QualityMetrics 里只比重叠区,就是给这种情况准备的。
长边 2400 是内存上限,不是画质上限。 一帧 13.5 MiB,页面同时持有四份(原图、低清、双三次、AI),再加两块 PixelMap 和 JPEG 缓冲。12 MP 的照片如果直接当 ground,光一帧就 48 MB。
max(SR_FACTOR, …) 兜住极小图。 3×2 的输入不能被规划成 0×0;测试里 neverPlansAZeroSizedFrame 钉的就是这条。
bytesOf() 让调用方先分配。 lowBytes / outputBytes 直接给出 w * h * 4,ArkTS 侧按这个数 new Uint8Array,Native 只写——这一版所有"出参"都是这个模式。
5.2 降采样与重建:面积均值、可分离卷积与 10 MiB 的浮点中间层
降采样是这条链的起点,它必须确定、可复现,而且不能偷偷引入偏置:
// ImageOps.kt - downsample()(节选)
val samples = factor * factor
// 每个 4×4 块把 16 个像素的 R/G/B 分别累加
val half = samples / 2
output[out] = ((red + half) / samples).toByte()
output[out + 1] = ((green + half) / samples).toByte()
output[out + 2] = ((blue + half) / samples).toByte()
output[out + 3] = 255.toByte()
+ half 是四舍五入(整数除法的 0.5 补偿);alpha 一律写 255。测试里 averagesEveryBlockOfPixels 用 8×8 的渐变图逐块验算均值(首块红通道 5、x=6 那块 65),usesEveryPixelExactlyOnce 再确认输出块数(3×2)和各通道不变。这一条比"看起来对"重要得多:降采样一旦漏了半行,后面的 PSNR 全是错的,而且错得很小、很难发现——纯色图测不出来,只有逐块验算的渐变图能抓。
重建是可分离的:先横向把每一行重采样到 outWidth,把结果存成 float;再纵向对每一列做一次。这样峰值内存只要 outWidth × inHeight × 3 个 float,而不是"整个输出的一份 float 拷贝":
// 同文件 - upsample()(节选)
val horizontal = buildTaps(width, outWidth, kernel)
val vertical = buildTaps(height, outHeight, kernel)
val intermediate = FloatArray(outWidth * height * 3)
抽头(taps)是预先算好的:每个输出位置对应源图上的一个小窗口,窗口中心和权重在 buildTaps() 里一次算完,循环里只做乘加:
// 同文件 - buildTaps()(节选)
val radius = when (kernel) {
ResampleKernel.BILINEAR -> 1
ResampleKernel.BICUBIC -> 2
ResampleKernel.LANCZOS3 -> 3
}
val taps = radius * 2
val scale = outSize.toDouble() / inSize
val centre = (index + 0.5) / scale - 0.5
val first = floor(centre).toInt() - radius + 1
// 权重归一化:sum 为 0 时退化成"只取最近的一个抽头"
几个细节:
权重必须归一化。 Lanczos3 在边界附近的抽头和并不严格等于 1,不归一化的话,平坦区域会整体偏亮或偏暗。测试 keepsAFlatAreaFlat 断言的是"精确相等",不是"误差小于 2"——这类不变量必须钉死。
边界用复制,不用零填充。 抽头窗口越界时把坐标夹到 [0, size-1],边缘就不会出现一圈黑边;零填充是插值最常见的"暗角"来源。
Double 权重 + Float 中间层。 权重用 Double 算,累加用 Float 存,最后一次 round 回 Byte。这个组合在精度和内存之间取了中间:如果中间层也用 Double,10.1 MiB 会翻成 20.3 MiB。
可选 unsharp。 sharpen > 0 时再走一遍 3×3 高斯 unsharp mask(强度夹在 0–1.5)。基线页面传 0——纯插值才是对照组;测试里 sharpeningRaisesTheSharpnessMetric 单独验证"加锐化确实会涨锐度"。
性能数据。 这条路径在 2in1 上是 742 ms:2400×1476 的输出、每个像素每个通道两个轴各 4 个抽头、10.1 MiB 的中间层来回读。Kotlin/Native 没有 JIT,这套循环就是逐条执行。它慢,但原因清楚:没有模型、没有黑盒,PSNR 28.18 dB 这个数绝大部分由这段代码决定。
5.3 指标:PSNR 偏爱护住均值的模糊,锐度偏爱高频的过冲
三项指标都在 QualityMetrics 里,输入都是紧凑 RGBA,比较时只取两张图重叠的左上角区域。
PSNR 最直接:RGB 三个通道逐像素求平方误差,再换算成 dB;完全相同的两帧 MSE 为 0,PSNR 是无穷大,JSON 没法表示,所以封顶 99 dB:
// QualityMetrics.kt - psnr()(节选)
val mse = squared / samples
if (mse <= 1e-12) return 99.0
return (10.0 * log10(255.0 * 255.0 / mse)).coerceAtMost(99.0)
SSIM 在亮度通道上按 8×8 块算均值、方差、协方差,块按实际像素数加权(边缘的不完整块也参与),常数用标准的那两个:
// 同文件 - ssim()(节选)
private const val SSIM_BLOCK = 8
private const val C1 = (0.01 * 255.0) * (0.01 * 255.0)
private const val C2 = (0.03 * 255.0) * (0.03 * 255.0)
val numerator = (2.0 * meanReference * meanCandidate + C1) * (2.0 * covariance + C2)
val denominator = (meanReference * meanReference + meanCandidate * meanCandidate + C1) *
(varianceReference + varianceCandidate + C2)
锐度是拉普拉斯方差:对亮度图做 4 邻域拉普拉斯,取方差。它对高频最敏感,也因此容易虚高——过冲、振铃、锐化都会把它推高:
// 同文件 - sharpness()(节选)
val laplacian = 4 * centre - luma[row + x - 1] - luma[row + x + 1] -
luma[row - width + x] - luma[row + width + x]
return max(0.0, squared / count - mean * mean)
为什么三个都要?因为它们衡量的方向并不一致,这种不一致本身就是信息:
- 双三次是线性插值,不会"发明"细节,所以它和原图逐像素更接近(PSNR / SSIM 更高),但高频被压平了(锐度低);
- 端侧超分模型偏向感知增强,边缘更硬、叶脉更连续(锐度高 6.4 倍),但那些"更硬"的高频不一定是原图真实的那一份,逐像素指标就会扣分(PSNR 低 0.66 dB,SSIM 低 0.023)。
几个指标在量不同的东西,所以 AI 的 PSNR 偏低并不说明接入出错。页面把三项一起摆出来,就是想让人自己权衡,而不是替人下结论。
还有两个校准细节值得记一笔:
自比必须是满分。 同一张图和自己比,PSNR 必须打到封顶 99 dB、SSIM 必须严格等于 1.0;测试 identicalFramesScorePerfectly 和自检里的"自比校准"都在钉这条。指标代码如果连自己都量不准,后面的比较全是噪声。
绝对数值跟内容强相关。 同一套双三次,在这张叶子上是 28.18 dB / 0.914 / 锐度 7;在单测那张合成的分辨率测试卡上是 19.585 dB / 0.8265 / 锐度 43.6(Lanczos3 是 19.696 / 0.8226 / 46.0)。测试卡有接近极限的线对,PSNR 天然低;叶子大面积平滑,PSNR 天然高。所以指标只能"同图比",不能跨图比,也不能拿 28 dB 去和别人的 30 dB 直接比较。
JVM 和设备的数字会差一点点。 我在 Mac 的 JVM 上用同一张 JPEG 复算双三次,得到 PSNR 28.223 dB / SSIM 0.9146 / 锐度 7.3;设备上是 28.18 / 0.914 / 7。算法是确定性的,差的是解码:ImageKit 和 ImageIO 的 JPEG 解码不会逐位相同,送进算法的像素本来就差一点。这也是单测只断言下限(> 18 dB、> 0.7 之类)而不是精确值的原因。
顺带一句,JSON 里的 edgeEnergy 也算了,但页面只展示三项——多个高度相关的指标同屏,只会分散重点。
5.4 桥:六个符号,两块缓冲区
超分这条链在 C ABI 上只有 6 个符号:VisionPlan、VisionDownscale、VisionUpscale、VisionMetrics、VisionChecks、VisionFree。全部是"数字进、JSON 出",像素只通过两块缓冲区走。
// example/nativeApp/src/ohosArm64Main/kotlin/com/ohos/vision/example/NativeBridge.kt(节选)
@CName("VisionUpscale")
public fun upscaleNative(
rgba: CPointer<ByteVar>?, length: Int, width: Int, height: Int,
outWidth: Int, outHeight: Int, kernelIndex: Int, sharpen: Double,
destination: CPointer<ByteVar>?,
): CPointer<ByteVar> = response {
val source = rgba ?: error("Missing image buffer")
val target = destination ?: error("Missing output buffer")
val kernel = ResampleKernel.byIndex(kernelIndex)
val started = TimeSource.Monotonic.markNow()
val output = ImageOps.upsample(
rgba = source.readBytes(length),
width = width, height = height,
outWidth = outWidth, outHeight = outHeight,
kernel = kernel, sharpen = sharpen,
)
writeTo(target, output)
VisionJson.upscale(
width = outWidth, height = outHeight,
kernel = kernel, sharpen = sharpen,
elapsedMs = started.elapsedNow().inWholeMilliseconds,
)
}
NAPI 壳负责把 JS 的 Uint8Array 变成指针,并在调用之前把尺寸查干净:
// example/ohosApp/entry/src/main/cpp/napi_init.cpp(节选)
const auto expectedSource = static_cast<size_t>(width) * static_cast<size_t>(height) * 4;
if (rgbaLength < expectedSource) {
napi_throw_range_error(env, nullptr, "source buffer is smaller than width * height * 4");
return nullptr;
}
const auto expectedOutput = static_cast<size_t>(outWidth) * static_cast<size_t>(outHeight) * 4;
if (destinationLength < expectedOutput) {
napi_throw_range_error(env, nullptr, "destination buffer is smaller than outWidth * outHeight * 4");
return nullptr;
}
七个取舍:
统计走 JSON,像素走缓冲区。 一帧 13.5 MiB,base64 膨胀到 18 MiB,JSON.parse 一次够算好几遍 PSNR 了。桥上的 JSON 只有尺寸、内核名、耗时、指标这些标量。
出参缓冲由调用方分配。 destination 是 ArkTS 侧 new 的 Uint8Array;Native 只校验够不够大,然后 memcpy。切换双三次 / Lanczos3 时尺寸不变,缓冲区可以按同一套规划反复用。
"零拷贝"是相对的。 ImageOps.upsample() 内部还是会新建一个输出 ByteArray(好写好测),最后 memcpy 一次 13.5 MiB,亚毫秒级。真要省,就得把 destination 传进 Kotlin、用 usePinned 直接写;这一版没做,因为这点拷贝在 742 ms 里是噪声。
字符串谁释放。 Kotlin 侧 nativeHeap.allocArray 分配,NAPI 壳 napi_create_string_utf8 复制成 JS 字符串后立刻 VisionFree。ArkTS 拿到的永远是独立字符串,不是指针。
参数校验全在壳里。 ReadNumbers 拒绝负数和非有限值(NaN/Inf),ReadBytes 要求非空 Uint8Array,源和目标缓冲区都要过尺寸检查;任何一条不满足都是可捕获的 JS 异常,而不是 native crash。
导出面收敛。 shared-library.map 只列 6 个符号、local: * 兜底,链接参数带 --entry=0。产物 1.05 MiB,进 HAP 时还会被 DoNativeStrip 处理一遍;整包 3.92 MB。
耗时含拷贝。 降采样和重建的 elapsedMs 是在 writeTo() 之后取的,所以 149 ms / 742 ms 里已经算进了那次 memcpy。
5.5 ArkTS 侧:一个分析器、一道单飞闸门和一次 GC 事故
系统能力的封装在 SuperResolution.ets 里,只有一百多行,但几乎每一行都对应一个真实约束:
// example/ohosApp/entry/src/main/ets/sr/SuperResolution.ets(节选)
private analyzer: imageSuperResolution.ImageSRAnalyzer | undefined = undefined;
private processing: boolean = false;
private inputBuffer: ArrayBuffer | undefined = undefined;
async upscale(pixels: Uint8Array, width: number, height: number): Promise<SrFrame> {
if (this.processing) {
throw new Error('上一次超分调用尚未结束');
}
const buffer = pixels.buffer.slice(
pixels.byteOffset,
pixels.byteOffset + width * height * 4,
) as ArrayBuffer;
this.inputBuffer = buffer;
const input = await this.createPixelMap(buffer, width, height);
this.processing = true;
try {
// …process() 与输出 PixelMap 的读取…
} finally {
this.processing = false;
this.inputBuffer = undefined;
await input.release();
}
}
几个不能省的细节:
分析器只创建一次,页面退出才释放。 ImageSRAnalyzer.create() 的成本是几百毫秒,每次点击都建一个,第一次交互就会出现"点了没反应"。页面在 aboutToAppear() 里初始化、aboutToDisappear() 里 release()。
单飞闸门。 系统能力不支持同进程并发调用;没有 processing 这道闸,连点两下就会有两个 process() 抢同一个分析器。闸门在入口抛 上一次超分调用尚未结束,页面再用 busy 把按钮尽量按住。
输入缓冲区要活到推理结束。 image.createPixelMap() 不承诺复制 buffer,而分析器是异步读它的;GC 一旦把这块 ArrayBuffer 回收,推理就会读到已释放的内存——表现是间歇性的、按块出现接缝的花屏,复现率随负载变化。修法是留一个 inputBuffer 字段,process() 结束后再置空(第 6 节坑三细说)。
输出要拷成调用方自己的字节。 服务返回的 PixelMap 在 finally 里 release();拷出之前先检查两件事:像素格式必须是 RGBA_8888,getPixelBytesNumber() 必须等于 width × height × 4。两个检查分别对应代码里那两句 超分输出像素格式不受支持 和 超分输出跨距不受支持。
尺寸对不上不算灾难,但要说明。 页面拿到 AI 结果后会核一次 frame.width/height 和规划值;不一致时给出警告"指标按重叠区域计算",而不是按对齐处理。
页面这一层的编排很短:plan → 降采样 → 双三次 → 指标 → AI → 指标 → 三张裁切 → JPEG。两个细节:
结论是页面自己算的。 右上角那句 AI:锐度 ×6.4 · PSNR -0.66 dB 不是写死的文案,是拿两份 MetricsJson 现算的:sharpness / baseSharpness 和 psnr - bicubicPsnr。换机型、换模型,这行字会跟着变。
内容列有宽度上限。 页面外层是 Scroll,内容列 constraintSize({ maxWidth: 960 }) 并居中;在 2in1 的宽窗口里不会把一行正文拉成 1600 px,截图里两侧的空白就是它。
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)。看到错误信息"就一个版本号",先怀疑工具链,别去翻代码。
坑二:能力没开时,页面要先显示失败原因。
AI 超分不可用:图像超分引擎创建失败(1018700001):Service exception
ImageSRAnalyzer.create() 失败时抛的是 1018700001(Service exception)。原因可能是设备不是 API 26、镜像里没内置模型、或者系统没开放这项能力。只写成功路径的话,失败时页面会停在"初始化中…",用户什么也看不到。现在先 canIUse('SystemCapability.AI.Vision.VisionBase') 探一次,创建失败就把错误码打到状态条,并把视图切到 KMP 双三次、显示 已展示 KMP 双三次回退结果。系统能力不可用时,回退要看得见,不能显示成成功。
坑三:输入缓冲被 GC 回收,推理花成马赛克。
这一条最难查,因为它是间歇性的。症状是 AI 结果上出现按块接缝的彩色噪点:有时候整张正常,有时候一跑就花。日志里没有任何异常——推理"成功"了,只是读到的输入已经不对。
根因在 image.createPixelMap() 的契约:它不承诺复制你给的 ArrayBuffer,而 process() 是异步读这块内存的。中间只要发生一次 GC,buffer 被回收,分析器读到的就是别人的内存。修法是给输入缓冲一个字段,活到 process() 结束:
/**
* Keeps the RGBA buffer that backs the input PixelMap alive.
*
* `image.createPixelMap` does not promise to copy the buffer, and the analyzer reads it
* asynchronously. Holding the reference until `process` settles avoids the intermittent
* tile-seam corruption that appears when the GC reclaims the buffer mid-inference.
*/
private inputBuffer: ArrayBuffer | undefined = undefined;
异步系统 API 的输入内存,生命周期要覆盖整个调用,不是覆盖调用那一刻。
坑四:AI 的 PSNR 比双三次低,差点以为接错了。
第一次看到 27.52 vs 28.18 dB 时,我的第一反应是"相位错了"。4× 重建最容易出的错就是半像素偏移:输出尺寸对了,但每个像素整体偏半格,PSNR 会掉、SSIM 会掉、锐度反而可能虚高。我用相位相关核了一遍,偏移是 0;把 AI 结果和双三次结果叠在一起看,边缘也是对齐的。
结论是模型本身偏感知增强:它把边缘"做硬"了,高频过冲被逐像素指标惩罚。页面把三项指标一起摆出来,就是为了让这个取舍可见,而不是挑一个好看的数。遇到"指标和观感相反",先验证几何,再接受模型的偏向。
坑五:连点两下,第二次调用直接抛异常。
系统分析器不支持同进程并发。页面第一版没有闸门,快速点两次"示例图"就会有两个 process() 同时在途:第二路在 upscale() 入口抛 上一次超分调用尚未结束,这一路的结果就变成"AI 失败、回退双三次"——用户看到的是一条警告,不是 AI 图。修法是 processing 布尔闸门:一次只允许一个在途推理,第二路在入口就被拒;页面再用 busy 把按钮尽量按住,减少并发冲突的机会。系统能力的并发约束,要在自己的入口就挡住,别等系统报错。
坑六:Uint8Array 不等于它背后的 ArrayBuffer。
image.createPixelMap(buffer, options) 只接受 ArrayBuffer,而且会从 buffer 的开头按 width × height × 4 读。问题是我们的 pixels 经常是一个视图:解码器返回的 buffer 可能带行对齐的尾部填充,readPixelsToBuffer 写进来的 byteLength 可能比 w × h × 4 大;pixels.buffer 比 pixels 本身大,pixels.byteOffset 也不一定是 0。直接把 pixels.buffer 交出去,轻则尺寸不符,重则读到别的内存。
修法只有一行,但要写在两个地方(超分输入、JPEG 编码):
const buffer = pixels.buffer.slice(
pixels.byteOffset,
pixels.byteOffset + width * height * 4,
) as ArrayBuffer;
跨 API 传像素,先把视图压平成"恰好大小"的 ArrayBuffer,不要依赖对方正确处理 byteOffset 和 byteLength。
7. 现在怎么用:从 Maven 坐标到 2in1 上的 234 ms
经过上面的整理,这个工程是三层交付(Apache-2.0):
- KMP 模块(
com.ohos.vision:vision):规划、降采样、双线性/双三次/Lanczos3、三项指标、8 项自检,jvm与ohosArm64两个变体,运行时零三方依赖; - 原生桥(
example/nativeApp):6 个@CName导出 + version script,编成libohos_vision.so; - ArkTS 封装(
example/ohosApp):VisionBridge(JSON)+SuperResolution(系统能力)+ImageCodec(编解码),以及整页示例。
接入 KMP 工程,先发布到本地 Maven 再引用:
JAVA_HOME=/path/to/jdk21 ./gradlew :vision:publishToMavenLocal
// commonMain
implementation("com.ohos.vision:vision:1.0.0")
产物是 vision(KMP 元数据)+ vision-jvm + vision-ohosarm64 三个坐标,Gradle 按目标自动选变体;消费端记得把 mavenLocal() 加进 repositories。这一版没有往公共仓库发——本机 本地 Maven 仓库 里能查到这三个变体,上面的坐标直接可用。
要接原生桥,把 example/nativeApp 的 6 个导出和 napi_init.cpp 里对应的壳抄过去即可;嫌麻烦就把 example/ohosApp 整个复制走,签名换成本机的。仓库本身不带签名材料(公开仓库不该提交证书),在 DevEco 里勾选 Automatically generate signature,或把本机证书写进 build-profile.json5。
# 1) 25 项 KMP 用例 + 2 项示例门面用例(在仓库根执行)
JAVA_HOME=/path/to/jdk21 ./gradlew :vision: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.vision.sample
宿主检查清单就四条:
- 接系统超分前先
canIUse('SystemCapability.AI.Vision.VisionBase'),创建失败要有可见回退; - 分析器只创建一次,
processing闸门保证同进程一次只有一个在途推理; - 给
createPixelMap的是"恰好w*h*4"的ArrayBuffer,不是随便一个Uint8Array.buffer; - 输出
PixelMap要检查RGBA_8888与紧凑跨距,并release();指标只算重叠区。
能力边界、构建步骤和 FAQ 都写在OpenHarmony 接入说明里,本文只挑了与这版超分链路直接相关的部分。
当前版本在 DevEco Studio 26.0.0.821 / HarmonyOS API 26 上验证:27 项 JVM 用例全绿(含分辨率测试卡的真实图回归和 8 项自检的同款断言),assembleHap 产出 3.92 MB 签名 HAP;2in1 上示例图 2400×1476 → 600×369 → 2400×1476,降采样 149 ms、双三次 742 ms、AI 234 ms,PSNR 28.18 / 27.52 dB,SSIM 0.914 / 0.891,锐度 7 / 45(AI ×6.4、PSNR −0.66 dB);页面自检 8 项通过,能力不可用时如实回退到 KMP 双三次。
下一步的计划也记在这里:一是换真实低清输入——现在低清图是自己用面积均值造的,下一步直接用相机小图、聊天软件压缩图、截图二次压缩,看这套指标还成不成立;二是把三种核暴露到页面上——双线性和 Lanczos3 已经在库里了,做一排按钮就能把"经典算法的上限"也量出来;三是把 PSNR / SSIM 换成更贴近观感的指标(比如在 SSIM 之外加一列梯度相似度),但前提是先把现在这三项指标的特性弄清楚。如果你想看哪一个,在仓库 issue 里提出来即可。
更多推荐



所有评论(0)