RapidOCR Python

RapidOCR Python

简介和说明

各个版本的ONNX模型下载地址：百度网盘 | Google Drive
所有常用的参数配置都在config.yaml下，一目了然，更加便捷
目前config.yaml中配置为权衡速度和准确度的最优组合。
每个独立的模块下均有独立的config.yaml配置文件，可以单独使用
det部分：
- det中mobile和server版，推理代码一致，直接更改配置文件中模型路径即可
- det中v2和v3两个版本，推理代码一致。
rec部分：
- rec中mobile和server版本，推理代码一致，直接更改配置文件中模型路径即可
- rec中v2和v3两个版本，共用同一个推理代码。
  - 两版本差别仅在输入shape和模型。经过测试，采用v3 rec模型+[3, 48, 320]效果最好。
  - 目前配置文件config.yaml中（如下所示）已是最优组合。
```
module_name: ch_ppocr_v3_rec
class_name: TextRecognizer
model_path: resources/models/ch_PP-OCRv3_rec_infer.onnx

rec_img_shape: [3, 48, 320]
rec_batch_num: 6
```
关于openvino详细的使用方法，参见openvino_readme。
关于选择哪个推理引擎（onnxruntime 或者 openvino）?

推理引擎推理速度更快占用内存更少

onnxruntime ✓

openvino ✓ 存在内存不释放的问题

（推荐）pip安装快速使用

安装rapidocr包
- rapidocr_onnxruntime → pip install rapidocr-onnxruntime
- rapidocr_openvino → pip install rapidocr-openvino
- 注意：两个包接口一致，只是推理引擎不同而已

推理使用

📌初始化RapidOCR可不提供config.yaml，默认使用rapidocr_onnxruntime目录下的。如有特殊需求，可以自行更改目录下的config.yaml。

import cv2
from rapidocr_onnxruntime import RapidOCR
# from rapidocr_openvino import RapidOCR

# RapidOCR可传入参数参考下面的命令行部分
rapid_ocr = RapidOCR()

img_path = 'tests/test_files/ch_en_num.jpg'

# 支持四种格式的输入：Union[str, np.ndarray, bytes, Path]
# str
result = rapid_ocr(img_path)

# np.ndarray
img = cv2.imread('tests/test_files/ch_en_num.jpg')
result = rapid_ocr(img)

# bytes
with open(img_path, 'rb') as f:
    result = rapid_ocr(f.read())

# Path
result = rapid_ocr(Path(img_path))
print(result)

# result: [[文本框坐标], 文本内容, 置信度]
# 示例：[[左上, 右上, 右下, 左下], '小明', '0.99']

# 如果没有有效文本，则result: (None, None)

命令行使用：

$ rapidocr_onnxruntime -h
usage: rapidocr_onnxruntime [-h] -img IMG_PATH [-p] [--text_score TEXT_SCORE]
                            [--use_angle_cls USE_ANGLE_CLS]
                            [--use_text_det USE_TEXT_DET]
                            [--print_verbose PRINT_VERBOSE]
                            [--min_height MIN_HEIGHT]
                            [--width_height_ratio WIDTH_HEIGHT_RATIO]
                            [--det_model_path DET_MODEL_PATH]
                            [--det_limit_side_len DET_LIMIT_SIDE_LEN]
                            [--det_limit_type {max,min}]
                            [--det_thresh DET_THRESH]
                            [--det_box_thresh DET_BOX_THRESH]
                            [--det_unclip_ratio DET_UNCLIP_RATIO]
                            [--det_use_dilation DET_USE_DILATION]
                            [--det_score_mode {slow,fast}]
                            [--cls_model_path CLS_MODEL_PATH]
                            [--cls_image_shape CLS_IMAGE_SHAPE]
                            [--cls_label_list CLS_LABEL_LIST]
                            [--cls_batch_num CLS_BATCH_NUM]
                            [--cls_thresh CLS_THRESH]
                            [--rec_model_path REC_MODEL_PATH]
                            [--rec_image_shape REC_IMAGE_SHAPE]
                            [--rec_batch_num REC_BATCH_NUM]

