rapidocr

使用 OpenCV 与 ONNX Runtime 完成图片文字检测、方向分类和识别。

版本 0.1.0 · 默认模型已随包提供 · 依赖 opencv、onnxruntime

快速开始

import rapidocr

auto engine = rapidocr.RapidOCR()
assert engine.valid()
auto output = engine.op_call("picture.png")
if output.ok() then
    println(output.text())
else
    println(output.error())
end
engine.release()

默认模型位于包的 models/ 目录；资源路径解析失败会抛错，不以空目录继续配置模型。识别成功但未发现文字时，ok() 为真，text() 为空。

接口

入口	用途
`RapidOCR()`	创建默认模型引擎；模型不可用时 `valid()` 为假。
`engine.op_call(path)`	识别图片并返回结果对象。
`output.text / to_json / error`	读取文本、结构化输出或失败原因。
`output.to_ocr_json() / rapidocr.to_ocr_items_json(result_json)`	将结果转换为 OCR 条目 JSON；支持文字和置信度阈值。
`release()`	提前释放引擎或结果；对象析构也会释放原生资源。

C 头文件 extlibs/rapidocr/include/rapidocr.h 当前提供后处理与可选原生桥接层入口。缺少或残缺桥接层时 C 创建与调用明确返回空句柄及错误，不再制造伪引擎或空 JSON；显式桥接路径失败不回退搜索。公开的 XLang 后处理入口遇到坏张量、缺字典或无效结果句柄会抛带诊断的 RuntimeError；合法无检测框仍返回 []。XLang 无桥接时仍可使用包内 OpenCV/ONNX 模型链路。C 不能独立完成整套 OCR 推理，不能把 C 后处理范例当作 C OCR 成品。

验证与现状

powershell -NoProfile -ExecutionPolicy Bypass -File extlibs/rapidocr/test/check.ps1 -SkipAot

固定测试图已真实识别为 HELLO123；当前 Windows 默认门禁通过严格 GCC、缺图/缺模型、真实推理 JIT/AOT、回退流水线与测试桥接的隐式句柄清理 JIT/AOT，以及 C/XLang 后处理对照。XLang 的路径与传入原生接口的 JSON 均拒绝内嵌 NUL。结果组装、三条检测框路径、识别与分类解码、字符表信息和 OCR 条目转换入口返回独立的 XRT 字符串，C 调用方以 xrtFree 释放；长文本、转义字符与错误输入已有定向测试。资源定位与可选 DLL 加载支持 UTF-8 路径；检测框几何使用结构化 JSON 解析。包级错误按线程隔离，可选后端首次加载使用 once。测试专用完整桥接层验证 C/XLang 成功、失败、恢复和释放，残缺桥接层被拒绝；这只证明公开 ABI 转发。包内 OpenCV/ONNX 调用链已验证；桥接实现与压力矩阵由插件独立维护。C 完整推理仍需真实桥接层。

2026-10-21：Windows 门禁将图片、测试 DLL 和可执行文件写入每次独占的 build/test/rapidocr/run_<id> 并在退出时清理；Linux C 门禁使用独占系统临时目录。既有固定目录文件不再被覆盖。Windows 真实模型 HELLO123、完整/残缺测试桥接调用和 Linux C 公开调用均复验通过；本轮未重跑压力模式，当时完整 AOT 未签收；2026-10-26 当前 Windows 默认门禁的真实 XLang 推理与句柄清理 AOT 已通过，C 完整推理桥接仍待补。