PyMuPDF 1.24.4 中文文档（十）（2）

PyMuPDF 1.24.4 中文文档（十）（1）https://developer.aliyun.com/article/1559521

文本页

原文：pymupdf.readthedocs.io/en/latest/textpage.html

此类代表文档页面上显示的文本和图像。支持所有的 MuPDF 文档类型。

创建文本页的常规方法是使用DisplayList.get_textpage()和Page.get_textpage()。因为此类中的方法集合有限，在 Page 中存在更方便使用的包装器。此表的最后一列显示了这些相应的 Page 方法。

对于此类的描述，请参阅附录 2。

类 API

class TextPage

extractText(sort=False)

extractTEXT(sort=False)

返回页面的完整文本字符串。文本是 UTF-8 unicode 格式的，与文档创建时指定的顺序相同。

参数：

sort (bool) – (v1.19.1 新增) 根据垂直然后水平坐标对输出进行排序。在许多情况下，这应该足以生成“自然”的阅读顺序。

返回类型：

str

extractBLOCKS()

以文本行分组的文本页内容列表。每个列表项如下所示：

(x0, y0, x1, y1, "lines in the block", block_no, block_type) 

前四个条目是块的 bbox 坐标，block_type为图像块为 1，文本为 0。block_no是块的序号。多个文本行通过换行符连接。

对于图像块，其 bbox 和带有一些图像元信息的文本行包含在内 – 不包括图像内容。

这是一种高速方法，提供了足够的信息以按所需阅读顺序输出纯文本。

返回类型：

列表

extractWORDS(delimiters=None)

• v1.23.5 中的变更：添加了 delimiters 参数

作为带有 bbox 信息的单词列表的文本页内容。此列表的项如下所示：

(x0, y0, x1, y1, "word", block_no, line_no, word_no) 

参数：

delimiters (str) – （v1.23.5 中新增）将这些字符用作 额外 的单词分隔符。默认情况下，所有空格（包括非断行空格 0xA0）表示单词的起始和结束。现在您可以指定更多字符来引起这种情况。例如，默认情况下将 "john.doe@outlook.com" 返回为一个单词。如果指定 delimiters="@."，那么四个单词 "john"、"doe"、"outlook"、"com" 将被返回。其他可能的用途包括忽略标点字符 delimiters=string.punctuation。这些“单词”字符串将不包含任何分隔字符。

这是一种高速方法，例如允许从给定区域提取文本或恢复文本阅读顺序。

返回类型：

列表

extractHTML()

以 HTML 格式的字符串表示的文本页内容。此版本包含完整的格式和位置信息。图像已包含（编码为 base64 字符串）。您需要一个 HTML 包来在 Python 中解释输出。您的互联网浏览器应能够充分显示此信息，但请参见 控制 HTML 输出的质量。

返回类型：

str

extractDICT(sort=False)

作为 Python 字典的文本页内容。提供与 HTML 相同的详细信息。请参见下面的结构。

参数：

sort (bool) – （v1.19.1 中新增）按垂直然后水平坐标对输出进行排序。在许多情况下，这应该足以生成“自然”的阅读顺序。

返回类型：

dict

extractJSON(sort=False)

以 json.dumps(TextPage.extractDICT()) 创建的 JSON 字符串表示的文本页内容。这是为了向后兼容而包含的。您可能仅用于将结果输出到某个文件。此方法检测到二进制图像数据并将其转换为 base64 编码字符串。

参数：

sort (bool) – （v1.19.1 中新增）按垂直然后水平坐标对输出进行排序。在许多情况下，这应该足以生成“自然”的阅读顺序。

返回类型：

str

extractXHTML()

以 XHTML 格式的字符串表示的文本页内容。文本信息的详细程度与 extractTEXT() 相当，但还包含图像（base64 编码）。此方法不试图重新创建原始的视觉外观。

返回类型：

str

extractXML()

