Qt 鸿蒙端侧图像超分实战:小图放大 4 倍,像素怎么过桥
一个只对 ArkTS 开放的端侧模型、一条同进程的回环 HTTP 桥、一次 4 倍(面积 16 倍)的重建——这篇文章用一个 Qt 6 CMake 库加一套可导入 DevEco 的 ArkTS 壳,把“怎么放大、怎么过桥、怎么显示”这三件事拆开讲。
仓库地址:https://atomgit.com/oh-tpc/qt-ohos-ai-vision
三方框架版本:https://wiki.qt.io/Qt_for_HarmonyOS
组织仓库链接:https://atomgit.com/ohos-qt
0. 环境与实测设备
三方库适配信息:
| 三方库 | 版本 | 形态 | 仓库地址 |
|---|---|---|---|
| qt-ohos-ai-vision | 0.2.0 | Qt 6 CMake 库(add_subdirectory / FetchContent,默认静态库) | https://atomgit.com/oh-tpc/qt-ohos-ai-vision |
| qt-ohos-ai-vision(ArkTS 侧) | 0.2.0 | HarmonyOS stage 工程(ohos/ 目录 + examples/ohos-app 完整 HAP) | 同仓库 |
实测环境:
| 项 | 版本/型号 |
|---|---|
| Qt | 6.11.0(桌面,Homebrew qtbase/qtdeclarative);库基线 Qt 6.5+;设备端 Qt for HarmonyOS 6.12 technology preview 载具(部署步骤见 OpenHarmony 示例说明) |
| 系统 SDK | HarmonyOS 26.0.0(API 26);compatible / compile / target 均 26.0.0 |
| DevEco Studio | 6.x(签名、真机运行、HAP 调试) |
| 构建 | 桌面 macOS arm64、Xcode 26.2、CMake 4.3.2、Ninja 1.13.2;设备 hvigor 6.26.4 |
| 测试 | QtTest 19 项(结果解析 9 + 引擎状态机 10;mock 传输,不开 socket) |
| 能力 | Core Vision Kit imageSuperResolution,API 26 起,固定 4×,仅中国境内 |
| 实测设备 | HUAWEI MateBook Pro S(MOR-M1),HarmonyOS 7.0.0.111(SP15C00E101R9P2),API 26 |
| 实测 | 360×240 → 1440×960(60 / 98 ms,PNG 1606 KB);419×600 → 1676×2400(210 ms,PNG 6890 KB);640×427 → 2560×1708(274 ms);3000×2000 → 1024×683 → 4096×2732(670 ms,响应 15,162,995 B,端到端约 4.9 s) |
1. 超分不是“放大”:我遇到的问题
这个仓库不是从零开始的。上一版是 qt-ohos-ocr:把 Core Vision Kit 的 textRecognition 接进 Qt,桥、引擎、单测、ArkTS 侧工程都已经跑通。后来翻 @kit.CoreVisionKit 的时候看到 imageSuperResolution:API 26 起、固定 4 倍、端侧、不需要联网。对 Qt 来说,这是另一个“ArkTS 有、C++ 没有”的能力,而且比 OCR 更适合展示——文字识别是一行行文本,超分是一张能直接放在窗口里对比的图。
桥不用重写。要换的是结果模型、尺寸策略,以及桥另一端的负载:OCR 传的是几 KB 的 JSON,超分传的是一张 1.6 MB 到 11 MB 的 PNG,base64 之后 JSON 能到 15 MB。同一个 127.0.0.1,同一套路由,负载换了一个量级。
我一开始对超分的理解很朴素:放大不就是插值吗?drawImage 一行、Lanczos 一下,像素变多,信息不变。第一次把内置的 360×240 样例丢进去,出来 1440×960、PNG 1606 KB;第二次从系统相册选了一张 419×600 的森林照片,出来 1676×2400、PNG 6890 KB。看到 6890 KB 那个数字,我才意识到这不是“画布变大”:模型真的在补细节,补出来的还是一张几 MB 的图,要原样搬回 Qt。
于是问题变成三个:
- 尺寸:4× 是宽高各 4 倍、面积 16 倍。什么图直接送、什么图先缩、输出多大、内存怎么算,得有一本明账。
- 传输:请求体是裸字节,响应体是 base64;大的响应 15 MB,不能指望一次 socket send 发完,还要定界、分片、超时。
- 显示:QML 的
Image要 URL,不要内存里的QImage;结果要落盘、要能保存、要能原图/结果对照,还要把downscaled这类元数据如实传给 UI。
下面是干完之后的记录,坑都在第 6 节。
2. 效果展示
先看效果。这三张运行图来自两个 UI 宿主:前两张是 examples/ohos-app 的 ArkTS 演示页,第三张是 Qt Quick 窗口。它们调的是同一个 SuperResolution、同一条桥。
第一张是内置示例,一张 360×240 的低清风景:山脊、太阳、芦苇、几只鸟。ArkTS 页跑完写的是 完成:360 × 240 → 1440 × 960,下面一行 原生耗时 60 ms · 输出 PNG 1606 KB。左边原图、右边 4× 结果;原图在卡片里被放大到和结果一样宽,所以两边构图一模一样——4 倍不在缩略图里,在文件里。内置示例也不是随便找的图:tools/make_sample.py 先画一张 1440×960,再缩到 360×240;4× 超分正好是这个过程的逆操作。这样至少知道“原本的细节”长什么样,不会被 4× 的数字唬住。

第二张换了一张 419×600 的森林照片,从系统相册选进来。输出 1676×2400、210 ms、PNG 6890 KB。1676 = 419 × 4、2400 = 600 × 4,宽高各 4 倍,像素数是 16 倍。这张图的信息量比内置示例大得多,PNG 从 1.6 MB 涨到 6.9 MB,base64 之后 JSON 约 9.2 MB——这是后面桥要面对的负载。
这张 419×600 的森林图在 Cordova 那篇里也出现过;那边写的是 344 ms、920.3 KB JPEG,这边是 210 ms、6890 KB PNG。数字别直接比:210 ms 只量 analyzer.process(),344 ms 是 Cordova 整条链路(含解码/编码/预览);JPEG 和 PNG 也不是一个体积口径。能横向比的只有输入/输出尺寸——都是 419×600 → 1676×2400。

第三张是 Qt Quick 窗口,同一张内置示例:360 × 240 → 1440 × 960 · 原生耗时 98 ms,PNG 1606 KB,底部 ArkTS 桥 127.0.0.1:52141 · 协议 1 · v0.2.0 · 设备支持。这张不是 mock:设备上跑着 ArkTS 桥,开发机用 hdc fport tcp:52141 tcp:52141 把端口转过来,Qt 示例用 QTOHOS_AI_VISION_ENDPOINT 直连,第 2 节那张 Qt 截图就是这么截的。Qt 窗口比 ArkTS 页多两个按钮:系统相册(只在 available && supported && pickerAvailable 时出现)和 保存结果(把当前 PNG 另存)。ArkTS 页只有选图和内置示例;两边是同一套桥,UI 各自按宿主能力裁剪。

