React Native 鸿蒙端侧 AI 图像超分实战:让 NPU 把细节补回来
一张 512px 的低清图,怎么在 RN 的 TurboModule 里被送进 NPU、放大 4 倍、再原样回到 JS?——这篇文章用一个跑在鸿蒙 PC 上的 React Native 0.84 三方库,把端侧 AI 超分这条链路拆开讲透,也讲清楚 AI 退回 CPU 时怎么发现。
仓库地址:https://atomgit.com/oh-react-native/react-native-ohos-ai-vision
版本地址:https://atomgit.com/oh-react-native/ohos_react_native/tree/0.84-main
三方库框架:https://atomgit.com/oh-react-native
0. 环境与实测设备
| 项 | 版本/型号 |
|---|---|
| DevEco Studio | <DevEco Studio 安装目录>(HarmonyOS SDK 26.0.0 / API 26) |
| 运行设备 | HUAWEI MateBook Pro S(MOR-M1),HarmonyOS 7.0.0.111(SP15C00E101R9P2),API 26 |
| React Native | 0.84.1 |
| React | 19.2.3(与 RN 0.84.1 内置 renderer 严格同版) |
| RNOH | @react-native-oh/react-native-harmony 0.84.3;OHPM @rnoh/react-native-openharmony 0.84.3 |
| 语言与构建 | TypeScript 5.9.3、Babel 7、Jest 29.7、Node.js 24.12.0 / npm 11.12.1 |
| 鸿蒙 SDK | 编译/目标 26.0.0;HAR compatibleSdkVersion: 26、minAPIVersion: 260000026 |
| hvigor | DevEco Studio 自带(HVIGOR_JS 可覆盖) |
| react-native-ohos-ai-vision | 0.3.0(本仓库,npm 包 + source-style HAR) |
| 示例应用 | Ohos AI Vision(example/harmony,deviceTypes: phone / tablet / 2in1) |
| 端侧引擎 | Core Vision Kit imageSuperResolution(NPU,API 26+)+ Catmull-Rom 双三次(CPU 兜底) |
1. AI 真的跑了吗:一次静默回退
这个库在 0.2 版本还是做 OCR 和文档扫描的。到了 0.3,整个方向被推倒重来:HarmonyOS 7 把 imageSuperResolution 放进了 Core Vision Kit,API 26 起可以在设备本地把一张图放大 4 倍,跑在 NPU 上。库名 react-native-ohos-ai-vision 没变,能力全换了——旧的 OhosOcr、文档扫描管线、subjectSegmentation 全部移除,TurboModule 改名 OhosSuperResolution,HAR 目录、CMake target、Package 类跟着改,compatibleSdkVersion 直接抬到 26。
换方向本身不算难,难的是怎么证明 AI 真的跑了。
第一次在鸿蒙 PC 上装好,页面看起来一切正常:nativeBridge: OK,能力行写着 API 26、Core Vision 可用、上限 2048px。选了一张图,几秒后结果出来,尺寸也是 4 倍。直到我往下看到那一行:
实际引擎:本地双三次(CPU)
能力说可用,结果却不是 NPU 出的。页面上没有任何报错,返回的图也是对的,能看出问题的只有 engine 字段。
查下去,根因藏在一行很不起眼的构造里:
Constructor is false
visionBase.Request 这个类型没有对外暴露构造函数,new visionBase.Request() 在设备上直接抛错;我的 try/catch 把它当成"这张图 AI 处理不了",顺手回退到了本地双三次。因为回退路径能出图,整个调用仍然是"成功"的。修复方式与官方示例一致——不再 new,而是用类型化对象字面量:
const input: visionBase.ImageData = { pixelMap };
const request: visionBase.Request = { inputData: input };
const response: imageSuperResolution.ISPResponse = await analyzer.process(request);
改完再跑,同一个操作稳定返回 core-vision。系统日志里也终于出现了 NPU 服务的痕迹:
ML_ISP_ImageSRServiceStub: initAlgorithmV2 complete, code:0
这件事定下了整个库的设计前提:
- 结果必须自报引擎:
engine不是调试字段,是契约的一部分,页面要把它显示给用户看; - 回退必须是显式的:AI 失败可以退 CPU,但要让调用方知道退过,而不是把 CPU 结果伪装成 NPU 结果;
- 一致性必须可验证:光看尺寸不够,得有一个跨平台的校验和,证明"同一张图、同一份像素"。
所以这篇记录的边界很清楚:
- 两条路线怎么选(AI 4× / 本地双三次 2/3/4×);
- 4 倍双三次怎么写才能和 ArkTS 逐字节一致;
- 512 → 2048 的像素和 PNG data URI 怎么经 RN 桥传给 JS;
- npm 包 + source-style HAR 怎么交付,以及我踩到的每一个真机坑。
2. 效果展示
先看效果。示例应用叫 Ohos AI Vision,在鸿蒙 PC 上是一个 2in1 窗口:

