demo/README_zh-CN.md

演示

MMOCR 为示例和应用，以 ocr.py 脚本形式，提供了方便使用的 API。

该 API 可以通过命令行执行，也可以在 python 脚本内调用。

---

案例一：文本检测

注： 使用 TextSnake 检测模型对图像上的文本进行检测，结果用 json 格式的文件（默认）导出，并保存可视化的文件。

• 命令行执行：

python mmocr/utils/ocr.py demo/demo_text_det.jpg --output demo/det_out.jpg --det TextSnake --recog None --export demo/

• Python 调用：

from mmocr.utils.ocr import MMOCR

# 导入模型到内存
ocr = MMOCR(det='TextSnake', recog=None)

# 推理
results = ocr.readtext('demo/demo_text_det.jpg', output='demo/det_out.jpg', export='demo/')

案例二：文本识别

注： 使用 CRNN_TPS 识别模型对多张图片进行批量识别。批处理的尺寸设置为 10，以防内存溢出引起的 CUDA 运行时错误。

• 命令行执行：

python mmocr/utils/ocr.py %INPUT_FOLDER_PATH% --det None --recog CRNN_TPS --batch-mode --single-batch-size 10 --output %OUPUT_FOLDER_PATH%

• Python 调用：

from mmocr.utils.ocr import MMOCR

# 导入模型到内存
ocr = MMOCR(det=None, recog='CRNN_TPS')

# 推理
results = ocr.readtext(%INPUT_FOLDER_PATH%, output = %OUTPUT_FOLDER_PATH%, batch_mode=True, single_batch_size = 10)

案例三：文本检测+识别

注： 使用 PANet_IC15（默认）检测模型和 SAR（默认）识别模型，对 demo/demo_text_det.jpg 图片执行 ocr（检测+识别）推理，在终端打印结果并展示可视化结果。

• 命令行执行：

python mmocr/utils/ocr.py demo/demo_text_ocr.jpg --print-result --imshow

:::{note}

当用户从命令行执行脚本时，默认配置文件都会保存在 configs/ 目录下。用户可以通过指定 config_dir 的值来自定义读取配置文件的文件夹。

:::

• Python 调用：

from mmocr.utils.ocr import MMOCR

# 导入模型到内存
ocr = MMOCR()

# 推理
results = ocr.readtext('demo/demo_text_ocr.jpg', print_result=True, imshow=True)

---

案例 4： 文本检测+识别+关键信息提取

注： 首先，使用 PS_CTW 检测模型和 SAR 识别模型，进行端到端的 ocr （检测+识别）推理，然后对得到的结果，使用 SDMGR 模型提取关键信息（KIE），并展示可视化结果。

• 命令行执行：

python mmocr/utils/ocr.py demo/demo_kie.jpeg  --det PS_CTW --recog SAR --kie SDMGR --print-result --imshow

:::{note}

当用户从命令行执行脚本时，默认配置文件都会保存在 configs/ 目录下。用户可以通过指定 config_dir 的值来自定义读取配置文件的文件夹。

:::

• Python 调用：

from mmocr.utils.ocr import MMOCR

# 导入模型到内存
ocr = MMOCR(det='PS_CTW', recog='SAR', kie='SDMGR')

# 推理
results = ocr.readtext('demo/demo_kie.jpeg', print_result=True, imshow=True)

---

API 参数

该 API 有多个可供使用的参数列表。下表是 python 接口的参数。

MMOCR():

参数	类型	默认值	描述
det	参考 模型 章节	PANet_IC15	文本检测算法
recog	参考 模型 章节	SAR	文本识别算法
kie [1]	参考 模型 章节	None	关键信息提取算法
config_dir	str	configs/	用于存放所有配置文件的文件夹路径
det_config	str	None	指定检测模型的自定义配置文件路径
det_ckpt	str	None	指定检测模型的自定义参数文件路径
recog_config	str	None	指定识别模型的自定义配置文件路径
recog_ckpt	str	None	指定识别模型的自定义参数文件路径
kie_config	str	None	指定关键信息提取模型的自定义配置路径
kie_ckpt	str	None	指定关键信息提取的自定义参数文件路径
device	str	None	推理时使用的设备标识, 支持 torch.device 所包含的所有设备字符. 例如, 'cuda:0' 或 'cpu'.

