RapidOCR4j项目学习

https://rapidai.github.io/RapidOCRDocs/install_usage/api/RapidOCR/#_1

功能实现

• 多平台OCR识别：支持 Windows、Linux、 macOS（包括 Intel 和 ARM 架构）
• 多种图片输入方式：支持图片路径（Path）、BufferedImage、byte[]、OpenCV 的 Mat 四种输入类型
• 模型推理：通过 ONNXRuntime 加载和推理 OCR 模型（检测 det.onnx、识别 rec.onnx、字典 txt）
• 图片预处理与后处理：利用 OpenCV 对图片进行预处理（如缩放、灰度化等），并对模型输出做后处理（如文本框坐标、文本内容提取）
• 可扩展性强：纯 Java 实现，便于二次开发和集成到其他 Java 项目中
• 支持 CPU 和 GPU：默认 CPU 推理，可选用 onnxruntime_gpu 依赖支持 CUDA GPU

实现原理与底层逻辑

整体架构

核心流程：图片输入 → OpenCV 预处理 → ONNXRuntime 推理（检测+识别）→ 结果后处理 → 输出结构化文本结果

模块划分：

• 配置模块（OcrConfig/ParamConfig）：管理模型路径、参数等
• 推理模块（RapidOCR）：负责模型加载、推理和流程调度
• 工具模块（OcrJsonConverter 等）：结果格式化、辅助功能

关键技术点

ONNXRuntime 推理

• 模型加载：通过 OcrConfig 配置 det.onnx（文本检测）、rec.onnx（文本识别）模型路径，以及字典文件路径
• 推理过程：
  • 文本检测模型（det.onnx）：定位图片中的文本区域，输出文本框坐标
  • 文本识别模型（rec.onnx）：对检测到的文本区域进行识别，输出文本内容
  • 推理引擎：ONNXRuntime 支持跨平台和多种硬件（CPU/GPU），Java 通过 JNI 调用底层 C++ 实现

OpenCV 图像处理

• 预处理：如图片缩放、灰度化、归一化等，提升模型识别准确率
• 后处理：如文本框坐标变换、NMS（非极大值抑制）去重等

多输入类型适配
支持 Path、BufferedImage、byte[]、Mat 四种输入，内部统一转为 OpenCV Mat 进行处理，保证接口灵活性和兼容性

结果结构化
识别结果通过 OcrResult 封装，支持转为 JSON，便于前后端交互或二次处理

代码示例

// 通过图片路径识别
rapidOCR.run("src/test/resources/a.png");// 通过 BufferedImage 识别
rapidOCR.run(bufferedImage, paramConfig);// 通过字节流识别
rapidOCR.run(byte[]);// 通过 OpenCV Mat 识别
rapidOCR.run(mat);

与 README.md 的底层逻辑呼应

• 配置灵活：通过 OcrConfig 可自定义模型路径、OpenCV 库路径等，适配不同平台和环境
• 依赖管理：Maven 依赖简单，支持 CPU/GPU 切换，便于集成
• 跨平台：底层依赖 ONNXRuntime 和 OpenCV，Java 层做了良好封装，保证了平台兼容性
• 二次开发友好：纯 Java 代码，接口清晰，易于扩展和集成到其他系统

总结

RapidOCR4j 是一个高效、跨平台、易集成的 OCR 解决方案，底层基于 ONNXRuntime（模型推理）和 OpenCV（图像处理），通过 Java 封装实现了多输入类型适配和结构化输出，支持 CPU/GPU，适合在多种业务场景下进行文本识别任务。其架构设计注重灵活性和可扩展性，便于后续功能拓展和平台适配。

OcrConfig 结构与参数详解

OcrConfig 是 RapidOCR4j 的主配置类，分为四大部分：全局配置（Global）、检测模块（Det）、分类模块（Cls）、识别模块（Rec）。

GlobalConfig（全局配置）

参数名	类型	默认值	作用说明
textScore	float	0.5	文本置信度阈值，低于该值的文本框会被过滤掉。
useDet	boolean	true	是否启用文本检测模块。
useCls	boolean	false	是否启用方向分类模块（如检测文本方向）。
useRec	boolean	true	是否启用文本识别模块。
printVerbose	boolean	true	是否打印详细日志，便于调试。
minHeight	int	30	处理图片的最小高度，低于该值的图片会被缩放。
widthHeightRatio	float	8	图片宽高比限制，防止极端长宽图片影响识别。
maxSideLen	int	2000	图片最大边长，超出会缩放。
minSideLen	int	30	图片最小边长，低于会缩放。
returnWordBox	boolean	false	是否返回单词级别的文本框（否则返回行级别）。
intraOpNumThreads	int	-1	ONNX 单线程操作数，-1 表示默认。
interOpNumThreads	int	-1	ONNX 多线程操作数，-1 表示默认。
opencvLibPath	String	null	OpenCV 动态库路径（dll/so），用于自定义 OpenCV 依赖。

