PyMuPDF 1.24.4 中文文档（十）

原文：https://pymupdf.readthedocs.io/en/latest/

Story

原文：pymupdf.readthedocs.io/en/latest/story-class.html

• v1.21.0 新增

方法 / 属性	简短描述
Story.reset()	将故事输出“倒带”到其开头
Story.place()	计算故事内容以适应提供的矩形
Story.draw()	将计算出的内容写入当前页面
Story.element_positions()	回调函数，记录当前处理的故事内容
Story.body	故事的基础body
Story.write()	将故事放置并绘制到 DocumentWriter 中
Story.write_stabilized()	将 HTML 内容按迭代方式布局到 DocumentWriter 中
Story.write_with_links()	类似于 write()，但还创建 PDF 链接
Story.write_stabilized_with_links()	类似于 write_stabilized()，但还创建 PDF 链接
Story.fit()	找到包含故事 self 的最佳矩形。
Story.fit_scale()
Story.fit_height()
Story.fit_width()

类 API

class Story

__init__(self, html=None, user_css=None, em=12, archive=None)

创建一个故事，可选择提供 HTML 和 CSS 源码。HTML 被解析，并作为 DOM（文档对象模型）保存在故事中。

可以通过 Xml 类的方法添加、复制、修改或删除内容（文本、图像）。此结构可能会被修改。

完成后，故事可以写入任何设备；在典型用法中，设备可能由 DocumentWriter 提供以创建新页面。

这里有一些一般性的备注：

• Story 构造函数解析和验证提供的 HTML 以创建 DOM。

• PyMuPDF 提供了多种方式来通过提供对底层 DOM 的节点访问来操作 HTML 源码。文档可以完全以编程方式从头开始构建，或者现有的 DOM 可以被任意修改。有关此接口的详细信息，请参阅 Xml 类。

• 如果不需要（或不再需要）对 DOM 进行更改，则故事已准备好进行布局，并传递给一系列设备（通常由 DocumentWriter 提供的设备）以生成新页面。

• 下一步是放置故事并将其写出。这可以直接完成，通过循环调用place()和draw()，或者可以选择使用write()或write_stabilised()方法来处理循环。选择哪种方法主要是个人口味的问题。

  • 要使用这些样式中的第一个进行工作，应使用以下循环：

    1. 获得一个适合的设备以进行写作；通常通过从 DocumentWriter 请求一个新的空白页面来完成。

    2. 确定页面上应该接收故事数据的一个或多个矩形。请注意，不是每一页都需要具有相同的矩形集。

    3. 将每个矩形传递给故事以放置它，学习该矩形的哪一部分已填充，以及是否有更多未适应的故事数据。此步骤可以重复多次，直到调用者对结果满意。

    4. 可选地，在这一点上，我们可以通过调用element_positions()方法来请求放置有趣项目的详细信息。如果其整数heading属性为非零（对应 HTML 标签h1 - h6），如果其id属性不为None（对应 HTML 标签id），或者如果其href属性不为None（对应 HTML 标签href），则项目被视为有趣项目。这可以方便地用于自动生成目录、图像索引或类似内容。

    5. 接下来，用draw()方法将该矩形绘制到设备上。

    6. 如果最近的一次调用place()表明所有故事数据已经适应，现在停止。

    7. 否则，我们可以回到循环。如果有更多矩形要放置在当前设备（页面）上，我们回到步骤 3 - 如果没有，我们回到步骤 1 获取一个新设备。

  • 或者，在使用 DocumentWriter 的情况下，可以使用write()或write_stabilized()方法。这些方法为您处理所有循环，但需要提供控制行为的回调（特别是枚举要使用的矩形/页面的回调）。

• 故事的哪一部分将落在哪个矩形/哪一页完全由 Story 对象控制，无法预测。

• 图像可能是故事的一部分。它们将与周围的文本一起放置。

• 多个故事可能 - 互不干扰地 - 写入同一页。例如，页面页眉、页脚、常规文本、评论框等可能有单独的故事。

参数：

• html (str) – HTML 源代码。如果省略，将生成基本的最小内容（见下文）。如果提供，则不需要完整的 HTML 文档。内置源解析器将容忍（许多/大多数）HTML 语法错误，并且还接受 HTML 片段，例如 "<b>Hello, <i>World!</i></b>"。

• user_css (str) – CSS 源代码。如果提供，必须包含有效的 CSS 规范。

• em (float) – 默认文本字体大小。

• archive –

  从中加载资源以进行渲染的 Archive。当前支持的资源类型为图像和文本字体。如果省略，则故事将不会尝试查找任何此类数据，因此可能会产生不完整的输出。

  Note

  Instead of an actual archive, valid arguments for creating an Archive can also be provided – in which case an archive will temporarily be constructed. So, instead of story = pymupdf.Story(archive=pymupdf.Archive("myfolder")), one can also shorter write story = pymupdf.Story(archive="myfolder").

place(where)

计算故事内容的那部分，适合于提供的矩形内。该方法维护一个指针，指示已写入故事内容的哪一部分，并在下次调用时从该指针位置恢复。

Parameters:

where (rect_like) – 布局当前内容部分以适应此矩形。这必须是页面 MediaBox 的子矩形。

Return type:

tuple[bool, rect_like]

Returns:

一个布尔值（int）more 和一个矩形 filled。如果 more == 0，则所有故事内容均已写入，否则还有待写入后续矩形/页面。矩形 filled 是实际填充的 where 部分。

draw(dev, matrix=None)

将由Story.place()准备的内容部分写入页面。

Parameters:

• dev – 由 dev = writer.begin_page(mediabox) 创建的 Device。该设备知道如何调用所有写入内容所需的 MuPDF 函数。

• matrix (matrix_like) – 用于在写入页面时转换内容的矩阵。例如，可以写入旋转文本的示例。默认情况下不进行转换（即 Identity 矩阵）。

element_positions(function, args=None)

让 Story 在计算出当前页面上某些 HTML 元素的位置后提供位置信息 - 即在Story.place()之后直接调用此方法。

Story将位置信息传递给function。例如，这些信息可用于生成目录。

Parameters:

• function (callable) – 一个接受ElementPosition对象的 Python 函数。它将由 Story 对象调用以处理位置信息。此函数必须是一个接受正好一个参数的可调用对象。

• args (dict) – 一个可选的字典，包含应该添加到传递给function的ElementPosition实例的任何附加信息。例如，当前输出页码。该字典中的每个键必须是符合有效 Python 标识符规则的字符串。所有信息的完整集合将在下面解释。

reset()

将故事文档倒回到开始以重新开始其输出。

body

故事 DOM 的body部分。此属性包含 PDF 制作的所有相关内容，位于“”和“”之间的 Xml 节点。

write(writer, rectfn, positionfn=None, pagefn=None)

将 Story 放置并绘制到 DocumentWriter。避免调用代码实现调用Story.place()和Story.draw()等循环的需要，代价是至少要提供rectfn()回调函数。

参数：

• writer – 一个 DocumentWriter，或者为 None。

• rectfn –

  一个可调用的函数，接受(rect_num: int, filled: Rect)并返回(mediabox, rect, ctm)：

  • mediabox：None 或新页面的矩形。

  • rect：下一个放置内容的矩形。

  • ctm：None 或者一个 Matrix。

• positionfn –

  None，或者一个接受(position: ElementPosition)的可调用函数：

  • 位置：

    一个带有额外的.page_num成员的ElementPosition。

  通常作为生成具有标题或 ID 的元素的多次调用。

• pagefn – None，或者一个接受(page_num, mediabox, dev, after)的可调用函数；在每页的开始（after=0）和结束（after=1）时调用。