以 XML 格式的字符串表示的文本页内容。此格式包含有关页面上每个字符的完整格式信息：字体、大小、行、段落、位置、颜色等。不包含图像。您需要一个 XML 包来在 Python 中解释输出。

返回类型：

str

extractRAWDICT(sort=False)

Textpage 内容作为一个 Python 字典 – 在技术上类似于 extractDICT()，它包含该信息的一个子集（包括任何图像）。它提供了每个字符的额外细节，这在许多情况下使得使用 XML 成为过时。见下文了解结构。

参数:

sort（bool） – （在 v1.19.1 中新添加）按垂直和水平坐标排序输出。在许多情况下，这应足以生成“自然”的阅读顺序。

返回类型:

dict

extractRAWJSON(sort=False)

Textpage 内容作为 JSON 字符串。通过 json.dumps(TextPage.extractRAWDICT()) 创建。你可能只会用这个方法将结果输出到某个文件中。该方法检测到二进制图像数据并将其转换为 base64 编码的字符串。

参数:

sort（bool） – （在 v1.19.1 中新添加）按垂直和水平坐标排序输出。在许多情况下，这应足以生成“自然”的阅读顺序。

返回类型:

str

search(needle, quads=False)

• 在 v1.18.2 中已更改

搜索字符串并返回找到的位置列表。

参数:

• needle（str） – 要搜索的字符串。如果 needle 只包含 ASCII 字母，则大小写都会匹配 – 对于 “Ä” 和 “ä” 等情况目前尚不适用。
  
• quads（bool） – 返回四边形而不是矩形。
  

返回类型:

list

返回:

一个包围找到的needle出现的 Rect 或 Quad 对象列表。由于搜索字符串可能包含空格，其部分可能在不同行上找到。在这种情况下，将返回多个矩形（或四边形）。(v1.18.2 中已更改) 该方法现在支持去连字符化，因此即使在两行中连字符分为“meth-”和“od”两部分，“method”也会被找到。返回的两个矩形将包含“meth”（没有连字符）和“od”。

注意

v1.18.2 变更概览:

1. hit_max 参数已移除：现在始终返回所有命中项。
   
2. Rect 参数在 TextPage 中得到了尊重：只检查此区域内的文本。仅考虑完全包含 bbox 的字符。包装方法 Page.search_for() 相应地支持 clip 参数。
   
3. 连字符词现在可以找到了。
   
4. 同一行中的重叠矩形现在会自动合并。我们假设这样的分离是由包含同一搜索针部分的多个标记内容组件创建的副产品。
   

示例 Quad 与 Rect：当搜索 needle “pymupdf” 时，相应的条目将是蓝色矩形，或者如果指定了 quads，则为四边形 Quad(ul, ur, ll, lr)。

rect

与文本页相关联的矩形。这可以等于创建页面的矩形或Page.get_textpage()及文本提取/搜索方法的clip参数。

注意

文本搜索和大多数文本提取的输出受此矩形的限制。然而，(X)HTML 和 XML 输出始终会提取整个页面。

字典输出结构

方法TextPage.extractDICT()，TextPage.extractJSON()，TextPage.extractRAWDICT()和TextPage.extractRAWJSON()返回包含页面文本和图像内容的字典。这四种方法的字典结构几乎相同。它们力求尽可能准确地映射文本页面的信息层次结构，包括块、行、跨度和字符，通过分别表示每个子字典来实现：

• 一页由一系列块字典组成。
  
• 一个（text）块由一系列行字典组成。
  
• 一行由一系列跨度字典组成。
  
• 一个跨度要么由文本本身组成，要么（对于 RAW 变体）由一系列字符字典组成。
  
• RAW 变体：字符是其来源、bbox 和 unicode 的字典。
  

此处所有 PyMuPDF 几何对象（点、矩形、矩阵）均以其**“like”**格式表示：使用rect_like tuple代替 Rect，等等。这样做的原因是性能和内存考虑：

