# rust-paddle-ocr-java

**Repository Path**: wuyuan/rust-paddle-ocr-java

## Basic Information

- **Project Name**: rust-paddle-ocr-java
- **Description**: 基于 paddle-ocr-capi（Rust + MNN 的 PaddleOCR C FFI）的 Java JNA 封装 + Spring Boot 4.1.1 示例应用。
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-05
- **Last Updated**: 2026-09-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ocr-java

基于 [paddle-ocr-capi](https://github.com/zibo-chen/paddle-ocr-capi)（Rust + MNN 的 PaddleOCR C FFI）的 **Java JNA 封装 + Spring Boot 4.1.1 示例应用**。

- 包名 / groupId：`com.podman.ocr`
- 模块：`ocr-core`（纯库，无 Spring 依赖）+ `ocr-app`（Spring Boot 4.1.1 Web 示例）
- Java 17+，Maven 多模块
- **core 不内置模型**：模型文件放在仓库外（项目根 `models/`），路径由 `application.yml` 配置，换模型无需重新打包

## 目录结构

```
ocr-java/
├── pom.xml                      # 父工程（聚合 + BOM 管理 Spring Boot 4.1.1）
├── models/                      # 模型文件（不在任何 jar 内，由配置指定路径）
│   ├── PP-OCRv6_small_det.mnn
│   ├── PP-OCRv6_small_rec.mnn
│   └── ppocr_keys_v6_small.txt
├── core/                        # ocr-core：JNA 封装库（独立 pom，可单独发布）
│   └── src/main/
│       ├── java/com/podman/ocr/core/
│       │   ├── OcrCapi.java     # JNA 接口（与 ocr_capi.h 一一对应）
│       │   ├── OcrEngine.java   # 高层引擎封装（AutoCloseable）
│       │   ├── OcrConfig.java   # 引擎配置 DTO
│       │   ├── OcrResult.java   # 识别结果 DTO
│       │   ├── NativeLibLoader.java  # 自动解压/加载当前平台原生库
│       │   └── ResourceFiles.java    # 模型路径解析 + 存在性校验
│       └── resources/
│           ├── native/windows/ocr_capi.dll   # Windows x64（随 jar 分发）
│           └── native/linux/libocr_capi.so   # Linux x86_64（随 jar 分发）
├── app/                         # ocr-app：Spring Boot 4.1.1 Web 服务
│   └── src/main/java/com/podman/ocr/app/
│       ├── OcrApplication.java
│       ├── config/   # OcrProperties + OcrConfigBean（引擎单例 Bean）
│       ├── service/  # OcrService
│       ├── web/      # OcrController（REST 接口）
│       └── dto/      # 响应 DTO
└── scripts/                     # 发布脚本（只发布 core）
    ├── deploy-core.ps1          # Windows / PowerShell
    └── deploy-core.sh           # Linux / CI
```

## 构建与测试

```bash
mvn clean install
```

- `ocr-core` 冒烟测试：从 `-Docr.models.dir`（默认项目根 `models/`）加载模型 + 当前平台原生库，对程序生成图片做真实识别。
- `ocr-app` 集成测试：surefire 工作目录设为项目根，`application.yml` 的 `./models/xxx` 相对路径在测试与真实运行中行为一致。

> Java 25 下 JNA 需 `--enable-native-access=ALL-UNNAMED`（surefire 已配置）。

## 运行

在项目根目录启动（模型路径 `./models/...` 基于工作目录解析）：

```bash
java --enable-native-access=ALL-UNNAMED -jar app/target/ocr-app-1.0.0.jar
```

生产部署建议：把 `ocr-app-1.0.0.jar` 与 `models/` 放同一目录后从该目录启动，或把模型路径改成绝对路径。

### REST 接口

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/api/ocr/version` | 引擎版本与模型名 |
| POST | `/api/ocr/recognize` | multipart 上传图片（字段名 `file`），支持 jpg/png/bmp 等 |
| POST | `/api/ocr/recognize-base64` | JSON `{"imageBase64": "...", "suffix": "png"}` |

> 服务端自动预处理：短边小于 960px 的图片会先等比放大到短边 960px 再识别。
> PP-OCR 检测模型对小尺寸图片（尤其文字密集的海报/截图）容易漏检，放大可显著提升召回率；正常尺寸图片不受影响。

响应示例：

```json
{"count":1,"items":[{"text":"Hello OCR 2026 v6","confidence":0.985,"box":{"x":34,"y":55,"width":481,"height":59}}]}
```

### 配置（application.yml，环境变量可覆盖）

| 配置 | 默认值 | 说明 |
|---|---|---|
| `ocr.model` | `PP-OCRv6_small` | 模型名（仅展示） |
| `ocr.det-model` | `./models/PP-OCRv6_small_det.mnn` | 检测模型路径 |
| `ocr.rec-model` | `./models/PP-OCRv6_small_rec.mnn` | 识别模型路径 |
| `ocr.charset` | `./models/ppocr_keys_v6_small.txt` | 字符集路径 |
| `ocr.thread-count` | `4` | 推理线程数 |
| `ocr.det-max-side-len` | `960` | 检测最大边长 |
| `ocr.min-result-confidence` | `0.5` | 结果最低置信度 |
| `ocr.backend` | `0` | 0=CPU（Release 仅含 CPU，GPU 需自编译） |

模型路径支持：

- **文件系统路径（推荐）**：相对路径（基于运行工作目录）或绝对路径，如 `D:/models/det.mnn`
- **classpath 资源**：`classpath:models/xxx`（仅当模型被打进依赖 jar 时，core 默认不内置）

路径错误时启动即报错（`模型/资源文件不存在: <绝对路径>`），不会带病运行。环境变量覆盖示例：
`OCR_DET_MODEL=/data/models/det.mnn java -jar app.jar`。

换模型：把 `.mnn` 与 keys 文件放到任意目录，改 `application.yml` 三个路径即可，无需重新构建。

## 单独使用 ocr-core（不依赖 Spring）

```java
import com.podman.ocr.core.OcrConfig;
import com.podman.ocr.core.OcrEngine;
import com.podman.ocr.core.OcrResult;

try (OcrEngine engine = OcrEngine.create(
        "./models/PP-OCRv6_small_det.mnn",
        "./models/PP-OCRv6_small_rec.mnn",
        "./models/ppocr_keys_v6_small.txt",
        new OcrConfig().threadCount(4))) {
    for (OcrResult r : engine.recognizeFile("test.png")) {
        System.out.println(r.getText() + " / " + r.getConfidence());
    }
}
```

## 发布到 Maven 仓库（只发布 core）

`ocr-core` 是独立 pom（不继承聚合父 pom），发布后依赖方只拉取这一个构件即可使用，无需父 pom。

### 私有仓库（Nexus / Artifactory / GitHub Packages 等）

```powershell
# Windows
.\scripts\deploy-core.ps1 -RepoId nexus -RepoUrl https://nexus.example.com/repository/maven-releases
# Linux
./scripts/deploy-core.sh -u https://nexus.example.com/repository/maven-releases -i nexus
```

凭据在 `~/.m2/settings.xml` 中按 `<server><id>nexus</id>` 配置。

### Maven Central

```powershell
.\scripts\deploy-core.ps1 -Central -GpgKeyname 0xABCDEF1234567890 -Version 1.1.0
```

Central 模式自动启用 `-P release`（sources/javadoc 附件 + GPG 签名），并需要：
- `settings.xml` 中配置 `<server><id>ossrh</id>` 账号密码
- 本机 GPG 密钥（发布前先把公钥上传到 keyserver）
- core pom 中 `<licenses>/<developers>/<scm>` 改为你自己的信息（发布前必改）

### 本地试跑（验证打包产物完整）

```powershell
.\scripts\deploy-core.ps1 -Local -SkipTests
```

产物输出到 `build/deploy-repo/`：jar、sources、javadoc、pom 及校验文件。

> 发布体积：core jar 约 5.5MB（仅原生库 + 类，不含模型）；模型按需部署在服务端，不进仓库。

## 原生库说明

- 来源：`zibo-chen/paddle-ocr-capi` Release v0.0.3
- `NativeLibLoader` 按运行平台从 jar 内 `native/{os}/` 自动解压加载：
  - Windows x64 → `ocr_capi.dll`（依赖 MSVC 运行库）
  - Linux x86_64 → `libocr_capi.so`（glibc）
- 也可用 `-Docr.native.lib.dir=xxx` 指定外部原生库目录，跳过内置解压。
- 官方 Release 为 CPU-only；GPU（Metal/OpenCL/Vulkan）需自行编译原生库。

## 模型来源

- 模型：`zibo-chen/rust-paddle-ocr`（分支 `next`，`models/` 目录），`.mnn` 为 MNN 格式。
- 下载通道：`cdn.jsdelivr.net/gh/zibo-chen/rust-paddle-ocr@next/models/...`（raw.githubusercontent.com 在国内网络时常超时）。
- 当前使用 PP-OCRv6 small 三件套；文件大小与上游仓库一致，已校验。

## 注意事项

- 引擎句柄线程非安全：`OcrEngine` 内部已加锁；高并发建议每线程/每请求池建独立引擎。
- 每个识别结果由封装层自动 `ocr_result_list_free`，引擎由 `close()`/`destroyMethod` 释放，无内存泄漏。
- 仓库未声明 LICENSE（父项目为 Apache-2.0），商用前请自行确认授权。