DriftLedger/plugins/ppocr/README.md

PP-OCRv5 (ONNX Runtime) Config Plugin

本插件在 expo prebuild 时注入 PP-OCRv5 本地 OCR 原生模块（plan.md 决策 4）。

引擎选用 ONNX Runtime（跨平台、微软官方、Windows 友好），替代原 NCNN 方案。

文件结构

plugins/ppocr/
├── app.plugin.js              # Config Plugin 入口（prebuild 时执行）
├── android/                   # Kotlin 原生实现（prebuild 时复制进原生工程）
│   ├── OcrModule.kt           # React Native Bridge：ONNX Runtime 推理 + det/rec 前后处理
│   └── OcrPackage.kt          # RN Package 注册（注入到 MainApplication.getPackages）
└── assets/                    # ONNX 模型 + 字典（需自行下载放置）
    ├── ppocrv5_det.onnx       # 文本检测模型
    ├── ppocrv5_rec.onnx       # 文本识别模型
    └── ppocr_keys_v1.txt      # CJK 字典（CTC 解码用）

模型获取（一键下载）

社区已转好的 ONNX 版本（来自官方 Paddle 权重，无质量损失）：

# 在项目根目录执行
mkdir -p plugins/ppocr/assets
cd plugins/ppocr/assets

# det 模型（4.8 MB）
curl -L -o ppocrv5_det.onnx https://huggingface.co/ilaylow/PP_OCRv5_mobile_onnx/resolve/main/ppocrv5_det.onnx

# rec 模型（16.6 MB）
curl -L -o ppocrv5_rec.onnx https://huggingface.co/ilaylow/PP_OCRv5_mobile_onnx/resolve/main/ppocrv5_rec.onnx

# CJK 字典（26 KB，PaddleOCR 标准字典）
curl -L -o ppocr_keys_v1.txt https://raw.githubusercontent.com/PaddlePaddle/PaddleOCR/release/2.6/ppocr/utils/ppocr_keys_v1.txt

或用 HuggingFace CLI（首次下载原生模型再转 ONNX 的方式，参见历史 git log）。

来源说明：ilaylow/PP_OCRv5_mobile_onnx 是社区维护的 PP-OCRv5 mobile ONNX 镜像，基于官方 PaddlePaddle/PP-OCRv5_mobile_det 与 _rec 转换而来。

性能配置（参考 AutoAccounting OcrProcessor.kt）

优化项	配置
引擎	ONNX Runtime Android 1.20.1
执行器	CPU（兼容性最稳，部分设备 GPU 会崩溃）
线程	intraOp=2 / interOp=2
det 图像	最大边 960px，短边压缩 720px
rec 图像	固定高度 48px
ABI	arm64-v8a（主流设备）

使用

在 app.json 注册插件：

{
  "plugins": ["./plugins/ppocr"]
}

JS 层通过 src/services/ocrBridge.ts 的 NativeOcrBridge 调用，桥接到 NativeModules.PpOcr：

• recognizeText(base64) → 返回纯文本（多行用 \n 连接）
• recognizeTextBlocks(base64) → 返回带坐标的文本块数组 [{text, x, y, width, height, confidence}]
• isReady() → 模型是否加载完成

当前状态

• app.plugin.js：✅ Config Plugin 逻辑（prebuild 注入 Kotlin + 模型 + gradle 依赖 + MainApplication 注册）
• android/OcrModule.kt：✅ ONNX Runtime 推理（det DB 后处理 + rec CTC 解码）
• android/OcrPackage.kt：✅ RN Package 注册
• assets/：需自行下载放置（见上「模型获取」），版权/体积原因不入仓库

真机构建步骤：放置模型文件 → npx expo prebuild --platform android → npx expo run:android。