#paddleocr

中国人民共和国
你好，世界。
MoonBit OCR 2026

#安装

moon add V1GreenSummer/paddleocr@0.1.0

///|
import {
  "V1GreenSummer/paddleocr",
}

///|
import {
  "V1GreenSummer/paddleocr/ocr",
}

#最小可运行示例

moon run examples/ctc

你好

#流水线

JPEG / PNG / BMP
        │  mizchi/image
        ▼
      RGBA
        │
        ├─ 检测：长边 ≤ 960，两边对齐 32，NCHW BGR，ImageNet 归一化
        │        moon-ort → DB 概率图
        │        四连通域 → 最小面积矩形 → unclip → 透视裁正
        │
        └─ 裁正后的横条，高度 48，均值和标准差都是 0.5
                 moon-ort → CTC 贪心解码
                 ▼
               文本行

1. sniff_raster 看文件头，decode_raster 解成 RGBA8。JPEG 只接受 baseline。
2. 检测输入把长边限制在 limit_side_len（默认 960），短边按比例缩放，再把两边舍入到 32 的倍数，最小 32。双线性插值。像素先除以 255，再按 OpenCV 的 BGR 顺序做 ImageNet 归一化：通道 0 是蓝，均值 (0.485, 0.456, 0.406)，标准差 (0.229, 0.224, 0.225)。
3. 检测模型的第 0 个输出当成单通道概率图。db_quads 做四连通域，用像素块的凸包求最小面积矩形。短边小于 min_size（3）或平均分低于 box_thresh（0.6）的块丢掉。剩下的矩形按 area * unclip_ratio / perimeter 沿边外扩（unclip_ratio 默认 1.5，前景阈值 0.3）。db_regions 用一次连通域同时给出两种框；db_boxes 仍保留轴对齐外接矩形，给只需要正框的调用方。
4. 四边形按检测图到原图的比例映回去。Rgba::warp 做透视裁切，把四条边拉成横条。高宽比至少 1.5 的竖条再逆时针转 90°。外接矩形用来分行：后一个框与当前行在竖直方向的重叠不少于较短高度的一半时并进同一行，行内按 x 排序。同一行的文字直接拼接，中间不插入空格。
5. 识别输入把裁块缩到高度 48（模型若把高度轴标成定长，就用那个高度）。宽度按宽高比向上取整，默认不超过 320。模型的宽度轴若是定长，右侧用归一化后的 0 补齐。识别归一化是 (x - 0.5) / 0.5，三个通道相同，因此 RGB 与 BGR 在这一步等价。
6. CTC 类别 0 是 blank，不出现在字典里。类别 k 对应字典第 k - 1 行。连续相同的类别折成一个字。Charset::from_text 按文件原样解析；Charset::ppocr 在末尾没有空格时补上一行，对应官方 use_space_char。字典里没有的类别被丢掉。ctc_decode 把保留下来的字符的概率取平均，低于 rec_thresh（默认 0.5）的框不进入结果。

///|
test {
  let (width, height) = @paddleocr.limit_side_size(1000, 500, limit=960)
  inspect(width, content="960")
  inspect(height, content="480")
  let charset = @paddleocr.Charset::from_text("你\n好\n")
  let logits : Array[Float] = [0.0, 1.0, 0.0, 0.0, 0.0, 1.0]
  inspect(
    @paddleocr.ctc_greedy(logits, time=2, classes=3, charset~),
    content="你好",
  )
}

#目标平台

#仓库

moon.mod                         模块 V1GreenSummer/paddleocr
decode.mbt / rgba.mbt            PNG、JPEG、BMP → RGBA
preprocess.mbt                   检测 / 识别张量
detect.mbt                       概率图 → 框 → 行
ctc.mbt / page.mbt               字典、CTC、Page
error.mbt                        OcrError
engine/                          native：Engine、EngineOptions、Backend 和批处理
ocr/                             native 单入口：重导出 Engine 与结果/几何类型
examples/ctc/                    不依赖模型的 CTC 最小示例
cmd/ocr/                         native 可执行文件

#第三方依赖与许可证

#准备运行时和模型

