mica-ppocr（Java 图片 OCR 识别） ​

Java CIJAVA 8Mica Maven release

PP-OCRv6 文字检测 + 识别的 Java 实现，纯 ONNX Runtime 推理，零 PaddlePaddle 依赖。完整复现预处理 / 后处理（DB 后处理、CTC 解码、pyclipper 等价的多边形 unclip），并与 Python 参考实现保持 bit-exact（默认 CPU 单线程）。

除纯 OCR 外，本项目还提供开箱即用的证件 / 票据结构化解析，省去从零写标签匹配的工作。

📦 模块导航 ​

模块说明
mica-ppocr-core核心引擎 PPOcrV6Engine：检测 → 排序 → 裁剪 → 识别
mica-ppocr-structured结构化解析层，各证件 / 票据的 XxxParser
mica-ppocr-spring-boot-starterSpring Boot 自动装配，注入 PPOcrTemplate 即可用

✨ 能力一览 ​

核心引擎 ​

  • 公开入口只暴露 String / File / Path / byte[] 四种入参，内部自动完成 OpenCV Mat 解码与 release，调用方无需关心 native 内存。
  • run(...) 完整 OCR（检测 → 排序 → 裁剪 → 识别）；detect(...) 仅检测。
  • 可选 doc_ori 文档方向分类模型，检测前对整图做方向校正（4 类：0°/90°/180°/270°），避免用户侧倒拍 / 横拍导致识别失败。
  • DB 阈值、识别批大小、ORT 线程数、GPU 加速等全部走 PPOcrV6Config 的 @Builder。

已实现的结构化解析器 ​

解析器结果类型生产验证
行驶证VehicleLicenseResult✅
身份证（正反面自动判定）IdCardResult✅
银行卡BankCardResult—
机动车驾驶证DriverLicenseResult—
营业执照BusinessLicenseResult—
增值税发票InvoiceResult—
火车票TrainTicketResult—
出租车票TaxiReceiptResult—
户口本（常住人口登记卡）HouseholdRegisterResult—
拼多多福袋（8 位邀请码）PddLuckyBagResult—

每个解析器同时提供静态 parse(List<PPOcrV6Result>) 与 SPI parseResults(...) 两种调用形式，便于自定义扩展。

🚀 快速开始 ​

1️⃣ 添加依赖 ​

xml
<!-- 核心引擎 -->
<dependency>
    <groupId>net.dreamlu</groupId>
    <artifactId>mica-ppocr-core</artifactId>
    <version>${mica.ppocr.version}</version>
</dependency>

<!-- 或 Spring Boot Starter（自动传递 core + structured） -->
<dependency>
    <groupId>net.dreamlu</groupId>
    <artifactId>mica-ppocr-spring-boot-starter</artifactId>
    <version>${mica.ppocr.version}</version>
</dependency>

2️⃣ 准备模型 ​

下载 PP-OCRv6 官方 ONNX 模型（det + rec）到 models/ppocr-v6/{tier}/：

档次detrec字符表定位
tiny1.7 MB4.3 MB约 2855轻量优先，速度快
small9.4 MB20.2 MB约 2855速度与精度均衡，推荐默认
medium59.2 MB73.0 MB约 7180精度优先，字符集更全

medium 的 det/rec 为 .onnx.zip，需解压后使用。

3️⃣ 跑通 ​

Spring Boot 入口（详见 mica-ppocr-core 的 Spring Boot 章节）：

java
@Autowired
private PPOcrTemplate ppocr;

@PostMapping("/ocr/vehicle")
public VehicleLicenseResult vehicle(@RequestParam MultipartFile file) throws IOException {
    return ppocr.vehicleLicense().parse(file.getBytes());  // 一行：检测 → 识别 → 结构化
}

纯 Java 引擎：

java
try (PPOcrV6Engine engine = new PPOcrV6Engine(config)) {
    List<PPOcrV6Result> results = engine.run("_assets/test_images/vehicle/vehicle1.png");
    for (PPOcrV6Result r : results) {
        System.out.printf("%s  (%.3f)%n", r.text(), r.score());
    }
}

🛠️ 环境要求 ​

组件版本说明
JDK8+
ONNX Runtime1.18.0内置原生库兼容更多操作系统版本
OpenCV4.10.0-0含 Windows/Linux/macOS 原生库
JTS1.20.0多边形偏移（pyclipper 等价物）
PDFBox3.0.8PDF 双通道（文本层抽取 + 渲染兜底）

⚙️ 调优要点 ​

  • intra-op-num-threads 建议设为 CPU 物理核数（非逻辑核）。
  • CPU arena / memory pattern 自 v1.2.0 起默认关闭：动态分辨率下两者不归还内存给 OS，会导致内存持续增长直至 OOM（issue #14），关闭约损失 10% 吞吐。输入分辨率固定且追求极致吞吐时可成对开启。
  • GPU：替换为 onnxruntime_gpu 并设 prefer-accelerator: true，此时 intra-op-num-threads 设为 1（甚至 0），把并行让给 GPU。

🤖 AI 辅助开发 ​

项目内置两个 skill，可通过 skills.sh 一键安装：

bash
npx skills add lets-mica/mica-ppocr
  • mica-ppocr-custom-parser — 新增证件 / 票据解析器的完整开发链路
  • ocr-parser-optimizer — 已有解析器的批量调优（跑批 → 失败模式诊断 → 最小改动 → 对比报告）

🔗 相关链接 ​

📄 License ​

Apache License 2.0