[paddleocr]版面区域检测模块使用教程

最新推荐文章于 2025-05-28 07:16:04 发布

原创最新推荐文章于 2025-05-28 07:16:04 发布 · 367 阅读

7 ·

CC 4.0 BY-SA版权

文章标签：

#开发语言

OCR 专栏收录该内容

44 篇文章

订阅专栏

版面区域检测模块使用教程¶

一、概述¶

版面区域检测任务的核心是对输入的文档图像进行内容解析和区域划分。通过识别图像中的不同元素（如文字、图表、图像、公式、段落、摘要、参考文献等），将其归类为预定义的类别，并确定这些区域在文档中的位置。

二、支持模型列表¶

版面检测模型，包含20个常见的类别：文档标题、段落标题、文本、页码、摘要、目录、参考文献、脚注、页眉、页脚、算法、公式、公式编号、图像、表格、图和表标题（图标题、表格标题和图表标题）、印章、图表、侧栏文本和参考文献内容

模型	模型下载链接	mAP(0.5)（%）	GPU推理耗时（ms） [常规模式 / 高性能模式]	CPU推理耗时（ms） [常规模式 / 高性能模式]	模型存储大小（M）	介绍
PP-DocLayout_plus-L	推理模型/训练模型	83.2	34.6244 / 10.3945	510.57 / -	126.01 M	基于RT-DETR-L在包含中英文论文、多栏杂志、报纸、PPT、合同、书本、试卷、研报、古籍、日文文档、竖版文字文档等场景的自建数据集训练的更高精度版面区域定位模型

注：以上精度指标的评估集是自建的版面区域检测数据集，包含中英文论文、杂志、报纸、研报、PPT、试卷、课本等 1300 张文档类型图片。

文档图像版面子模块检测，包含1个版面区域类别，能检测多栏的报纸、杂志的每个子文章的文本区域：

模型	模型下载链接	mAP(0.5)（%）	GPU推理耗时（ms） [常规模式 / 高性能模式]	CPU推理耗时（ms） [常规模式 / 高性能模式]	模型存储大小（M）	介绍
PP-DocBlockLayout	推理模型/训练模型	95.9	34.6244 / 10.3945	510.57 / -	123.92 M	基于RT-DETR-L在包含中英文论文、多栏杂志、报纸、PPT、合同、书本、试卷、研报、古籍、日文文档、竖版文字文档等场景的自建数据集训练的文档图像版面子模块检测模型

注：以上精度指标的评估集是自建的版面子区域检测数据集，包含中英文论文、杂志、报纸、研报、PPT、试卷、课本等 1000 张文档类型图片。

版面检测模型，包含23个常见的类别：文档标题、段落标题、文本、页码、摘要、目录、参考文献、脚注、页眉、页脚、算法、公式、公式编号、图像、图表标题、表格、表格标题、印章、图表标题、图表、页眉图像、页脚图像、侧栏文本

模型	模型下载链接	mAP(0.5)（%）	GPU推理耗时（ms） [常规模式 / 高性能模式]	CPU推理耗时（ms） [常规模式 / 高性能模式]	模型存储大小（M）	介绍
PP-DocLayout-L	推理模型/训练模型	90.4	34.6244 / 10.3945	510.57 / -	123.76 M	基于RT-DETR-L在包含中英文论文、杂志、合同、书本、试卷和研报等场景的自建数据集训练的高精度版面区域定位模型
PP-DocLayout-M	推理模型/训练模型	75.2	13.3259 / 4.8685	44.0680 / 44.0680	22.578	基于PicoDet-L在包含中英文论文、杂志、合同、书本、试卷和研报等场景的自建数据集训练的精度效率平衡的版面区域定位模型
PP-DocLayout-S	推理模型/训练模型	70.9	8.3008 / 2.3794	10.0623 / 9.9296	4.834	基于PicoDet-S在中英文论文、杂志、合同、书本、试卷和研报等场景上自建数据集训练的高效率版面区域定位模型

注：以上精度指标的评估集是自建的版面区域检测数据集，包含中英文论文、报纸、研报和试卷等 500 张文档类型图片。