optional arguments:
-h, --help            show this help message and exit
-img IMG_PATH, --img_path IMG_PATH MUST
-p, --print_cost

Global:
--text_score TEXT_SCORE
--use_angle_cls USE_ANGLE_CLS
--use_text_det USE_TEXT_DET
--print_verbose PRINT_VERBOSE
--min_height MIN_HEIGHT
--width_height_ratio WIDTH_HEIGHT_RATIO

Det:
--det_model_path DET_MODEL_PATH
--det_limit_side_len DET_LIMIT_SIDE_LEN
--det_limit_type {max,min}
--det_thresh DET_THRESH
--det_box_thresh DET_BOX_THRESH
--det_unclip_ratio DET_UNCLIP_RATIO
--det_use_dilation DET_USE_DILATION
--det_score_mode {slow,fast}

Cls:
--cls_model_path CLS_MODEL_PATH
--cls_image_shape CLS_IMAGE_SHAPE
--cls_label_list CLS_LABEL_LIST
--cls_batch_num CLS_BATCH_NUM
--cls_thresh CLS_THRESH

Rec:
--rec_model_path REC_MODEL_PATH
--rec_image_shape REC_IMAGE_SHAPE
--rec_batch_num REC_BATCH_NUM

$ rapidocr_onnxruntime -img tests/test_files/ch_en_num.jpg

源码使用步骤

下载整个项目到本地
```
cd RapidOCR/python
```

下载链接下的resources目录（包含模型和显示的字体文件）

下载链接：Github | Gitee | 百度网盘 | Google Drive
resources/models下模型搭配已经为最优组合（速度和精度平衡）
```
ch_PP-OCRv3_det + ch_ppocr_mobile_v2.0_cls +  ch_PP-OCRv3_rec
```

最终目录如下，自行比对:

.
├── README.md
├── demo.py
├── rapidocr_onnxruntime
│   ├── __init__.py
│   ├── ch_ppocr_v2_cls
│   ├── ch_ppocr_v3_det
│   ├── ch_ppocr_v3_rec
│   ├── config.yaml
│   ├── rapid_ocr_api.py
│   └── models
│        ├── ch_PP-OCRv3_det_infer.onnx
│        ├── ch_ppocr_mobile_v2.0_cls_infer.onnx
│        └── ch_PP-OCRv3_rec_infer.onnx
├── rapidocr_openvino
│   ├── __init__.py
│   ├── README.md
│   ├── ch_ppocr_v2_cls
│   ├── ch_ppocr_v3_det
│   ├── ch_ppocr_v3_rec
│   ├── config.yaml
│   ├── rapid_ocr_api.py
│   └── models
│        ├── ch_PP-OCRv3_det_infer.onnx
│        ├── ch_ppocr_mobile_v2.0_cls_infer.onnx
│        └── ch_PP-OCRv3_rec_infer.onnx
├── requirements.txt
└── resources
      └── fonts
         └── FZYTK.TTF

安装运行环境
- 基于onnxruntime推理所需环境安装：
```
pip install onnxruntime>=1.7.0

pip install -r requirements.txt
```
- 基于openvino推理所需环境安装：
```
pip install openvino

pip install -r requirements.txt
```
- Note: 在Windows端，Shapely库自动安装可能会有问题，解决方案参见Q15

运行示例

运行单元测试
```
pytest tests/test_*.py
```

接口调用

import cv2

# 基于onnxruntime引擎推理
from rapidocr_onnxruntime import RapidOCR

# 基于openvino引擎推理
# from rapidocr_openvino import RapidOCR

rapid_ocr = RapidOCR()

image_path = r'test_images/det_images/ch_en_num.jpg'
img = cv2.imread(image_path)

result = rapid_ocr(img)
print(result)

# result: [[文本框坐标], 文本内容, 置信度]
# 示例：[[左上, 右上, 右下, 左下], '小明', '0.99']