页面只做一件事:相册图片 → 4× 超分。顶部三枚能力标签是 API 26、Core Vision 可用、上限 2048px;中间三个按钮分别走 AI 4×、本地双三次 3×、内置示例照片 4×;下面是原图与结果的并排对比。
这张截图里的数字:
- 原图
512 × 341,超分结果2048 × 1364,正好 4 倍; - 状态行:
超分完成(Core Vision Kit)· 端侧 2682ms · 端到端 3630ms; - 端侧耗时是原生管线自己量的:解码、推理、读回、校验和、PNG 编码都算在里面;端到端多出来的是 JS 调用、JSON 解析和 React 状态更新;
- 图右侧的岩石纹理、远处山脊和路面颗粒,是 4× 之后补出来的细节,不是把原图插值拉大。
对比图下方还有几行统计:实际引擎(Core Vision Kit(NPU) 或 本地双三次(CPU))、RGBA 校验和、PNG 体积(base64 字符数),以及一份把 base64 折成 <data URI · N chars> 的 JSON。再往下是确定性引擎契约卡片:三个演示场景的校验和、原生与纯 TS 引擎 JSON 逐字符一致、6 条自检。这些内容截图里只露出了一部分,但验收时要逐项核对。
两个交互细节,截图里看不出来:
- 如果 AI 服务对这张图失败,或者请求的是 2×/3×(AI 只有 4× 模型),页面不会报错,而是把
实际引擎改成本地双三次(CPU),结果照常返回; - 请求进行中三个按钮全部禁用,因为官方明确不支持同进程并发调用;原生侧还有一道
busy锁,第二次进入直接 rejectImage super-resolution is already running。
也要提前说清楚一个反直觉的现象:文字截图不是这个模型的好输入。把一张代码编辑器截图放大 4 倍,笔画会被模型"脑补"成更粗、更连的形状,反而不如本地双三次好读。示例页因此把两条路线都放进了按钮:自然照片走 AI 4×,文字/图形截图可以走 3× 双三次。这是分布外输入的常见表现,不算缺陷。
3. 两条路线,一份契约:超分到底怎么发生
写代码之前先把链路捋清楚。整条管线全在设备本地,没有网络请求;AI 路线在 NPU 上跑,CPU 路线是确定性的 Catmull-Rom 双三次:
JS(React)
└─ pickImage() ──► 系统 PhotoViewPicker ──► file://media/...
│
▼
superResolution(uri, 4) ──► OhosSuperResolution(TurboModule,跨 C++ 桥)
│
▼
SrImage.superResolution(ArkTS,设备本地)
├─ decodeImage(uri, 512) RGBA_8888,长边 ≤ 512
├─ processPixelMap
│ ├─ AI:pixelMapToRgba → createRgbaPixelMap
│ │ → ImageSRAnalyzer.process → 尺寸校验
│ │ → pixelMapToRgba → checksum → 重新封装
│ └─ CPU:pixelMapToRgba → upscale(Catmull-Rom) → checksum
├─ toDataUri(PNG, 100) data:image/png;base64,...
└─ imageResultToJson 固定字段顺序
│
▼
{ uri, id, source, factor, inputWidth, inputHeight, outputWidth,
outputHeight, engine, durationMs, checksum, image }
| 路线 | 触发条件 | 实现 | engine |
|---|---|---|---|
| Core Vision Kit(NPU) | API 26+,且 factor = 4 | imageSuperResolution.ImageSRAnalyzer.create() → process() → 4× PixelMap | core-vision |
| 确定性双三次(CPU) | 其它平台、AI 异常、factor = 2/3 | upscale(),Catmull-Rom(a = -0.5),纯整数最终取整 | local-bicubic |
官方对 AI 接口的约束有四条,直接决定了工程形态:
- 输入不超过 2048 × 2048;
- 输出固定 4 倍,没有 2× / 3× 模型;
- 同一进程不支持并发调用;
- 能力从 API 26 才开放,所以 HAR 的
compatibleSdkVersion必须是 26。
这四条里,第一条和第三条最容易被低估。2048 的输入上限看起来宽裕,但 4 倍输出就是 8192px;再加上 PNG data: URI 要经过 RN 桥、进 JS 堆,字符串会大到不可接受。所以这个库把输入长边先缩到 512px,输出 2048px:
const MAX_INPUT_EDGE = 512;
const AI_FACTOR = 4;
const MAX_OUTPUT_EDGE = MAX_INPUT_EDGE * AI_FACTOR; // 2048
512 是一个折中值:AI 模型对 512 的输入仍有明显的细节补全效果,输出 2048 既落在官方规格内,PNG base64 也还在桥能承受的范围。验收记录里同一尺寸的 512 × 341 图输出 2048 × 1364,PNG base64 约 4,787,226 字符——这已经是一个接近 4.8 MB 的字符串了。如果再放大输入,字符串会线性膨胀,移动端 JS 堆首先吃不消。
为什么还要一套 CPU 引擎
如果只做 AI 路线,这个库在非鸿蒙宿主、API 26 以下、AI 异常、2×/3× 请求这四种情况下都会直接不可用。所以它带了一套确定性 Catmull-Rom 双三次引擎:
- 同一份
SuperResolutionEngine.ts在src/(纯 TS)和harmony/.../sr/SrEngine.ts(ArkTS)各放一份,两份逐字节相同,CI 会校验; - 支持 2/3/4 倍;演示语料是三个 96×64 的程序化场景(人像、标签、截图),不依赖图片解码器;
- 每个结果带 8 位 FNV-1a
checksum,同一张图在原生和纯 TS 两侧必须得到同一个值; - 非鸿蒙宿主上
superResolution返回null,调用方可以降级到upscale(),而不是崩掉。
CPU 引擎在这里提供的是可复现的基准:没有它,就无法证明 AI 输出的像素是对的。 页面上的 原生与纯 TS 引擎 JSON 逐字符一致,比任何"AI 已启用"的文案都可信。
校验和的成本
AI 路线也会算 checksum,代价是把 4× 的 PixelMap 读回 RGBA:
- 2048 × 2048 × 4 字节 = 16 MB(截图这张 2048 × 1364 约 11.2 MB);
- 读回、遍历、FNV-1a 计算、再重新封装成
PixelMap,真机上大约 200–500ms; - 这段时间被算进
durationMs,所以 AI 的端侧耗时看起来比"纯推理"高。
这是刻意换来的:没有 checksum,AI 的结果只能靠尺寸和肉眼判断;有了 checksum,原生与纯 TS 的输出可以逐字符对拍,PNG 编码前后的像素也能自洽。对一个"看不见模型"的端侧库来说,这 200–500ms 是为可验证性付的成本。
4. 工程怎么搭:一个 npm 包、一个 source-style HAR、一个 2in1 示例
先看整体结构。这个库由一个 npm 包 + 一个原生 HAR + 一个示例宿主组成,三层各自解决不同的问题:
react-native-ohos-ai-vision/ # npm 库根目录(package.json,v0.3.0)
├─ src/ # 纯 TS:引擎、spec、安全包装
│ ├─ NativeOhosSuperResolution.ts # codegen spec:6 个方法
│ ├─ SuperResolutionEngine.ts # 演示语料 + Catmull-Rom + checksum
│ ├─ SrModels.ts # RgbaImage / Result / 校验
│ ├─ SrJson.ts # 固定字段顺序的 JSON 契约
│ ├─ nativeBridge.ts # 纯 TS 兜底,永不抛错
│ ├─ ohosModule.ts # 原生安全包装,不可用 resolve null
│ └─ index.ts
├─ lib/ # Babel CJS/ESM + tsc 声明(构建产物)
├─ harmony/
│ ├─ ohos_super_resolution/ # HAR 源模块
│ │ ├─ Index.ets / BuildProfile.ets / ts.ts
│ │ ├─ oh-package.json5 / build-profile.json5
│ │ └─ src/main/
│ │ ├─ ets/RNOhosSuperResolutionTurboModule.ts
│ │ ├─ ets/RNOhosSuperResolutionPackage.ets
│ │ ├─ ets/generated/ # codegen:ArkTS Spec + ts.ts
│ │ ├─ ets/sr/SrImage.ts # 解码、AI 调用、回退、出图
│ │ ├─ ets/sr/SrPixels.ts # PixelMap / 行宽 / data URI
│ │ ├─ ets/sr/SrEngine.ts # 引擎副本(与 src 逐字节相同)
│ │ └─ cpp/ # CMake + Package + codegen C++ 桥
│ └─ ohos_super_resolution.har # source-style HAR
├─ example/
│ ├─ App.tsx # 单页超分演示
│ ├─ samplePhoto.ts # 内置 512px 示例照片(base64)
│ └─ harmony/ # ★ DevEco 打开这个目录运行
├─ templates/ # 手动接线的 ArkTS / C++ 模板
├─ tools/build-har.sh # 组装 source-style HAR
├─ scripts/ # HAP 构建、包校验、bundle 预置头检查
├─ __tests__/ # Jest 29 例
├─ tests/ # node:test 原生模块 6 例
├─ artifacts/ # 构建日志与 npm 压缩包(不进包)
├─ index.d.ts / react-native.config.js
└─ README*.md / CHANGELOG.md / VALIDATION.md

