离线OCR组件系列项目：

• PaddleOCR-json
• RapidOCR-json

PaddleOCR-json

支持：Win7 x64、Linux x64、Docker

这是一个基于PaddleOCR v2.6和v2.8 cpp_infer的离线图片OCR文字识别程序，可以快速为你的程序添加OCR功能。它可以作为子进程被上层程序调用，也可以作为独立进程通过TCP调用。本项目提供了Python等语言的API，你可以忽略技术细节，通过两行代码使用它。

本项目旨在提供一个封装好的OCR引擎组件，使得没有C++编程基础的开发者也可以用其他语言简单地调用OCR，享受更快的运行效率和更便捷的打包部署方式。

• 方便：部署简单，解压即用，无需安装和配置环境，无需联网。发布方便，可嵌入程序包也可作为外挂组件。
• 高速：基于PPOCR C++版引擎，识别效率高于Python版本PPOCR及其他一些由Python处理任务流的OCR引擎。
• 精准：附带PPOCR-v3 / v4识别库，对非常规字形（手写、艺术字、小字、杂乱背景等）也有不错的识别率。
• 灵活：可以以多种方式指定OCR任务，支持识别本地图片路径、Base64编码的图片、TCP局域网调用。

应用：Umi-OCR批量图片转文字工具

兼容性

• 系统：x86-64的Windows 7+、Linux。

• 若Win7报错"计算机中丢失VCOMP140.DLL"，请安装VC运行库。

• CPU必须具有AVX指令集。常见的家用CPU一般都满足该条件。

  AVX	支持的产品系列	不支持
  Intel	酷睿Core，至强Xeon	凌动Atom，安腾Itanium，赛扬Celeron，奔腾Pentium
  AMD	推土机架构及之后的产品，如锐龙Ryzen、速龙Athlon、FX等	K10架构及之前的产品

• 如果需要在无AVX的CPU上使用OCR，可以看看RapidOCR-json。

准备工作

下载可执行文件包：

• https://github.com/hiroi-sora/PaddleOCR-json/releases/latest

简单试用

PaddleOCR-json.exe -image_path="test.jpg"

通过API调用

调用流程大体分为以下几步。不同API的具体接口可能有细微差别。

• 启动：启动并初始化引擎子进程。
• 工作：调用识图接口，获取返回值。目前支持识别本地图片文件、剪贴板中的图片、Base64编码的图片。
• 关闭：结束引擎进程，释放内存资源。

API列表

资源目录下有更详细的使用说明及演示示例。

1. Python API

资源目录

from PPOCR_api import GetOcrApi

# 初始化识别器对象，传入 PaddleOCR_json.exe 的路径
ocr = GetOcrApi("……\PaddleOCR-json.exe")

# 识别图片，传入图片路径
getObj = ocr.run(r'………\测试.png')
print(f'图片识别完毕，状态码：{getObj["code"]} 结果：\n{getObj["data"]}\n')

2. Node.js API

资源目录

npm install paddleocrjson

const OCR = require('paddleocrjson');

// const OCR = require('paddleocrjson/es5'); // ES5

const ocr = new OCR('PaddleOCR-json.exe', [/* '-port=9985', '-addr=loopback' */], {
    cwd: './PaddleOCR-json',
}, false);

ocr.flush({ image_path: 'path/to/test/img' })
    .then((data) => console.log(data));
    .then(() => ocr.terminate());

3. PowerShell API

资源目录

4. Java API

资源目录

5. .NET API

资源目录

6. Rust API

资源目录

7. Go API

资源目录

更多语言API

欢迎补充！请参考 详细使用指南。

常用配置参数说明

更多参数详见 args.cpp。（不支持其中GPU相关、表格识别相关的参数。）

语言库与切换识别语言：

Release压缩包中，默认附带了 简中,繁中,英,日,韩 的语言库与配置文件，在 models 目录下。

models 目录中，每一个 config_xxx.txt 是一组语言配置文件（如英文是config_en.txt）。只需将这个文件的路径传入 config_path 参数，即可切换为对应的语言。以 Python API 为例：

enginePath = "D:/Test/PaddleOCR_json.exe"  # 引擎路径
argument = {"config_path": "models/config_en.txt"}  # 指定使用英文库
ocr = GetOcrApi(enginePath, argument)

如果 config_path 为空，PaddleOCR-json 将默认加载并使用简体中文识别库。