[1]: kie 当且仅当同时指定了文本检测和识别模型时才有效。

:::{note}

mmocr 为了方便使用提供了预置的模型配置和对应的预训练权重，用户可以通过指定 det 和/或 recog 值来指定使用，这种方法等同于分别单独指定其对应的 *_config 和 *_ckpt。需要注意的是，手动指定 *_config 和 *_ckpt 会覆盖 det 和/或 recog 指定模型预置的配置和权重值。 同理 kie， kie_config 和 kie_ckpt 的参数设定逻辑相同。

:::

readtext()

参数	类型	默认值	描述
img	str/list/tuple/np.array	必填	图像，文件夹路径，np array 或 list/tuple （包含图片路径或 np arrays）
output	str	None	可视化输出结果 - 图片路径或文件夹路径
batch_mode	bool	False	是否使用批处理模式推理 [1]
det_batch_size	int	0	文本检测的批处理大小（设置为 0 则与待推理图片个数相同）
recog_batch_size	int	0	文本识别的批处理大小（设置为 0 则与待推理图片个数相同）
single_batch_size	int	0	仅用于检测或识别使用的批处理大小
export	str	None	存放导出图片结果的文件夹
export_format	str	json	导出的结果文件格式
details	bool	False	是否包含文本框的坐标和置信度的值
imshow	bool	False	是否在屏幕展示可视化结果
print_result	bool	False	是否展示每个图片的结果
merge	bool	False	是否对相邻框进行合并 [2]
merge_xdist	float	20	合并相邻框的最大x-轴距离

[1]: batch_mode 需确保模型兼容批处理模式（见下表模型是否支持批处理）。

[2]: merge 只有同时运行检测+识别模式，参数才有效。

以上所有参数在命令行同样适用，只需要在参数前简单添加两个连接符，并且将下参数中的下划线替换为连接符即可。 （例如： det_batch_size 变成了 --det-batch-size）

对于布尔类型参数，添加在命令中默认为true。 （例如： python mmocr/utils/ocr.py demo/demo_text_det.jpg --batch_mode --print_result 意为 batch_mode 和 print_result 的参数值设置为 True）

---

模型

文本检测：

名称	batch_mode 推理支持
DB_r18	:x:
DB_r50	:x:
DRRG	:x:
FCE_IC15	:x:
FCE_CTW_DCNv2	:x:
MaskRCNN_CTW	:x:
MaskRCNN_IC15	:x:
MaskRCNN_IC17	:x:
PANet_CTW	:heavy_check_mark:
PANet_IC15	:heavy_check_mark:
PS_CTW	:x:
PS_IC15	:x:
TextSnake	:heavy_check_mark:

文本识别：

名称	batch_mode 推理支持
ABINet	:heavy_check_mark:
CRNN	:x:
SAR	:heavy_check_mark:
SAR_CN	:heavy_check_mark:
NRTR_1/16-1/8	:heavy_check_mark:
NRTR_1/8-1/4	:heavy_check_mark:
RobustScanner	:heavy_check_mark:
SATRN	:heavy_check_mark:
SATRN_sm	:heavy_check_mark:
SEG	:x:
CRNN_TPS	:heavy_check_mark:

:::{note}

SAR_CN 是唯一支持中文字符识别的模型，并且它需要一个中文字典。以便推理能成功运行，请先从 这里 下载辞典。

:::

关键信息提取：

名称	batch_mode 支持
SDMGR	:heavy_check_mark:

---

其他需要注意

• 执行检测+识别的推理（端到端 ocr），需要同时定义 det 和 recog 参数
• 如果只需要执行检测，则 recog 参数设置为 None。
• 如果只需要执行识别，则 det 参数设置为 None。
• details 参数仅在端到端的 ocr 模型有效。
• det_batch_size 和 recog_batch_size 指定了在同时间传递给模型的图片数量。为了提高推理速度，应该尽可能设置你能设置的最大值。最大的批处理值受模型复杂度和 GPU 的显存大小限制。

如果你对新特性有任何建议，请随时开一个 issue，甚至可以提一个 PR:)