static write_stabilized(writer, contentfn, rectfn, user_css=None, em=12, positionfn=None, pagefn=None, archive=None, add_header_ids=True)

执行 HTML 内容的迭代布局到 DocumentWriter 的静态方法。

例如，这允许在确保页码稳定之前添加目录部分。

从(contentfn(), user_css, em, archive)创建一个新的 Story 并使用内部调用Story.write()布局它；使用 None writer 并提取传递给下一个contentfn()调用的ElementPosition列表。

当contentfn()的 HTML 变化不再变化时，我们使用writer进行最终迭代。

参数：

• writer – 一个 DocumentWriter。

• contentfn – 接受ElementPosition列表并返回包含 HTML 的字符串的函数。返回的 HTML 可以依赖于位置列表，例如在开头附近有目录。

• rectfn –

  一个可调用的函数，接受(rect_num: int, filled: Rect)并返回(mediabox, rect, ctm)：

  • mediabox：None 或新页面的矩形。

  • rect：下一个放置内容的矩形。

  • ctm：一个 Matrix。

• pagefn – None，或者一个接受(page_num, medibox, dev, after)的可调用函数；在每页的开始（after=0）和结束（after=1）时调用。

• archive –

• add_header_ids – 如果为真，我们为所有尚未具有 ID 的标题标签添加唯一的 ID。这有助于自动生成目录。

返回：

无。

write_with_links(rectfn, positionfn=None, pagefn=None)

类似于write()，但我们没有writer参数，返回一个 PDF 文档，其中为每个内部 HTML 链接创建了链接。

static write_stabilized_with_links(contentfn, rectfn, user_css=None, em=12, positionfn=None, pagefn=None, archive=None, add_header_ids=True)

类似于write_stabilized()，但我们没有writer参数，而是返回一个 PDF 文档，其中为每个内部 HTML 链接创建了链接。

class FitResult

来自Story.fit*()方法的结果。

成员：

big_enough：

True如果适合成功。

filled：

从上一次调用Story.place()。

more：

False如果适合成功。

numcalls：

调用self.place()的次数。

parameter：

成功的参数值，或最大的失败值。

Rect:

从parameter创建的 rect。

fit(self, fn, pmin=None, pmax=None, delta=0.001, verbose=False)

找到包含故事self的最佳 rect。

返回一个Story.FitResult 实例。

成功时，最后一次调用self.place()将使用返回的矩形，因此可以直接使用self.draw()。

参数：

• fn –

  一个可调用对象，接受一个浮点parameter并返回一个pymupdf.Rect()。如果 rect 为空，我们假设故事不会适合，并且不调用self.place()。

  必须确保当给定 rect fn(parameter)作为parameter增加时，self.place()行为单调递增。通常情况下，随着parameter增加，宽度和高度都会增加或保持不变。

• pmin – 要考虑的最小参数；None表示负无穷。

• pmax – 要考虑的最大参数；None表示正无穷。

• delta – 返回的parameter的最大误差。

• verbose – 如果为真，我们输出诊断信息。

fit_scale(self, rect, scale_min=0, scale_max=None, delta=0.001, verbose=False)

在范围scale_min..scale_max中找到一个比例scale，其中scale * rect足够大以容纳故事self。

返回一个Story.FitResult 实例。

参数：

• width – rect 的宽度。

• height – rect 的高度。

• scale_min – 要考虑的最小比例，必须>= 0。

• scale_max – 要考虑的最大比例，必须>= scale_min 或None表示无限。

• delta – 返回的比例的最大误差。

• verbose – 如果为真，我们输出诊断信息。

fit_height(self, width, height_min=0, height_max=None, origin=(0, 0), delta=0.001, verbose=False)

在范围height_min..height_max中找到一个 rect 的最小高度，其中一个大小为(width, height)的 rect 足够大以包含故事self。

返回一个Story.FitResult 实例。

参数：

• width – rect 的宽度。

• height_min – 要考虑的最小高度；必须>= 0。

• height_max – 考虑的最大高度，必须>= height_min 或None表示无限。

• origin – rect 的(x0, y0)。

• delta – 返回的高度的最大误差。

• verbose – 如果为真，我们输出诊断信息。

fit_width(self, height, width_min=0, width_max=None, origin=(0, 0), delta=0.001, verbose=False)

查找在范围width_min..width_max内最小的宽度，在该宽度下矩形大小为(width, height)足够大以包含故事self。

返回Story.FitResult实例。

参数：

• height – 矩形的高度。

• width_min – 要考虑的最小宽度；必须 >= 0。

• width_max – 要考虑的最大宽度；必须 >= width_min 或者None表示无限宽度。

• origin – 矩形的(x0, y0)坐标。

• delta – 返回宽度的最大误差。

• verbose – 如果为 true，则输出诊断信息。

元素定位回调函数

回调函数可用于记录关于故事输出的信息。该函数对信息的访问是只读的：它无法影响故事的输出。

使用此方法执行故事的典型循环如下所示：

HTML = """
<html>
 <head></head>
 <body>
 <h1>Header level 1</h1>
 <h2>Header level 2</h2>
 <p>Hello MuPDF!</p>
 </body>
</html>
"""
MEDIABOX = pymupdf.paper_rect("letter")  # size of a page
WHERE = MEDIABOX + (36, 36, -36, -36)  # leave borders of 0.5 inches
story =  pymupdf.Story(html=HTML)  # make the story
writer = pymupdf.DocumentWriter("test.pdf")  # make the writer
pno = 0 # current page number
more = 1  # will be set to 0 when done
while more:  # loop until all story content is processed
    dev = writer.begin_page(MEDIABOX)  # make a device to write on the page
    more, filled = story.place(WHERE)  # compute content positions on page
    story.element_positions(recorder, {"page": pno})  # provide page number in addition
    story.draw(dev)
    writer.end_page()
    pno += 1  # increase page number
writer.close()  # close output file

def recorder(elpos):
    pass 

ElementPosition 类的属性

必须向Story.element_positions()提供的函数传递一个参数。它是一个具有以下属性的对象：

传递给recorder函数的参数是一个具有以下属性的对象：

• elpos.depth (int) – 箱结构中此元素的深度。

• elpos.heading (int) – 标题级别，如果没有标题则为 0，对应h1至h6的 1 至 6。

• elpos.href (str) – href属性的值，如果未定义则为 None。

• elpos.id (str) – id属性的值，如果未定义则为 None。

• elpos.rect (tuple) – 页面上元素的位置。

• elpos.text (str) – 元素的即时文本。

• elpos.open_close (int 位字段) – 比特 0 设置：打开元素，比特 1 设置：关闭元素。适用于可能包含其他元素并因此创建/打开后可能不会立即关闭的元素。

• elpos.rect_num (int) – 到目前为止故事中填充的矩形数量。

• elpos.page_num (int) – 页码；仅在使用pymupdf.Story.write*()函数时出现。

您对此页面有何反馈？

---

本软件按原样提供，不附带任何形式的明示或暗示担保。本软件按许可分发，未经授权不得复制、修改或分发。有关详细信息，请参阅artifex.com，或联系位于美国加利福尼亚州旧金山 94129 号梅萨街 39 号 108A 套房的 Artifex Software Inc。

此文档涵盖所有 1.24.4 版本。

元素定位回调函数

回调函数可用于记录关于故事输出的信息。该函数对信息的访问是只读的：它无法影响故事的输出。

使用此方法执行故事的典型循环如下所示：