同一张 360×240,ArkTS 页 60 ms,Qt 窗口 98 ms,PNG 都是 1606 KB。不是 Qt 慢,也不是两次结果不同:elapsedMs 只量 analyzer.process(),模型实测在 61–105 ms 之间浮动,60 和 98 都在这个量级;三次实测的输出逐字节一致,说明模型对同一输入是确定性的,差异只在耗时,不在像素。真要比快慢,得把解码、PNG 编码、base64、HTTP 传输都算进去,那是另一个数字。
这里得说清楚:截图里看不出 4 倍。Qt 窗口 1080 宽,左右各一张卡,1440×960 的结果被压到四百多像素宽;ArkTS 页同理。整图缩略只用来看构图和颜色,判断 4× 得把两边都放到 1:1 像素下裁一块对比——Cordova 那篇做过 1:1 细节区,Qt 示例目前没有,这是它不如那篇直观的地方。要补也不难:在 ImageCard 里加一个裁切/放大模式,或者单独开一个细节对比页。
截图时还遇到过一次 offscreen 渲染的纹理残影:连拍时画面里叠着上一张的纹理,重拍就没了。三次模型输出逐字节一致(diff max 0),所以那是渲染/截图的锅,不是模型的。遇到类似现象,先重拍,别急着怀疑 NPU。
3. 4 倍之后,像素从哪来:一次超分的六段链路
写代码之前得先把原理捋好。一次 4× 超分从用户点按钮开始,到 QML 拿到 imageUrl 结束,中间是六段:
QML / C++:enhanceFile / enhanceBytes / pickAndEnhance
│
▼
QOhosSuperResolution(C++) Idle → Busy → enhanced / failed
├─ 读文件:QtConcurrent 工作线程
├─ 请求:BridgeHttpTransport(QNAM)
└─ 结果:base64 PNG → QImage + 临时文件 URL
│
▼ POST /v1/enhance?source=... raw PNG/JPEG bytes
127.0.0.1:52141(同进程回环)
│
▼
SrBridgeService(ArkTS,573 行) 手写 HTTP/1.1 子集
├─ 解析 Content-Length / 半包
├─ 路由 /v1/ping · /v1/enhance · /v1/pick
└─ 响应按 128 KiB 分片写回
│
▼
SuperResolution(ArkTS)
├─ ImageSource → PixelMap(必要时先缩到长边 1024)
├─ ImageSRAnalyzer.create()(进程内复用)
├─ analyzer.process()(串行、60 s 超时)
└─ PixelMap → PNG → base64
│
▼
Core Vision Kit · imageSuperResolution(端侧 NPU / 系统服务)
第 1 段:按钮。 QML 调 enhanceFile()、enhanceBytes() 或 pickAndEnhance()。读文件在 QtConcurrent 工作线程;busy 立刻置 true,一直保持到结果或失败回来。Busy 期间再点,直接 SR_BUSY,不排队。
第 2 段:请求。 编码后的图片字节原样 POST,Content-Type: application/octet-stream,不做 base64。/v1/enhance 的传输超时 120 秒,/v1/ping 20 秒,/v1/pick 600 秒——选图要等用户,不能 2 分钟就掐。
第 3 段:桥。 SrBridgeService 读 Content-Length,半包就等下一段 message;三个路由各自处理。请求体是裸字节,响应体是 UTF-8 JSON。
第 4 段:模型。 SuperResolution 解码成 PixelMap;长边超过 1024 先等比缩到 1024;ImageSRAnalyzer.create() 建分析器,analyzer.process() 出 4× PixelMap。同一进程同一特性不支持并发,所以 ArkTS 侧用 Promise 链串行,单次 60 秒超时;超时就丢弃分析器,下一次重建。
第 5 段:回包。 PixelMap 编成 PNG,base64 塞进 JSON;几何、耗时、downscaled 一起回。响应按 128 KiB 分片写,Content-Length 是完整 JSON 的字节数。
第 6 段:Qt。 QJsonDocument 解析,base64 解回 PNG,QImage::fromData() 解码;结果 PNG(以及可解码的原图)各写一份到临时目录,imageUrl / sourceUrl 给 QML,QImage 给 C++;发 enhanced()。
把尺寸列出来,4× 的成本就很直观了:
| 输入 | 送入模型 | 输出 | 输出像素 | 输出 RGBA | 输出 PNG | 响应 JSON |
|---|---|---|---|---|---|---|
| 200×150 | 200×150 | 800×600 | 0.48 MP | 约 1.8 MB | — | — |
| 360×240 | 360×240 | 1440×960 | 1.38 MP | 约 5.5 MB | 1606 KB | 约 2.1 MB |
| 419×600 | 419×600 | 1676×2400 | 4.02 MP | 约 16.1 MB | 6890 KB | 约 9.2 MB |
| 640×427 | 640×427 | 2560×1708 | 4.37 MP | 约 17.5 MB | — | — |
| 3000×2000 | 1024×683 | 4096×2732 | 11.19 MP | 约 44.7 MB | 约 11 MB | 15,162,995 B(约 15 MB) |
“输出 RGBA”是按 宽 × 高 × 4 算的,“响应 JSON”是按 PNG 的 4/3 估的;1606 KB、6890 KB、15,162,995 B 是实测或记录里的数,其余标了“约”。这张表要说明的是面积 16 倍:PNG 编码、base64、socket send、Qt 解码、QImage 内存,每一层都按 16 倍像素算。
1024 这个数是算出来的,不是拍脑袋的。 模型的输入约束是宽高都大于 16、小于 2048,官方建议 1024 以下。一个 3:2 的 2047×1365 图,4× 之后是 8188×5460,RGBA 约 178 MB;3000×2000 不缩的话,输出 12000×8000(96 MP),更不用说。本库把长边钳到 1024:3000×2000 先缩到 1024×683,再出 4096×2732。downscaled 为 true,inputWidth/Height 一起回传,UI 会写“输入已缩放到 …”。
请求方向和响应方向是不对称的。 请求不做 base64,QNAM 直接 POST 原始字节,省一次编码,也省 1/3 体积;响应必须 base64,因为 JSON 要自带几何、耗时、downscaled、错误和图片。如果返回裸 PNG,就得自定义响应头或多段协议,curl 和调试都变麻烦。代价是响应体积 +33%,这也是为什么 1024 的上限不能松。
为什么是回环 HTTP,而不是别的? 把可选通道摆在一起:
| 方案 | 结论 |
|---|---|
| N-API 回调 | C++ 无法发起调用,需要 ArkTS 主动轮询,侵入 Qt 事件循环 |
| 共享内存 / 文件 | 同步与生命周期复杂,跨语言约定多,大图还要自己分片 |
| WebSocket / 自定义 TCP | 需要事件循环与大消息分片,收益不明显 |
| 回环 HTTP(本方案) | 请求-响应语义天然匹配、两端都易实现、可 curl 直接调试 |
和系列里其它载具摆在一起,Qt 这一格的特殊之处还是“载具本身没有 C++ → ArkTS 通道”:
| 载具 | 与 ArkTS 的通道 | 谁调系统 API |
|---|---|---|
| 原生 ArkTS | 同语言直接调用 | ArkTS |
| KMP(kmp-ohos-ai-vision) | Kotlin/Native → C ABI → N-API | ArkTS |
| Cordova(cordova-ohos-ai-vision) | Cordova 插件(ArkTS 侧实现) | ArkTS |
| Flutter(flutter_ohos_core_vision) | MethodChannel 插件 | ArkTS |
| React Native(react-native-ohos-ai-vision) | RNOH 原生模块 | ArkTS |
| Electron(electron-ohos-ai-vision) | hdc 四步 + 设备侧 ArkTS 代理 | 设备代理 |
| Qt(本库) | 同进程 127.0.0.1 回环 HTTP(QNAM) | ArkTS 桥 |
能力边界也如实写:固定 4×,没有倍数参数,也没有 1× 增强/去噪;输入宽高必须大于 16,长边超过 1024 会先缩;同一进程串行,一次一张;输出 PNG 1.6–11 MB,base64 后 2.1–15 MB,最大那档端到端约 5 秒;仅 API 26+ 的 phone/tablet/2in1,仅中国境内;桌面必须靠 mock 或设备转发桥。ArkTS 演示页底部那行 需要 HarmonyOS 26.0.0(API 26)及以上,能力仅在中国境内提供 不是装饰,是硬门槛。但超分补的是统计上合理的细节,不是事实——别拿它去做取证、医学影像,或者把模糊车牌“变清楚”。
性能账再记一笔:360×240 的模型耗时 60–105 ms,419×600 是 210 ms,640×427 是 274 ms,3000×2000 送进模型的是 1024×683,模型 670 ms。大图的时间主要花在回包:15.16 MB 的 JSON、116 个 128 KiB 分片、base64 和 PNG 编码,端到端约 4.9 秒。模型是几百毫秒的事,搬运是几秒的事——超分把桥的负载从 KB 级推到了 MB 级。
4. 工程怎么搭:一份 CMake 库,一份 ArkTS 工程
先看整体结构。库本体是标准 Qt 6 CMake 工程,ohos/ 是待合并进载具的 ArkTS 侧文件,另有桌面示例和可直接导入 DevEco 的完整鸿蒙工程:
qt-ohos-ai-vision/
├─ include/qt-ohos-ai-vision/ # 公共头:引擎 / 结果 / 传输接口
│ ├─ qohossuperresolution.h # QML/C++ 异步门面
│ ├─ ohossuperresolutionresult.h # Q_GADGET 结果 + 几何/耗时/PNG
│ └─ bridge/
│ ├─ BridgeTransport.h # IBridgeTransport(mock 注入点)
│ └─ BridgeHttpTransport.h # QNAM 回环实现
├─ src/ # 引擎、结果解析、回环 HTTP
├─ ohos/ # ArkTS 壳:sr/、srbridge/、EntryAbility、诊断页
├─ examples/
│ ├─ quick/ # Qt Quick 示例(前后对照 + 保存 + 截图)
│ └─ ohos-app/ # DevEco 直接导入的演示 HAP
├─ tests/ # QtTest 19 项(mock 传输)
├─ tools/
│ ├─ mock_bridge.py # 桌面 4× Lanczos + 锐化模拟桥
│ └─ make_sample.py # 生成 360×240 内置样例
├─ docs/ # API、架构、验证、预览图
└─ CMakeLists.txt · README.md · README.en.md · CHANGELOG.md