直接运行demo.py，可直接可视化查看结果。
```
python demo.py
```

`config.yaml`中常用参数介绍

Global部分

参数名称	取值范围	默认值	作用
`text_score`	[0, 1]	0.5	文本识别结果置信度，值越大，把握越大
`use_angle_cls`	`bool`	`true`	是否使用文本行的方向分类
`print_verbose`	`bool`	`true`	是否打印各个部分耗时信息
`min_height`	`int`	30	图像最小高度（单位是像素）低于这个值，会跳过文本检测阶段，直接进行后续识别
`width_height_ratio`	`int`	8	如果输入图像的宽高比大于`width_height_ratio`，则会跳过文本检测，直接进行后续识别 `width_height_ratio=-1`：不用这个参数

min_height是用来过滤只有一行文本的图像（如下图），这类图像不会进入文本检测模块，直接进入后续过程。

Det部分

参数名称	取值范围	默认值	作用
`use_cuda`	`bool`	`false`	是否使用CUDA，加速推理
`limit_side_len`	-	736	限制图像边的长度的像素值
`limit_type`	`[min, max]`	`min`	限制图像的最小边长度还是最大边为`limit_side_len` 示例解释：当`limit_type=min`和`limit_side_len=736`时，图像最小边小于736时，会将图像最小边拉伸到736，另一边则按图像原始比例等比缩放。
`thresh`	[0, 1]	0.3	图像中文字部分和背景部分分割阈值值越大，文字部分会越小
`box_thresh`	[0, 1]	0.5	文本检测所得框是否保留的阈值，值越大，召回率越低
`max_candidates`	-	1000	图像中最大可检测到的文本框数目，一般够用
`unclip_ratio`	[1.6, 2.0]	1.6	控制文本检测框的大小，值越大，检测框整体越大
`use_dilation`	`bool`	`true`	是否使用形态学中的膨胀操作，一般采用默认值即可
`score_mode`	`string`	`fast`	`fast`是求rectangle区域的平均分数，容易造成弯曲文本漏检，`slow`是求polygon区域的平均分数，会更准确，但速度有所降低，可按需选择

Cls部分

参数名称	取值范围	默认值	作用
`cls_img_shape`	-	`[3, 48, 192]`	输入方向分类模型的图像Shape（CHW）
`cls_batch_num`	-	6	批次推理的batch大小，一般采用默认值即可，太大并没有明显提速，效果还可能会差
`cls_thresh`	`[0, 1]`	0.9	方向分类结果的置信度
`label_list`	-	`[0, 180]`	方向分类的标签，0°或者180°，该参数不能动

Rec部分

参数名称	取值范围	默认值	作用
`rec_img_shape`	-	`[3, 48, 320]`	输入文本识别模型的图像Shape（CHW）
`rec_batch_num`	-	6	批次推理的batch大小，一般采用默认值即可，太大并没有明显提速，效果还可能会差

onnxruntime-gpu版相关说明

目前已知在onnxruntime-gpu上测试过的小伙伴，反映都是GPU推理速度比在CPU上慢很多。经过探索，初步确定原因为onnxruntime在推理动态图输入时，速度就会慢很多。关于该问题，已经提了相关issue,具体可参见onnxruntime issue#13198
为了便于比较onnxruntime上推理的基准比较，简单整理了一个AI Studio: TestOrtInfer项目，小伙伴想要测试的，可以直接Fork来运行查看。

onnxruntime-gpu版推理配置

onnxruntime-gpu需要严格按照与CUDA、cuDNN版本对应来安装，具体参考文档，这一步关乎后面是否可以成功调用GPU。

以下是安装示例：

所用机器环境情况：
- nvcc-smi显示CUDA Driver API版本：11.7
- nccc -V显示CUDA Runtime API版本：11.6
- 以上两个版本的对应关系，可参考博客

具体安装命令如下：

conda install cudatoolkit=11.6.0
conda install cudnn=8.3.2.44
pip install onnxruntime-gpu==1.12.0