❗ 以上列出的是版面检测模块重点支持的5个核心模型，该模块总共支持13个全量模型，包含多个预定义了不同类别的模型，完整的模型列表如下：

👉模型列表详情

三、快速开始¶

❗ 在快速开始前，请先安装 PaddleOCR 的 wheel 包，详细请参考安装教程。

使用一行命令即可快速体验：

paddleocr layout_detection -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/layout.jpg

您也可以将版面区域检测模块中的模型推理集成到您的项目中。运行以下代码前，请您下载示例图片到本地。

from paddleocr import LayoutDetection

model = LayoutDetection(model_name="PP-DocLayout_plus-L")
output = model.predict("layout.jpg", batch_size=1, layout_nms=True)
for res in output:
    res.print()
    res.save_to_img(save_path="./output/")
    res.save_to_json(save_path="./output/res.json")

运行后，得到的结果为：

{'res': {'input_path': 'layout.jpg', 'page_index': None, 'boxes': [{'cls_id': 2, 'label': 'text', 'score': 0.9870226979255676, 'coordinate': [34.101906, 349.85275, 358.59213, 611.0772]}, {'cls_id': 2, 'label': 'text', 'score': 0.9866003394126892, 'coordinate': [34.500324, 647.1585, 358.29367, 848.66797]}, {'cls_id': 2, 'label': 'text', 'score': 0.9846674203872681, 'coordinate': [385.71445, 497.40973, 711.2261, 697.84265]}, {'cls_id': 8, 'label': 'table', 'score': 0.984126091003418, 'coordinate': [73.76879, 105.94899, 321.95303, 298.84888]}, {'cls_id': 8, 'label': 'table', 'score': 0.9834211468696594, 'coordinate': [436.95642, 105.81531, 662.7168, 313.48462]}, {'cls_id': 2, 'label': 'text', 'score': 0.9832247495651245, 'coordinate': [385.62787, 346.2288, 710.10095, 458.77127]}, {'cls_id': 2, 'label': 'text', 'score': 0.9816061854362488, 'coordinate': [385.7802, 735.1931, 710.56134, 849.9764]}, {'cls_id': 6, 'label': 'figure_title', 'score': 0.9577341079711914, 'coordinate': [34.421448, 20.055151, 358.71283, 76.53663]}, {'cls_id': 6, 'label': 'figure_title', 'score': 0.9505634307861328, 'coordinate': [385.72278, 20.053688, 711.29333, 74.92744]}, {'cls_id': 0, 'label': 'paragraph_title', 'score': 0.9001723527908325, 'coordinate': [386.46344, 477.03488, 699.4023, 490.07474]}, {'cls_id': 0, 'label': 'paragraph_title', 'score': 0.8845751285552979, 'coordinate': [35.413048, 627.73596, 185.58383, 640.52264]}, {'cls_id': 0, 'label': 'paragraph_title', 'score': 0.8837394118309021, 'coordinate': [387.17603, 716.3423, 524.7841, 729.258]}, {'cls_id': 0, 'label': 'paragraph_title', 'score': 0.8508939743041992, 'coordinate': [35.50064, 331.18445, 141.6444, 344.81097]}]}}

参数含义如下： - input_path：输入的待预测图像的路径 - page_index：如果输入是PDF文件，则表示当前是PDF的第几页，否则为 None - boxes：预测的目标框信息，一个字典列表。每个字典代表一个检出的目标，包含以下信息： - cls_id：类别ID，一个整数 - label：类别标签，一个字符串 - score：目标框置信度，一个浮点数 - coordinate：目标框坐标，一个浮点数列表，格式为[xmin, ymin, xmax, ymax]

可视化图片如下：

相关方法、参数等说明如下：

LayoutDetection实例化目标检测模型（此处以PP-DocLayout_plus-L为例），具体说明如下：