这次设计最关键的决定有三个。
传输是一个接口,不是一条写死的 HTTP 调用。 IBridgeTransport 只有 ping / postEnhance / postPick 三个操作,BridgeHttpTransport 是它的 QNAM 实现。单测注入 mock,19 项测试不开 socket;未来官方开放 C++ → ArkTS 通道,换一个实现类,引擎和 QML 不动。这个注入口就是整个库的可测试性所在,也是为什么引擎能在没有设备的情况下被完整测一遍。
桌面先行的理由很实际:没有设备也能把 QML 侧做完。 桌面没有 ArkTS 运行时,但 tools/mock_bridge.py 用 Lanczos 4× + 锐化模拟同一套协议;QML 的对照、状态、错误、保存、截图都能在桌面做完。要真实结果,就 hdc fport 把设备桥转过来,Qt 示例改一个环境变量直连——同一份 QML,不换分支。第 2 节那张 Qt 截图就是后者。
ArkTS 按 merge 块组织,不替换载具的 QAbility。 把 ohos/entry/src/main/ets/sr/ 与 srbridge/ 两个目录拷进载具的 ets/,再把 EntryAbility.ets 里标好的两段合并块并进 QAbility.onCreate() / onDestroy()。嫌麻烦就直接用 examples/ohos-app/——一套能导入、能签名、能跑的完整 stage 工程。
对 QML 侧来说,API 就这么点:
import QtOhosAiVision 1.0
QOhosSuperResolution {
id: sr
onEnhanced: (result) => {
viewer.source = result.imageUrl // 已落盘的临时 PNG
console.log(result.outputWidth + "×" + result.outputHeight,
result.elapsedMs + " ms")
}
onFailed: (error) => console.warn(error) // "SR_CODE: message"
}
Component.onCompleted: sr.probeAvailability()
C++ 侧也一样,不经过 QML 直接用:
#include <qt-ohos-ai-vision/qt_ohos_ai_vision.h>
QOhosSuperResolution sr;
QObject::connect(&sr, &QOhosSuperResolution::enhanced,
[](const OhosSuperResolutionResult &result) {
result.image().save("enhanced.png");
qInfo() << result.originalSize() << "->" << result.outputSize()
<< result.elapsedMs() << "ms";
});
QObject::connect(&sr, &QOhosSuperResolution::failed, [](const QString &error) {
qWarning() << error;
});
sr.probeAvailability();
sr.enhanceFile(QUrl::fromLocalFile("/path/to/low-res.jpg"));
Qt 示例里“原图 / 超分结果”两张卡片的绑定也就这几行,imageUrl 和 sourceUrl 都是引擎落好的临时文件:
ImageCard {
heading: qsTr("原图")
imageSource: root.originalUrl
caption: root.result !== null
? root.result.originalWidth + " × " + root.result.originalHeight
+ (root.result.downscaled ? " · 超分前缩放到 "
+ root.result.inputWidth + " × "
+ root.result.inputHeight : "")
: "—"
}
ImageCard {
heading: qsTr("超分结果")
badge: "4×"
imageSource: root.result !== null ? root.result.imageUrl : ""
caption: root.result !== null
? root.result.outputWidth + " × " + root.result.outputHeight
+ " · PNG " + Math.round(root.result.byteSize / 1024) + " KB"
: "—"
}
下面把库内部拆开讲:引擎怎么管一次任务、桥怎么搬几 MB 的图、SuperResolution 怎么把分析器和 60 秒超时管住、结果怎么从 JSON 落成可显示的图,最后是上鸿蒙的合并链路。
5. 把代码讲透
5.1 引擎:Busy 只有一位,临时文件只有一份
QOhosSuperResolution 的状态机很小:
Idle ── enhanceBytes()/enhanceFile()/pickAndEnhance() ──▶ Busy
Busy ── 桥回复 ──▶ enhanced(result) | failed(err) ──▶ Idle
所有公开入口都在调用线程(QML 下就是 GUI 线程)立即返回。读文件丢给 QtConcurrent,传输本身是 QNAM 异步;Busy 期间再调用,直接 SR_BUSY,不改 busy。probeAvailability() 是唯一允许并行的操作——探测不该被一次大图挡住。
// src/qohossuperresolution.cpp(节选)
void QOhosSuperResolution::enhanceFile(const QUrl &fileUrl)
{
if (m_busy) {
rejectCall(QStringLiteral("SR_BUSY: an enhancement is already running"));
return;
}
// Accept file URLs, plain paths and Qt resource URLs. QFile() does not
// understand the qrc: scheme, but it does understand the ":/" form, so
// the bundled sample can stay inside the application binary.
QString path;
if (fileUrl.isLocalFile()) {
path = fileUrl.toLocalFile();
} else if (fileUrl.scheme() == QLatin1String("qrc")) {
path = QLatin1Char(':') + fileUrl.path(); // qrc:/x → :/x
} else {
path = fileUrl.toString(QUrl::PreferLocalFile);
}
if (path.isEmpty()) {
rejectCall(QStringLiteral("SR_INVALID_ARGUMENT: file URL must not be empty"));
return;
}
if (m_available && !m_supported) {
rejectCall(QStringLiteral("SR_UNSUPPORTED: this device does not advertise "
"Core Vision Kit image super-resolution"));
return;
}
setBusy(true); // held for the whole read + enhancement
auto *watcher = new QFutureWatcher<QByteArray>(this);
connect(watcher, &QFutureWatcherBase::finished, this, [this, watcher, path]() {
const QByteArray bytes = watcher->result();
watcher->deleteLater();
if (bytes.isEmpty()) {
failOperation(QStringLiteral("SR_IO_ERROR: cannot read ") + path);
return;
}
startEnhanceBytes(bytes, QFileInfo(path).fileName());
});
watcher->setFuture(QtConcurrent::run([path]() -> QByteArray {
QFile file(path);
if (!file.open(QIODevice::ReadOnly))
return QByteArray();
return file.readAll();
}));
}
这段里有四个决定:
先探测,再决定要不要发图。 如果 ping 回来 supported:false,enhanceBytes/enhanceFile/pickAndEnhance 都直接失败,不把几 MB 的图片发出去。m_available && !m_supported 这个条件很关键:还没探测过时不能拦,否则第一次调用会被误杀。
qrc: 与 :/ 是两套写法。 QFile 不认 qrc: scheme,只认 :/。内置样例用 qrc:/samples/sample.png 打进二进制,enhanceFile() 里必须映射一次,否则桌面点“内置示例”直接吃 SR_IO_ERROR: cannot read qrc:/samples/sample.png。
回调必须归一。 mock 可能在 postEnhance() 返回前就同步回调,QNAM 走的是异步信号。queued() 用 QMetaObject::invokeMethod(..., Qt::QueuedConnection) 把所有回调压到引擎线程,状态机始终单线程,测试才稳定:
// 同上(节选)
BridgeCallback QOhosSuperResolution::queued(
std::function<void(const BridgeReply &)> handler)
{
// Capture by value: the mock may fire before this function returns.
return [this, handler](const BridgeReply &reply) {
QMetaObject::invokeMethod(this, [this, handler, reply]() {
handler(reply);
}, Qt::QueuedConnection);
};
}
临时文件只有一份当前结果。 引擎把增强 PNG 和原图各写一份到 QStandardPaths::TempLocation/qt-ohos-ai-vision/,新结果替换旧文件;clearResult() 和析构都会删。QML 只拿 imageUrl,不要长期缓存那个路径——下一次超分就把文件换了。
QML 那边注册的值类型名是小写的 ohosSuperResolutionResult(qmlRegisterUncreatableType<OhosSuperResolutionResult>(..., "ohosSuperResolutionResult", ...))。QML 的值类型命名要求小写,写成大写会注册不上或 QML 侧拿不到类型;引擎类型 QOhosSuperResolution 则只注册一次。
5.2 桥服务:图片进、base64 出,中间还有 128 KiB
ArkTS 侧 SrBridgeService 用 @ohos.net.socket 的 TCPSocketServer 监听回环,路由三条:
| 方法 | 路径 | 请求体 | 响应 |
|---|---|---|---|
| GET | /v1/ping | — | {"name":"qt-ohos-ai-vision-bridge","protocol":1,"version":"0.2.0","capability":"imageSuperResolution","supported":true,"picker":true,"api":26,"scale":4,"minEdge":17,"maxEdge":1024} |
| POST | /v1/enhance?source= | 原始图片字节 | 几何 + elapsedMs + base64 PNG |
| POST | /v1/pick | — | 结果 JSON,或 {"cancelled":true} |
传输规则收得很窄:HTTP/1.1 over 127.0.0.1:52141、Connection: close、一连接一请求、Content-Length 定界、ping 20 秒 / enhance 120 秒 / pick 600 秒。OCR 那版只有 20 秒;超分把 enhance 放宽到 120 秒,是因为模型 60 秒超时之后还要 base64、分片、传输,不能 60 秒一到就把回包掐了。
响应体是手写 JSON,图片 base64 直接拼进去:
// ohos/entry/src/main/ets/srbridge/SrBridgeService.ets(节选)
private static enhanceBody(run: SrRun): string {
const helper: util.Base64Helper = new util.Base64Helper();
const data: string = helper.encodeToStringSync(run.png);
let text: string = `{"source":${jsonQuote(run.source)}` +
`,"format":"png","scale":4` +
`,"original":{"width":${run.originalWidth},"height":${run.originalHeight}}` +
`,"input":{"width":${run.inputWidth},"height":${run.inputHeight}}` +
`,"output":{"width":${run.outputWidth},"height":${run.outputHeight}}` +
`,"downscaled":${run.downscaled}` +
`,"elapsedMs":${run.elapsedMs}` +
`,"data":${jsonQuote(data)}`;
if (run.originalPng !== null) {
text += `,"originalData":${jsonQuote(helper.encodeToStringSync(run.originalPng))}`;
}
return text + '}';
}
/v1/pick 会多带一个 originalData:系统相册选中的原图编码字节,Qt 侧据此写出 sourceUrl,前后对照才有“前”。这也意味着 picker 路径的响应比 enhance 多一张原图,base64 体积更大;UI 上只是多一个左侧卡片,桥上是实打实的几 MB。
回写要分片,一次 send 只写 128 KiB:
// 同上(节选)
private async write(
client: socket.TCPSocketConnection,
handled: Handled,
): Promise<void> {
const bodyBytes: Uint8Array = SrBridgeService.encodeUtf8(handled.body);
const header: string =
`HTTP/1.1 ${handled.status} ${handled.reason}\r\n` +
`Content-Type: application/json; charset=utf-8\r\n` +
`Content-Length: ${bodyBytes.length}\r\n` +
`Connection: close\r\n` +
`\r\n`;
const headerBytes: Uint8Array = SrBridgeService.encodeUtf8(header);
const payload: Uint8Array =
new Uint8Array(headerBytes.length + bodyBytes.length);
payload.set(headerBytes, 0);
payload.set(bodyBytes, headerBytes.length);
try {
// A 4x PNG of a large input crosses a few megabytes; chunking keeps
// each socket send comfortably small.
const chunkSize: number = 128 * 1024;
for (let offset = 0; offset < payload.length; offset += chunkSize) {
const end: number = Math.min(offset + chunkSize, payload.length);
await client.send({ data: payload.slice(offset, end).buffer });
}
} finally {
SrBridgeService.closeQuietly(client);
this.drop(client);
}
}
Content-Length 是完整 JSON 的字节数,不是单个分片的长度;Qt 侧 QNetworkReply::readAll() 收齐后一次性解析。15 MB 的响应大约 116 个分片。把 15 MB 一次 send 出去,等待时间和失败面都不可控;按 128 KiB 切片,每一片都有明确的完成边界。切片大小选 128 KiB 是为了可控,与吞吐优化无关。
HTTP 解析还是那套最小子集,但有两个边界值得单独说。GET 没有 body:QNAM 的 GET /v1/ping 不带 Content-Length,解析器一开始对所有方法都要求长度,ping 直接回 411 Length Required / SR_BRIDGE_BAD_REQUEST: Content-Length is required。修复是按方法给默认值:
// 同上(节选)
if (state.contentLength < 0) {
// GET/HEAD/OPTIONS/DELETE carry no body, and Qt's
// QNetworkAccessManager does not send Content-Length for them
// (the GET /v1/ping probe is the important case).
const method: string = SrBridgeService.methodOf(headerText);
if (method === 'GET' || method === 'HEAD' ||
method === 'OPTIONS' || method === 'DELETE') {
state.contentLength = 0;
} else {
this.respondError(client, 411, 'Length Required',
'SR_BRIDGE_BAD_REQUEST', 'Content-Length is required');
return;
}
}
头部有 64 KiB 上限,超了回 431 Request Header Fields Too Large;半包则 received.length < total 就 return,等下一段 message。这两条和模型无关,是手写 HTTP 必须自己兜的底。
错误也走同一层:{"error":{"code":"SR_TOO_SMALL","message":"..."}},HTTP 状态按错误码映射——SR_INVALID_ARGUMENT / SR_INVALID_IMAGE / SR_TOO_SMALL → 400,SR_UNSUPPORTED / SR_UNAVAILABLE → 503,SR_TIMEOUT → 504,其它 SR_VISION_ERROR → 500。Qt 侧原样映射成 "CODE: message",QML 不用解析裸字符串。用户取消选图是 {"cancelled":true} → SR_PICKER_CANCELLED——取消不是错误,UI 静默处理。
5.3 SuperResolution:分析器、串行队列和 60 秒
ArkTS 侧 SuperResolution 是实际调用模型的地方。它不长,351 行,但每一段都在处理设备侧的限制:
// ohos/entry/src/main/ets/sr/SuperResolution.ets(节选)
private static async run(bytes: Uint8Array, source: string): Promise<SrRun> {
const analyzer: imageSuperResolution.ImageSRAnalyzer =
await SuperResolution.ensureAnalyzer();
let imageSource: image.ImageSource | null = null;
let input: image.PixelMap | null = null;
let output: image.PixelMap | null = null;
try {
imageSource = image.createImageSource(SuperResolution.toArrayBuffer(bytes));
const sourceInfo: image.ImageInfo = await imageSource.getImageInfo();
const originalWidth: number = sourceInfo.size.width;
const originalHeight: number = sourceInfo.size.height;
if (originalWidth < MIN_EDGE || originalHeight < MIN_EDGE) {
throw new SrError('SR_TOO_SMALL',
`Image is ${originalWidth}×${originalHeight}; both edges must be at ` +
`least ${MIN_EDGE} px`);
}
let inputWidth: number = originalWidth;
let inputHeight: number = originalHeight;
let downscaled: boolean = false;
const longEdge: number = Math.max(originalWidth, originalHeight);
if (longEdge > MAX_EDGE) {
const ratio: number = MAX_EDGE / longEdge;
inputWidth = Math.max(MIN_EDGE, Math.round(originalWidth * ratio));
inputHeight = Math.max(MIN_EDGE, Math.round(originalHeight * ratio));
downscaled = true;
}
const decoding: image.DecodingOptions = {
desiredPixelFormat: image.PixelMapFormat.RGBA_8888,
};
if (downscaled) {
decoding.desiredSize = { width: inputWidth, height: inputHeight };
}
input = await imageSource.createPixelMap(decoding);
MAX_EDGE = 1024、MIN_EDGE = 17、PROCESS_TIMEOUT_MS = 60000 是三个硬常数。1024 的来历第 3 节算过;17 是因为模型要求宽高都大于 16;60 秒是“模型卡住”和“正常大图”之间的折中——正常 1024×683 只要 670 ms,60 秒足够覆盖慢设备,又不至于让 UI 挂死。
分析器创建一次,进程内复用。 ImageSRAnalyzer.create() 不便宜;ensureAnalyzer() 先查 canIUse('SystemCapability.AI.Vision.VisionBase'),再查静态缓存,最后才 create。release() 在 EntryAbility.onDestroy() 调,analyzer.destroy() 失败也只是吞掉——进程都要走了。
模型不支持并发,所以串行。 官方约束写得很清楚:同一特性不支持同进程并发调用。serialized() 用一条 Promise 链把 run() 排成一队,前一个失败也不能堵住后一个:
// 同上(节选)
private static serialized(task: () => Promise<SrRun>): Promise<SrRun> {
const run: Promise<SrRun> = SuperResolution.tail.then(
(): Promise<SrRun> => task(),
(): Promise<SrRun> => task());
SuperResolution.tail = run.then((): void => {
}, (): void => {
});
return run;
}
注意 then 的第二个参数:上一条任务失败时也要执行下一条。只写 then(task) 的话,一次 SR_TOO_SMALL 会让整条链变成 rejected 状态,后面的调用全跟着失败——这是 Promise 链最容易踩的坑之一。
超时之后要丢掉分析器。 withTimeout() 给 analyzer.process() 套 60 秒;超时抛 SR_TIMEOUT,run() 里捕获到就把静态分析器置空并异步 destroy(),下一次调用重新 create。不丢的话,下一次会继续等一个已经卡死的实例,等于把 60 秒的坑变成永久卡死:
// 同上(节选)
const started: number = Date.now();
let response: imageSuperResolution.ISPResponse;
try {
response = await SuperResolution.withTimeout(analyzer.process(request));
} catch (error) {
if (error instanceof SrError && error.code === 'SR_TIMEOUT') {
SuperResolution.resetAnalyzer();
}
if (error instanceof Error) {
throw error;
}
throw new SrError('SR_VISION_ERROR', srErrorMessage(error));
}
const elapsedMs: number = Date.now() - started;
finally 里的释放顺序是 output → input → imageSource,逆着获取顺序,每个都包 try/catch。原因很实际:释放失败不能盖住结果或原始错误;逆序释放,避免先放掉还被前面引用的底层对象。elapsedMs 从 analyzer.process() 之前开始,到它返回结束——只算模型,不含解码、PNG 编码、base64、传输。这也是为什么 60 ms/98 ms/210 ms 这些数字不能和 Cordova 那篇的 344 ms(整条链路)直接比。
最后 encodePng() 用 image.createImagePacker(),format: 'image/png'、quality: 100;finally 释放 packer。PNG 是无损的,所以 419×600 的输出能到 6890 KB——4 MP 的 RGBA 照片本来就大,和编码优化无关。
5.4 结果解析:图片是真相,JSON 只是说明
Qt 侧 OhosSuperResolutionResult::fromWireJson() 的规则是“对负载严格,对元数据宽容”:
// src/ohossuperresolutionresult.cpp(节选)
const QByteArray png = QByteArray::fromBase64(
object.value(QStringLiteral("data")).toString().toLatin1());
if (png.isEmpty()) {
setError(errorMessage, QStringLiteral("\"data\" is missing or empty"));
return false;
}
const QImage image = QImage::fromData(png);
if (image.isNull()) {
setError(errorMessage,
QStringLiteral("the bridge returned a picture Qt cannot decode"));
return false;
}
// The picture itself is the ground truth for its dimensions.
parsed.m_png = png;
parsed.m_image = image;
parsed.m_outputSize = image.size();
parsed.m_scaleFactor = object.value(QStringLiteral("scale")).toInt(4);
if (parsed.m_scaleFactor <= 0)
parsed.m_scaleFactor = 4;
QSize input;
QSize original;
if (!readSize(object, QStringLiteral("input"), &input, errorMessage)
|| !readSize(object, QStringLiteral("original"), &original, errorMessage)) {
return false;
}
if (!input.isValid()) {
input = QSize(qMax(1, parsed.m_outputSize.width() / parsed.m_scaleFactor),
qMax(1, parsed.m_outputSize.height() / parsed.m_scaleFactor));
}
if (!original.isValid())
original = input;
parsed.m_inputSize = input;
parsed.m_originalSize = original;
parsed.m_downscaled = object.contains(QStringLiteral("downscaled"))
? object.value(QStringLiteral("downscaled")).toBool(false)
: (original != input);
几个决定值得说:
输出尺寸以解码后的图片为准,不以 JSON 为准。 JSON 里也写了 output.width/height,但 QImage 解出来是多大就是多大;模型和编码器给的是实际像素,JSON 可能过期或写错。这个选择让“图片坏了但 JSON 看起来正常”这种半成品不会当成成功。
输入/原图尺寸可以缺,缺了就从输出反推。 input = output / scale,original = input;如果 original != input 且没有 downscaled 字段,就推断为 true。这样 mock 或旧版桥少给字段时 UI 仍能显示,不会因为缺元数据把整张图丢掉。
缺 data 或解不出图,直接失败。 SR_BRIDGE_PROTOCOL,不是“返回一张空图”。这条在测试里专门钉住:
// tests/tst_ohossuperresolutionresult.cpp(节选)
const QImage output = testImage(32, 20);
const QByteArray payload = QJsonDocument(QJsonObject{
{QStringLiteral("source"), QStringLiteral("plain.png")},
{QStringLiteral("data"), QString::fromLatin1(imagePng(output).toBase64())},
}).toJson(QJsonDocument::Compact);
OhosSuperResolutionResult result;
QVERIFY(OhosSuperResolutionResult::fromWireJson(payload, &result));
QCOMPARE(result.outputSize(), QSize(32, 20));
// 没有 input/original 时按 4× 反推:32/4=8,20/4=5。
QCOMPARE(result.inputSize(), QSize(8, 5));
QCOMPARE(result.originalSize(), QSize(8, 5));
QVERIFY(!result.downscaled());
这段测试只给 source 和 data,故意不给几何;如果实现偷偷依赖 input,这里就红了。契约不靠注释,靠断言。
临时文件是另一半。QOhosSuperResolution::writeTemp() 把 PNG 写到 <temp>/qt-ohos-ai-vision/,文件名带毫秒时间戳和自增计数器;新结果替换旧文件,clearResult() 和析构删除。原图预览是“尽力而为”:写失败不影响超分本身,sourceUrl 为空,QML 左侧卡片显示占位。这个取舍很重要——不能因为一张对照图写不出来,把已经成功的结果判失败。
saveResult() 则相反:用户主动保存,失败必须报。QImageWriter 按后缀选格式,没后缀默认 PNG;路径为空、图无效、写不进去,返回 false 并发 SR_IO_ERROR。
5.5 上鸿蒙:Qt 载具、hdc fport 和一次真机联调截图
上鸿蒙分两条路。只跑 ArkTS 半边:DevEco 打开 examples/ohos-app/,自动签名,运行;页面自己就能完成选图/超分。接 Qt:用 Qt for HarmonyOS 的 harmonydeployqt 生成官方 stage 壳,把 sr/、srbridge/ 拷进去,合并两段:
// ohos/entry/src/main/ets/entryability/EntryAbility.ets(节选)
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
// ---- qt-ohos-ai-vision merge block 1/2: start the bridge ----------
SrBridgeService.getInstance().start(this.context);
// ---------------------------------------------------------------------
// Qt carrier note: keep the carrier template's Qt initialization call
// here (loading the Qt runtime / your Qt main()).
}
onDestroy(): void {
// ---- qt-ohos-ai-vision merge block 2/2: stop the bridge -----------
SrBridgeService.getInstance().stop();
// Release the process-wide Core Vision Kit analyzer; not awaited.
SuperResolution.release().catch((): void => {
});
}
QAbility 是载具模板生成的文件,不要替换;只在它生成的生命周期里加这两段。桥在 onCreate 尽早启动,避免 Qt UI 第一帧就发请求时端口还没监听。module.json5 里要有 ohos.permission.INTERNET(loopback socket 需要,system_grant,无运行时弹窗);不需要相册/存储权限,选图走系统 Picker。
构建和真机联调大概是这样一条线:
# 前提:演示 HAP 已安装并启动(构建/安装命令见第 7 节)
# 1) 把设备桥端口转到开发机,先验协议
hdc fport tcp:52141 tcp:52141
curl -s http://127.0.0.1:52141/v1/ping
# 2) 桌面 Qt 示例直连设备桥,截一张真机结果的图
QTOHOS_AI_VISION_ENDPOINT=http://127.0.0.1:52141 \
./build-desktop/examples/quick/quick_example --sample --capture preview.png
最后一步就是那张截图的来源。hdc fport 把设备的 52141 转到开发机,Qt 示例以为自己在连本地,其实是设备上的 ArkTS 桥在跑模型。--capture 等 4.5 秒才截图(OCR 示例是 2.2 秒),因为超分 + PNG 编码 + base64 比文本慢;第一次按 OCR 的 2.2 秒等,截到的是“正在超分…”,后来才调到 4.5 秒。
需要说明的是:仓库里验证的是“桌面 Qt 示例 + hdc fport + 设备 ArkTS 桥”这条链路;把 Qt 运行时和示例可执行文件整个装进 HarmonyOS 载具的部署不在本仓库 CI 里,命令和合并清单在 OpenHarmony 示例说明里。桥这半边已经用真机跑通,Qt 载具那半边按文档接——这也是为什么第 2 节的 Qt 截图是桌面窗口,不是设备桌面上的 Qt 窗口。
Qt for HarmonyOS 这边还有两个现实约束:官方载具目前是 Qt 6.12 technology preview,主机以 Linux 为主,macOS 走 Qt 官方安装器 + DevEco;Qt 6.8/6.9 的发布说明里没有 OpenHarmony/HarmonyOS,别拿网上的“官方支持”当依据。手工集成(不用 harmonydeployqt)时,Qt 运行库进 entry/libs/arm64-v8a/,QML 模块文件进 entry/src/main/resources/resfile/qml/——so 走 libs、QML 文件走 resfile,少一条都 import 失败。
6. 踩坑与经验
这一节全是坑,全部来自这次开发的真实报错、代码注释、提交记录和实测。
坑一:4× 还是 2×?文档摘要骗了我。 有摘要把 imageSuperResolution 写成 2×,我按 2× 算过 360×240 的预期输出是 720×480;实际跑出来是 1440×960。200×150 → 800×600、419×600 → 1676×2400、640×427 → 2560×1708,全是宽高各 4×。接口没有倍数参数,别在代码里写死 2,也别按“面积 4 倍”算内存——是面积 16 倍。以设备实测为准,别以摘要为准。
坑二:2047 的输入上限,不等于 2047 可以随便给。 模型要求宽高小于 2048,但 4× 之后是 8188 长边;一个 3:2 的 2047×1365 图输出 8188×5460,RGBA 约 178 MB,还没算 PNG 编码和 base64。本库把长边钳到 1024:3000×2000 → 1024×683 → 4096×2732,RGBA 约 44 MB。downscaled=true 和 inputWidth/Height 必须回传,否则 UI 会把一张缩过的图当成原尺寸结果。模型的“能收”和设备的“能扛”是两回事。
坑三:同一进程不支持并发,Promise 链还会被一次失败卡死。 官方约束是同一特性不支持同进程并发调用;Qt 侧同时只允许一个任务,SR_BUSY 直接失败。ArkTS 侧用 Promise 链串行,这里有个很容易写错的点:只写 tail.then(task) 的话,一次 SR_TOO_SMALL 会让整条链变 rejected,后面的任务全跟着失败。实现里是 then(task, task):成功和失败都继续下一条。串行队列的失败分支,比成功分支更重要。
坑四:60 秒超时之后,分析器必须一起丢掉。 withTimeout() 抛 SR_TIMEOUT 只是让这次调用失败;如果静态 analyzer 还留着,下一次 process() 会继续等一个已经卡死的实例。代码里超时后走 resetAnalyzer():置空 + 异步 destroy(),下次重建。正常 1024×683 只要 670 ms,60 秒是给慢设备/大图留的余量;真超时了,分析器多半已经不可用。超时要连资源一起重置,不能只重置 Promise。
坑五:15 MB 的响应,不能指望一次 socket send。 1024×683 → 4096×2732 的那次,HTTP 响应 15,162,995 字节,端到端约 4.9 秒。把整个 payload 一次 client.send,等待时间和失败面都不可控;实现里按 128 KiB 分片、await 每一片,15 MB 那次完整回来。Content-Length 仍然是完整 JSON 的字节数,Qt 侧 readAll() 收齐再解析。大响应不能只靠多等一会儿,发送方式本身要改。
坑六:超分成功了,ArkTS 页两栏还是空的。 这个单独一个 commit:fix(ohos-app): 修复超分结果面板不刷新。现象是 status 已经变成“完成:360×240 → 1440×960”,左右两栏还停在“选择图片开始”/“结果会显示在这里”。原因是 @Builder beforePane(pixelMap) / afterPane(pixelMap) 把 PixelMap 当参数传进去;ArkUI 的 @Builder 参数按值传递,@State 变了但 Builder 不重绘。修复是 Builder 里直接读 this.before / this.after,不再传参。代码注释写得很直白:parameters are passed by value and do not refresh when the PixelMap state changes。ArkUI 的 Builder 不是 React 组件,别把状态当 props 传。
坑七:buffer.Buffer.buffer 是池化的,Content-Length 会对不上。 ArkTS 侧一开始用 buffer.from(...).buffer 拼响应,设备上偶尔出现 Content-Length 和实际字节数不一致,Qt 侧随后报 SR_BRIDGE_PROTOCOL。原因是 Buffer 的底层是池化 ArrayBuffer,byteOffset/length 不一定是 0/长度。修复是用 util.TextEncoder 生成独立的 Uint8Array。跨语言边界上,字节数组必须是“独立的”,不能是别人池子里的一段。
坑八:GET /v1/ping 被自家桥回了 411。 QNAM 的 GET 不带 Content-Length,而微型解析器一开始对所有方法都要求长度,ping 直接 411 Length Required / SR_BRIDGE_BAD_REQUEST: Content-Length is required。修复是 GET/HEAD/OPTIONS/DELETE 默认 0,其它方法才回 411。HTTP 子集越小,越要把“谁带 body”写死。
坑九:API 26、中国境内、支持的设备类型,一个不满足就是 SR_UNSUPPORTED。 模拟器通常没有这个 AI 服务;低版本系统、非 phone/tablet/2in1、境外设备都可能直接 supported:false 或模型创建失败。canIUse('SystemCapability.AI.Vision.VisionBase') 只能说明系统声明了能力,不代表模型服务真的可用——真机实测才是准。遇到 SR_UNSUPPORTED,先看系统版本/设备类型/地区,再怀疑代码。别在模拟器上验端侧 AI,验 UI 和桥就够了。
7. 现在怎么用:从 add_subdirectory 到 1676×2400
经过上面的整理,这个工程是“Qt 6 CMake 库 + ArkTS 工程”双形态交付(版本 0.2.0,MIT)。接入两种方式:
# 方式一:add_subdirectory
find_package(Qt6 6.5 REQUIRED COMPONENTS Core Gui Quick Qml Network)
add_subdirectory(third_party/qt-ohos-ai-vision)
target_link_libraries(my_app PRIVATE
Qt6::Quick
qt-ohos-ai-vision::qt_ohos_ai_vision)
# 方式二:FetchContent
include(FetchContent)
FetchContent_Declare(qt_ohos_ai_vision
GIT_REPOSITORY https://atomgit.com/oh-tpc/qt-ohos-ai-vision.git
GIT_TAG main)
set(QT_OHOS_AI_VISION_BUILD_EXAMPLES OFF CACHE BOOL "" FORCE)
set(QT_OHOS_AI_VISION_BUILD_TESTS OFF CACHE BOOL "" FORCE)
FetchContent_MakeAvailable(qt_ohos_ai_vision)
宿主检查清单六条:加载 QML 前调 qtOhosAiVisionRegisterQmlTypes();QAbility 合并两个 merge 块;module.json5 加 ohos.permission.INTERNET;sr/ 与 srbridge/ 拷进载具;改端口时 SrBridgeService.start(context, port) 与 QTOHOS_AI_VISION_ENDPOINT 成对;设备不支持时 supported:false 要 fail fast,别把图发出去。
桌面构建有一处 Homebrew 的坑:qtbase 和 qtdeclarative 是两个 keg,只给一个 CMAKE_PREFIX_PATH 时 CMake 会报找不到 Qt6Quick 的 config;两个前缀都给了才行:
cmake -S . -B build-desktop -G Ninja \
-DCMAKE_PREFIX_PATH=/opt/homebrew/opt/qtbase \
-DQT_ADDITIONAL_PACKAGES_PREFIX_PATH=/opt/homebrew/opt/qtdeclarative
cmake --build build-desktop --parallel
ctest --test-dir build-desktop --output-on-failure
桌面看完整效果,先起 mock 桥(需要 Pillow),再跑内置示例:
python3 tools/mock_bridge.py &
QTOHOS_AI_VISION_ENDPOINT=http://127.0.0.1:52141 \
./build-desktop/examples/quick/quick_example --sample
# 截图模式在结果出来后写文件并退出
QTOHOS_AI_VISION_ENDPOINT=http://127.0.0.1:52141 \
./build-desktop/examples/quick/quick_example --sample --capture sr.png
设备侧一条 hvigor 命令出 HAP,DevEco 配自动签名后安装;桥的协议可以直接从开发机调:
# 安装演示 HAP
cd examples/ohos-app
hvigorw --mode module -p product=default -p module=entry@default assembleHap
hdc install -r entry/build/default/outputs/default/entry-default-signed.hap
hdc shell aa start -a EntryAbility -b com.example.qt_ohos_ai_vision_app
# 端口转发 + 能力探测
hdc fport tcp:52141 tcp:52141
curl -s http://127.0.0.1:52141/v1/ping
# 直接调超分:原始图片字节进,JSON 出,data 是 base64 PNG
curl -s --data-binary @examples/quick/samples/sample.png \
-H 'Content-Type: application/octet-stream' \
'http://127.0.0.1:52141/v1/enhance?source=sample.png' -o sr.json
# 看桥日志
hdc shell hilog | grep qt_ohos_ai_vision
更完整的 API、协议、错误码和合并步骤在仓库的文档里:
- 中文主文档(能力边界、环境、集成、构建、部署、FAQ);
- 英文说明:英文版;
- API 文档:
QOhosSuperResolution、OhosSuperResolutionResult、传输层与错误码; - 架构文档:架构、为什么桥、生命周期、尺寸策略、完整协议;
- 验证记录:桌面单测、ArkTS 编译、真机 ping/enhance 记录;
- OpenHarmony 示例说明:DevEco 导入、签名、hdc 验证、载具合并;
tests/:19 项 QtTest(结果解析 9 + 引擎状态机 10,mock 传输,不开 socket)。
当前版本在 Qt 6.11.0(macOS arm64)与 HUAWEI MateBook Pro S(API 26,2in1)上验证:Qt 侧 2/2 测试二进制、19 项函数全绿(几何回退、base64/PNG 严格校验、落盘、能力探测、不支持 fail-fast、桥不可用、SR_BUSY、错误体映射、选图取消、文件读取、保存/清理、协议违规);ArkTS 两份工程在 API 26 下编译出 HAP;设备上 /v1/ping、/v1/enhance 实测通过,360×240 三次 61/83/85 ms 且输出逐字节一致,419×600 210 ms / 6890 KB,640×427 274 ms,3000×2000 先缩到 1024×683 再出 4096×2732(模型 670 ms,响应 15,162,995 字节,端到端约 4.9 s);Qt 示例经 hdc fport 直连设备桥,截到 98 ms / 1606 KB 的那张图。4 倍的产出是 16 倍像素:模型算完,还要 PNG 编码、base64、HTTP 传输、Qt 解码、落盘,最后给到 QML。两端都在 127.0.0.1,中间每一段都有协议约束。
更多推荐



所有评论(0)