• libonnxruntime.so.1.30.0。版本必须是 1.30.0，否则 moon-ort 报 API 不匹配。推荐从官方 release 下载 Linux x64 包：
  https://github.com/microsoft/onnxruntime/releases/download/v1.30.0/onnxruntime-linux-x64-1.30.0.tgz
  该 tarball 的 SHA256 是 a5ed5a3cac51fbb2e90da632ae43d19212faaa20e76484e62bcb7c23ddb3b3fd（与 moon-ort CI 使用的一致）。解压后使用 lib/libonnxruntime.so.1.30.0。也可以从 Python 包 onnxruntime==1.30.0 的 manylinux wheel 提取；本项目验证时使用的文件 SHA256 是 c902c70b3003c0e99fada202f37478c515ae9bba7944c2b2abd0017bae0c82ed。
• PP-OCRv4 中文检测、识别 ONNX。模型来自 PaddleOCR，RapidOCR 提供 ONNX 转换和模型列表。验证用的是：

  文件	SHA256
  ch_PP-OCRv4_det_infer.onnx	d2a7720d45a54257208b1e13e36a8479894cb74155a5efe29462512d42f49da9
  ch_PP-OCRv4_rec_infer.onnx	48fc40f24f6d2a207a2b1091d3437eb3cc3eb6b676dc3ef9c37384005483683b

• ppocr_keys_v1.txt：一行一个字符。文件本身通常不含空格。Engine::load 用 Charset::ppocr 读它，并在末尾补上 PP-OCR 的空格类。已经以空格结尾的字典不会再补第二次。验证时使用的字典 SHA256 是 28b2362ad4ab2dc38769aa72feb535e3a9ddb3fd2a7585a05920e6393b1dc7f7。

export MOON_ORT_LIBRARY=/path/to/libonnxruntime.so.1.30.0

#命令行

moon run --target native cmd/ocr -- page.png \
  --det ch_PP-OCRv4_det_infer.onnx \
  --rec ch_PP-OCRv4_rec_infer.onnx \
  --dict ppocr_keys_v1.txt \
  --boxes

63,59,352,46	0.9941148446743899	0.9998255542346409	中国人民共和国
57,134,280,53	0.9936801729464608	0.9986610412597656	你好，世界。
60,219,444,41	0.989933144244093	0.9717656522989273	MoonBit OCR 2026

#在代码里调用

///|
import {
  "V1GreenSummer/paddleocr/ocr",
}

let page = @ocr.with_engine(
  det=det_path,
  rec=rec_path,
  dict=dict_path,
  engine => {
    engine.recognize_file(image_path)
  },
)
println(page.render())

///|
let settings = @ocr.EngineOptions::standard()
  .with_intra_op_threads(4)
  .with_rec_batch_size(8)

///|
let engine = @ocr.Engine::load(
  det=det_path,
  rec=rec_path,
  dict=dict_path,
  options=settings,
)

let engine = @ocr.Engine::load(det=det_path, rec=rec_path, dict=dict_path)
let quads = engine.detect(image)                 // 只检测
let page = engine.recognize_quads(image, quads)  // 改框后识别
let raw = engine.recognize_regions(crops)        // 只识别已有裁块
engine.close()

#边界

• 识别用的是最小面积矩形外扩后的四边形，再透视裁正。--boxes 打印的是这个四边形的外接矩形。弯曲的一行仍会被收成一个矩形，邻行贴得很近时也会粘在一起。
• 竖排文字会转成横条。整行倒转 180° 时还没有方向分类模型，识别会按倒着的顺序读。
• 识别是每步取最大类别的 CTC，没有词典束搜索。同宽 crop 在动态 batch 模型上会合并成一次 session 调用。置信度低于 rec_thresh（默认 0.5）的框被丢掉；recognize_regions 不做这一步过滤。
• 能认哪些字取决于加载的识别模型和字典。load 只为 PP-OCR 补末尾空格类；别的模型继续用 Engine::open 和 Charset::from_text。
• 同一行里的多个框直接拼接，框与框之间不另插空格。空格只来自模型预测到的空格类。
• 识别批处理只在模型 batch 维是动态时启用；固定 batch 维为 1 的模型逐条识别。
• JPEG 只支持 baseline。自然场景的效果取决于检测模型；阈值沿用 Paddle 的默认值。
• riantr/tesseract 是一个 JSON 数据库，和 OCR 无关。

#测试

moon test
moon test --target native