参数	参数说明	参数类型	可选项	默认值
`model_name`	模型名称	`str`	无	无
`model_dir`	模型存储路径	`str`	无	无
`device`	模型推理设备	`str`	支持指定GPU具体卡号，如“gpu:0”，其他硬件具体卡号，如“npu:0”，CPU如“cpu”。	`gpu:0`
`img_size`	输入图像大小；如果不指定，PP-DocLayout_plus-L模型将默认使用800x800	`int/list/None`	int, 如 640 , 表示将输入图像resize到640x640大小列表, 如 [640, 512] , 表示将输入图像resize到宽为640，高为512大小 None, 不指定，PP-DocLayout_plus-L模型将默认使用800x800	None
`threshold`	用于过滤掉低置信度预测结果的阈值；如果不指定，将默认使用0.5	`float/dict/None`	float，如 0.2，表示过滤掉所有阈值小于0.2的目标框字典，字典的key为int类型，代表`cls_id`，val为float类型阈值。如 `{0: 0.45, 2: 0.48, 7: 0.4}`，表示对cls_id为0的类别应用阈值0.45、cls_id为1的类别应用阈值0.48、cls_id为7的类别应用阈值0.4 None, 不指定，将默认使用0.5	None
`layout_nms`	是否使用NMS后处理，过滤重叠框；如果不指定，将默认不使用NMS	`bool/None`	bool, True/False , 表示使用/不使用NMS进行检测框的后处理过滤重叠框 None, 不指定，将默认不使用	None
`layout_unclip_ratio`	检测框的边长缩放倍数；如果不指定，将默认使用1.0	`float/list/dict/None`	float, 大于0的浮点数，如 1.1 , 表示将模型输出的检测框中心不变，宽和高都扩张1.1倍列表, 如 [1.2, 1.5] , 表示将模型输出的检测框中心不变，宽度扩张1.2倍，高度扩张1.5倍字典, 字典的key为int类型，代表`cls_id`, value为tuple类型，如`{0: (1.1, 2.0)}`, 表示将模型输出的第0类别检测框中心不变，宽度扩张1.1倍，高度扩张2.0倍 None, 不指定，将默认使用1.0
`layout_merge_bboxes_mode`	模型输出的检测框的合并处理模式；如果不指定，将默认使用union模式	`string/dict/None`	large, 设置为large时，表示在模型输出的检测框中，对于互相重叠包含的检测框，只保留外部最大的框，删除重叠的内部框。 small, 设置为small，表示在模型输出的检测框中，对于互相重叠包含的检测框，只保留内部被包含的小框，删除重叠的外部框。 union, 不进行框的过滤处理，内外框都保留 dict, 字典的key为int类型，代表`cls_id`, value为str类型, 如`{0: "large", 2: "small"}`, 表示对第0类别检测框使用large模式，对第2类别检测框使用small模式 None, 不指定，将默认使用union模式	None
`use_hpip`	是否启用高性能推理插件	`bool`	无	`False`
`hpi_config`	高性能推理配置	`dict` \| `None`	无	`None`

调用目标检测模型的 predict() 方法进行推理预测，该方法会返回一个结果列表。另外，本模块还提供了 predict_iter() 方法。两者在参数接受和结果返回方面是完全一致的，区别在于 predict_iter() 返回的是一个 generator，能够逐步处理和获取预测结果，适合处理大型数据集或希望节省内存的场景。可以根据实际需求选择使用这两种方法中的任意一种。predict() 方法参数有 input、batch_size和threshold，具体说明如下：