HTML = """
<html>
 <head></head>
 <body>
 <h1>Header level 1</h1>
 <h2>Header level 2</h2>
 <p>Hello MuPDF!</p>
 </body>
</html>
"""
MEDIABOX = pymupdf.paper_rect("letter")  # size of a page
WHERE = MEDIABOX + (36, 36, -36, -36)  # leave borders of 0.5 inches
story =  pymupdf.Story(html=HTML)  # make the story
writer = pymupdf.DocumentWriter("test.pdf")  # make the writer
pno = 0 # current page number
more = 1  # will be set to 0 when done
while more:  # loop until all story content is processed
    dev = writer.begin_page(MEDIABOX)  # make a device to write on the page
    more, filled = story.place(WHERE)  # compute content positions on page
    story.element_positions(recorder, {"page": pno})  # provide page number in addition
    story.draw(dev)
    writer.end_page()
    pno += 1  # increase page number
writer.close()  # close output file

def recorder(elpos):
    pass 

ElementPosition 类的属性

必须向 Story.element_positions() 提供的函数传递一个参数。它是具有以下属性的对象：

传递给 recorder 函数的参数是具有以下属性的对象：

• elpos.depth（int）- 此元素在框结构中的深度。

• elpos.heading（int）- 标题级别，如果没有标题则为 0，h1 - h6 对应 1-6。

• elpos.href（str）- href 属性的值，如果未定义则为 None。

• elpos.id（str）- id 属性的值，如果未定义则为 None。

• elpos.rect（tuple）- 页面上的元素位置。

• elpos.text（str）- 元素的即时文本。

• elpos.open_close（int 位字段）- 设置位 0：打开元素，设置位 1：关闭元素。对于可能包含其他元素的元素以及因此可能在创建/打开后不会立即关闭的元素相关。

• elpos.rect_num（int）- 故事到目前为止填充的矩形数量。

• elpos.page_num（int）- 页码；仅在使用 pymupdf.Story.write*() 函数时存在。

在这页上有任何反馈吗？

---

本软件按原样提供，不附带任何明示或暗示的保证。本软件在许可下分发，并且除非根据该许可明确授权，否则不得复制、修改或分发本软件。有关详细信息，请参阅 artifex.com 上的许可信息，或联系 Artifex Software Inc.，39 Mesa Street，Suite 108A，San Francisco CA 94129，United States。

此文档涵盖所有版本，直至 1.24.4。

ElementPosition 类的属性

必须向 Story.element_positions() 提供的函数传递一个参数。它是具有以下属性的对象：

传递给 recorder 函数的参数是具有以下属性的对象：

• elpos.depth（int）- 此元素在框结构中的深度。

• elpos.heading（int）- 标题级别，如果没有标题则为 0，h1 - h6 对应 1-6。

• elpos.href（str）- href 属性的值，如果未定义则为 None。

• elpos.id（str）- id 属性的值，如果未定义则为 None。

• elpos.rect（tuple）- 页面上的元素位置。

• elpos.text（str）- 元素的即时文本。

• elpos.open_close（int 位字段）- 设置位 0：打开元素，设置位 1：关闭元素。对于可能包含其他元素的元素以及因此可能在创建/打开后不会立即关闭的元素相关。

• elpos.rect_num（int）- 故事到目前为止填充的矩形数量。

• elpos.page_num（int）- 页码；仅在使用 pymupdf.Story.write*() 函数时存在。

在这页上有任何反馈吗？

---

此软件按原样提供，不附任何明示或暗示的保证。此软件在许可下分发，未经许可明确授权，不得复制、修改或分发。请参阅artifex.com获取许可信息，或联系美国旧金山 94129 Mesa 街 39 号 108A 套房 Artifex Software Inc.以获取进一步信息。

此文档覆盖所有版本直至 1.24.4。

文本页

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

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

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

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

方法	描述	页面 get_text 或 search 方法
extractText()	提取纯文本	“text”
extractTEXT()	与上一个同义	“text”
extractBLOCKS()	分组在块中的纯文本	“blocks”
extractWORDS()	带有它们的 bbox 的所有单词	“words”
extractHTML()	HTML 格式的页面内容	“html”
extractXHTML()	XHTML 格式的页面内容	“xhtml”
extractXML()	XML 格式的页面文本	“xml”
extractDICT()	dict 格式的页面内容	“dict”
extractJSON()	JSON 格式的页面内容	“json”
extractRAWDICT()	dict 格式的页面内容	“rawdict”
extractRAWJSON()	JSON 格式的页面内容	“rawjson”
search()	在页面中搜索字符串	Page.search_for()

类 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() 和相关功能)。

页面字典

键	值
width	clip 矩形的宽度 (浮点数)
height	clip 矩形的高度 (浮点数)
blocks	图像块字典的 列表

块字典

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

• (在 v1.18.0 中更改) – 新字典键 number，块编号。

• (在 v1.18.11 中更改) – 新字典键 transform，图像块的图像变换矩阵。

• (在 v1.18.11 中更改) – 新字典键 size，图像块的图像大小，以字节为单位。

图像块:

键	值
type	1 = 图像 (整数)
bbox	页面上图像的 bbox (rect_like)
number	块计数 (整数)
ext	图像类型 (字符串)，作为文件扩展名，请参见下文
width	原始图像宽度 (整数)
height	原始图像高度 (整数)
colorspace	颜色空间组件计数 (整数)
xres	x 方向分辨率 (整数)
yres	y 方向分辨率 (整数)
bpc	每组件位数 (整数)
transform	将图像矩形转换为 bbox 的矩阵 (matrix_like)
size	图像大小，以字节为单位 (整数)
image	图像内容 (字节)

“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”命令（错误地或有意省略）。在这种情况下，该图像将不会出现在文本页中。

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

文本块：

Key	Value
type	0 = 文本 (整数)
bbox	块矩形，rect_like
number	块计数 (整数)
lines	文本行字典列表

行字典

Key	Value
bbox	行矩形，rect_like
wmode	编写模式 (整数)：0 = 水平，1 = 垂直
dir	编写方向，point_like
spans	span 字典列表

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

Span 字典

Span 包含实际文本。如果一行包含具有不同字体属性的文本，则包含多个 span。

• 自版本 1.14.17 更改 Spans 现在也有一个 bbox 键（再次）。

• 自版本 1.17.6 更改 Spans 现在也有一个 origin 键。

Key	Value
bbox	span 矩形，rect_like
origin	第一个字符的来源，point_like
font	字体名称 (字符串)
ascender	字体的 ascender (浮点数)
descender	字体的 descender (浮点数)
size	字体大小 (浮点数)
flags	字体特性 (整数)
color	sRGB 格式下的文本颜色 (整数)
text	(仅适用于 extractDICT()) 文本 (字符串)
chars	(仅适用于 extractRAWDICT()) 字符字典的列表

(新增于版本 1.16.0): “color” 是以 sRGB 编码的文本颜色（整数），例如红色为 0xFF0000。有函数可以将此整数转换回格式 (r, g, b)（PDF 中的浮点值从 0 到 1）sRGB_to_pdf()，或者 (R, G, B)，sRGB_to_rgb()（整数值从 0 到 255）。

(新增于 v1.18.5): “ascender” 和 “descender” 是字体属性，相对于 fontsize 1。请注意，descender 是一个负值。以下图片展示了它们与其他值和属性的关系。

这些数字可以用来计算字符（或 span）的最小高度，与“bbox”值中提供的标准高度相对应（实际上代表行高）。以下代码重新计算 span 的 bbox，确保其高度与 fontsize 恰好适合文本内容：

>>> a = span["ascender"]
>>> d = span["descender"]
>>> r = pymupdf.Rect(span["bbox"])
>>> o = pymupdf.Point(span["origin"])  # its y-value is the baseline
>>> r.y1 = o.y - span["size"] * d / (a - d)
>>> r.y0 = r.y1 - span["size"]
>>> # r now is a rectangle of height 'fontsize' 

