PyMuPDF中的TextPage类详解：PDF文本提取核心技术-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_01051/article/details/148464476

PyMuPDF中的TextPage类详解：PDF文本提取核心技术

PyMuPDF PyMuPDF is a high performance Python library for data extraction, analysis, conversion & manipulation of PDF (and other) documents. 项目地址: https://gitcode.com/gh_mirrors/py/PyMuPDF

什么是TextPage类

TextPage是PyMuPDF库中用于处理文档页面文本和图像内容的核心类。它代表了一个文档页面上显示的所有文本和图像信息，支持所有MuPDF文档类型（包括PDF、XPS、ePub等）。

创建TextPage对象

通常有两种方式创建TextPage对象：

通过DisplayList对象的get_textpage方法
通过Page对象的get_textpage方法

由于TextPage类本身的方法集有限，Page类提供了更便捷的包装方法，这些方法内部实际上也是通过TextPage实现的。

核心功能方法

TextPage类提供了多种文本提取方法，每种方法返回不同格式的数据：

| 方法名称 | 功能描述 | 对应Page方法 | |-------------------|----------------------------|-------------| | extractText/extractTEXT | 提取纯文本内容 | "text" | | extractBLOCKS | 按文本块分组的纯文本 | "blocks" | | extractWORDS | 带边界框的所有单词 | "words" | | extractHTML | HTML格式的页面内容 | "html" | | extractXHTML | XHTML格式的页面内容 | "xhtml" | | extractXML | XML格式的页面文本 | "xml" | | extractDICT | 字典格式的页面内容 | "dict" | | extractJSON | JSON格式的页面内容 | "json" | | extractRAWDICT | 包含字符级细节的字典格式 | "rawdict" | | extractRAWJSON | 包含字符级细节的JSON格式 | "rawjson" | | search | 在页面中搜索字符串 | search_for |

方法详解

基础文本提取

extractText(sort=False)
extractTEXT(sort=False)

返回页面完整文本的UTF-8字符串，保持文档创建时的原始顺序。

参数sort(v1.19.1新增)：按垂直和水平坐标排序输出，有助于生成"自然"阅读顺序。

结构化文本提取

extractBLOCKS()

返回按文本块分组的文本行列表，每个列表项格式为： (x0, y0, x1, y1, "块内文本行", 块序号, 块类型)

块类型：0表示文本块，1表示图像块。对于图像块，会包含其边界框和一些元信息（但不包含图像内容本身）。

单词级提取

extractWORDS(delimiters=None)

返回带边界框信息的单词列表，每个列表项格式为： (x0, y0, x1, y1, "单词", 块序号, 行号, 单词序号)

参数delimiters(v1.23.5新增)：指定额外的单词分隔符。例如，默认会将"john.doe@outlook.com"视为一个单词，但如果指定delimiters="@."，则会返回四个单词："john"、"doe"、"outlook"和"com"。

富格式提取

extractHTML()

返回包含完整格式和定位信息的HTML字符串，图像以base64编码嵌入。

extractXHTML()

返回XHTML格式内容，文本信息细节与extractTEXT类似，但也包含base64编码的图像。

extractXML()

返回包含每个字符完整格式信息的XML字符串（不包含图像）。

字典/JSON格式提取

extractDICT(sort=False)
extractRAWDICT(sort=False)
extractJSON(sort=False)
extractRAWJSON(sort=False)

这些方法返回字典或JSON格式的页面内容，提供了从块到字符的多级结构化信息。

RAWDICT/RAWJSON变体包含更细粒度的字符级信息，使XML在许多情况下变得不必要。

文本搜索功能

search(needle, quads=False)

在页面中搜索字符串，返回找到的位置列表。

参数：

needle：要搜索的字符串（目前仅支持ASCII字母的大小写不敏感匹配）
quads：是否返回四边形而不是矩形

包含每个匹配项位置（Rect或Quad对象）的列表

v1.18.2版本的重要改进：

移除了hit_max参数，现在总是返回所有匹配项
支持在TextPage的rect参数指定区域内搜索
支持查找跨行连字符连接的单词
自动合并同一行中的重叠矩形

数据结构详解

字典输出方法（extractDICT/extractRAWDICT等）返回的结构遵循页面内容的自然层次：

页面(Page)：包含块(block)字典列表
块(Block)：
- 文本块：包含行(line)字典列表
- 图像块：包含图像元数据
行(Line)：包含跨(span)字典列表
跨(Span)：
- 普通变体：包含文本本身
- RAW变体：包含字符(char)字典列表
字符(Char)：包含位置、边界框和Unicode信息

几何表示

出于性能和内存考虑，所有几何对象（点、矩形、矩阵）都以简化的元组格式表示，而不是完整的几何类对象：

4元组表示矩形（约168字节），而Rect对象需要472字节
8元组表示四边形（约488字节）

对于大多数水平文本，边界框提供的信息已经足够。如果需要完整的四边形信息，可以使用以下恢复方法：

recover_quad()：恢复整个跨的四边形
recover_span_quad()：恢复跨中字符子集的四边形
recover_line_quad()：恢复行的四边形
recover_char_quad()：恢复单个字符的四边形

图像块特殊处理

图像块字典包含丰富的图像元数据：

{
    "type": 1,  # 表示图像块
    "bbox": (x0, y0, x1, y1),  # 图像在页面上的边界框
    "number": 块序号,
    "ext": "png",  # 图像类型（如"png"、"jpeg"等）
    "width": 原始宽度,
    "height": 原始高度,
    "colorspace": 色彩空间组件数,
    "xres": x方向分辨率,
    "yres": y方向分辨率,
    "bpc": 每组件位数,
    "transform": 变换矩阵,
    "size": 图像字节大小,
    "image": 图像内容(bytes),
    "mask": 透明图像的掩码内容
}

注意事项：