参数	参数说明	参数类型	可选项	默认值
`input`	待预测数据，支持多种输入类型	`Python Var`/`str`/`list`	Python变量，如`numpy.ndarray`表示的图像数据文件路径，如图像文件的本地路径：`/root/data/img.jpg` URL链接，如图像文件的网络URL：示例本地目录，该目录下需包含待预测数据文件，如本地路径：`/root/data/` 列表，列表元素需为上述类型数据，如`[numpy.ndarray, numpy.ndarray]`，`["/root/data/img1.jpg", "/root/data/img2.jpg"]`，`["/root/data1", "/root/data2"]`	无
`batch_size`	批大小	`int`	大于0的任意整数	1
`threshold`	用于过滤掉低置信度预测结果的阈值	`float/dict/None`	float，如 0.2，表示过滤掉所有阈值小于0.2的目标框字典，字典的key为int类型，代表`cls_id`，val为float类型阈值。如 `{0: 0.45, 2: 0.48, 7: 0.4}`，表示对cls_id为0的类别应用阈值0.45、cls_id为1的类别应用阈值0.48、cls_id为7的类别应用阈值0.4 None, 不指定，将默认使用 `creat_model` 指定的 `threshold` 参数，如果 `creat_model` 也没有指定，则默认使用0.5
`layout_nms`	是否使用NMS后处理，过滤重叠框；如果不指定，将默认不使用NMS	`bool/None`	bool, True/False , 表示使用/不使用NMS进行检测框的后处理过滤重叠框 None, 不指定，将默认使用 `creat_model` 指定的 `layout_nms` 参数，如果 `creat_model` 也没有指定，则默认不使用NMS	None
`layout_unclip_ratio`	检测框的边长缩放倍数；如果不指定，将默认使用1.0	`float/list/dict/None`	float, 大于0的浮点数，如 1.1 , 表示将模型输出的检测框中心不变，宽和高都扩张1.1倍列表, 如 [1.2, 1.5] , 表示将模型输出的检测框中心不变，宽度扩张1.2倍，高度扩张1.5倍字典, 字典的key为int类型，代表`cls_id`, value为tuple类型，如`{0: (1.1, 2.0)}`, 表示将模型输出的第0类别检测框中心不变，宽度扩张1.1倍，高度扩张2.0 None, 不指定，将默认使用 `creat_model` 指定的 `layout_unclip_ratio` 参数，如果 `creat_model` 也没有指定，则默认使用1.0
`layout_merge_bboxes_mode`	模型输出的检测框的合并处理模式；如果不指定，将默认使用union模式	`string/dict/None`	large, 设置为large时，表示在模型输出的检测框中，对于互相重叠包含的检测框，只保留外部最大的框，删除重叠的内部框。 small, 设置为small，表示在模型输出的检测框中，对于互相重叠包含的检测框，只保留内部被包含的小框，删除重叠的外部框。 union, 不进行框的过滤处理，内外框都保留 dict, 字典的key为int类型，代表`cls_id`, value为str类型, 如`{0: "large", 2: "small"}`, 表示对第0类别检测框使用large模式，对第2类别检测框使用small模式 None, 不指定，将默认使用 `creat_model` 指定的 `layout_merge_bboxes_mode` 参数，如果 `creat_model` 也没有指定，则默认使用union模式	无

对预测结果进行处理，每个样本的预测结果均为对应的Result对象，且支持打印、保存为图片、保存为json文件的操作:

方法	方法说明	参数	参数类型	参数说明	默认值
`print()`	打印结果到终端	`format_json`	`bool`	是否对输出内容进行使用 `JSON` 缩进格式化	`True`
		`indent`	`int`	指定缩进级别，以美化输出的 `JSON` 数据，使其更具可读性，仅当 `format_json` 为 `True` 时有效	4
		`ensure_ascii`	`bool`	控制是否将非 `ASCII` 字符转义为 `Unicode`。设置为 `True` 时，所有非 `ASCII` 字符将被转义；`False` 则保留原始字符，仅当`format_json`为`True`时有效	`False`
`save_to_json()`	将结果保存为json格式的文件	`save_path`	`str`	保存的文件路径，当为目录时，保存文件命名与输入文件类型命名一致	无
		`indent`	`int`	指定缩进级别，以美化输出的 `JSON` 数据，使其更具可读性，仅当 `format_json` 为 `True` 时有效	4
		`ensure_ascii`	`bool`	控制是否将非 `ASCII` 字符转义为 `Unicode`。设置为 `True` 时，所有非 `ASCII` 字符将被转义；`False` 则保留原始字符，仅当`format_json`为`True`时有效	`False`
`save_to_img()`	将结果保存为图像格式的文件	`save_path`	`str`	保存的文件路径，当为目录时，保存文件命名与输入文件类型命名一致	无