项目简介

mica-ppocr 是 PP-OCRv6 文字检测与识别流水线的 Java 移植版，使用纯 ONNX Runtime 推理、零 PaddlePaddle 依赖，并完整复现预处理 / 后处理（DB 后处理、CTC 解码、pyclipper 等价的多边形 unclip）。移植自 AIwork4me/ppocrv6_onnx 的单文件 Python 参考实现，与 Python 版本保持 bit-exact（默认 CPU 单线程，跨平台输出确定）。

定位上，mica-ppocr 不只是一个 OCR 引擎，更是一套面向证件 / 票据 / 卡证场景的端到端识别方案：

• OCR 核心 mica-ppocr-core：检测 + 识别 + 文档方向分类 + PDF 双通道

• 结构化解析 mica-ppocr-structured：内置 10 类常用证件 / 票据解析器

• Spring Boot Starter mica-ppocr-spring-boot-starter：自动装配引擎与解析器，开箱即用

• Solon 插件 mica-ppocr-solon-plugin：Solon 用户同等体验
  全模块 Java 8 兼容，已发布到 Maven Central，坐标 net.dreamlu:mica-ppocr-*。

核心特性

• 零 Paddle 依赖：仅需 ONNX Runtime + OpenCV + JTS（PDF 模块再 + PDFBox），没有 C++ 编译、没有原生 Paddle 库，jar 包直跑。

• 与 Python 参考 bit-exact：默认 intraOp=interOp=1，跨机器输出完全一致，便于回归测试与模型调优。

• Java 8 全兼容：源码、依赖字节码均校验为 Java 8，可直接用于 Spring Boot 2.x / Solon 等 Java 8 老项目。

• 10 类内置结构化解析器：行驶证、身份证（正反面自动判定）、银行卡、机动车驾驶证、营业执照、增值税发票（含新版数电票）、火车票、出租车票、户口本（常住人口登记卡）、拼多多福袋（8 位邀请码）。

• PDF 双通道：run(byte[]) / run(Path) 自动嗅探 %PDF- 魔数，文字型 PDF 直接走 PDFBox 文本层抽取（无 OCR 开销），扫描件自动降级渲染位图 + OCR（DPI 可配）。

• 文档方向分类（可选）：在检测前对整图做 4 类方向（0°/90°/180°/270°）校正，避免侧拍 / 横拍导致的识别失败。

• 按调用覆盖检测阈值：run(...) / runMat(...) 新增 DbDetParams 重载，临时调整 thresh / boxThresh / unclipRatio 等，无需改动引擎配置，线程安全。

• 可视化友好：结构化结果同时返回 rawResults（全部文字框）与 fieldBoxes（字段→坐标），可在前端高亮"这个字段来自画面哪几块"。

• AI 协作原生支持：项目内置 mica-ppocr-custom-parser 与 ocr-parser-optimizer 两个 Skill，覆盖新增解析器全链路与已有解析器批量调优，可通过 npx skills add lets-mica/mica-ppocr 一键安装到 Claude Code / Cursor 等 AI 编码工具。

快速上手（Spring Boot 一行接入）

• 引入 starter：

    net.dreamlu
    mica-ppocr-spring-boot-starter
    1.2.3

application.yml 指定模型路径：

mica:
  ai:
    ppocr:
      det-model-path: models/ppocr-v6/tiny/det.onnx
      rec-model-path: models/ppocr-v6/tiny/rec.onnx
      rec-char-dict-path: models/ppocr-v6/tiny/dict.txt

• Controller 直接调：

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

已实现的结构化解析器

模型三档速览

版本更新汇总（v1.0.0 → v1.2.3）

v1.2.3 - 2026-09-12（本次主推）