警告

上述计算可能会得到一个更大的高度！例如在 OCR 文档中可能发生，那里各种文本伪影的风险较高。MuPDF 尝试提供一个合理的 bbox 高度，与 PDF 中找到的 fontsize 无关。因此，请确保 span["bbox"] 的高度大于 span["size"]。

注意

您可以通过执行 pymupdf.TOOLS.set_small_glyph_heights(True) 要求 PyMuPDF 自动执行以上所有操作。这会设置一个全局参数，以便所有后续的文本搜索和文本提取都基于降低的字形高度，而这些高度是有意义的。

下图显示了原始 span 矩形为红色，重新计算高度后的矩形为蓝色。

“标志” 是一个整数，代表字体属性，但第一个位 0 除外。其解释如下：

• 第 0 位：上标 (2⁰) - 不是字体属性，MuPDF 代码检测到的。

• 第 1 位：斜体 (2¹)

• 位 2：衬线体 (2²)

• 位 3：等宽字体 (2³)

• 第 4 位：粗体 (2⁴)

测试这些特性的方式如下：

>>> if flags & 2**1: print("italic")
>>> # etc. 

位 1 到 4 是字体属性，即在字体程序中编码。请注意，此信息未必正确或完整：字体往往在这里包含错误数据。

extractRAWDICT() 的字符字典

键	值
origin	字符的左基线点，point_like
bbox	字符矩形，rect_like
c	字符（Unicode）

此图显示了字符的边界框和其四边形之间的关系：

脚注

你对这一页有什么反馈吗？

---

此软件按原样提供，不带任何明示或暗示的保证。此软件根据许可分发，未经授权不得复制、修改或分发。有关详细信息，请参阅artifex.com，或联系美国加利福尼亚州旧金山市 Mesa 街 39 号 108A 室的 Artifex Software Inc。。

此文档涵盖了所有 1.24.4 版本及以前的版本。

## 字典输出的结构

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

• 一个 页面 由一系列 块字典 组成。

• 一个（文本） 块 由一系列 行字典 组成。

• 一条 线 由一系列 跨度字典 组成。

• 一个 跨度 可以是文本本身，也可以是原始变体的 字符字典 列表。

• 原始变体：一个 字符 是其原点、边界框和 Unicode 的字典。

这里所有的 PyMuPDF 几何对象（点、矩形、矩阵）都用其 “like” 格式表示：使用 rect_like 元组 代替 Rect 等。这样做是出于性能和内存考虑：

• 此代码是用 C 语言编写的，其中 Python 元组可以轻松生成。另一方面，几何对象仅在 Python 源代码中定义。将每个 Python 元组转换为其相应的几何对象会增加显著的执行时间，这在大多数情况下是不必要的。

• 一个 4 元组大约需要 168 字节，相应的 Rect 则需要 472 字节，几乎是前者的三倍大小。一个文本密集型页面的 “dict” 字典包含 300 多个 bbox 对象，因此以 4 元组形式需要约 50 KB 存储空间，而以 Rect 对象形式需要约 140 KB。然而，对于这样的页面，“rawdict”输出将包含 4 到 5 千个 bbox，这种情况下大约是 750 KB 对比 2 MB。

还请注意，仅返回 bboxes (= rect_like 4 元组)，而 TextPage 实际上具有完整的位置信息 – 以 Quad 格式表示。再次考虑内存使用的原因，做出这样的决定：quad_like 需要 488 字节（是 rect_like 的三倍大小）。考虑到生成的 bbox 数量，返回 quad_like 信息会有显著影响。

在绝大多数情况下，我们只处理 水平文本，在这种情况下，bbox 提供的信息已经完全足够。

另外，完整的四边形信息没有丢失：可以根据需要使用以下列表中的适当函数来恢复行、跨度和字符的四边形信息：

• recover_quad() – 完整跨度的四边形

• recover_span_quad() – 跨度子集的四边形

• recover_line_quad() – 行的四边形

• recover_char_quad() – 字符的四边形

正如前述的，只有在文本 非水平写入 的情况下才需要使用这些函数 – line["dir"] != (1, 0) – 并且需要用于文本标记注释的四边形 (Page.add_highlight_annot() 和其它相关函数)。

页面字典

键	值
width	clip 矩形的宽度 (浮点数)
height	clip 矩形的高度 (浮点数)
blocks	块字典的 列表

块字典

块字典有两种不同的格式，分别用于 图像块 和 文本块。

• (更改于 v1.18.0) – 新字典键 number，块编号。

• (更改于 v1.18.11) – 新字典键 transform，图像块的图像变换矩阵。

• (更改于 v1.18.11) – 新字典键 size，图像块中图像的大小（以字节为单位）。

图像块：

键	值
type	1 = 图像 (整数)
bbox	页面上图像边界框（rect_like）
number	块计数 (整数)
ext	图像类型 (字符串)，作为文件扩展名，详见下文
width	原始图像宽度 (整数)
height	原始图像高度 (整数)
colorspace	色彩空间组件计数 (整数)
xres	x 方向的分辨率 (整数)
yres	y 方向的分辨率 (整数)
bpc	每个组件的比特数 (整数)
transform	将图像矩形转换为边界框的矩阵（matrix_like）
size	图像大小，以字节为单位 (整数)
image	图像内容 (字节)

“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”命令（错误地或有意）。在这种情况下，该图像将不会出现在文本页中。

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

文本块：

键	值
type	0 = 文本 (整数)
bbox	块矩形，rect_like
number	块计数 (整数)
lines	文本行字典的列表

行字典

键	值
bbox	行矩形，rect_like
wmode	书写模式 (int): 0 = 水平, 1 = 垂直
dir	书写方向，point_like
spans	跨度字典的列表

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

跨度字典

跨度包含实际文本。如果一行包含具有不同字体属性的文本，则该行包含多个跨度。

• 从版本 1.14.17 更改，跨度现在也有一个bbox键（再次）。

• 从版本 1.17.6 更改，跨度现在也有一个origin键。

键	值
bbox	跨度矩形，rect_like
origin	第一个字符的起源，point_like
font	字体名称 (str)
ascender	字体的上升部分 (float)
descender	字体的下降部分 (float)
size	字体大小 (float)
flags	字体特性 (int)
color	sRGB 格式文本颜色 (int)
text	（仅适用于extractDICT()）文本 (str)
chars	（仅适用于extractRAWDICT()）字符字典的列表

(自版本 1.16.0 新增): “color” 是以 sRGB（int）格式编码的文本颜色，例如红色为 0xFF0000。有函数可将此整数转换回格式（r, g, b）（PDF 中浮点值从 0 到 1）sRGB_to_pdf()，或（R, G, B），sRGB_to_rgb()（值从 0 到 255 的整数）。

(新增于 v1.18.5): “ascender” 和 “descender” 是与fontsize 1 相关的字体属性。注意 descender 是一个负值。以下图片显示了与其他值和属性的关系。

这些数字可用于计算字符（或跨度）的最小高度 - 与“bbox”值中提供的标准高度相反（实际上代表行高）。以下代码重新计算跨度的 bbox，确保其高度完全适合文本内的fontsize：

>>> a = span["ascender"]
>>> d = span["descender"]
>>> r = pymupdf.Rect(span["bbox"])
>>> o = pymupdf.Point(span["origin"])  # its y-value is the baseline
>>> r.y1 = o.y - span["size"] * d / (a - d)
>>> r.y0 = r.y1 - span["size"]
>>> # r now is a rectangle of height 'fontsize' 