• 此代码用 C 语言编写，其中 Python 元组可以轻松生成。另一方面，几何对象仅在 Python 源代码中定义。将每个 Python 元组转换为其对应的几何对象将增加显著的（但基本上不必要的）执行时间。
  
• 一个  4 元组大约需要 168 字节，相应的 Rect 需要 472 字节 - 几乎是其三倍大小。对于文本密集型页面，一个“dict”字典包含  300 多个 bbox 对象 - 因此，需要约 50 KB 存储空间作为 4 元组，而作为 Rect 对象则需要约 140  KB。然而，对于这样的页面，一个“rawdict”输出将包含4 至 5 千个 bbox，因此在这种情况下，我们谈论的是 750 KB 与 2 MB 的区别。
  

还请注意，只有 bbox（= rect_like 的四元组）被返回，而实际上 TextPage 包含了 完整的位置信息 – 以 Quad 格式展示。再次提及这一决定的原因是内存考量：一个 quad_like 需要 488 字节（是 rect_like 大小的 3 倍）。考虑到生成的 bbox 数量，返回 quad_like 信息将会产生显著影响。

在绝大多数情况下，我们处理的是仅水平文本，其中 bbox 提供了完全足够的信息。

此外，完整的四边形信息并未丢失：可以通过以下列表中的适当函数按需恢复行、跨度和字符的信息：

• recover_quad() – 完整跨度的四边形
  
• recover_span_quad() – 跨度字符子集的四边形
  
• recover_line_quad() – 行的四边形
  
• recover_char_quad() – 字符的四边形
  

如前所述，仅在文本 非水平书写 – line["dir"] != (1, 0) – 且需要用于文本标记注释的四边形时，才有必要使用这些函数 (Page.add_highlight_annot() 和相关功能)。

页面字典

块字典

块字典以 图像块 和 文本块 两种不同格式出现。

• (在 v1.18.0 中更改) – 新字典键 number，块编号。
  
• (在 v1.18.11 中更改) – 新字典键 transform，图像块的图像变换矩阵。
  
• (在 v1.18.11 中更改) – 新字典键 size，图像块的图像大小，以字节为单位。
  

图像块:

“ext”键的可能值为“bmp”, “gif”, “jpeg”, “jpx” (JPEG 2000), “jxr” (JPEG XR), “png”, “pnm”和“tiff”。

注

1. 页面上的每一张图片都会生成一个图像块。因此，如果一个图片在不同位置显示，可能会有重复。
   
2. TextPage 和相应的方法Page.get_text()适用于所有文档类型。仅对于 PDF 文档，方法Document.get_page_images() / Page.get_images()在图像列表方面提供部分重叠功能。但两个列表可能包含相同的项，也可能不同。任何差异很可能是由以下原因之一引起的：

• PDF 页面的“内嵌”图像（见 Adobe PDF 参考手册第 214 页）包含在文本页中，但不会显示在Page.get_images()中。
• 
  
• 注释也可能包含图像 - 这些图像将不会显示在Page.get_images()中。
• 
  
• 文本页中的图像块会生成所有图像位置，无论是否存在重复。这与Page.get_images()不同，后者每个参考名称仅列出一次图像。
• 
  
• 页面上的object定义中提到的图像将始终出现在Page.get_images()中 [1]。但可能会发生以下情况，即页面的contents中没有“display”命令（错误地或有意省略）。在这种情况下，该图像将不会出现在文本页中。

1. 图像的“变换矩阵”定义为满足表达式bbox / transform == pymupdf.Rect(0, 0, 1, 1)的矩阵，详细信息请参阅：图像变换矩阵。
   

文本块：

行字典

键 “dir” 的值是相对于 x 轴的角度的单位向量 dir = (cosine, -sine)，见下图：每个象限内的单词（顺时针从右上到右下）分别旋转 30°、120°、210°和 300°。

PyMuPDF 1.24.4 中文文档（十）（3）https://developer.aliyun.com/article/1559523