• feat：run 系列方法全面支持按调用覆盖 DB 参数。run / runMat 新增 DbDetParams 重载（thresh / boxThresh / unclipRatio / maxCandidates / minSize），按调用临时调整检测阈值、无需改动引擎构造期配置，线程安全（临时构造 DbPostProcessor，不修改共享状态）；同步下沉到 PDF 双通道，BaseStructuredParser 新增 5 个 parse(..., DbDetParams) 重载，Spring Boot / Solon PPOcrTemplate 同步支持。

• fix：修复词典空白 token 处理导致识别结果丢空格、英文单词粘连问题。CtcLabelDecoder 对齐 Python 参考实现（仅剥 \n\r），原样保留词典中间全角空格（U+3000）与末尾 ASCII 空格两个空白 token，并新增回归测试锁定。（GitHub #23）

• fix：修复发票大写金额转换 parseJiaoFen 的整型隐患（curDigit 由 long 改为 int），消除 CodeQL 告警。

v1.2.2 - 2026-09-07

• feat：新增 PDF 双通道模块，文字型 PDF 走文本层抽取（无 OCR 开销），扫描件自动降级 PDFBox 渲染位图（DPI 可配，默认 200）。

• feat：新增 DbDetParams + detectMat(Mat, DbDetParams) 按调用覆盖 DB 阈值。（GitHub #24）

• fix：修复发票商品名称跨行被误拆为两条明细。明细行的"锚"是数值列（金额 / 税额），InvoiceTableParser 新增续行合并。

• fix：修复 GPU 加速 provider 未注册问题。

v1.2.1 - 2026-09-01

• feat：优化行驶证结构化解析。

• feat：发票解析统一入口 + 支持新版电子发票（数电票）。

• fix：修复发票解析器地址电话 / 开户行账号多框拼接与发票号码解析。

v1.2.0 - 2026-08-27

• fix：根治动态分辨率下内存持续增长（GitHub #14）。新增 enableCpuMemArena（默认 false）、enableMemoryPattern（默认 false）配置，关闭 ONNX Runtime CPU arena / 内存模式优化，临时内存用完即释放，Docker 等内存受限环境不再 OOM；新增 execMode 配置（sequential / parallel）暴露 ORT 执行模式。

• refactor：全面支持 Java 8。record / List.of / Path.of 等 Java 9+ API 替换为 CollUtil 工具与 Lombok @Value 风格；Spring Boot Starter 改用 @Configuration 兼容 2.5~4.x。

v1.1.7 - 2026-08-26

• feat：新增拼多多福袋 OCR 结构化解析器，从"百亿补贴 抽福袋"分享图提取 8 位福袋码（邀请码）。

• feat：身份证性别解析支持合并框切割，兼容"性别男民族汉"双标签连写合并框及"性""别"字缺失场景。

• fix：优化身份证地址跨行解析逻辑与消除多标签合并框告警。

• fix：提升身份证识别精度。

• fix：新增真实 OCR 样本单元测试验证合并框"所有人 xxx"正确剥离前缀。

• fix：修正户籍信息日期识别和关系字段匹配逻辑。

• fix：修复 PPOcrV6Engine.decodeMat 泄漏 MatOfByte native buffer。

v1.1.6 - 2026-08-21

• fix：还原 detLimitSideLen、detLimitType 默认组合为 64 + min，更适合证件类解析。

v1.1.4 - 2026-08-21

• feat：新增火车票、出租车票、户口本（常住人口登记卡）OCR 结构化解析器。

• feat：兼容 15 位身份证号解析，并增加按身份证号推算出生日期的兜底。

• feat：模型路径支持 classpath: 前缀，可把模型打进 Spring Boot Fat Jar。

• refactor：文档方向分类阈值由 0.3 调至 0.4；detLimitSideLen、detLimitType 默认组合由 64 + min 改为 960 + max（PaddleX v4 / v5 / v6 官方推荐组合）。

• refactor：简化 PPOcrTemplate 结构化解析器管理实现，Solon 与 Spring Boot Starter 同步新增户口本解析器注册及参数校验。

• docs：新增 mica-ppocr-custom-parser skill，覆盖自定义结构化解析器全链路。