注意

上述计算可能会得到更大的高度！这可能发生在 OCRed 文档中，那里各种文本伪影的风险很高。MuPDF 试图独立于 PDF 中找到的fontsize，提供一个合理的 bbox 高度。因此，请确保span["bbox"]的高度大于span["size"]。

注意

您可以通过执行pymupdf.TOOLS.set_small_glyph_heights(True)来请求 PyMuPDF 自动执行上述所有操作。这会设置一个全局参数，以便所有后续的文本搜索和文本提取都基于降低的字形高度（在有意义时）。

这里显示了原始跨度矩形为红色，重新计算高度后的矩形为蓝色。

“flags” 是一个整数，代表除了第一个位 0 以外的字体属性。它们应该按照以下方式解释：

• 位 0: 上标（2⁰） – 不是字体属性，由 MuPDF 代码检测。

• 位 1: 斜体（2¹）

• 位 2: 衬线字体（2²）

• 位 3: 等宽字体（2³）

• 位 4: 粗体（2⁴）

如此测试这些特性：

>>> if flags & 2**1: print("italic")
>>> # etc. 

位 1 到 4 是字体属性，即编码在字体程序中。请注意，此信息未必正确或完整：字体往往在此处包含错误数据。

extractRAWDICT() 的字符字典

关键字	数值
origin	字符左基线点，point_like
bbox	字符矩形，rect_like
c	字符（unicode）

这幅图展示了字符 bbox 与其 quad 之间的关系：

脚注

您对本页面有何反馈？

---

此软件按原样提供，不带任何明示或暗示的担保。此软件在许可证下分发，并且未经授权不得复制、修改或分发。请参阅artifex.com的许可信息或联系美国加利福尼亚州旧金山 Mesa 街 39 号 108A 套房的 Artifex Software Inc.了解更多信息。

本文档涵盖所有 1.24.4 版本及更早版本。

页面字典

关键字	数值
width	clip 矩形的宽度 (浮点数)
height	clip 矩形的高度 (浮点数)
blocks	块 字典列表

块字典

块字典有两种不同的格式，适用于图像块和文本块。

• (在 v1.18.0 中更改) – 新的字典键 number，块编号。

• (在 v1.18.11 中更改) – 新字典键 transform，图像块的转换矩阵。

• (在 v1.18.11 中更改) – 新字典键 size，图像块的字节大小。

图像块：

关键字	数值
类型	1 = 图像 (int)
bbox	页面上的图像边界框 (rect_like)
数量	块计数 (int)
扩展名	图像类型 (str)，作为文件扩展名，见下文
宽度	原始图像宽度 (int)
高度	原始图像高度 (int)
颜色空间	颜色空间组件计数 (int)
xres	x 方向分辨率 (int)
yres	y 方向分辨率 (int)
bpc	每分量的位数 (int)
转换	将图像矩形转换为边界框的矩阵 (matrix_like)
大小	图像大小（字节为单位） (int)
图像	图像内容 (bytes)

“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”命令（错误或故意省略）。在这种情况下，图像将不会出现在文本页中。

3. 图像的“转换矩阵”被定义为满足表达式 bbox / transform == pymupdf.Rect(0, 0, 1, 1) 的矩阵，详情请参见：图像转换矩阵。

文本块：

键	值
类型	0 = 文本 (整数)
bbox	块矩形，rect_like
数量	块计数 (整数)
lines	文本行字典列表

行字典

键	值
bbox	行矩形，rect_like
wmode	写作模式 (整数)：0 = 水平，1 = 垂直
dir	写作方向，point_like
spans	跨度字典列表

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

跨度字典

跨度包含实际的文本。只有当一行包含具有不同字体属性的文本时，它才包含 多个跨度。

• 更改于版本 1.14.17，跨度现在也有一个 bbox 键（再次）。

• 更改于版本 1.17.6，跨度现在也有一个 origin 键。

键	值
bbox	跨度矩形，rect_like
origin	第一个字符的原点，point_like
font	字体名称 (字符串)
ascender	字体的升头 (浮点数)
降头	字体的降头 (浮点数)
size	字体大小 (浮点数)
flags	字体特征 (整数)
color	文本颜色，sRGB 格式 (整数)
text	（仅用于 extractDICT()）文本 (字符串)
chars	（仅用于 extractRAWDICT()）字符字典列表

(版本 1.16.0 新增)： “color” 是以 sRGB (整数) 格式编码的文本颜色，例如红色的 0xFF0000。有函数可以将此整数转换回格式（r，g，b）（从 0 到 1 的浮点数）sRGB_to_pdf()，或（R，G，B），sRGB_to_rgb()（从 0 到 255 的整数值）。

(版本 1.18.5 新增)： “ascender” 和 “descender” 是字体属性，相对于 fontsize 1 提供。请注意，descender 是一个负值。下图显示了它们与其他值和属性的关系。

这些数字可用于计算字符（或跨度）的最小高度 - 与“bbox”值中提供的标准高度相对（实际上表示 行高）。以下代码重新计算跨度 bbox，使其高度正好为 fontsize，以适应其中的文本：

>>> a = span["ascender"]
>>> d = span["descender"]
>>> r = pymupdf.Rect(span["bbox"])
>>> o = pymupdf.Point(span["origin"])  # its y-value is the baseline
>>> r.y1 = o.y - span["size"] * d / (a - d)
>>> r.y0 = r.y1 - span["size"]
>>> # r now is a rectangle of height 'fontsize' 

注意

上述计算可能会得到一个更大的高度！这种情况可能发生在 OCR 文档中，那里各种文本伪影的风险很高。MuPDF 试图提供一个合理的 bbox 高度，独立于 PDF 中找到的fontsize。因此，请确保span["bbox"]的高度大于span["size"]。

注意

您可以通过执行pymupdf.TOOLS.set_small_glyph_heights(True)来请求 PyMuPDF 自动完成上述所有操作。这将设置一个全局参数，以便所有后续的文本搜索和文本提取都基于降低的字形高度，以提供更有意义的结果。

下面显示了原始 span 矩形为红色，重新计算高度后的矩形为蓝色。

*“flags”*是一个整数，代表字体属性，除了第一个位 0。它们应该这样解释：

• bit 0: 上标（2⁰） - 不是字体属性，由 MuPDF 代码检测到。

• bit 1: 斜体（2¹）

• bit 2: 衬线字体（2²）

• bit 3: 等宽字体（2³）

• bit 4: 粗体（2⁴）

测试这些特性如下：

>>> if flags & 2**1: print("italic")
>>> # etc. 

位 1 到 4 是字体属性，即编码在字体程序中。请注意，这些信息不一定正确或完整：字体往往在这里包含错误的数据。

提取extractRAWDICT()的字符字典

关键词	数值
origin	字符的左基线点，point_like
bbox	字符矩形，rect_like
c	字符（Unicode）

此图片展示了字符 bbox 与其 quad 之间的关系：

脚注

您对本页有任何反馈吗？

---

本软件按原样提供，不附带任何明示或暗示的保证。此软件在许可下分发，未经授权不得复制、修改或分发。请参阅artifex.com的许可信息或联系美国旧金山 CA 94129 Mesa 街 39 号 108A 套房的 Artifex Software Inc.以获取更多信息。

此文档覆盖了所有版本直到 1.24.4。

文本写入器

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

此类仅适用于 PDF。

• v1.16.18 中的新功能

此类表示 MuPDF 的文本对象。其基本思想是将文本准备（1）和输出到 PDF 页面（2）分离。