然而，当使用默认路径或单独设置 config_path 时，PaddleOCR-json 可执行文件必须与语言库位于同一目录下。例如：

.
├─ PaddleOCR-json.exe
└─ models
    ├─ ...

如果语言库位于另一个文件夹中，PaddleOCR-json 将无法找到它。

在这种情况下，你可以使用 models_path 参数来设置语言库的位置。PaddleOCR-json 将以用户设置的语言库位置为基准来加载其他文件。

这样，即使 PaddleOCR-json 与语言库不在同一目录下也能正常使用。以 Python API 为例：

enginePath = "D:/Test/PaddleOCR_json.exe"  # 引擎路径
modelsPath = "D:/Hello/models"             # 语言库路径
# 这里的参数顺序不影响结果
argument = {
  # 指定语言库位置
  "models_path": "D:/Hello/models",
  # 指定使用英文库
  "config_path": "D:/Hello/models/config_en.txt",
}
ocr = GetOcrApi(enginePath, argument)

本项目支持 PP-OCR 系列官方 V2~V4 模型，或符合PP规范的自训练模型。更多 PP-OCR 系列官方模型下载：https://github.com/PaddlePaddle/PaddleOCR/blob/main/doc/doc_ch/models_list.md

删除语言库：

如果你想删除不用的语言库文件以减少软件体积，可以删除 models 目录中包含对应语言前缀和 rec_infer 后缀的文件夹。比如要删除日语japan相关的库，只需删除这个文件夹： japan_PP-OCRv3_rec_infer

一组语言的rec库大约占用10MB空间（未压缩）。如果删除到只剩1组语言，可以节省约60MB空间。

请不要删除cls_infer和det_infer后缀的文件夹，这是所有语言共用的检测/方向分类库。

返回值说明

通过API调用一次OCR，无论成功与否，都会返回一个字典。

字典中，根包含两个元素：状态码code和内容data。

状态码code为整数，每种状态码对应一种情况：

100 识别到文字

• data内容为数组。数组每一项为字典，包含三个固定元素：
  • text：文本内容，字符串。
  • box：文本包围盒，长度为4的数组，分别为左上角、右上角、右下角、左下角的[x,y]。整数。
  • score：识别置信度，0~1的浮点数。越接近1表示文字内容越可信。
• （v1.4.0新增）如果启用了 cls 和 use_angle_cls，那么会多出两个元素：
  • cls_label：方向分类标签，整数。0 表示文字方向是顺时针 0°或90°，1 表示 180°或270°。
  • cls_score：方向分类置信度，0~1的浮点数。越接近1表示方向分类越可信。
• 例：

    {'code':100,'data':[{'box':[[13,5],[161,5],[161,27],[13,27]],'score':0.9996442794799805,'text':'飞舞的因果交流'}]}
  

101 未识别到文字

• data为字符串：No text found in image. Path:"图片路径"
• 例：{'code':101,'data':'No text found in image. Path: "D:\\空白.png"'}
• 这是正常现象，识别没有文字的空白图片时会出现这种结果。

200 图片路径不存在

• data：Image path dose not exist. Path:"图片路径".
• 例：{'code':200,'data':'Image path dose not exist. Path: "D:\\不存在.png"'}
• 注意，在系统未开启utf-8支持（使用 Unicode UTF-8 提供全球语言支持）时，不能读入含emoji等特殊字符的路径（如😀.png）。但一般的中文及其他 Unicode 字符路径是没问题的，不受系统区域及默认编码影响。

201 图片路径string无法转换到wstring

• data：Image path failed to convert to utf-16 wstring. Path: "图片路径".
• 使用API时，理论上不会报这个错。
• 开发API时，若传入字符串的编码不合法，有可能报这个错。

202 图片路径存在，但无法打开文件

• 数据：图片打开失败。路径："图片路径"。
• 可能由系统权限等原因引起。

203 图片打开成功，但读取到的内容无法被OpenCV解码

• 数据：图片解码失败。路径："图片路径"。
• 注意，引擎不以文件后缀来区分各种图片，而是对存在的路径，均读入字节尝试解码。若传入的文件路径不是图片，或图片已损坏，则会报这个错。
• 反之，将正常图片的后缀改为别的（如.png改成.jpg或.exe），也可以被正常识别。

300 base64字符串解析为string失败