说明：这些参数主要控制整体流程、图片预处理、日志输出和多线程性能调优。opencvLibPath 可用于适配不同平台的 OpenCV 动态库。

DetConfig（检测模块配置）

参数名	类型	默认值	作用说明
intraOpNumThreads	int	-1	ONNX 单线程操作数。
interOpNumThreads	int	-1	ONNX 多线程操作数。
useCuda	boolean	false	是否启用 CUDA（GPU）加速。
deviceId	int	0	GPU 设备编号。
useDml	boolean	false	是否启用 DML（DirectML，Windows 下的 GPU 加速）。
modelPath	String	models/ch_PP-OCRv4_det_infer.onnx	检测模型路径。
limitSideLen	int	736	输入图片边长限制，超出会缩放。
limitType	String	“min”	边长限制类型（min/max）。
thresh	float	0.3	检测阈值，低于该值的候选框会被过滤。
boxThresh	float	0.5	边框置信度阈值。
maxCandidates	int	1000	最大候选框数量。
unclipRatio	float	1.5	NMS 后扩展比例，影响文本框大小。
useDilation	boolean	true	是否使用膨胀操作，提升文本框闭合性。
scoreMode	String	“fast”	评分模式（如 fast/normal，影响速度和精度）。
useArena	boolean	false	是否启用 arena 内存池（提升速度但增加内存占用）。

说明：这些参数主要影响文本检测的性能、精度和硬件加速方式。useArena 是底层 ONNX 的内存池策略，适合高性能场景但需注意内存占用。

ClsConfig（分类模块配置）

参数名	类型	默认值	作用说明
intraOpNumThreads	int	-1	ONNX 单线程操作数。
interOpNumThreads	int	-1	ONNX 多线程操作数。
useCuda	boolean	false	是否启用 CUDA。
deviceId	int	0	GPU 设备编号。
useDml	boolean	false	是否启用 DML。
modelPath	String	models/ch_ppocr_mobile_v2.0_cls_infer.onnx	分类模型路径。
clsImageShape	int[]	{3,48,192}	分类输入图片形状（通道数、高、宽）。
clsBatchNum	int	1	分类批处理数量。
clsThresh	float	0.9	分类置信度阈值。
labelList	String[]	{“0”,“180”}	分类标签（如 0: 正常，180: 旋转180°）。
useArena	boolean	false	是否启用 arena 内存池。

说明：主要用于文本方向分类，适合竖排/横排混合或有旋转文本的场景。clsImageShape、clsBatchNum 可调节性能和适配不同模型。

RecConfig（识别模块配置）

参数名	类型	默认值	作用说明
intraOpNumThreads	int	-1	ONNX 单线程操作数。
interOpNumThreads	int	-1	ONNX 多线程操作数。
useCuda	boolean	false	是否启用 CUDA。
deviceId	int	0	GPU 设备编号。
useDml	boolean	false	是否启用 DML。
modelPath	String	models/ch_PP-OCRv4_rec_infer.onnx	识别模型路径。
recImgShape	int[]	{3,48,320}	识别输入图片形状（通道数、高、宽）。
recBatchNum	int	1	识别批处理数量。
useArena	boolean	false	是否启用 arena 内存池。
recKeysPath	String	null	字典路径（如不设置，默认从模型获取）。

说明：recImgShape、recBatchNum 可根据模型和硬件调整，recKeysPath 用于自定义字典（如支持不同语言/字符集）。

底层未暴露但可调节的参数

• ONNXRuntime 线程数（intraOpNumThreads/interOpNumThreads）：可根据服务器 CPU 核心数调优，提升并发性能。
• Arena 内存池（useArena）：适合高吞吐场景，但需监控内存占用。
• DML 支持：Windows 下可用 DirectML 进行 GPU 加速，适合没有 CUDA 的机器。
• OpenCV 动态库路径（opencvLibPath）：可自定义 OpenCV 版本，适配不同平台或自编译库。

每个参数/代码的实际作用举例

config.getDet().setModelPath("models/det.onnx");
// 设置检测模型路径，决定用哪个 onnx 模型做文本检测。config.getRec().setRecKeysPath("xxx.txt");
// 设置识别字典路径，支持自定义字符集。config.getGlobal().setUseDet(false);
// 关闭文本检测，适合已知文本区域的场景。config.getRec().setUseCuda(true);
// 启用 GPU 加速，提升识别速度。

总结

• OcrConfig 提供了极为丰富的参数，涵盖了模型路径、硬件加速、图片预处理、批处理、内存策略等各个方面。
• 绝大多数参数都可以通过 OcrConfig 进行灵活配置，适配不同业务场景和硬件环境。
• 还有部分底层参数如线程数、arena 内存池、DML 支持等，适合对性能有极致要求的场景。
• 如需进一步了解每个参数的底层实现细节，可以继续查看各模块（如 TextDetector、TextRecognizer、TextClassifier）的源码实现。