在准备阶段，文本写入器将任意数量的文本片段（“跨度”）及其位置和各自的字体信息存储起来。文本写入器准备的内容可以多次输出到任何具有兼容页面尺寸的 PDF 页面上。

文本写入器是Page.insert_text()等方法的一个优雅替代品：

• 改进的文本定位： 选择任何插入文本应该开始的点。存储文本后返回“光标位置”，即跨度的最后一个字符之后。

• 自由字体选择： 每个文本跨度都有自己的字体和fontsize。这使得在组成更大文本时可以轻松切换字体。

• 自动回退字体： 如果所选字体不支持某个字符，系统会自动搜索替代字体。这大大减少了输出中看到无法打印符号（看起来像小矩形的“TOFUs”）的风险。PyMuPDF 现在还提供通用字体“Droid Sans Fallback Regular”，支持所有拉丁字母（包括西里尔字母和希腊字母）以及所有 CJK 字符（中文、日文、韩文）。

• 西里尔字母和希腊字母支持： PDF 基本 14 字体集成了对西里尔字母和希腊字母的支持，无需指定编码。你的文本可以混合使用拉丁字母、希腊字母和西里尔字母。

• 透明度支持： 支持opacity参数。这提供了一种便捷的方式来创建水印式文本。

• 文本对齐： 支持任何字体 - 不仅仅是像Page.insert_textbox()中的简单字体。

• 可重用性： TextWriter 对象存在独立于 PDF 页面之外。它可以多次写入，无论是同一页面还是其他页面，同一 PDF 或不同 PDF，还可以选择不同的颜色或透明度。

使用此对象包括三个步骤：

1. 创建时，TextWriter 需要一个固定的页面矩形，以此为基础计算文本位置。文本写入器只能写入这种大小的页面。

2. 使用TextWriter.append()、TextWriter.appendv()和TextWriter.fill_textbox()方法将文本存储在 TextWriter 中，可以根据需要频繁调用。

3. 在一些 PDF 页面上输出 TextWriter 对象。

注意

• 从版本 1.17.0 开始，通过TextWriter.write_text()的morph参数，TextWriter 现在支持文本旋转。

• 还存在Page.write_text()，它将一个或多个 TextWriter 组合在一起，并将它们联合写入到给定的矩形和给定的旋转角度中，就像Page.show_pdf_page()一样。

方法 / 属性	简短描述
append()	水平写入模式添加文本
appendv()	垂直写入模式添加文本
fill_textbox()	填充矩形（水平写入模式）
write_text()	将 TextWriter 输出到 PDF 页面
color	文本颜色（可更改）
last_point	最后一个写入的字符在此结束
opacity	文本不透明度（可更改）
rect	此 TextWriter 使用的页面矩形
text_rect	到目前为止所占据的区域

类 API

class TextWriter

__init__(self, rect, opacity=1, color=None)

参数：

• rect (rect-like) – 用于文本定位计算的矩形。

• opacity (float) – 设置文本存储的透明度。超出区间0, 1)的值将被忽略。例如 0.5 的值表示 50%的透明度。

• color (float*,*sequ) – 文本的颜色。所有颜色都以浮点数表示，0 <= color <= 1。一个浮点数表示一些灰度级别，一个序列意味着颜色空间通过其长度。

append(pos, text, font=None, fontsize=11, language=None, right_to_left=False, small_caps=0)

• v1.18.9 中更改

• v1.18.15 中更改

添加一些新的水平书写文本。

参数：

• pos (point_like) – 文本的起始位置，第一个字符的左下角点。

• text (str) – 任意长度的字符串。将从“pos”位置开始写入。