验证是否可以onnxruntime-gpu正常调用GPU

验证get_device()是否可返回GPU

import onnxruntime as ort

print(ort.get_device())
# GPU

如果第一步满足了，继续验证onnxruntime-gpu加载模型时是否可以调用GPU

import onnxruntime as ort

providers = [
    ('CUDAExecutionProvider', {
        'device_id': 0,
        'arena_extend_strategy': 'kNextPowerOfTwo',
        'gpu_mem_limit': 2 * 1024 * 1024 * 1024,
        'cudnn_conv_algo_search': 'EXHAUSTIVE',
        'do_copy_in_default_stream': True,
    }),
    'CPUExecutionProvider',
]

# download link: https://github.com/openvinotoolkit/openvino/files/9355419/super_resolution.zip
model_path = 'super_resolution.onnx'
session = ort.InferenceSession(model_path, providers=providers)

print(session.get_providers())
# 如果输出中含有CUDAExecutionProvider,则证明可以正常调用GPU
# ['CUDAExecutionProvider', 'CPUExecutionProvider']

更改config.yaml中对应部分的参数即可，详细参数介绍参见官方文档。

use_cuda: true
CUDAExecutionProvider:
    device_id: 0
    arena_extend_strategy: kNextPowerOfTwo
    gpu_mem_limit: 2 * 1024 * 1024 * 1024
    cudnn_conv_algo_search: EXHAUSTIVE
    do_copy_in_default_stream: true

推理情况

下载基准测试数据集（test_images_benchmark），放到tests/benchmark目录下。
- 百度网盘 | Google Drive
- 最终目录结构如下：
```
tests/benchmark/
    ├── benchmark.py
    ├── config_gpu.yaml
    ├── config.yaml
    └── test_images_benchmark
```

运行以下代码（python目录下运行）：

# CPU
python tests/benchmark/benchmark.py --yaml_path config.yaml

# GPU
python tests/benchmark/benchmark.py --yaml_path config_gpu.yaml

运行相关信息汇总：（以下仅为个人测试情况，具体情况请自行测试）

环境

测试者	设备	OS	CPU	GPU	onnxruntime-gpu
[1]zhsunlight	宏碁(Acer) 暗影骑士·威N50-N93游戏台式机	Windows	十代i5-10400F 16G 512G SSD	NVIDIA GeForce GTX 1660Super 6G	1.11.0
[2]SWHL	服务器	Linux	AMD R9 5950X	NVIDIA GeForce RTX 3090	1.12.1

耗时

对应上面序号 CPU总耗时(s) CPU平均耗时(s/img) GPU总耗时(s) GPU平均耗时(s/img)

[1] 296.8841 1.18282 646.14667 2.57429

[2] 149.35427 0.50504 250.81760 0.99927

OpenVINO GPU推理配置

官方参考文档：docs
考虑到openvino只能使用自家显卡推理，通用性不高，这里暂不作相关配置说明。

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

RapidOCR Python

简介和说明

（推荐）pip安装快速使用

源码使用步骤

`config.yaml`中常用参数介绍

onnxruntime-gpu版相关说明

onnxruntime-gpu版推理配置

OpenVINO GPU推理配置

对应上面序号	CPU总耗时(s)	CPU平均耗时(s/img)	GPU总耗时(s)	GPU平均耗时(s/img)
[1]	296.8841	1.18282	646.14667	2.57429
[2]	149.35427	0.50504	250.81760	0.99927

推理引擎	推理速度更快	占用内存更少
onnxruntime		✓
openvino	✓	存在内存不释放的问题

Files

README.md

Latest commit

History

README.md

File metadata and controls

RapidOCR Python

简介和说明

（推荐）pip安装快速使用

源码使用步骤

config.yaml中常用参数介绍

onnxruntime-gpu版相关说明

onnxruntime-gpu版推理配置

OpenVINO GPU推理配置

`config.yaml`中常用参数介绍