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

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

一、概述¶

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

二、支持模型列表¶

• 版面检测模型，包含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	保存的文件路径，当为目录时，保存文件命名与输入文件类型命名一致	无

• 此外，也支持通过属性获取带结果的可视化图像和预测结果，具体如下：

属性	属性说明
json	获取预测的json格式的结果
img	获取格式为dict的可视化图像

四、二次开发¶

由于 PaddleOCR 并不直接提供版面区域检测模块的训练，因此，如果需要训练版面区域测模型，可以参考 PaddleX 版面区域检测模块二次开发部分进行训练。训练后的模型可以无缝集成到 PaddleOCR 的 API 中进行推理。