Qt 鸿蒙端侧 OCR 实战:当系统 API 只给了 ArkTS 入口
Core Vision Kit 的
textRecognition只对 ArkTS 开放,没有 NDK,也没有 C++ 绑定;官方 N-API 的方向是 ArkTS 调 C++。Qt 应用的界面和业务在 C++/QML 这半边,系统 OCR 在那半边,中间没有门。这个库的做法是在同一个应用进程里监听127.0.0.1:52141,用几十行 HTTP/1.1 传图片,ArkTS 侧调recognizeText,再把契约 JSON 交回 C++。下面记桥的实现、长图条带,以及模拟器上那次 1001400001。
仓库地址:https://atomgit.com/lqjmac/qt-ohos-ocr
三方框架版本:https://wiki.qt.io/Qt5.12.12_Open_Source_Release_for_HarmonyOS_zh
组织仓库链接:https://atomgit.com/ohos-qt
0. 环境与实测设备
三方库适配信息:
| 三方库 | 版本 | 形态 | 仓库地址 |
|---|---|---|---|
| qt-ohos-ocr | 0.1.0 | Qt 6 CMake 库(add_subdirectory / FetchContent,默认静态库) | https://atomgit.com/lqjmac/qt-ohos-ocr |
| flutter_ohos_ocr(ArkTS 移植源) | 1.0.x | ohos/ocr/ 目录移植来源(MIT) | https://atomgit.com/lqjmac/flutter_ohos_ocr |
实测环境:
| 项 | 版本/型号 |
|---|---|
| Qt | 6.5+(桌面开发与单测);设备端 Qt for HarmonyOS 载具(Qt 6.12 technology preview,或 Qt Wiki 5.12.12 / 5.15.16 移植版) |
| OpenHarmony/HarmonyOS SDK | API 12+(textRecognition 起始版本);Qt6 载具社区版最低 API 20/23 |
| DevEco Studio | 5.x / 6.x(真机运行、签名、HAP 调试) |
| CMake / C++ | 3.21+ / C++17(组件:Core、Quick、Network、Concurrent) |
| 测试 | QtTest 19 项(模型 9 + 引擎 10;传输 mock 注入,不需要设备) |
| 实测设备 | HarmonyOS 2in1 模拟器(127.0.0.1:5555,3120×2080),OpenHarmony 7.0.0.105,API 26;443 ms 的 55 行截图来自另一次设备运行,型号未入库 |
| 实测数据 | 示例截图 3120×2080:55 行、原生耗时 443 ms(界面读数);桌面 mock 桥预览 900×620:7 行、186 ms;PC 长图 1242×6500:140 行约 3.5 s |
验证记录的主机是 macOS arm64、Qt 6.11.0(Homebrew qtbase / qtdeclarative)、CMake 4.3.2、Ninja;鸿蒙侧是 DevEco Studio 6.x、hvigor 6.26.4、ohpm 6.0.1、SDK API 26,模拟器为 2in1、3120×2080。下面的 ctest 输出、HAP 大小和模拟器日志都来自那份记录。
1. 55 行结果,和它证不了的事