三层分工要拎清,否则很容易在 DevEco 里打开错地方:
src/是纯 TS,负责确定性引擎、JSON 契约和没有鸿蒙宿主时的降级;harmony/ohos_super_resolution/是 HAR 源模块,承载 TurboModule、AI 调用和像素管线;example/harmony/才是带entry的示例宿主,DevEco 打开它才能跑;示例的deviceTypes覆盖phone、tablet、2in1,截图里就是 2in1 窗口。
这个库要同时满足三种消费者,所以 package.json 里三套入口并存:
{
"name": "react-native-ohos-ai-vision",
"version": "0.3.0",
"source": "./src/index.ts",
"main": "./lib/commonjs/index.js",
"module": "./lib/module/index.js",
"types": "index.d.ts",
"react-native": "./src/index.ts",
"harmony": {
"alias": "react-native-ohos-ai-vision",
"autolinking": {
"ohPackageName": "react-native-ohos-ai-vision",
"etsPackageClassName": "RNOhosSuperResolutionPackage",
"cppPackageClassName": "RNOhosSuperResolutionPackage",
"cmakeLibraryTargetName": "rnoh_ohos_super_resolution"
}
}
}
- Metro 走
react-native条件,直接读src/index.ts; - 不用源码的工程走
main/module和types,读lib/里的预编译产物; - RNOH 靠
harmony.autolinking找到 OHPM 包名、ArkTS Package 类、C++ Package 类和 CMake target。
HAR 是 source-style,不是 hvigor 编出来的二进制产物。tools/build-har.sh 会把 ArkTS 源码、codegen 生成的 C++ 桥、CMakeLists.txt、module.json 和 oh-package.json5 一起装进 package/,再打成 tar.gz:
STAGE_DIR="$(mktemp -d)"
PKG_DIR="${STAGE_DIR}/package"
cp -R "${MODULE_DIR}/src/main/ets/." "${PKG_DIR}/src/main/ets/"
cp -R "${MODULE_DIR}/src/main/cpp/." "${PKG_DIR}/src/main/cpp/"
(cd "${STAGE_DIR}" && COPYFILE_DISABLE=1 tar --exclude='._*' --exclude='.DS_Store' \
-czf "${OUTPUT_HAR}" package)
原因很实际:RNOH autolinking 会把模块的 src/main/cpp 加进宿主构建,所以 HAR 里必须有 C++ 源码、生成的 OhosSuperResolution.cpp 和 CMake 文件;只发编好的 HAR,宿主那边就没有可以链接的 target。HAR 是能力,编译发生在宿主。
HAR 的 module.json 里还有两个硬约束:
{
"app": { "bundleName": "com.reactnative.aivision", "minAPIVersion": 260000026 },
"module": { "name": "ohos_super_resolution", "type": "har", "deviceTypes": ["phone", "tablet", "2in1"] }
}
minAPIVersion 直接卡在 26:imageSuperResolution 是 API 26 才开放的能力,低版本系统找不到该服务,模块加载会失败。纯 TS 引擎不受这条限制,可以在任意 RN ≥ 0.68 的宿主里用。
示例宿主的接线只有三处。ArkTS 侧注册 Package:
// example/harmony/entry/src/main/ets/RNPackagesFactory.ets
import { RNOHPackage, RNPackageContext } from '@rnoh/react-native-openharmony';
import { RNOhosSuperResolutionPackage } from 'react-native-ohos-ai-vision';
export function createRNPackages(ctx: RNPackageContext): RNOHPackage[] {
return [new RNOhosSuperResolutionPackage(ctx)];
}
C++ 侧把生成的 Package 加进 PackageProvider,CMake 侧把 target 链上:
add_subdirectory("${OH_MODULE_DIR}/react-native-ohos-ai-vision/src/main/cpp" ./ohos_super_resolution)
target_link_libraries(rnoh_app PUBLIC rnoh_ohos_super_resolution)
对使用方来说,最终看到的 API 只有两类:一次能力探测,和一次超分。
const caps = await capabilities(); // 非鸿蒙宿主为 null
if (caps?.coreVision) {
const uri = await pickImage(); // 取消时 null
if (uri !== null) {
const result = await superResolution(uri, 4);
console.log(result?.engine, result?.outputWidth, result?.durationMs);
}
}
下面就按"路由 → 双三次 → 像素管道 → 桥接 → 交付"的顺序,把代码拆开讲。
5. 把代码讲透
5.1 路由:先问 AI 能不能跑,再决定谁来放大
所有超分请求都汇到 processPixelMap。它的结构是一个"先试 AI、失败再退 CPU"的分支:
if (factor === AI_FACTOR && coreVisionAvailable()) {
let candidate: image.PixelMap | null = null;
let aiInput: image.PixelMap | null = null;
try {
// 给模型一张全新的、自己持有的 RGBA_8888 图
const sourceImage: RgbaImage = await pixelMapToRgba(pixelMap);
aiInput = await createRgbaPixelMap(sourceImage.pixels, sourceImage.width, sourceImage.height);
candidate = await runCoreVision(aiInput);
if (await hasExpectedSize(candidate, width * factor, height * factor)) {
const aiImage: RgbaImage = await pixelMapToRgba(candidate);
resultChecksum = checksum(aiImage);
engine = SuperResolutionEngineKind.CoreVision;
// 重新封装,编码器不直接碰服务自己的 native buffer
output = await createRgbaPixelMap(aiImage.pixels, aiImage.width, aiImage.height);
} else {
const info: image.ImageInfo = await candidate.getImageInfo();
Logger.warn(`Core Vision size mismatch: ${info.size.width}x${info.size.height}, ` +
`expected ${width * factor}x${height * factor}; using bicubic`);
}
} catch (error) {
Logger.warn(`Core Vision fallback to bicubic: ${describeError(error)}`);
} finally {
await releasePixelMap(aiInput);
await releasePixelMap(candidate);
}
}
if (output === null) {
const source: RgbaImage = await pixelMapToRgba(pixelMap);
const upscaled: RgbaImage = upscale(source, factor);
resultChecksum = checksum(upscaled);
output = await createRgbaPixelMap(upscaled.pixels, upscaled.width, upscaled.height);
engine = SuperResolutionEngineKind.LocalBicubic;
}
这段代码里有四个刻意的处理,每一个都对应一类真机问题:
第一,给模型一张"干净"的输入图。 解码器产出的 PixelMap 带着解码器的元数据,直接交给 AI 模型不一定稳妥;代码先 pixelMapToRgba 读出像素,再 createRgbaPixelMap 造一张全新的、OPAQUE、RGBA_8888、自己持有的图。这一步多一次拷贝,但把"模型能不能吃这张图"变成了确定的事。
第二,AI 的结果要验尺寸。 官方说输出 4 倍,不代表每次都对。hasExpectedSize 在拿到 candidate 后先看 ImageInfo,尺寸不对就记一条 warn,走 CPU 分支。没有这一步,页面可能把一张尺寸不对的图标成 4 倍。
第三,AI 的输出也要重新封装。 candidate 是服务返回的 native buffer,直接交给 ImagePacker 编码可能受服务生命周期影响;代码先读成 RgbaImage、算 checksum,再用 createRgbaPixelMap 造一张自己的图给编码器。candidate 在 finally 里释放。
第四,engine 只在尺寸校验通过后才改。 这样"AI 跑过但结果不合规"不会被误报成 core-vision;页面上的 实际引擎 永远对应真正产生像素的那条路。
runCoreVision 本身很短,但那个 request 的写法是整篇文章的起点:
async function runCoreVision(pixelMap: image.PixelMap): Promise<image.PixelMap> {
const analyzer: imageSuperResolution.ImageSRAnalyzer =
await imageSuperResolution.ImageSRAnalyzer.create();
try {
// visionBase.Request 没有公开构造函数,不能 new
const input: visionBase.ImageData = { pixelMap };
const request: visionBase.Request = { inputData: input };
const response: imageSuperResolution.ISPResponse = await analyzer.process(request);
return response.pixelMap;
} finally {
try {
await analyzer.destroy();
} catch (error) {
// 释放不能掩盖处理错误
}
}
}
最后是并发锁。官方说同一进程不支持并发,原生模块用一个模块级 busy 标志把第二次请求挡在门外:
if (busy) {
throw new Error('Image super-resolution is already running');
}
busy = true;
try {
// decode → processPixelMap → JSON
} finally {
busy = false;
}
这是"库层保护",不是"UI 层禁用"。示例页在请求期间也禁用了按钮,但真正防止 NPU 被两个请求同时占用的是 busy——任何调用方都绕不过去。
5.2 双三次:8 个抽头、两次卷积、一次取整
CPU 路线要解决两个问题:像质和确定性。像质决定回退结果能不能看,确定性决定它能不能和 ArkTS 侧逐字节对拍。
先看核函数。Catmull-Rom 的权重只跟采样点到输出点的距离有关:
function cubicWeight(distance: number): number {
const value = Math.abs(distance);
if (value <= 1) {
return ((1.5 * value - 2.5) * value) * value + 1;
}
if (value < 2) {
return (((-0.5 * value + 2.5) * value) - 4) * value + 2;
}
return 0;
}
每个轴上的输出位置只取 4 个源像素,权重按距离算一次,缓存成 indices + weights:
function buildTaps(sourceLength: number, targetLength: number): ResampleTaps {
const scale = targetLength / sourceLength;
const indices = new Int32Array(targetLength * 4);
const weights = new Float32Array(targetLength * 4);
for (let target = 0; target < targetLength; target += 1) {
const center = (target + 0.5) / scale - 0.5;
const base = Math.floor(center);
const delta = center - base;
const tap = target * 4;
indices[tap] = clampIndex(base - 1, sourceLength);
indices[tap + 1] = clampIndex(base, sourceLength);
indices[tap + 2] = clampIndex(base + 1, sourceLength);
indices[tap + 3] = clampIndex(base + 2, sourceLength);
weights[tap] = cubicWeight(delta + 1);
weights[tap + 1] = cubicWeight(delta);
weights[tap + 2] = cubicWeight(1 - delta);
weights[tap + 3] = cubicWeight(2 - delta);
}
return new ResampleTaps(indices, weights);
}
采样下标用 clampIndex 夹在 [0, length - 1],不引入镜像或循环边界。边界处理必须统一,否则原生和 TS 在图像最外一圈会算出不同的值,checksum 立刻对不上。
放大分两趟:水平趟把结果存进 Float32Array,保留小数;垂直趟读四行、加权、只在这时取整一次:
for (let x = 0; x < targetWidth * 4; x += 1) {
output[targetRow + x] = clampChannel(
horizontal[row0 + x] * weight0 +
horizontal[row1 + x] * weight1 +
horizontal[row2 + x] * weight2 +
horizontal[row3 + x] * weight3,
);
}
这样做的好处是每个输出像素的每个通道只做 8 次乘加(水平 4 次 + 垂直 4 次),而不是二维卷积的 16 次;同时只取整一次,避免两趟各自舍入带来的偏差。Float32Array 的精度足够,且所有运行时都遵循 IEEE-754,结果可复现。
确定性的另一半是 checksum。FNV-1a 的 32 位乘法在 JS 里有一个坑:Math.imul 在某些运行时/引擎版本上行为不一致。这个库手写了 16 位分段乘法:
function fnvMultiply(value: number): number {
const high = (value >>> 16) * 16777619;
const low = (value & 0xffff) * 16777619;
return (((high & 0xffff) * 65536 + (low % 4294967296)) % 4294967296) >>> 0;
}
再加上"无随机数、无平台数学库、无 SIMD"的约束,同一个 Uint8Array 在 ArkTS 和纯 TS 里必须得到同一个 8 位十六进制串。三个演示场景的 checksum 分别是 d0734028、1af608c7、5c94bc69;测试会直接执行两边的源码比对,不是只比最终 JSON。
5.3 像素进出:512、行宽、16MB 与 4.79M 字符
解码入口先把长边压到 512,并统一成 RGBA_8888:
const scale = Math.min(1, limit / Math.max(info.size.width, info.size.height));
const width = Math.max(1, Math.round(info.size.width * scale));
const height = Math.max(1, Math.round(info.size.height * scale));
const options: image.DecodingOptions = {
editable: false,
desiredPixelFormat: image.PixelMapFormat.RGBA_8888,
desiredSize: { width, height },
};
pixelMap = await source.createPixelMap(options);
512 × 341 的输入就是这样来的:原图可能是 4K,但解码时只保留长边 512,输出 2048。这一步同时决定了 AI 的输入尺寸和 PNG 的体积上限。
读像素时不能假设缓冲区紧排。PixelMap 的行宽可能带对齐 padding,readRgba 先问 getBytesNumberPerRow(),不一致就逐行重排:
const rowBytes = pixelMap.getBytesNumberPerRow();
const totalBytes = pixelMap.getPixelBytesNumber();
const buffer = new ArrayBuffer(totalBytes);
await pixelMap.readPixelsToBuffer(buffer);
const tightRowBytes = width * 4;
if (rowBytes === tightRowBytes) {
return new Uint8Array(buffer);
}
// 行尾有 padding:逐行重排到 tightRowBytes
这个细节不处理,图会越往下越斜,而且不会报错——最后只能靠肉眼发现"超分结果怎么歪了"。
AI 路线的内存开销集中在这里:candidate 是 4× 的 PixelMap,读成 RgbaImage 后是 2048 × 1364 × 4 ≈ 11.2 MB(最大 2048 × 2048 时 16 MB);aiInput、candidate、output 三张图同时在生命周期里,峰值会更高。所以 finally 里的释放顺序是:先放 aiInput 和 candidate,再放 output,最后放解码得到的 DecodedImage。任何一个漏掉,连续超分几次就会把内存占满。
出图统一走 PNG data URI:
const packer = image.createImagePacker();
try {
const option: image.PackingOption = { format: mime, quality };
const encoded = await packer.packing(pixelMap, option);
const base64 = new util.Base64Helper().encodeToStringSync(new Uint8Array(encoded));
return `data:${mime};base64,${base64}`;
} finally {
await packer.release();
}
为什么是 PNG 而不是 JPEG?超分结果是像素级的细节,JPEG 的块效应会把刚补出来的纹理再糊掉;PNG 无损,二值/图形内容也压得好。代价是字符串大:验收记录里一张 2048 × 1364 的结果 base64 约 4,787,226 字符,接近 4.8 MB。示例页的对策是在 JSON 面板里把它折成 <data URI · N chars>,真正的 result.image 仍然完整留给 <Image>:
<Image source={{ uri: result.image }} style={{ width: '100%', aspectRatio: 1.5 }} resizeMode="contain" />
data: URI 的好处是不落盘、不要权限、JS 直接能渲染;坏处是字符串要跨桥、进堆。所以输入长边取 512,不取官方允许的 2048:桥能接受的字符串体积决定了输出尺寸的上限。
5.4 桥:六个方法、六条异步元数据、一份字段顺序固定的 JSON
RN 侧对原生只有一个入口:codegen spec。src/NativeOhosSuperResolution.ts 声明了六个方法,全部返回 Promise<string>:
export interface Spec extends TurboModule {
result(index: number, revision: number): Promise<string>;
checks(): Promise<string>;
capabilities(): Promise<string>;
pickImage(): Promise<string>;
superResolution(uri: string, factor: number): Promise<string>;
superResolutionData(base64: string, factor: number): Promise<string>;
}
export default TurboModuleRegistry.get<Spec>('OhosSuperResolution');
为什么返回字符串而不是对象?因为这条契约要和纯 TS 引擎逐字符对齐。对象过桥会被重新序列化,字段顺序、数字格式、转义都可能变;字符串不会。imageResultToJson 手工拼 JSON,字段顺序就是契约的一部分:
return (
`{"uri":${jsonQuote(result.uri)}` +
`,"id":${jsonQuote(model.id)}` +
`,"source":${jsonQuote(model.source)}` +
`,"factor":${model.factor}` +
`,"inputWidth":${model.inputWidth}` +
`,"inputHeight":${model.inputHeight}` +
`,"outputWidth":${model.outputWidth}` +
`,"outputHeight":${model.outputHeight}` +
`,"engine":${jsonQuote(engine)}` +
`,"durationMs":${model.durationMs}` +
`,"checksum":${jsonQuote(model.checksum)}` +
`,"image":${jsonQuote(result.image)}}`
);
jsonQuote 不是 JSON.stringify 的包装,而是逐字符处理引号、反斜杠、换行、回车、制表符和所有 < 0x20 的控制字符。这样原生和纯 TS 的输出可以直接用字符串比较,测试里也是这么做的。
codegen 把 spec 变成两半:ArkTS 的 OhosSuperResolution.Spec 接口,和 C++ 的异步桥。生成的 OhosSuperResolution.cpp 里有六条元数据:
ARK_ASYNC_METHOD_METADATA(result, 2),
ARK_ASYNC_METHOD_METADATA(checks, 0),
ARK_ASYNC_METHOD_METADATA(capabilities, 0),
ARK_ASYNC_METHOD_METADATA(pickImage, 0),
ARK_ASYNC_METHOD_METADATA(superResolution, 2),
ARK_ASYNC_METHOD_METADATA(superResolutionData, 2),
每条告诉 RNOH 这个方法是不是异步、有几个参数。少一条,对应的 JS 方法就不会以异步方式注册,Promise 回不来。codegen 还生成了 BaseReactNativeOhosAiVisionPackage.h,C++ Package 只要继承它就能被 autolinking 找到:
namespace rnoh {
class RNOhosSuperResolutionPackage
: public BaseReactNativeOhosAiVisionPackage {
public:
explicit RNOhosSuperResolutionPackage(Package::Context ctx)
: BaseReactNativeOhosAiVisionPackage(ctx) {}
};
}
ArkTS 侧的 Package 只做一件事:把 OhosSuperResolution 这个名字映射到实现类。
export class RNOhosSuperResolutionPackage extends RNOHPackage {
getUITurboModuleFactoryByNameMap(): Map<string, (ctx: UITurboModuleContext) => UITurboModule> {
return new Map<string, (ctx: UITurboModuleContext) => UITurboModule>([
[RNOhosSuperResolutionTurboModule.NAME,
(ctx: UITurboModuleContext): UITurboModule => new RNOhosSuperResolutionTurboModule(ctx)],
]);
}
}
JS 侧不直接碰 TurboModule,而是走 ohosModule.ts 的安全包装。非鸿蒙宿主(iOS / Android / Web / Expo)上 TurboModuleRegistry.get('OhosSuperResolution') 会返回 null 或者抛错;包装层统一成 null:
function getNativeModule(): OhosSuperResolutionSpec | null {
try {
return TurboModuleRegistry.get<OhosSuperResolutionSpec>('OhosSuperResolution') ?? null;
} catch {
return null;
}
}
export async function superResolution(uri: string, factor = 4): Promise<SuperResolutionPayload | null> {
const nativeModule = getNativeModule();
if (nativeModule === null) {
return null;
}
const json = await nativeModule.superResolution(uri, factor);
return JSON.parse(json) as SuperResolutionPayload;
}
除了 superResolution(uri, factor),还有一条 superResolutionData(base64, factor):不打开文件,直接把内存里的 JPEG/PNG/WebP base64 交给原生解码。示例页内置的那张 512px 照片就是 base64,走这条路,结果里的 uri 是 memory:image。两条路径共用同一个 processPixelMap,所以 AI/CPU 的选择、checksum、PNG 编码完全一致。
capabilities() 返回设备的超分能力:
{"coreVision":true,"apiVersion":26,"factor":4,"maxInputEdge":512,"maxOutputEdge":2048}
页面顶部的三枚标签就是它:API 26、Core Vision 可用、上限 2048px。调用方可以在超分之前决定要不要走 AI,而不是等失败再猜。
5.5 交付:114 个文件、两份逐字节相同的引擎
构建分三条线:
npm run verify:package # npm pack + HAR 内容 + 类型解析 + autolinking 元数据
npm run build:har # 组装 harmony/ohos_super_resolution.har
npm run build:example # Metro bundle + ohpm install + Hvigor 构建 unsigned HAP
build:har 走 tools/build-har.sh,verify:package 走 scripts/verify-package.cjs。后者不信任工作区,而是先 npm pack,再解开 tarball 逐项断言:入口文件、lib 的 CJS/ESM/声明、HAR 内的 OhosSuperResolution.cpp、SrImage.ts、SrEngine.ts,以及 package.json 里的四个 autolinking 字段。它还会拒绝 oh_modules、build、.hvigor、.cxx、artifacts 和签名材料。
当前包的结果是 114 个文件、100,741 字节(解包后 353,172 字节),包内容、HAR、Node16/Node 类型解析与 autolinking 元数据全部通过。示例 HAP 是 39,952,884 字节(约 38 MB);从 npm 压缩包安装、走 autolinking 构建的独立消费方 HAP 是 39,745,429 字节。
这里要说的是引擎的两份副本。HAR 必须自包含,所以 src/SuperResolutionEngine.ts 和 harmony/ohos_super_resolution/src/main/ets/sr/SrEngine.ts 各放一份,内容逐字节相同;tests/native-module.test.cjs 会直接读两个文件做字节比对。任何一边改了算法、忘了同步另一边,测试立刻失败。跨语言契约靠两份文件必须一样来约束,文档只是说明。
6. 我踩过的坑(每一条都有真实报错或真机现象)
以下坑全部来自这次开发的报错、真机现象和排查记录,按踩到的顺序排列。
坑一:visionBase.Request 不能 new,AI 路线静默退回 CPU。 这是整篇文章的起点。第一次在鸿蒙 PC 上跑,页面 nativeBridge: OK、Core Vision 可用,选图后结果尺寸也对,但 实际引擎 显示 本地双三次(CPU)。日志里只有一条被 catch 接住、没有往上抛的:
Constructor is false
原因是 visionBase.Request 没有公开构造函数,官方示例用的是类型化对象字面量:
const request: visionBase.Request = { inputData: input };
改掉之后 engine 立刻变成 core-vision。这个坑的教训是:回退路径太顺滑,会把失败伪装成成功。 如果页面不显示 engine,我会一直以为 NPU 在跑。
坑二:setCaps 拼错,首次安装页面直接报错。 示例页把 setCapabilities 写成了 setCaps,真机首次安装显示:
nativeBridge: FAILED · Property 'setCaps' doesn't exist
这类错误在 TypeScript 里本应被 tsc 挡住,但示例页当时没有走完整的类型检查路径。修复就是改名,教训是:示例代码也要进类型检查,不能因为"只是 demo"就放过。
坑三:Logger 的 hilog 格式串多了一个参数。 原代码:
hilog.error(0x0000, 'OhosSuperResolution', '%{public}s, %{public}s', message);
格式串有两个占位符,只传了一个参数,日志尾部残留一个 %{public}s。它不影响功能,但会污染每一条日志。改成 '%{public}s' 即可。这种问题只有真机看日志才会发现,单测和编译都不会报。
坑四:AI 说它是 4×,不代表它真的是 4×。 官方承诺输出固定 4 倍,但代码不能只信承诺。hasExpectedSize 在拿到 candidate 后先读 ImageInfo,尺寸不对就记一条 warn 并走 CPU 分支。这个检查没有等它出问题才加——如果没有这道检查,一旦某个设备/图片返回了非 4 倍的结果,页面会把它标成 core-vision,用户看到的"4×"就只是个标签。尺寸是模型契约的一部分,必须验。
坑五:4× 的 PixelMap 读回来是 16MB,checksum 不是免费的。 AI 路线为了算 checksum,要把 2048 × 2048 的 RGBA 读回 ArkTS 侧可比较的缓冲区:16 MB 内存、200–500ms 的遍历。一开始我以为 checksum 只是"加个哈希",实测才发现它把 AI 的端侧耗时抬高一截。最后的取舍是保留:没有它,原生和纯 TS 的一致性只能靠肉眼;有了它,两边可以逐字符对拍。代价写进 durationMs,不藏。
坑六:4.79M 字符的 base64,先把调试面板卡住了。 第一版把 result.image 原样塞进页面上的 JSON 预览,验收记录里一张 2048 × 1364 的图让页面明显卡顿——PNG 本身不算大,但 base64 膨胀 33%,再经过一次 JSON.stringify 和一次桥传输,字符串在 JS 堆里翻了几倍。修复是示例页在展示 JSON 前把 data: 字段折成 <data URI · N chars>;原生侧把输入长边压在 512,从源头上限制输出体积。如果业务真的需要归档大图,正确做法是让原生写沙箱文件返回 file://,而不是把几 MB 的字符串塞进 JSON。
7. 现在怎么用:从一次 pickImage 到一张 2048 的图
这个工程现在是一个标准的 React Native 三方库(包名 react-native-ohos-ai-vision,版本 0.3.0)。仓库已经按 npm 发布形态准备好,现阶段用本地 tarball 或 path 依赖接入:
# 先生成压缩包
npm pack
# 在应用的 JS 根目录安装
npm install /absolute/path/to/react-native-ohos-ai-vision-0.3.0.tgz
它只使用 peer 依赖,不捆绑 react / react-native;纯 TS 路径要求 react-native >= 0.68,原生路径要求 HarmonyOS 7(API 26)+ RNOH 0.84。本文的验证环境是 React 19.2.3 + RN 0.84.1 + RNOH 0.84.3。
最小用法:
import React, { useState } from 'react';
import { Image, Pressable, Text, View } from 'react-native';
import {
capabilities,
isOhosSuperResolutionAvailable,
pickImage,
superResolution,
type SuperResolutionPayload,
} from 'react-native-ohos-ai-vision';
export function UpscaleCard() {
const [result, setResult] = useState<SuperResolutionPayload | null>(null);
const [message, setMessage] = useState('选择一张低清照片');
const run = async () => {
if (!isOhosSuperResolutionAvailable()) {
setMessage('当前宿主没有注册原生 OhosSuperResolution');
return;
}
const caps = await capabilities();
setMessage(`API ${caps?.apiVersion} · Core Vision ${caps?.coreVision ? '可用' : '不可用'}`);
const uri = await pickImage();
if (uri === null) {
return;
}
const payload = await superResolution(uri, 4);
if (payload === null) {
setMessage('原生超分模块不可用');
return;
}
setResult(payload);
setMessage(`超分完成 · ${payload.engine} · 端侧 ${payload.durationMs}ms`);
};
return (
<View>
<Pressable onPress={run}><Text>选择图片并超分(4×)</Text></Pressable>
<Text>{message}</Text>
{result !== null ? (
<>
<Image source={{ uri: result.image }} style={{ width: '100%', aspectRatio: result.outputWidth / result.outputHeight }} resizeMode="contain" />
<Text selectable>校验和 {result.checksum} · {result.outputWidth} × {result.outputHeight}</Text>
</>
) : null}
</View>
);
}
返回结构:
| 字段 | 类型 | 说明 |
|---|---|---|
uri | string | 输入图片 URI;内存图路径为 memory:image |
id / source | string | 结果标识与来源标签 |
factor | number | 本次放大倍数(2/3/4) |
inputWidth / inputHeight | number | 解码后的输入尺寸(长边 ≤ 512) |
outputWidth / outputHeight | number | input × factor,由模型构造器强制 |
engine | 'core-vision' | 'local-bicubic' | 实际产生像素的路线 |
durationMs | number | 设备端实测(解码 + 推理 + 读回 + checksum + 编码) |
checksum | string | 8 位小写十六进制 FNV-1a |
image | string | PNG data: URI,可直接 <Image> 渲染 |
API 一览:
| API | 说明 |
|---|---|
superResolution(uri, factor = 4) | 文件/相册 URI 的端侧超分;不可用时 resolve null |
superResolutionData(base64, factor = 4) | 内存 JPEG/PNG/WebP base64 超分;uri 为 memory:image |
pickImage() | 系统 PhotoViewPicker;取消或不可用时 null,不需要相册权限 |
capabilities() | { coreVision, apiVersion, factor, maxInputEdge, maxOutputEdge } |
isOhosSuperResolutionAvailable() | 原生模块是否注册 |
resultJson / checksJson | 原生演示结果 / 自检 JSON;不可用时 null |
SuperResolutionEngine | 纯 TS 确定性引擎(demoImage / result / runChecks) |
upscale(image, factor) | 2/3/4 倍双三次放大,返回 RgbaImage |
checksum(image) | 8 位 FNV-1a 校验和 |
toJson / imageResultToJson | 固定字段顺序的 JSON 序列化 |
superResolutionResultJson / runChecksJson | 纯 TS 桥接,失败返回 {"error":"..."} 而不抛错 |
构建与验证:
npm ci
npm test # Jest 29 例 + node:test 原生模块 6 例
npm run typecheck # tsc --noEmit
npm run build:har # 组装 source-style HAR
npm run build:example # 构建示例 HAP(需要 DevEco 的 hvigor / ohpm)
npm run verify:package # 校验 npm tarball、HAR、类型与 autolinking
npm run verify:integration # 打包产物 → autolinking → 独立消费方 HAP
当前版本的验证结果:
| 项目 | 状态 |
|---|---|
npm test | 通过:Jest 29 / 29;node:test 原生模块 6 / 6 |
npm run typecheck | 通过,0 错误 |
npm run codegen:harmony | 通过:6 条 ARK_ASYNC_METHOD_METADATA,ArkTS Spec 同步 |
npm run build:har | 通过:BUILD SUCCESSFUL in 4 s 229 ms,产出 source-style HAR |
npm run build:example | 通过:Metro bundle、ArkTS/C++ 链接,unsigned HAP 39,952,884 字节(约 38 MB) |
npm run verify:package | 通过:114 个文件、100,741 字节;HAR、类型解析与 autolinking 全部通过 |
npm run verify:integration | 通过:从 npm 压缩包安装 → autolinking → 独立消费方 HAP 39,745,429 字节 |
| 真机 | HUAWEI MOR-M1 鸿蒙 PC(HarmonyOS 7.0.0.111 / API 26):engine = core-vision;512×341 → 2048×1364;端侧 2.64–2.68s、端到端 3.46–3.63s(两次记录);RGBA 校验和 67f7ebb6(验收记录);日志可见 ML_ISP_ImageSRServiceStub: initAlgorithmV2 complete, code:0 |
能力边界也写清楚:
- 原生模块只支持 API 26+:HAR 的
compatibleSdkVersion是 26,低版本系统加载会失败;纯 TS 引擎不受影响,可以在任意 RN ≥ 0.68 的宿主里跑; - AI 只支持 4×:2× / 3× 永远走本地双三次,
factor只接受 2…4 的整数; - 输入长边被压到 512:官方允许 2048,但为了让 PNG
data:URI 能通过 RN 桥,本库在解码阶段就缩到 512;需要更大输出时改MAX_INPUT_EDGE,同时要承担更大的 JS 字符串; - 不支持并发:同一进程第二次调用会 reject
Image super-resolution is already running,UI 应该在请求期间禁用入口; - 它不是"万能增强":文字截图属于分布外输入,笔画会被模型"脑补",不如本地双三次好读;自然照片才是 AI 路线的正确演示对象;
- checksum 有成本:4× RGBA 读回 + 遍历约 200–500ms,已计入
durationMs;不需要跨端对拍时可以在宿主侧关掉这段逻辑(需要改原生实现); - 结果不落盘:PNG 以
data:URI 返回,适合展示与转发,不适合归档超大图;需要落盘时由业务把 base64 写到沙箱。
更完整的说明在仓库的文档里:
- 能力、API、JSON 契约、算法与兼容性;
- RNOH 接入、手动链接、构建与真机验收步骤;
- 构建记录、包校验与已知约束;
example/App.tsx:本文截图对应的单页超分示例;templates/:宿主手动接线的 ArkTS / C++ 模板。
同系列的其它实现走了不同的路:kmp-ohos-ai-vision、electron-ohos-ai-vision、cordova-ohos-ai-vision 共享同一份 JSON 契约,但承载方式各不相同;RN 这条选的是 TurboModule + NPU + 确定性双三次兜底,一次调用同时拿回像素与可验证的元数据,不申请相册权限,也不落盘。
更多推荐

所有评论(0)