• 数据：Base64解码失败。
• 传入非法Base64字符串引起。（注意，传入Base64信息不应带有data:image/jpg;base64,前缀。）

301 base64字符串解析成功，但读取到的内容无法被OpenCV解码

• 数据：Base64数据图像解码失败。

400 JSON对象转字符串失败

• 数据：JSON转储失败。CODE_ERR_JSON_DUMP
• 输入异常：传入非法JSON字符串，或者字符串含非UTF-8编码字符导致无法解析引起。

401 JSON字符串转对象失败

• 数据：JSON转储失败。CODE_ERR_JSON_DUMP
• 输出异常：输出时OCR结果无法被编码为JSON字符串。

402 JSON对象解析某个键时失败

• 数据：JSON解析键"键名"失败。
• 比错误码400更精准的提示。如果发生异常，程序优先报402，无法处理才报400。

403 未发现有效任务

• 数据：没有有效任务。
• 本次传入的指令中不含有效任务。

详细使用指南

👆当你需要修改或开发新API时欢迎参考。

项目构建指南

稳定版，基于PP-OCR v2.6

• Windows平台构建步骤
• Linux平台构建步骤
• Docker部署

最新开发版，基于PP-OCR v2.8

• Windows 平台构建步骤
• Linux 平台构建步骤
• Docker 部署
• 移植指南（需要移植项目到不同平台时可供参考）

致谢

本项目使用了 ReneNyffenegger/cpp-base64：

"基于 C++ 的 base64 编码和解码"

本项目使用了 nlohmann/json：

"现代 C++ 的 JSON 库"

感谢 PaddlePaddle/PaddleOCR，没有它就不会有本项目：

"基于 PaddlePaddle 的出色多语言 OCR 工具包"

感谢所有为本项目开发 API 及贡献代码的朋友们！

更新日志

版本号链接可前往对应备份分支。

v1.4.1 dev 1 2024.7.31

• 更新推理后端至 Paddle Inference 3.0.0 beta-1。
• 大幅优化内存占用：峰值由 2.5GB 降至约 1.5GB。
• 增加命令行参数：内存自动清理界限 --cpu_mem。详见 文档。
• 小幅优化初始化耗时。
• 支持 PP-OCR V4 系列模型库，及 PPOCR 算法挑战赛 冠军方案模型库。
• 由于后端依赖库的更新，在 非 AVX512 的 CPU 上，OCR 速度可能有 小幅下降。
• 由于语言库 cyrillic（斯拉夫字母/俄语）的准确度较低、使用频率较低，发行包中不再包含此语言库。有需要的用户可 自行下载。
• Python API：修复了布尔类型启动参数设为 False 不生效的问题。

v1.4.0 2024.7.22

v1.4.0 beta 2 2024.7.9

• 返回值新增：文字方向分类相关参数。

v1.4.0 beta 2024.7.5

• 兼容 Linux。
• 调整：默认禁用剪贴板识图功能，需自行编译开启。

v1.3.1 2023.10.10

• 兼容 Win7 x64。

v1.3.0 2023.6.19

• 修复了一些 BUG。

v1.3.0 alpha 2023.5.26

• 重构代码，条理更清晰，易于移植。
• 新功能：Base64 传图片。
• 新功能：套接字服务器模式。

v1.2.1 2022.9.28

• 修复了一些 BUG。
• 解决非中文 Windows 难以读取中文路径的问题，拥抱 UTF-8，彻底摆脱对 GBK 等区域性编码的依赖。
• 新功能：直接读取并识别剪贴板内存中的图片。
• 错误代码和提示更详细。

v1.2.0 2022.8.29

• 修复了一些 BUG。
• 增强了面对不合法编码时的健壮性。
• 默认开启 MKLDNN 加速。
• 新功能：JSON 输入及热更新。

v1.2.0 beta 2022.8.26

• 重构整个工程，核心代码同步 PaddleOCR 2.6。
• 对 v3 版识别库的支持更好。
• 新功能：启动参数。
• 新功能：ASCII 转义。（感谢 @AutumnSun1996 的提议 issue #4）

v1.1.1 2022年4月16日

• 修复了一个漏洞：当"文本检测"识别到区域但"文本识别"未在该区域内检测到文字时，可能会输出不匹配的边界框。

v1.1.0 2022年4月2日

• 修改了JSON输出格式，改为状态码+内容的形式，以便调用方进行判断。

v1.0 2022年3月28日