截图里第 44 行是 in 384 ms,第 48 行是 9:4 CRLF。这两行都来自界面本身:前者像一段终端输出的结尾,后者是编辑器状态栏的编码提示。OCR 把这类界面碎片也逐字抓了下来,连同正文一共 55 行,原生耗时 443 ms。窗口标题 qt-ohos-ocr demo,状态行写着 识别到 55 行 · 原生耗时 443 ms;左边预览是那张 3120×2080 的整屏截图(screenshot_20261112_012756_com.example.ohosnotes.jpg,HarmonyOS Cordova 的入门指南),文件名和尺寸下面又标了一次耗时。右边列表从第 37 条滚到第 55 条,使用Harmony Cordova,您可以构建一个鸿蒙应用程序。、安装Node.js、AppScope 这些行都在。窗口底部一行是桥的自述:bridge listening · 127.0.0.1:52141 · protocol 1 · v0.1.0。这是 C++ 解析完 55 个块、QML 渲染出来的列表,ArkTS 页面里没有这份东西。
443 ms 是这次运行的原生耗时,别和另外几组数字混了:仓库内置的小票是 900×620(examples/quick/samples/ocr_sample.png),桌面 mock 桥预览那次 7 行、186 ms;契约文档里的 1000×1400 和 durationMs: 142 只是 JSON 样例,跟这次识别没有关系。我第一次看这张图,也以为 55 行来自小票,直到把预览文件名和尺寸对了一遍。
这张图能证明的东西有限:桥通了、C++ 收到并解析了 55 个块、QML 长列表没有裁行。它不能证明每台设备都能识别。11 月 13 日换到 2in1 模拟器,/v1/ping 正常返回,/v1/recognize 返回 OCR_VISION_ERROR,设备侧 textRecognition.init() 超时 200,直接调 recognizeText 是 1001400001。
2. 为什么 C++ 调不到 textRecognition
找 C++ 绑定直接调 textRecognition 这条路走不通:textRecognition 只有 ArkTS 接口,N-API 的方向是 ArkTS 调 C++,载具没有留反向的口子。
Qt 官方把 HarmonyOS 写作 technology preview:doc.qt.io 的 HarmonyOS 文档从 Qt 6.12 才开始出现,工具链的开发和测试主机是 Linux,DevEco Studio 用于真机/模拟器调试;Qt 6.8 / 6.9 的发布说明和支持平台列表里没有 OpenHarmony/HarmonyOS。Qt Wiki 上另有 5.12.12、5.15.16 的开源移植版和 Qt 6.12 的构建指南。
Core Vision Kit 的 textRecognition 自 API 12 起可用,只有 ArkTS API。C++ 与 ArkTS 的官方互操作是 N-API,方向为 ArkTS → C++:ArkTS 把 native 函数注册进来,自己调;反过来,从 C++ 调 ArkTS,需要持有 ArkTS 运行时的 JS 引用并在它的线程上执行。NDK 直调没有绑定;QML 里嵌 ArkUI 原生视图再转发事件,复杂且体验割裂。剩下的选择是 socket:Qt 有 QNetworkAccessManager,ArkTS 有 @ohos.net.socket,两边都只用稳定 API。
问题不在头文件,在运行时。textRecognition 在系统里是一个 ArkTS 模块,方法签名和 PixelMap / TextRecognitionResult 类型都定义在 ArkTS 声明里;SDK 没有对应的 C 头,也没有 NDK 导出。C++ 拿不到 ArkTS 的模块对象、事件循环和 Promise,除非载具额外暴露一个 JS 运行时入口;Qt 载具里负责装载运行时和窗口的是 QAbility,它没有这个入口。桥能做的其实很少:把“调用 ArkTS”这件事交给同一进程里的 ArkTS 自己做。
约束也写清楚:桥需要 system_grant 的 ohos.permission.INTERNET(回环监听在权限模型里也算网络操作,但没有运行时弹窗);图片字节在进程内多一次拷贝;端口默认 52141,改端口要两端成对改。这是本项目的工程方案,不是 Qt 或华为的官方通道。将来 Core Vision Kit 开放 NDK 接口,或者载具提供 C++→ArkTS 的官方互操作,只需要换掉 IOcrTransport 的实现,引擎和 QML 不动。
3. 桥的三条路由
ArkTS 侧 OcrBridgeService 用 TCPSocketServer 监听回环,路由一共三条:
| 方法 | 路径 | 请求体 | 响应 |
|---|---|---|---|
| GET | /v1/ping | — | {"name":"qt-ohos-ocr-bridge","protocol":1,"version":"0.1.0","vision":true} |
| POST | /v1/recognize?source=&language= | 原始图片字节 | OcrResult JSON + width/height |
| POST | /v1/pick?language= | — | 结果 JSON 或 {"cancelled":true} |
2026-11-13 在模拟器上把端口转出来,用 curl 直接打:
hdc fport tcp:52141 tcp:52141
curl http://127.0.0.1:52141/v1/ping
# {"name":"qt-ohos-ocr-bridge","protocol":1,"version":"0.1.0","vision":true}
curl -X POST --data-binary @ocr_sample.png \
"http://127.0.0.1:52141/v1/recognize?source=ocr_sample.png&language=CHINESE"
# {"error":{"code":"OCR_VISION_ERROR","message":"Core Vision Kit init failed (200): Run timed out, please try again later."}}
ping 返回 protocol: 1 就算桥在位,C++ 的 probeAvailability() 只认这个字段,不认版本字符串。识别失败时返回 HTTP 500 加统一错误体,code 和 message 由 ArkTS 侧填,C++ 侧原样拼成 "CODE: message"。
传输规则刻意收窄:HTTP/1.1 over 127.0.0.1:52141、Connection: close、一连接一请求、Content-Length 定界读 body、客户端 20 秒传输超时。图片体走 application/octet-stream 原始字节,不做 base64:回环带宽从来吃不满,编码解码的 CPU 和体积膨胀才是多余的。JSON 响应用 Content-Type: application/json; charset=utf-8,Content-Length 按 UTF-8 字节数算,不按字符数。
微型服务一开始想支持 keep-alive,省几次握手。状态机复杂度立刻翻倍:连接复用、半包、超时回收都要自己写,而 OCR 是低频操作,握手开销在总耗时里测不出来。最后砍掉,Connection: close、一连接一请求,服务端解析和客户端 QNAM 都简单。
端口发现三级:setEndpoint() 显式设置 → 环境变量 QTOHOS_OCR_ENDPOINT → 默认 127.0.0.1:52141。服务启动后还会把 {"port":<port>,"protocol":1} 写进沙箱 files/qt_ohos_ocr_bridge.json,诊断工具不连 hilog 也能知道桥起在哪个端口;C++ 不自动读这个文件,它只是给人看的。
4. 库、骨架和可直接导入的示例工程
库本体是标准 Qt 6 CMake 工程,ohos/ 是待合并进载具的 ArkTS 骨架,另有桌面示例和一套可直接导入 DevEco 的完整示范工程:
qt-ohos-ocr/
├─ CMakeLists.txt # 库 + examples + tests 顶层
├─ include/qt-ohos-ocr/ # 公共头
│ ├─ qohosocrengine.h # QML/C++ 异步引擎门面
│ ├─ ohosocrresult.h # Q_GADGET 结果模型
│ └─ ocrbridge/
│ ├─ OcrTransport.h # 传输接口(mock 注入点)
│ └─ OcrHttpBridge.h # QNAM 回环实现
├─ src/ # 实现,含手写 JSON 契约编解码
├─ ohos/ # ArkTS 桥接模块骨架(合并目标)
│ └─ entry/src/main/ets/
│ ├─ entryability/EntryAbility.ets # 含标注好的 merge 块
│ ├─ pages/Index.ets # 选图识别演示页(含桥状态)
│ ├─ ocrbridge/OcrBridgeService.ets # 回环 HTTP 服务
│ └─ ocr/ # 移植自 flutter_ohos_ocr
├─ examples/
│ ├─ quick/ # Qt Quick 桌面示例(FileDialog + 状态行)
│ └─ ohos-app/ # 可直接导入 DevEco 的完整鸿蒙应用
├─ tests/ # QtTest 19 项(mock 传输)
└─ docs/api.md · docs/architecture.md