• font – 一个[字体。如果省略，则将使用pymupdf.Font("helv")。

• fontsize (float) – 字体大小，一个正数，默认为 11。

• language (str) – 要使用的语言，例如英语的“en”。有意义的值应符合 ISO 639 标准 1、2、3 或 5。保留供将来使用：目前据我们所知没有任何影响。

• right_to_left (bool) – (v1.18.9 中新增) 是否应该从右向左写入文本。适用于阿拉伯语或希伯来语等语言。默认为False。如果为True，则文本中的任何拉丁部分将自动转换。没有其他后果，即TextWriter.last_point仍将是最右边的字符，也不会进行任何对齐。因此，您可能希望改用TextWriter.fill_textbox()。

• small_caps (bool) –

  (v1.18.15 新增) 寻找字体中字符的小型大写版本。如果存在，则取该值。否则将采用原始字符（当前字体或备用字体）。备用字体不会返回小型大写字母。例如，以下代码片段：

  >>> doc = pymupdf.open()
  >>> page = doc.new_page()
  >>> text = "PyMuPDF: the Python bindings for MuPDF"
  >>> font = pymupdf.Font("figo")  # choose a font with small caps
  >>> tw = pymupdf.TextWriter(page.rect)
  >>> tw.append((50,100), text, font=font, small_caps=True)
  >>> tw.write_text(page)
  >>> doc.ez_save("x.pdf") 
  

  将生成此 PDF 文本：

  

返回：

text_rect 和 last_point。(v1.18.0 更改：) 对不支持的字体引发异常 – 通过Font.is_writable检查。

appendv(pos, text, font=None, fontsize=11, language=None, small_caps=0)

v1.18.15 更改

在垂直方向上添加一些新文本，从顶部到底部的书写方式。

参数：

• 位置 (point_like) – 文本的起始位置，即第一个字符的左下角点。

• 文本 (str) – 字符串。将从“pos”位置开始写入。

• 字体 – 字体。如果省略，则使用 pymupdf.Font("helv")。

• 字体大小 (float) – 字体大小，正浮点数，默认为 11。

• 语言 (str) – 要使用的语言，例如英语的“en”。有意义的值应符合 ISO 639 标准的 1、2、3 或 5。保留供将来使用：目前据我们所知没有任何影响。

• small_caps (bool) – (v1.18.15 新增) 参见 append()。

返回：

text_rect 和 last_point。(v1.18.0 更改：) 对不支持的字体引发异常 – 通过Font.is_writable检查。

fill_textbox(rect, text, *, pos=None, font=None, fontsize=11, align=0, right_to_left=False, warn=None, small_caps=0)

• 1.17.3 版本更改：新增参数 pos，指定在矩形内开始书写的位置。

• v1.18.9 更改：返回不适合矩形的行的列表。支持从右到左书写（例如阿拉伯文、希伯来文）。

• v1.18.15 更改：如支持字体，则优先使用小型大写字母。

用水平书写方式在给定的矩形中填充文本。这是一个方便的替代方法，可以用来替代append()。

参数：

• 矩形 (rect_like) – 要填充的区域。文本的任何部分不会出现在此区域之外。

• 文本 (str*,*sequ) – 文本。可以指定为（UTF-8）字符串或字符串列表/元组。字符串将首先使用 splitlines() 转换为列表。每个列表项将从新行开始（强制换行）。

• 位置 (point_like) – (v1.17.3 新增) 开始存储的位置。默认是接近矩形左上角的点。

• 字体 – 字体，默认为 pymupdf.Font("helv")。

• 字体大小 (float) – 字体大小。

• 对齐方式 (int) – 文本对齐方式。使用 TEXT_ALIGN_LEFT、TEXT_ALIGN_CENTER、TEXT_ALIGN_RIGHT 或 TEXT_ALIGN_JUSTIFY 中的一个。

• right_to_left (bool) – (v1.18.9 新增) 决定文本是否从右向左书写。适用于阿拉伯语或希伯来语等语言。默认为 False。如果为 True，则任何拉丁部分会自动翻转。仍需设置对齐方式（如果需要右对齐），不会自动发生 – 其他对齐选项仍然可用。

• warn (bool) –

  当文本溢出时，不执行任何操作、警告或引发异常。溢出文本永远不会被写入。v1.18.9 中已更改：

  • 默认为 None。

  • 返回溢出行的列表。

• small_caps (bool) – (v1.18.15 新增) 参见 append()。

返回类型：

列表

返回：

v1.18.9 新增 – 未适合矩形的行的列表。每个项目都是包含字符串及其在页面上长度的元组 (text, length)。

注意

可根据需要多次使用这些方法 – 没有技术上的限制（除了系统的内存限制）。还可以混合 append() 和文本框，并且可以拥有多个文本框。文本定位完全由插入点控制。因此，无需遵循任何顺序。(v1.18.0 中已更改：) 不支持的字体引发异常 – 通过 Font.is_writable 进行检查。

write_text(page, opacity=None, color=None, morph=None, overlay=True, oc=0, render_mode=0)

将 TextWriter 文本写入页面，这是唯一必需的参数。其他参数可以用于临时覆盖创建 TextWriter 时使用的值。

参数：

• page – 写入到此 Page。

• opacity (float) – 覆盖此输出的 TextWriter 的值。

• color (sequ) – 覆盖此输出的 TextWriter 的值。

• morph (sequ) – 通过应用矩阵修改文本外观。如果提供，必须是一个包含像点一样的 fixpoint 和矩阵一样的 matrix 的序列。典型示例是围绕 fixpoint 旋转文本。

• overlay (bool) – 放置在前景（默认）或背景。

• oc (int) – (v1.18.4 新增) xref 的一个 OCG 或 OCMD。

• render_mode (int) –

  PDF Tr 运算符的值。取值：0（默认）、1、2、3（不可见）。

  

text_rect

当前占用的区域。

返回类型：

Rect

last_point

“光标位置” – Point – 最后一个字符的底部右下角。

返回类型：

Point

opacity

文本不透明度（可修改）。

返回类型：

float

color

文本颜色（可修改）。

返回类型：

float, tuple

rect

创建此 TextWriter 的页面矩形。必须不被修改。

返回类型：

Rect

注意

若要查看处理 TextWriter 的一些演示脚本，请访问 此 仓库。

1. 不透明度和颜色适用于此对象中的所有文本。

2. 如果需要不同的颜色/透明度，必须创建单独的 TextWriter。每当确定颜色应该更改时，只需将文本附加到相应的 TextWriter，使用先前返回的last_point作为新文本范围的位置。

3. 附加项或文本框可以以任意顺序出现：只有位置参数控制文本显示的位置。

4. 字体和fontsize可以在同一个 TextWriter 内自由变化。这可以用来让具有不同属性的文本显示在同一行上：只需相应地指定pos，例如设置为上一个添加项的last_point。

5. 您可以使用TextWriter.fill_textbox()的pos参数设置第一个文本字符的位置。这允许使用不同 TextWriter 对象的内容填充相同的文本框，从而实现多种颜色、不透明度等效果。

6. MuPDF 不支持所有具有此功能的字体，例如没有 Type3 字体。从 v1.18.0 开始，可以通过字体属性Font.is_writable检查此功能。在使用 TextWriter 方法时也会检查此属性。

对本页面有任何反馈吗？

---

此软件按原样提供，不附带任何明示或暗示的保证。此软件根据许可证分发，未经许可明确授权，不得复制、修改或分发。请参阅artifex.com的许可信息或联系美国旧金山 CA 94129 Mesa Street 39 号 108A 套房的 Artifex Software Inc.以获取更多信息。

此文档涵盖所有版本直至 1.24.4。

Tools

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

此类是一组围绕内存管理的实用方法和属性。为了简化和加速其使用，在导入 PyMuPDF 时，它会自动实例化为 TOOLS。

方法 / 属性	描述
Tools.gen_id()	生成唯一标识符
Tools.store_shrink()	缩小可存储缓存 [1]
Tools.mupdf_warnings()	返回累积的 MuPDF 警告
Tools.mupdf_display_errors()	返回累积的 MuPDF 警告
Tools.reset_mupdf_warnings()	清空 MuPDF 输出的消息
Tools.set_aa_level()	设置抗锯齿值
Tools.set_annot_stem()	设置新注解 / 链接 ID 的前缀
Tools.set_small_glyph_heights()	使用小的 bbox 高度搜索和提取
Tools.set_subset_fontnames()	控制子集字体名称标签的抑制
Tools.show_aa_level()	返回抗锯齿值
Tools.unset_quad_corrections()	禁用 PyMuPDF 特定代码
Tools.fitz_config	PyMuPDF 的配置设置
Tools.store_maxsize	最大可存储缓存大小
Tools.store_size	当前可存储缓存大小

类 API

class Tools

gen_id()

一个方便的方法返回一个唯一的正整数，在每次调用时增加 1。例如用于在数据库中创建唯一键 - 其创建速度应比使用时间戳快一个数量级。

注意

MuPDF 在 v1.14.0 中放弃了对此的支持，因此我们重新实现了一个类似的功能，有以下差异：

• 它不是 MuPDF 全局上下文的一部分，也不是线程安全的（在 PyMuPDF 中不支持线程，因此这不是问题）。

• 它被实现为 int。这意味着最大数是 sys.maxsize。如果这个数超过了，计数器会从 1 重新开始。

返回类型：

int

返回：

一个唯一的正整数。

set_annot_stem(stem=None)

• v1.18.6 中的新功能

设置或查询新注解、字段或链接的 ID 前缀。

参数：

stem (str) – 如果省略，则返回当前值，默认为“fitz”。在 PDF 文档中，注释、字段/小部件和链接技术上都是相同类型的对象（/Annot）的子类型。每个适用的子类型，PyMuPDF 分别生成标识符“stem-Annn”，“stem-Wnnn”或“stem-Lnnn”。数字“nnn”用于强制要求的唯一性。

返回类型：

字符串

返回：

当前值。

set_small_glyph_heights(on=None)

• 新版本 v1.18.5 中

在文本提取和文本搜索方法中设置或查询减少的 bbox 高度。

参数：

on (bool) – 如果省略或为 None，则返回当前设置。对于其他值，将应用 bool() 函数以设置全局变量。如果为 True，Page.search_for() 和 Page.get_text() 方法将返回具有 字体大小 高度的字符、跨度、行或块 bbox。如果为 False（PyMuPDF 导入时的标准设置），bbox 高度将基于字体属性，并且通常等于 行高。

返回类型：

布尔值

返回：

真 或 假。

注意

直接包装 MuPDF 代码的文本提取选项“xml”，“xhtml”和“html”不受此影响。

set_subset_fontnames(on=None)

• 新版本 v1.18.9 中

控制文本提取中子集字体名称标签的抑制。

参数：

on (bool) – 如果省略 / None，则返回当前设置。评估为 True 或 False 的参数设置一个全局变量。如果为 True，选项“dict”，“json”，“rawdict”和“rawjson”将返回例如 "NOHSJV+Calibri-Light"，否则仅返回 "Calibri-Light"（默认值）。设置保持有效直到再次更改。

返回类型：

布尔值

返回：

真 或 假。

注意

除了上述提到的情况外，没有其他文本提取变体受到影响。对于基于 MuPDF 代码的选项“xml”，“xhtml”和“html”，特别是如此。它们提取字体名称"Calibri-Light"，甚至只提取family名称 - 在本例中是Calibri。

unset_quad_corrections(on=None)

• 新版本 v1.18.10 中

启用/禁用 PyMuPDF 特定代码，当在Page.get_text()文本提取中遇到无意义的内容时，尝试重建有效的字符四边形。这段代码依赖于某些字体属性（ascender 和 descender），这些属性在某些情况下不存在，并在试图访问它们时导致分段错误。此方法在 PyMuPDF 中设置一个全局参数，该参数抑制此代码的执行。

参数：

on (bool) – 如果省略或为 None，则返回当前设置。对于其他值，将应用 bool() 函数以设置全局变量。如果为 True，PyMuPDF 将不尝试访问相应的字体属性，并使用值 ascender=0.8 和 descender=-0.2。

返回类型：

布尔值

返回：

真 或 假。

store_shrink(percent)

通过其当前大小的百分比减少可存储的高速缓存。

参数：

percent (int) – 当前大小的百分比以释放。如果是 100+，存储将被清空；如果为零，则不会发生任何操作。MuPDF 的缓存策略是“最近最少使用”，因此低使用率的元素首先被删除。

返回类型：

整数

返回：

新的当前存储大小。根据情况，大小减小可能大于请求的百分比。

show_aa_level()

• 版本 1.16.14 中的新功能

返回当前抗锯齿值。这些值控制图形和文本元素的呈现质量。

返回类型：

字典

返回类型：

一个字典，初始内容如下：{'graphics': 8, 'text': 8, 'graphics_min_line_width': 0.0}。

set_aa_level(level)

• 版本 1.16.14 中的新功能

设置用于抗锯齿的新位数。目前图形和文本渲染使用相同的值。这可能会在未来的 MuPDF 发布中更改。

参数：

level (int) – 一个介于 0 和 8 之间的整数。超出此范围的值将被静默更改为有效值。该值将在当前会话中或下次更改之前保持有效。

reset_mupdf_warnings()

• 版本 1.16.0 中的新功能

清空 MuPDF 警告消息缓冲区。

mupdf_display_errors(value=None)

• 版本 1.16.8 中的新功能

显示或设置是否应显示 MuPDF 错误。

参数：

value (bool) – 如果不是布尔值，则返回当前设置。如果为真，则在 sys.stderr 上显示 MuPDF 错误，否则将其抑制。无论如何，消息继续存储在警告存储中。在导入 PyMuPDF 时，此值为 True。

返回：

True 或 False

mupdf_warnings(reset=True)

• 版本 1.16.0 中的新功能

返回所有存储的 MuPDF 消息作为带有插入换行符的字符串。

参数：

reset (bool) – (1.16.7 版本中的新功能) 是否自动清空存储。

fitz_config

包含用于配置 PyMuPDF 和 MuPDF 的实际值的字典。还请参阅安装章节。这是一个概述键的字典，每个键描述一个支持方面的状态。

Key	支持包括 …
plotter-g	灰度色彩空间渲染
plotter-rgb	RGB 色彩空间渲染
plotter-cmyk	CMYK 色彩空间渲染
plotter-n	印刷过渡渲染
pdf	PDF 文档
xps	XPS 文档
svg	SVG 文档
cbz	CBZ 文档
img	IMG 文档
html	HTML 文档
epub	EPUB 文档
jpx	JPEG2000 图像
js	JavaScript
tofu	所有 TOFU 字体
tofu-cjk	CJK 字体子集（中国，日本，韩国）
tofu-cjk-ext	CJK 字体扩展
tofu-cjk-lang	CJK 字体语言扩展
tofu-emoji	TOFU 表情符号字体
tofu-historic	TOFU 历史字体
tofu-symbol	TOFU 符号字体
tofu-sil	TOFU SIL 字体
icc	ICC 配置文件
py-memory	使用 Python 内存管理 [2]
base14	Base-14 字体（应始终为真）

有关“TOFU”术语的解释，请参见此维基百科文章：

In [1]: import pymupdf
In [2]: TOOLS.fitz_config
Out[2]:
{'plotter-g': True,
 'plotter-rgb': True,
 'plotter-cmyk': True,
 'plotter-n': True,
 'pdf': True,
 'xps': True,
 'svg': True,
 'cbz': True,
 'img': True,
 'html': True,
 'epub': True,
 'jpx': True,
 'js': True,
 'tofu': False,
 'tofu-cjk': True,
 'tofu-cjk-ext': False,
 'tofu-cjk-lang': False,
 'tofu-emoji': False,
 'tofu-historic': False,
 'tofu-symbol': False,
 'tofu-sil': False,
 'icc': True,
 'py-memory': False,
 'base14': True} 

返回类型：

字典

store_maxsize

最大存储缓存大小（以字节为单位）。PyMuPDF生成的默认值为 268’435’456（256 MB），因此您应该始终在这里看到此值。如果此值为零，则允许“无限”增长。

返回类型：

整数

store_size

当前存储缓存大小（以字节为单位）。这个值可能会随着每次使用PyMuPDF函数而改变（通常会增加）。只有当将要超过Tools.store_maxsize时，它才会（自动）减少：在这种情况下，MuPDF会逐出低使用对象，直到值再次在范围内。

返回类型：

整数

示例会话

>>> import pymupdf
# print the maximum and current cache sizes
>>> pymupdf.TOOLS.store_maxsize
268435456
>>> pymupdf.TOOLS.store_size
0
>>> doc = pymupdf.open("demo1.pdf")
# pixmap creation puts lots of object in cache (text, images, fonts),
# apart from the pixmap itself
>>> pix = doc[0].get_pixmap(alpha=False)
>>> pymupdf.TOOLS.store_size
454519
# release (at least) 50% of the storage
>>> pymupdf.TOOLS.store_shrink(50)
13471
>>> pymupdf.TOOLS.store_size
13471
# get a few unique numbers
>>> pymupdf.TOOLS.gen_id()
1
>>> pymupdf.TOOLS.gen_id()
2
>>> pymupdf.TOOLS.gen_id()
3
# close document and see how much cache is still in use
>>> doc.close()
>>> pymupdf.TOOLS.store_size
0
>>> 

脚注

您对本页面有任何反馈吗？

---

本软件按原样提供，不附带任何明示或暗示的担保。本软件根据许可证分发，未经许可不得复制、修改或分发。请参阅artifex.com获取许可信息，或联系位于美国加利福尼亚州圣弗朗西斯科 94129 Mesa 街 39 号 108A 套房的 Artifex Software Inc.获取更多信息。

此文档涵盖所有版本直至 1.24.4。

示例会话

>>> import pymupdf
# print the maximum and current cache sizes
>>> pymupdf.TOOLS.store_maxsize
268435456
>>> pymupdf.TOOLS.store_size
0
>>> doc = pymupdf.open("demo1.pdf")
# pixmap creation puts lots of object in cache (text, images, fonts),
# apart from the pixmap itself
>>> pix = doc[0].get_pixmap(alpha=False)
>>> pymupdf.TOOLS.store_size
454519
# release (at least) 50% of the storage
>>> pymupdf.TOOLS.store_shrink(50)
13471
>>> pymupdf.TOOLS.store_size
13471
# get a few unique numbers
>>> pymupdf.TOOLS.gen_id()
1
>>> pymupdf.TOOLS.gen_id()
2
>>> pymupdf.TOOLS.gen_id()
3
# close document and see how much cache is still in use
>>> doc.close()
>>> pymupdf.TOOLS.store_size
0
>>> 

脚注

您对本页面有任何反馈吗？

---

本软件按原样提供，不附带任何明示或暗示的担保。本软件根据许可证分发，未经许可不得复制、修改或分发。请参阅artifex.com获取许可信息，或联系位于美国加利福尼亚州圣弗朗西斯科 94129 Mesa 街 39 号 108A 套房的 Artifex Software Inc.获取更多信息。

此文档涵盖所有版本直至 1.24.4。