v1.1.3 - 2026-08-15

• feat：身份证多标签合并框解析逻辑优化，新增正面字段标签数组，支持"性别男民族汉"双标签连写的合并框切分。

• refactor：重构结构化解析器基类及测试基类。BaseStructuredParser 由接口改为抽象类，统一持有 PPOcrV6Engine 引擎并提供一站式 parse() 实现，子类构造时绑定引擎、仅需重写 parseResults。

• refactor：简化 PPOcrTemplate 模板，各个结构化解析器改为链式调用。

v1.1.2 - 2026-08-13

• feat：新增 Solon 插件适配模块 mica-ppocr-solon-plugin，提供 PPOcrTemplate 一站式封装与结构化解析器自动装配，能力与 Spring Boot Starter 对齐。

• feat：新增营业执照结构化解析器（BusinessLicenseParser），抽取社会信用代码、单位名称、住址、法定代表人、有效日期至、成立日期、类型、注册资本、经营范围共 9 个字段。

• feat：新增增值税发票结构化解析支持（InvoiceParser），配套上海 / 湖北 / 江苏等多张发票 OCR JSON 样本。

• refactor：优化 BusinessLicenseParser 编码规范，12 个 LABEL 常量、5 个调参常量集中化、4 个子函数便于单测。

• refactor：结构化解析模块日志级别全面由 info 调整为 debug，显著降低控制台噪音。

v1.1.1 - 2026-08-13

• feat：支持 PP-OCRv6 文档方向分类（use_doc_orientation_classify）。使用 PP-LCNet_x1_0_doc_ori 模型（4 类：0°/90°/180°/270°），在 OCR 检测前对整图做方向校正。新增 useDocOrientationClassify / docOrientationModelPath / docOrientationThresh 配置项，行为完全向后兼容（默认关闭）。

• perf：性能优化 + 修 native Mat 泄漏。DocOrientationPreprocessor 修 resizeShort 返回新 Mat 未 release 的泄漏；CtcLabelDecoder 解码循环 3 合并为 1 次。

• chore：onnxruntime 依赖版本降级为 1.18.0，兼容更多系统版本。

v1.1.0 - 2026-08-12

• feat：新增 mica-ppocr-structured 结构化解析模块，支持行驶证、身份证、银行卡、驾驶证 4 类证件；提供 SPI 接口 BaseStructuredParser 与公共骨架 LabelMatcher（标签定位 + 位置匹配 + 正则兜底）。

• feat：新增 PPOcrTemplate 一站式封装（mica-ppocr-spring-boot-starter），自动装配 PPOcrTemplate 与 4 个结构化解析器 Bean。

• feat：结构化结果支持可视化坐标，新增 BaseStructuredResult 抽象类，统一持有 rawResults（完整 OCR 原始框）与 fieldBoxes（字段→坐标列表映射）。

• refactor：公开 API 去掉 Mat 入参；PPOcrV6Engine 的 run / detect 统一委托到 Path 版本，新增 String / File / Path / byte[] / InputStream 5 种入参重载；内部统一 try-finally 释放 Mat，调用方无需任何 native 内存管理。

v1.0.1 - 2026-08-10

• fix：释放原生推理资源，避免本地句柄泄漏；新增泄漏回归测试并加固构造器清理路径。

• refactor：OpenCV 加载方法由 loadShared 改为 loadLocally。

v1.0.0 - 2026-08-07

• feat：实现 PP-OCRv6 文字检测与识别核心功能（DB 后处理 + CTC 解码）。

路线与计划

• 持续打磨已实现的 10 类结构化解析器精度与鲁棒性。

• 跟进 PaddleOCR / PP-OCR 系列新模型（如更高精度模型、行业版模型）。

• 持续完善 PDF 双通道与文档方向分类的边界场景。

• 欢迎社区贡献：自定义解析器、更多 OCR 噪声场景 case、Spring Boot / Solon 生态适配。