作为依赖接入两种方式:
# 方式一:add_subdirectory
add_subdirectory(third_party/qt-ohos-ocr)
target_link_libraries(your_app PRIVATE Qt6::Quick qt-ohos-ocr::qt_ohos_ocr)
# 方式二:FetchContent(git 地址用 AtomGit)
include(FetchContent)
FetchContent_Declare(qt_ohos_ocr
GIT_REPOSITORY https://atomgit.com/lqjmac/qt-ohos-ocr.git
GIT_TAG v0.1.0)
FetchContent_MakeAvailable(qt_ohos_ocr)
add_subdirectory 适合把仓库放进 third_party/,FetchContent 适合锁 tag 后直接编;两种方式都会导出 qt-ohos-ocr::qt_ohos_ocr 目标。
传输抽成一个接口:IOcrTransport 只定义 ping、postRecognize、postPick 三个操作,OcrHttpBridge 是 QNAM 实现;单测注入 MockTransport,19 项全部离线跑。引擎构造函数收 IOcrTransport* 并接管所有权。
桥探测失败在桌面上属于预期状态,装坏了才会是另一回事:桌面机器上没有 ArkTS 运行时,127.0.0.1:52141 没有进程监听,ping 的连接被拒绝,引擎把 available 留在 false,probeAvailability() 之后 lastError 是 OCR_BRIDGE_UNAVAILABLE: the ArkTS bridge did not answer /v1/ping。这时 QML 仍能加载、模型和 19 项测试照跑;pickAndRecognize 按钮因为 visible: ocr.available 被隐藏,文件选择走 Qt 自己的 FileDialog,但识别请求会以同一个错误码回来。要在桌面看完整结果,起 tools/mock_bridge.py,它只回固定小票数据,用于 UI 和解析,不代表设备能力。
bridgeText() 在 QML 里把这两种状态分开显示:available 为真时是 bridge listening · 127.0.0.1:52141 · protocol 1,为假时是 bridge unavailable · 127.0.0.1:52141;桌面开发时后者是常态,不会挡住窗口加载。
ArkTS 骨架按 merge 块组织:载具工程已经生成的 EntryAbility.ets 里用注释标出两段,onCreate 启动 OcrBridgeService,onDestroy 停桥并释放 VisionOcr;ocrbridge/ 与 ocr/ 两个目录整拷进载具 entry 的 ets/ 下。嫌麻烦就直接用 examples/ohos-app/,一套能跑的完整 stage 工程,ets/ 与根 ohos/ 逐文件同源。
5. C++ 侧:把异步收进一个小状态机
QOhosOcrEngine 的状态只有两个:
Idle ── recognizeBytes()/recognizeFile()/pickAndRecognize() ──▶ Busy
Busy ── transport reply ──▶ recognized(OhosOcrResult) | failed(err) ──▶ Idle
Busy 期间的第二次识别立即以 OCR_BUSY 失败,不排队:OCR 是重操作,静默排队会让用户以为界面卡死。唯一允许并行的是 probeAvailability(),探测不该被一次大图识别堵住。文件读取丢给 QtConcurrent 工作线程,传输本身是异步的,GUI 线程不碰磁盘也不等网络。
QML 侧只接两个信号:
// examples/quick/Main.qml · recognizeFile / runSample / runPicker
function recognizeFile(url) {
root.imageUrl = url
root.result = null
root.errorMessage = ""
root.statusText = qsTr("正在识别…")
ocr.recognizeFile(url)
}
function runSample() {
root.recognizeFile("qrc:/samples/ocr_sample.png")
}
function runPicker() {
root.imageUrl = ""
root.result = null
root.errorMessage = ""
root.statusText = qsTr("正在打开系统相册…")
ocr.pickAndRecognize()
}
recognizeFile 清空上一次结果、把状态行改成“正在识别…”,然后调 ocr.recognizeFile(url);runSample 把 qrc:/samples/ocr_sample.png 交给同一个入口,所以桌面示例不依赖设备文件系统也能演示;runPicker 走 /v1/pick,由 ArkTS 侧调起系统相册。按钮的 enabled: !ocr.busy 和 visible: ocr.available 都绑在引擎属性上,状态机是唯一的事实来源。
回调最后落在 handleRecognitionReply:
// src/qohosocrengine.cpp · handleRecognitionReply()
void QOhosOcrEngine::handleRecognitionReply(const OhosOcrTransportReply &reply)
{
if (!reply.ok) {
failRecognition(QStringLiteral("OCR_BRIDGE_UNAVAILABLE: ") + reply.errorMessage);
return;
}
if (reply.status != 200) {
failRecognition(bridgeError(reply, QStringLiteral("OCR_BRIDGE_HTTP")));
return;
}
const QJsonDocument document = QJsonDocument::fromJson(reply.body);
if (document.isObject()
&& document.object().value(QLatin1String("cancelled")).toBool(false)) {
failRecognition(QStringLiteral("OCR_PICKER_CANCELLED: the user dismissed the picker"));
return;
}
QString parseError;
const OhosOcrResult result = OhosOcrResult::fromJson(reply.body, &parseError);
if (!parseError.isNull()) {
failRecognition(QStringLiteral("OCR_BRIDGE_PROTOCOL: ") + parseError);
return;
}
recordFailure(QString());
setBusy(false);
emit recognized(result);
}
四层判断的顺序不能换:传输层失败先报 OCR_BRIDGE_UNAVAILABLE,因为这时没有 HTTP 状态可看;非 200 再解析错误体,解析不出 code 才退回 OCR_BRIDGE_HTTP: HTTP status <n>;200 里先看 {"cancelled":true},用户取消映射成 OCR_PICKER_CANCELLED,与选图失败 OCR_PICKER_ERROR 分开;最后才 fromJson,解析不出来报 OCR_BRIDGE_PROTOCOL,跟识别失败是两码事。成功时清 lastError、清 busy、发 recognized,三个动作在同一个槽里完成。
传输回调可能同步触发(mock),也可能从 QNAM 的信号里来。queued() 统一用 QMetaObject::invokeMethod 的 Qt::QueuedConnection 把它们归一到引擎线程,所以状态机是单线程的,测试里用 QTRY_* 转事件循环就能观察信号。send() 里设了 20 秒 setTransferTimeout、Connection: close;图片走 application/octet-stream,ping 用 application/json;GET 和 POST 共用一个出口。
6. ArkTS 侧:代理只做定界和转发
服务端不解析业务字段,只负责按 \r\n\r\n 和 Content-Length 把 TCP 字节流切成一个完整请求、按路径分发、把结果写成 HTTP 响应。路由全在 dispatch 里:
// ohos/entry/src/main/ets/ocrbridge/OcrBridgeService.ets · dispatch()
private async dispatch(
client: socket.TCPSocketConnection,
method: string,
target: string,
body: Uint8Array,
): Promise<Handled> {
const path: string = target.split('?')[0];
const query: QueryMap = OcrBridgeService.parseQuery(target);
if (path === '/v1/ping') {
if (method !== 'GET' && method !== 'HEAD') {
return OcrBridgeService.handledError(405, 'Method Not Allowed',
'OCR_BRIDGE_METHOD', `${method} is not allowed on ${path}`);
}
const bodyText: string = `{"name":"qt-ohos-ocr-bridge"` +
`,"protocol":${BRIDGE_PROTOCOL}` +
`,"version":${jsonQuote(BRIDGE_VERSION)}` +
`,"vision":true}`;
return { status: 200, reason: 'OK', body: bodyText };
}
if (path === '/v1/recognize') {
if (method !== 'POST') {
return OcrBridgeService.handledError(405, 'Method Not Allowed',
'OCR_BRIDGE_METHOD', `${method} is not allowed on ${path}`);
}
if (body.length === 0) {
return OcrBridgeService.handledError(400, 'Bad Request',
'OCR_INVALID_ARGUMENT', 'image bytes must not be empty');
}
const language: OcrLanguage =
languageFromWire(query.get('language', 'CHINESE'));
const source: string = query.get('source', 'image');
try {
const run: VisionRun =
await VisionOcr.recognizeBytes(body, source, language);
return { status: 200, reason: 'OK', body: OcrBridgeService.recognizeBody(run) };
} catch (error) {
return OcrBridgeService.handledError(500, 'Internal Server Error',
'OCR_VISION_ERROR', visionErrorMessage(error));
}
}
if (path === '/v1/pick') {
if (method !== 'POST') {
return OcrBridgeService.handledError(405, 'Method Not Allowed',
'OCR_BRIDGE_METHOD', `${method} is not allowed on ${path}`);
}
const language: OcrLanguage =
languageFromWire(query.get('language', 'CHINESE'));
try {
const run: VisionRun | null = await VisionOcr.pickAndRecognize(language);
if (run === null) {
return { status: 200, reason: 'OK', body: '{"cancelled":true}' };
}
return { status: 200, reason: 'OK', body: OcrBridgeService.recognizeBody(run) };
} catch (error) {
return OcrBridgeService.handledError(500, 'Internal Server Error',
'OCR_PICKER_ERROR', visionErrorMessage(error));
}
}
return OcrBridgeService.handledError(404, 'Not Found',
'OCR_NOT_FOUND', `no route for ${path}`);
}
/v1/recognize 只接受 POST;空 body 返回 400 和 OCR_INVALID_ARGUMENT;language 只是元数据,languageFromWire 把未知值落到 CHINESE,Core Vision Kit 自己检测语种;VisionOcr.recognizeBytes 抛出的错误统一包成 500 + OCR_VISION_ERROR,message 里带原始 code。/v1/pick 的取消按正常流程走,返回 200 的 {"cancelled":true},由 C++ 映射成专属错误码。/v1/ping 同时接受 GET 和 HEAD,剩下的路径一律落到 404 + OCR_NOT_FOUND。
recognizeBody 用 toJson(run.result) 拿到契约 JSON,再去掉最后一个 } 补上 ,"width":<w>,"height":<h>}。这个写法不好看,但保证了字段顺序和 OcrJson.ets 逐字节一致;C++ 的 fromJson 忽略这两个扩展字段。
接收侧的手写解析比路由长:每个连接维护 received、bodyStart、contentLength 三个状态;header 超过 64 KiB 返回 431;GET/HEAD/OPTIONS/DELETE 没有 Content-Length 时按 0 处理,其它方法缺这个头返回 411;body 没收满就继续等下一个 chunk。TCPSocketServer.close() 自 API 20 起提供,所以 compatibleSdkVersion 是 6.0.0(20);textRecognition 自 API 12 起可用,两个下限取高的那个。
EntryAbility.onCreate 第一件事就是 OcrBridgeService.getInstance().start(this.context),早于 Qt UI 的第一次识别;onDestroy 停桥并 VisionOcr.release()。桥活在回环 socket 上,和当前屏幕上加载的是 Qt 窗口还是 ArkTS 诊断页无关。
start() 是幂等的,重复调用直接返回;stop() 会关监听和所有还开着的连接。端口被占用时 listen 的 catch 只写 hilog,不抛到 UI:桌面侧会看到 OCR_BRIDGE_UNAVAILABLE: Connection refused,然后按端口发现顺序去查 QTOHOS_OCR_ENDPOINT。
一次识别在 C++ 侧看是四段:recognizeBytes 同步校验并置 Busy;postRecognize 把字节交给 QNAM 后立即返回;ArkTS 侧 receive 收满 header 和 body 后进 dispatch,VisionOcr 解码、初始化、recognizeText;回包到了以后 queued 把回调排到引擎线程,handleRecognitionReply 解析并清 Busy。QNAM 设了 20 秒传输超时,超时后 C++ 收到传输错误并报 OCR_BRIDGE_UNAVAILABLE;ArkTS 侧没有单独的超时,recognizeText 挂住时只能等 C++ 先断。模拟器上是 init 先失败(200;直接调 recognizeText 则是 1001400001),还没走到 20 秒;真机上目前没有触发过这条超时。
7. 长图:4800 / 5000 / 6500
Core Vision Kit 对图高有隐性上限。OpenHarmony 接入说明记的 PC 实测是:1242×4800 全量返回,1242×5000 开始丢尾行,1242×6500 只剩几块。长截图、长聊天记录这类 Qt 桌面场景的刚需图片,恰恰容易超过 5000 px。
4800 和 5000 的分界一度被当成识别质量问题,把图高量出来才看清。
解法是把高图切成重叠的横向条带分别识别,再按行位置合并。三个常数:MAX_TILE_HEIGHT = 3000、TILE_OVERLAP = 160、MIN_TAIL_HEIGHT = 600。重叠必须高于最高的文字行,保证跨界行至少在某个条带里是完整的;每个条带只认领去掉首尾各半个重叠的区间,跨界行只会被单个条带认领。
实际跑条带的是 recognizeAllLines:
// ohos/entry/src/main/ets/ocr/VisionOcr.ets · recognizeAllLines()
/** Recognizes every line, splitting tall images into overlapping strips. */
private static async recognizeAllLines(
imageSource: image.ImageSource,
width: number,
height: number,
): Promise<PositionedLine[]> {
const regions: image.Region[] = VisionOcr.tileRegions(width, height);
const lines: PositionedLine[] = [];
for (let i = 0; i < regions.length; i++) {
const region: image.Region = regions[i];
const isFirst: boolean = i === 0;
const isLast: boolean = i === regions.length - 1;
// Each line is owned by exactly one strip: the owned range is trimmed
// by half the overlap on both sides, so the same line is never emitted
// twice and no line at a strip boundary is dropped.
const ownedTop: number = region.y + (isFirst ? 0 : TILE_OVERLAP / 2);
const ownedBottom: number =
region.y + region.size.height - (isLast ? 0 : TILE_OVERLAP / 2);
let pixelMap: image.PixelMap | null = null;
try {
pixelMap = regions.length === 1
? await imageSource.createPixelMap()
: await imageSource.createPixelMap({ desiredRegion: region });
const visionInfo: textRecognition.VisionInfo = { pixelMap: pixelMap };
const output: textRecognition.TextRecognitionResult =
await textRecognition.recognizeText(visionInfo);
VisionOcr.appendOwnedLines(output, region.y, ownedTop, ownedBottom, lines);
} finally {
if (pixelMap !== null) {
await pixelMap.release();
}
}
}
return lines;
}
regions.length === 1 时不传 desiredRegion,直接 createPixelMap(),避免给普通图片多一次裁剪;多条带时用 desiredRegion 只解码当前条带。ownedTop / ownedBottom 在首尾条带不裁,中间条带各裁 80 px。每行的 centerY 由 cornerPoints 的 min/max 求出,加上条带偏移换成原图坐标,落在认领区间的才 push。只有 block 没有 lines 的情况,把 block 文本放在条带中心,保证只出现一次。
太短的尾条带会被前一段条带吞并(MIN_TAIL_HEIGHT),不为三行字多跑一次推理。1242×6500 的图切完是 140 行全量返回,约 3.5 s;这个数字来自 OpenHarmony 接入说明的 PC 实测。
8. JSON 契约:C++ 这端怎么校验
同一份 OcrResult 契约,家族里已经有 Kotlin(kmp-ohos-ocr)、ArkTS(flutter_ohos_ocr 的 ohos 侧)和 Dart 三个实现,C++ 是第四份。fromJson 不信任 ArkTS 回来的任何字段:
// src/ohosocrresult.cpp · fromJson()
OhosOcrResult OhosOcrResult::fromJson(const QByteArray &wire, QString *error)
{
if (error)
error->clear();
const QJsonDocument document = QJsonDocument::fromJson(wire);
if (!document.isObject()) {
if (error)
*error = QStringLiteral("OcrResult payload must be a JSON object");
return OhosOcrResult();
}
const QJsonObject root = document.object();
const QString id = root.value(QLatin1String("id")).toString();
if (id.trimmed().isEmpty()) {
if (error)
*error = QStringLiteral("Result id must not be blank");
return OhosOcrResult();
}
// durationMs is required and must be non-negative; elapsedMs is an
// accepted alias so payloads produced by the C++ side round-trip too.
qint64 duration = -1;
const QJsonValue durationValue = root.contains(QLatin1String("durationMs"))
? root.value(QLatin1String("durationMs"))
: root.value(QLatin1String("elapsedMs"));
if (durationValue.isDouble())
duration = static_cast<qint64>(durationValue.toDouble());
if (duration < 0) {
if (error)
*error = QStringLiteral("Duration must be non-negative");
return OhosOcrResult();
}
QList<OhosOcrBlock> blocks;
const QJsonArray blockArray = root.value(QLatin1String("blocks")).toArray();
for (const QJsonValue &item : blockArray) {
const QString text = item.toObject().value(QLatin1String("text")).toString().trimmed();
if (text.isEmpty())
continue; // blank lines carry no content
const QJsonValue confidenceValue =
item.toObject().value(QLatin1String("confidence"));
double confidence = confidenceValue.isDouble() ? confidenceValue.toDouble() : 0.0;
if (!std::isfinite(confidence))
confidence = 0.0;
confidence = qBound(0.0, confidence, 1.0);
blocks.append(OhosOcrBlock(text, confidence));
}
return OhosOcrResult(id,
root.value(QLatin1String("source")).toString(),
languageFromWire(root.value(QLatin1String("language")).toString()),
blocks,
duration);
}
id 必须非空;durationMs 必须有且非负,缺字段或负数都报错,elapsedMs 是接受的别名,方便 C++ 自己序列化的结果再读回来;block 文本 trim 后为空就丢,重复文本保留——小票上两个 ¥0.00 必须留两行,这一点和 kmp/flutter 版的去重语义相反,中文 仓库说明里单独写了;置信度落到 NaN 或 Infinity 就归 0,再夹到 0…1;未知字段忽略,width/height 就是这么被跳过的。
必填的只有 id 和 durationMs。source 缺了是空字符串,language 缺了落到 CHINESE,blocks 缺了按空数组处理;缺 id 报 “Result id must not be blank”,缺 durationMs 报 “Duration must be non-negative”(缺字段时 duration 是 -1,和负数走同一个分支),整个 body 若解不出对象,报 “OcrResult payload must be a JSON object”。这些错误在引擎里包成 OCR_BRIDGE_PROTOCOL,不会当成识别失败;区分这两个,排查时才知道是桥/契约的问题还是 Core Vision Kit 的问题。confidence 缺省 0.0,越界夹到 0…1,不会因为一个坏置信度丢掉整次结果。反过来,fromJson 返回空 blocks、error 为空,是一次合法的空页,引擎不该把它算成失败。
toJson 是另一头的手写纪律:字段顺序 id, source, language, fullText, averageConfidence, durationMs, blocks;列表分隔符 ", "(对齐 Kotlin joinToString 默认值);整值浮点保留尾随 .0(0.0 不写成 0);转义表与 Kotlin/ArkTS/Dart 一致,emoji 的代理对按 UTF-16 原样保留,不拆成 \ud83d。C++ 结构体字段叫 elapsedMs,线上叫 durationMs,头文件注释里写明对应关系。
契约靠断言,不靠注释:
// tests/tst_ohosocrresult.cpp · toJsonMatchesContractBytes()
void TestOhosOcrResult::toJsonMatchesContractBytes()
{
const OhosOcrResult result(
QStringLiteral("vision-on-device"),
QStringLiteral("ocr_sample.png"),
QStringLiteral("CHINESE"),
{OhosOcrBlock(QStringLiteral("门店收银小票"), 0.0),
OhosOcrBlock(QStringLiteral("合计 ¥44.00"), 0.0)},
142);
const QByteArray expected = QByteArray(
R"json({"id":"vision-on-device","source":"ocr_sample.png","language":"CHINESE","fullText":"门店收银小票\n合计 ¥44.00","averageConfidence":0.0,"durationMs":142,"blocks":[{"text":"门店收银小票","confidence":0.0}, {"text":"合计 ¥44.00","confidence":0.0}]})json");
QCOMPARE(result.toJson(), expected);
}
这个测试直接比字节,字段顺序、空格、.0 任何一处变了都会失败。另有 fromJsonDropsBlankButKeepsDuplicateBlocks 断言空行丢弃、重复行保留;fromJsonRejectsInvalidPayloads 覆盖非 JSON、数组、空 id、负时长。引擎测试用一个 MockTransport 把回调存起来,测试里手动 finishRecognize(),不碰 socket,QTRY_* 只负责转事件循环。两个测试二进制一共 19 个测试函数(模型 9 + 引擎 10),QtTest 的 Totals 会把 initTestCase / cleanupTestCase 算进去,所以显示 11 + 12 passed。
9. 1001400001 和构建输出
模拟器上桥是通的,识别不通。同一组 curl 在 11 月 13 日拿到了 500:/v1/ping 正常,识别请求返回 {"error":{"code":"OCR_VISION_ERROR","message":"Core Vision Kit init failed (200): Run timed out, please try again later."}}。设备侧 textRecognition.init() 返回 code=200 / Run timed out,直接调 recognizeText 则是 1001400001 / Failed to run OCR, please try again.。这是 2in1 模拟器镜像不带设备端 AI 服务;桥、权限和图片格式都没有问题。应用页会显示“Core Vision Kit 初始化超时(200)。鸿蒙模拟器通常不支持端侧 OCR,请改用真机”,并继续显示内置示例图预览;不会用演示数据伪造结果。C++ 侧收到 500 + OCR_VISION_ERROR,failed() 里带原始 code,QML 的错误条原样显示。
桌面构建与单测:
cmake -S . -B build-desktop -G Ninja \
-DQT_OHOS_OCR_BUILD_EXAMPLES=ON \
-DQT_OHOS_OCR_BUILD_TESTS=ON
cmake --build build-desktop --parallel
ctest --test-dir build-desktop --output-on-failure
输出:
1/2 Test #1: tst_ohosocrresult ................ Passed 0.36 sec
2/2 Test #2: tst_qohosocrengine ............... Passed 0.47 sec
100% tests passed, 0 tests failed out of 2
鸿蒙侧:
cd examples/ohos-app
ohpm install --all
hvigorw --mode module -p module=entry@default -p product=default \
-p buildMode=debug assembleHap --no-daemon
BUILD SUCCESSFUL,产物 entry-default-unsigned.hap 约 206 KB。仓库里的预览截图是 tools/mock_bridge.py 起的假桥生成的:7 行、900×620、186 ms,用来验证 QML 布局和 C++ 解析,不冒充设备识别。真机安装需要本机 DevEco 自动签名,签名材料不提交。
10. 验证范围与边界
仓库 11 月 13 日的验证覆盖了模拟器:桥通、UI 通、错误路径通。11 月 12 日那张 55 行截图是设备上的另一次运行,环境表里 443 ms 那一行就是从那一次来的,作为参考读数记录。
桥这一侧能确定的是路由、契约和桌面上的 19 项测试:传输失败、契约失败、识别失败各走各的错误码,failed() 里带的是原始 code,QML 不用自己拆字符串。Core Vision Kit 那半边有 11 月 12 日的一张截图作参考;识别质量由系统引擎决定,桥替不了。
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念,把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起,为开发者提供从开发、训练到部署的一站式体验。
更多推荐

所有评论(0)