函数#

以下是一些杂项函数和属性，涉及相当低层次的技术细节。

一些函数提供对PDF结构的详细访问。其他函数则是其他提供更多信息函数的精简、高性能版本。

还有一些是方便的通用工具。

函数	简短描述
`Annot.apn_bbox`	仅限PDF：外观对象的边界框
`Annot.apn_matrix`	仅限PDF：外观对象的矩阵
`Page.is_wrapped`	检查内容是否存在换行
`adobe_glyph_names()`	在 Adobe Glyph List 中定义的字形名称列表
`adobe_glyph_unicodes()`	在 Adobe Glyph List 中定义的 unicode 列表
`Annot.clean_contents()`	仅限PDF：清理注释的 `contents` 对象
`Annot.set_apn_bbox()`	仅限PDF：设置外观对象的边界框
`Annot.set_apn_matrix()`	仅限PDF：设置外观对象的矩阵
`ConversionHeader()`	返回get_text方法的头部字符串
`ConversionTrailer()`	返回get_text方法的尾部字符串
`Document.del_xml_metadata()`	仅限PDF：移除XML元数据
`Document.get_char_widths()`	仅限PDF：返回字体的字符宽度列表
`Document.get_new_xref()`	仅限PDF：创建并返回一个新的 `xref` 条目
`Document.is_stream()`	仅限PDF：检查一个`xref`是否为流对象
`Document.xml_metadata_xref()`	仅限PDF: 返回XML元数据 `xref` 编号
`Document.xref_length()`	仅限PDF: 返回`xref` 表的长度
`EMPTY_IRECT()`	返回（标准）空/无效矩形
`EMPTY_QUAD()`	返回（标准）空的/无效的四元组
`EMPTY_RECT()`	返回（标准）空白/无效矩形
`get_pdf_now()`	返回当前时间戳，以PDF格式显示
`get_pdf_str()`	返回PDF兼容字符串
`get_text_length()`	返回给定字体和 `fontsize` 的字符串长度
`glyph_name_to_unicode()`	从字形名称返回unicode
`image_profile()`	返回一个基本图像属性的字典
`INFINITE_IRECT()`	返回（唯一存在的）无限矩形
`INFINITE_QUAD()`	返回（唯一存在的）无限四边形
`INFINITE_RECT()`	返回（唯一存在的）无限矩形
`make_table()`	将矩形拆分为子矩形
`Page.clean_contents()`	仅限PDF：清理页面的 `contents` 对象
`Page.get_bboxlog()`	包含文本、绘图或图像对象的矩形列表
`Page.get_contents()`	仅限PDF：返回内容`xref`编号的列表
`Page.get_displaylist()`	创建页面的显示列表
`Page.get_text_blocks()`	提取文本块作为Python列表
`Page.get_text_words()`	提取文本单词作为Python列表
`Page.get_texttrace()`	低级文本信息
`Page.read_contents()`	仅限PDF：获取完整的、连接的 /Contents 源
`Page.run()`	通过设备运行一个页面
`Page.set_contents()`	仅限PDF：将页面的 `contents` 设置为某些 `xref`
`Page.wrap_contents()`	用堆叠命令包装内容
`css_for_pymupdf_font()`	为包pymupdf_fonts中的字体创建CSS源
`paper_rect()`	返回已知纸张格式的矩形
`paper_size()`	返回已知纸张格式的宽度和高度
`paper_sizes()`	预定义纸张格式的字典
`planish_line()`	矩阵用于将一条线映射到x轴
`recover_char_quad()`	计算字符的四元组（“rawdict”）
`recover_line_quad()`	计算一部分行跨度的四元数
`recover_quad()`	计算一个跨度的四重态（“dict”，“rawdict”）
`recover_span_quad()`	计算一部分跨度字符的四分之一
`set_messages()`	设置PyMuPDF消息的目标。
`sRGB_to_pdf()`	从sRGB整数返回PDF RGB颜色元组
`sRGB_to_rgb()`	返回 (R, G, B) 颜色元组，从 sRGB 整数
`unicode_to_glyph_name()`	从unicode返回字形名称
`get_tessdata()`	定位Tesseract-OCR安装的语言支持
`fitz_fontdescriptors`	可用补充字体的字典
`PYMUPDF_MESSAGE`	PyMuPDF 消息的目的地。
`pdfcolor`	在PDF格式中几乎包含500个RGB颜色的字典。

paper_size(s)#

便利函数用于返回已知纸张格式代码的宽度和高度。这些值以像素为单位，标准分辨率为72像素 = 1英寸。

当前定义的格式包括 ‘A0’ 到 ‘A10’、‘B0’ 到 ‘B10’、‘C0’ 到 ‘C10’、‘Card-4x6’、‘Card-5x7’、‘Commercial’、‘Executive’、‘Invoice’、‘Ledger’、‘Legal’、‘Legal-13’、‘Letter’、‘Monarch’ 和 ‘Tabloid-Extra’，每种格式都可以选择纵向或横向。

格式名称必须作为字符串提供（不区分大小写），可选地以“-L”（横向）或“-P”（纵向）作为后缀。没有后缀默认为纵向。

Parameters:

s (str) – 上述任何格式名，可以是大写或小写，例如 “A4” 或 “letter-l”。

Return type:

元组

Returns:

纸张格式的(width, height)。对于未知格式，返回(-1, -1)。例子：pymupdf.paper_size(“A4”) 返回 (595, 842) 和 pymupdf.paper_size(“letter-l”) 返回 (792, 612)。

paper_rect(s)#
方便的函数，用于返回已知纸张格式的Rect。

Parameters:

s (str) – 由 paper_size() 支持的任何格式名称。

Return type:

矩形

Returns:

pymupdf.Rect(0, 0, width, height) 与 width, height=pymupdf.paper_size(s)。
>>> import pymupdf
>>> pymupdf.paper_rect("letter-l")
pymupdf.Rect(0.0, 0.0, 792.0, 612.0)
>>>

set_messages(*, text=None, fd=None, stream=None, path=None, path_append=None, pylogging=None, pylogging_logger=None, pylogging_level=None, pylogging_name=None)#

将PyMuPDF 消息的目标设置为文件描述符、文件、现有流或Python 的日志系统。

通常只会设置一个参数，或一个或多个 pylogging* 参数。

Parameters:

文本 (str) – 目的地的文本规范；有关详细信息，请参见环境变量 PYMUPDF_MESSAGE 的描述。

fd (int) – 写入文件描述符。

stream – 写入已存在的流，该流必须具有方法 .write(text) 和 .flush()。

路径 (字符串) – 写入文件。

path_append (str) – 附加到文件中。

pylogging – 写入Python的 logging 系统。

pylogging_logger (logging.Logger) – 使用指定的 Logger 写入 Python 的 logging 系统。

pylogging_level (int) – 使用指定级别写入Python的 logging 系统。

pylogging_name (str) – 使用指定的日志记录器名称向Python的 logging 系统写入信息。
只有在 pylogging_logger 为 None 时使用。默认值是 pymupdf。

如果任何 pylogging* 参数不是 None，我们会写入 Python 的日志系统。

sRGB_to_pdf(srgb)#

v1.17.4中新功能

便利函数返回给定sRGB颜色整数的PDF颜色三元组（红、绿、蓝），该颜色整数出现在Page.get_text()字典“dict”和“rawdict”中。

Parameters:

srgb (int) – 一种格式为 RRGGBB 的整数，其中每个颜色组件都是范围在(255)内的整数。

Returns:

一个包含浮点项的元组（红色，绿色，蓝色），其值在区间0 <= item <= 1内，表示相同的颜色。示例sRGB_to_pdf(0xff0000) = (1, 0, 0)（红色）。

sRGB_to_rgb(srgb)#

v1.17.4中新功能

一个便捷函数，用于返回给定sRGB颜色整数的颜色（红色、绿色、蓝色）。

Parameters:

srgb (int) – 格式为 RRGGBB 的整数，其中每个颜色分量是范围在 (255) 之间的整数。

Returns:

一个包含整数项的元组 (red, green, blue)，其值在 range(256) 之间，表示相同的颜色。示例 sRGB_to_pdf(0xff0000) = (255, 0, 0) （红色）。

glyph_name_to_unicode(name)#

v1.18.0中的新功能

根据Adobe Glyph List返回一个字形名称的unicode编号。

Parameters:

name (str) – 某个字形的名字。该函数基于 Adobe Glyph List。

Return type:

整型

Returns:

unicode。无效的 name 条目返回 0xfffd (65533)。

注意

相似的功能由包 fontTools 在其 agl 子包中提供。

unicode_to_glyph_name(ch)#

v1.18.0的新特性

根据Adobe Glyph List返回unicode编号的字形名称。

Parameters:

ch (int) –
由例如 ord("ß") 提供的unicode。该函数基于 Adobe Glyph List。

Return type:

字符串

Returns:

字形名称。比如 pymupdf.unicode_to_glyph_name(ord("Ä")) 返回 'Adieresis'。

注意

包 fontTools 提供了类似的功能：在其 agl 子包中。

adobe_glyph_names()#

v1.18.0中的新功能

返回一个在 Adobe 字形列表 中定义的字形名称列表。

Return type:

列表

Returns:

字符串列表。

注意

相似的功能由包 fontTools 在其 agl 子包中提供。

adobe_glyph_unicodes()#

v1.18.0的新特性

返回一个Unicode列表，表示在Adobe Glyph List中存在一个字形名称。

Return type:

列表

Returns:

整数列表。

注意

相似的功能由包 fontTools 在其 agl 子包中提供。

css_for_pymupdf_font(fontcode, *, CSS=None, archive=None, name=None)#
v1.21.0中新功能

用于“故事”应用程序的实用函数。

为给定的字体代码在 pymupdf-fonts 中创建 CSS @font-face 项。为所有以字符串 “fontcode” 开头的字体创建一个 CSS 字体系列。

包pymupdf-fonts中的字体命名约定是“fontcode”，其中后缀“sf”可以是“”（空）、“it”/“i”、“bo”/“b”或“bi”。因此，这些后缀表示该字体的常规、斜体、粗体或粗斜体变体。

例如，字体代码“notos”指的是字体

“notos” - “Noto Sans Regular”

“notosit” - “诺托无衬线体斜体”

“notosbo” - “诺托无衬线粗体”

“notosbi” - “诺托黑体粗斜体”

该函数创建（最多）四个 CSS @font-face 定义，并将 font-family 名称“notos”集合地分配给它们（或者如果提供了则为“name”值）。相关的字体缓冲区被放置/添加到提供的档案中。

要在故事的Python API中使用该字体，请执行 .set_font(fontcode)（如果给定，则为“name”）。正确的字体粗细或样式将根据需要自动选择。

例如，要用上述的“notos”替换“sans-serif” HTML标准（即 Helvetica），请执行以下操作。每当使用“sans-serif”（无论是显式还是隐式）时，将选择 Noto Sans 字体。

CSS = pymupdf.css_for_pymupdf_font("notos", name="sans-serif", archive=...)

期望并返回CSS源，并附加新的CSS定义。

Parameters:

fontcode (str) – 在包 pymupdf-fonts 中存在的字体代码之一（通常）表示字体系列的常规版本。

CSS (str) – 任何已存在的CSS源，或 None。该函数将其新定义附加到此。这是创建故事时必须使用的字符串 user_css。

归档 – 归档，强制性的。所有找到的字体二进制文件（即最多四个）将被添加到“fontcode”的归档中。这是必须使用的归档，作为归档在创建故事时使用。

name (str) – 字体“fontcode” 应该找到的名称。如果省略，将使用“fontcode”。

Return type:

字符串

Returns:

修改后的 CSS，附加了每种字体变体的 @font-face 语句。与 “fontcode” 关联的字体缓冲区将已添加到 'archive'。该函数将自动找到最多 4 种字体变体。所有 pymupdf-fonts（没有特殊用途，如数学、音乐等）都有常规、粗体、斜体和粗斜体变体。要查看当前可用的字体代码，请检查 pymupdf.fitz_fontdescriptors.keys()。这将显示类似 dict_keys(['cascadia', 'cascadiai', 'cascadiab', 'cascadiabi', 'figbo', 'figo', 'figbi', 'figit', 'fimbo', 'fimo', 'spacembo', 'spacembi', 'spacemit', 'spacemo', 'math', 'music', 'symbol1', 'symbol2', 'notosbo', 'notosbi', 'notosit', 'notos', 'ubuntu', 'ubuntubo', 'ubuntubi', 'ubuntuit', 'ubuntm', 'ubuntmbo', 'ubuntmbi', 'ubuntmit'])。

以下是使用“Noto Sans”字体代替“Helvetica”的完整代码片段：
arch = pymupdf.Archive()
CSS = pymupdf.css_for_pymupdf_font("notos", name="sans-serif", archive=arch)
story = pymupdf.Story(user_css=CSS, archive=arch)

make_table(rect, cols=1, rows=1)#

v1.17.4中新功能

便利函数将矩形划分为相等大小的子矩形。返回一个包含 rows 个列表的列表，每个列表包含 cols 个 Rect 项。每个子矩形可以通过其行和列索引进行访问。

Parameters:

rect (rect_like) – 要分割的矩形。

cols (int) – 所需列数。

rows (int) – 所需的行数。

Returns:

一个大小相等的Rect对象的列表，其并集等于rect。以下是通过cell = pymupdf.make_table(rect, cols=4, rows=3)创建的3x4表格的布局：

planish_line(p1, p2)#
在版本 1.16.2 中的新功能)*

返回一个矩阵，该矩阵将从 p1 到 p2 的线映射到 x 轴，使得 p1 变为 (0,0)，而 p2 成为与 (0,0) 具有相同距离的点。
Parameters:

p1 (point_like) – 线的起始点。

p2 (point_like) – 线的终点。

Return type:

矩阵

Returns:
一个结合了旋转和位移的矩阵：
>>> p1 = pymupdf.Point(1, 1)
>>> p2 = pymupdf.Point(4, 5)
>>> abs(p2 - p1)  # 点的距离
5.0
>>> m = pymupdf.planish_line(p1, p2)
>>> p1 * m
Point(0.0, 0.0)
>>> p2 * m
Point(5.0, -5.960464477539063e-08)
>>> # 结果点的距离
>>> abs(p2 * m - p1 * m)
5.0

paper_sizes()#

一个预定义纸张格式的字典。用作paper_size()的基础。

fitz_fontdescriptors#
在v1.17.5中的新功能

来自库 pymupdf-fonts 的可用字体字典。条目以其保留的字体名称为键，并提供如下信息：
In [2]: pymupdf.fitz_fontdescriptors.keys()
Out[2]: dict_keys(['figbo', 'figo', 'figbi', 'figit', 'fimbo', 'fimo',
'spacembo', 'spacembi', 'spacemit', 'spacemo', 'math', 'music', 'symbol1',
'symbol2'])
In [3]: pymupdf.fitz_fontdescriptors["fimo"]
Out[3]:
{'name': 'Fira Mono Regular',
'size': 125712,
'mono': True,
'bold': False,
'italic': False,
'serif': True,
'glyphs': 1485}
如果 pymupdf-fonts 未安装，字典为空。

字典键可以用来定义一个 Font 例如 font = pymupdf.Font("fimo") – 就像你可以使用内置字体 “Helvetica” 和其他字体一样。

PYMUPDF_MESSAGE#

如果在 os.environ 中导入 PyMuPDF，则设置 PyMuPDF 消息的目的地。否则，消息将发送到 sys.stdout。

如果值以 fd: 开头，则剩余的文本应为一个整数文件描述符，消息将写入该描述符。

例如 PYMUPDF_MESSAGE=fd:2 将消息发送到 stderr。

如果值以 path: 开头，剩余的文本是消息写入的文件路径。如果文件已经存在，它将被截断。

如果值以 path+: 开头，则剩余文本为消息写入的文件路径。如果文件已经存在，我们将输出附加到文件中。

如果值以 logging: 开头，消息将写入 Python 的日志系统。其余文本可以包含以逗号分隔的 name=value 项：

level= 设置日志级别。

name= 设置记录器名称（默认是 pymupdf）。

其他项目被忽略。

其他前缀将导致错误。

另外请参见 set_messages()。

pdfcolor#

v1.19.6中的新内容

包含大约 500 种 RGB 颜色，格式为 PDF，颜色名称作为键。要查看其中的内容，您可以显然查看 pymupdf.pdfcolor.keys()。

示例：

pymupdf.pdfcolor["red"] = (1.0, 0.0, 0.0)

pymupdf.pdfcolor["skyblue"] = (0.5294117647058824, 0.807843137254902, 0.9215686274509803)

pymupdf.pdfcolor["wheat"] = (0.9607843137254902, 0.8705882352941177, 0.7019607843137254)

get_pdf_now()#

方便的函数，用于返回当前本地时间戳的PDF兼容格式，例如 D:20170501121525-04’00’ 表示在UTC子午线向西偏移4小时的时区内，2017年5月1日12:15:25的本地日期时间。

Return type:

字符串

Returns:

当前本地PDF时间戳。

get_text_length(text, fontname='helv', fontsize=11, encoding=TEXT_ENCODING_LATIN)#

在1.14.7版本中的新功能

计算输出文本的长度，使用给定的内置字体、fontsize和编码。

Parameters:

文本 (str) – 文本字符串。

fontname (str) – 字体名称。必须是PDF Base 14 Fonts或CJK字体之一，使用其“保留”字体名称进行识别（请参见Page.insert_font()中的表格）。

fontsize (float) – 字体大小 fontsize。

编码 (int) – 要使用的编码。除了 0 = 拉丁文，1 = 希腊文和 2 = 西里尔字母（俄文）可用。这仅适用于基础14字体“Helvetica”、“Courier”和“Times”及其变体。确保使用与相应文本插入相同的值。

Return type:

浮点数

Returns:

字符串将在点数上具有的长度（例如，当用于 Page.insert_text() 时）。

注意

此函数将仅执行计算 - 不会插入字体或文本。

注意

这个 Font 类提供了一个类似的方法 Font.text_length()，支持 Base-14 字体和任何具有字符映射（CMap，Type 0 字体）的字体。

警告

如果您使用此函数来确定（页面或形状）insert_textbox 方法所需的矩形宽度，请注意它们是在按字符级别进行计算的。由于舍入效应，这通常会导致一个稍大的数字：sum([pymupdf.get_text_length(c) for c in text]) > pymupdf.get_text_length(text)。因此，要么 (1) 做同样的事情，或者 (2) 使用类似pymupdf.get_text_length(text + “’”)的计算。

get_pdf_str(text)#

制作一个PDF兼容的字符串：如果文本包含字符代码 ord(c) > 255，则将其转换为带BOM的UTF-16BE，以十六进制字符字符串的形式括在“<>”中，例如。否则，它将返回括在（圆）括号中的字符串，将任何超出ASCII范围的字符替换为某些特殊代码。此外，每个“(”、“)”或反斜杠都用反斜杠转义。

Parameters:

文本 (str) – 要转换的对象

Return type:

字符串

Returns:

用()或<>括起来的PDF兼容字符串。

image_profile(stream)#
v1.16.7 新功能

在 v1.19.5 中更改：如果存在，还将返回从 EXIF 数据中提取的自然图像方向。

在 v1.22.5 中发生更改：在错误情况下始终返回 None，而不是空字典。

显示作为内存区域提供的图像的重要属性。它的主要目的是避免仅仅为了确定这些属性而使用其他Python包。
Parameters:

stream (bytes|bytearray|BytesIO|file) – 可以是内存中的图像或一个已打开的文件。内存中的图像可以是任何格式 bytes, bytearray 或 io.BytesIO。

Return type:

字典

Returns:
永远不会引发异常。如果发生错误，将返回 None。否则，有以下项目：
在 [2]: pymupdf.image_profile(open("nur-ruhig.jpg", "rb").read())
输出[2]:
{'width': 439,
'height': 501,
'orientation': 0,  # 自然方向 (来自 EXIF)
'transform': (1.0, 0.0, 0.0, 1.0, 0.0, 0.0),  # 方向矩阵
'xres': 96,
'yres': 96,
'colorspace': 3,
'bpc': 8,
'ext': 'jpeg',
'cs-name': 'DeviceRGB'}
以下是与 Exif 信息在 orientation 中编码的关系，并在 transform 矩阵中相应地表示（引自 MuPDF 文档，ccw = 逆时针）：

未定义

0度逆时针旋转。 (Exif = 1)

90度逆时针旋转。 (Exif = 8)

180度逆时针旋转。 (Exif = 3)

270度逆时针旋转。 (Exif = 6)

在 X 轴翻转。 (Exif = 2)

在 X 轴翻转，然后逆时针旋转 90度。 (Exif = 5)

在 X 轴翻转，然后逆时针旋转 180度。 (Exif = 4)

在 X 轴翻转，然后逆时针旋转 270度。 (Exif = 7)

注意

对于一些“奇特”的图像（传真编码、RAW 格式等），此方法将无效。但是，您仍然可以在 PyMuPDF 中处理这些图像，例如通过使用 Document.extract_image() 或通过 Pixmap(doc, xref) 创建像素图。这些方法会在返回结果之前自动将奇特图像转换为 PNG 格式。

您还可以通过其 xref 获取嵌入 PDF 中图像的属性。在这种情况下，确保提取原始流： pymupdf.image_profile(doc.xref_stream_raw(xref))。

通过使用“dict”或“rawdict”选项的 Page.get_text() 返回的图像块也受支持。

ConversionHeader("text", filename="UNKNOWN")#

返回将页面文本输出转换为有效文档所需的标题字符串。

Parameters:

output (str) – 文档类型。使用与get_text()的输出参数相同的类型。

filename (str) – 可选的任意名称，用于输出类型“json”和“xml”。

Return type:

字符串

ConversionTrailer(output)#

返回将页面文本输出转换为有效文档所需的尾部字符串。请参见 Page.get_text() 了解示例。

Parameters:

输出 (str) – 文档的类型。与get_text()的输出参数相同。

Return type:

字符串

Document.del_xml_metadata()#

从PDF中删除包含基于XML的元数据的对象。 (Py-) MuPDF不支持基于XML的元数据。如果您想确保仅使用传统的元数据字典，请使用此方法。许多第三方PDF程序以XML格式插入自己的元数据，因此可能会覆盖您存储在传统字典中的内容。此方法删除任何此类引用，相应的PDF对象将在文件的下次垃圾回收期间被删除。

Document.xml_metadata_xref()#

如果存在，则返回基于 XML 的元数据 xref 的 PDF - 另请参阅 Document.del_xml_metadata()。您可以使用 Document.xref_stream() 来检索该内容，然后使用一些 XML 软件进行处理。

Return type:

整型

Returns:

xref 的PDF文件级别XML元数据 - 如果不存在则为0。

Page.run(dev, transform)#

通过设备运行一个页面。

Parameters:

dev (设备) – 设备，来自某个设备构造函数。

transform (Matrix) – 应用于页面的转换。如果不需要转换，请将其设置为 Identity。

Page.get_bboxlog(layers=False)#

v1.19.0中的新功能

在 v1.22.0 版本中更改：可选择性地返回适用于边界框的 OCG 名称。

Returns:

一个包含文本、图像或绘图对象的矩形列表。每个项目是一个元组 (type, (x0, y0, x1, y1))，其中第二个元组由矩形坐标组成，type 是以下值之一。如果 layers=True，则有一个第三项包含 OCG 名称或 None： (type, (x0, y0, x1, y1), None).

"fill-text" – 普通文本（没有字符边框的绘制）

"stroke-text" – 仅显示字符边框的文本

"ignore-text" – 不应显示的文本（例如 OCR 文本层使用的文本）

"fill-path" – 填充颜色的绘图（没有边框）

"stroke-path" – 有边框的绘图（没有填充颜色）

"fill-image" – 显示一张图像

"fill-shade" – 显示一个阴影

项目序列表示 这些命令执行的顺序 以构建页面的外观。因此，如果一个项目的 bbox 与前一个项目相交或包含它，则前一个项目可能会被（部分）覆盖/隐藏。

因此，这个列表可以用来检测这种情况。该列表中项目的索引等于 "seqno" 在由 Page.get_drawings() 和 Page.get_texttrace() 返回的字典中的值。

Page.get_texttrace()#
v1.18.16中的新功能

在 v1.19.0 中更改：添加了关键字“seqno”。

在 v1.19.1 中更改：描边和填充颜色现在始终是 RGB 或 GRAY

在 v1.19.3 中更改：如果 dir != (1, 0)，则 span 和字符边框现在也是正确的。

在 v1.22.0 中更改：添加新字典键“layer”。

返回页面的低级文本信息。该方法适用于所有文档类型。结果是一个包含以下内容的Python字典列表：
{
   'ascender': 0.83251953125,          # font ascender (1)
   'bbox': (458.14019775390625,        # span bbox x0 (7)
            749.4671630859375,         # span bbox y0
            467.76458740234375,        # span bbox x1
            757.5071411132812),        # span bbox y1
   'bidi': 0,                          # bidirectional level (1)
   'chars': (                          # char information, tuple[tuple]
               (45,                    # unicode (4)
               16,                     # glyph id (font dependent)
               (458.14019775390625,    # origin.x (1)
               755.3758544921875),     # origin.y (1)
               (458.14019775390625,    # char bbox x0 (6)
               749.4671630859375,      # char bbox y0
               462.9649963378906,      # char bbox x1
               757.5071411132812)),    # char bbox y1
               ( ... ),                # more characters
            ),
   'color': (0.0,),                    # text color, tuple[float] (1)
   'colorspace': 1,                    # number of colorspace components (1)
   'descender': -0.30029296875,        # font descender (1)
   'dir': (1.0, 0.0),                  # writing direction (1)
   'flags': 12,                        # font flags (1)
   'font': 'CourierNewPSMT',           # font name (1)
   'linewidth': 0.4019999980926514,    # current line width value (3)
   'opacity': 1.0,                     # alpha value of the text (5)
   'layer': None,                      # name of Optional Content Group (9)
   'seqno': 246,                       # sequence number (8)
   'size': 8.039999961853027,          # font size (1)
   'spacewidth': 4.824785133358091,    # width of space char
   'type': 0,                          # span type (2)
   'wmode': 0                          # writing mode (1)
}
详情：

标记为“(1)”的信息与TextPage中解释的含义和价值相同。

请注意，字体 flags 的值永远不会包含一个上标标志位：上标的检测是在 MuPDF TextPage 代码中完成的 – 它并不是任何字体的属性。

还要注意，文本 color 编码为通常的浮点元组 0 <= f <= 1 – 而不是 sRGB 格式。根据 span["type"]，将其解释为填充颜色或描边颜色。

有 3 种文本跨度类型：

0: 填充文本 - 相当于PDF文本渲染模式0 (0 Tr，PDF中的默认值)，仅显示每个字符的“内部”。

1：描边文本 – 等同于 1 Tr，仅显示字符的边框。

3: 被忽略的文本 – 相当于 3 Tr (隐藏文本)。

在此上下文中，线宽仅在处理 span["type"] != 0 时重要：它决定了字符边框线的厚度。此值可能与文本数据完全不提供。在这种情况下，生成的值为 fontsize 的 5% (span["size"] * 0,05)。通常，在 PDF 中，"人造" 粗体文本是通过 2 Tr 创建的。对此情况没有等效的 span 类型。相反，相应的文本由两个连续的 spans 表示——在各个方面都相同，除了它们的类型，分别为 0 和 1。处理这种情况是您的责任 - 在 Page.get_text() 中，MuPDF 为您处理这个问题。

为了数据紧凑，这里提供了字符的unicode。使用内置函数 chr() 来获取字符本身。

span文本的透明度值，0 <= opacity <= 1，0表示无文本，1（100%）表示完全不透明。根据span["type"]，将此值解释为填充透明度或描边透明度。

(在 v1.19.0 中更改) 此值等于或接近 char["bbox"] 的 “rawdict”。特别是，bbox 高度值始终计算为如果请求了 “小字形高度” 时的情况。

(v1.19.0 新增) 这是所有字符边界框的联合。

(v1.19.0中的新功能) 列出构建页面外观的命令。可以用来判断文本是否被后绘制的对象有效隐藏，或者在某个对象上方。因此，如果有一个更高序列号的绘图或图像，其边界框与此文本跨度的（部分）重叠，则可以假设这样的对象隐藏了相应的文本。如果不同的文本跨度是在一次操作中创建的，则它们具有相同的序列号。

(v1.22.0新功能) 如果适用，可选内容组（OCG）的名称，或者 None。

这里是 page.get_texttrace() 与 page.get_text("rawdict") 的相似之处和不同之处的列表：
该方法比“rawdict”提取快两倍，这取决于文本的数量。

返回的数据非常 小得多 – 尽管它提供了更多的信息。

其他类型的文本 不可见性可以被检测到：不透明度 = 0 或类型 > 1 或与序列号更高的对象的边界框重叠。

如果MuPDF对无法识别的字符返回unicode 0xFFFD (65533)，你仍然可以从字符的图形ID中推断出所需的信息。

该 span["chars"] 不包含空格，除非文档创建者明确编码了它们。它们 将永远不会被生成，就像在 Page.get_text() 方法中发生的那样。为了帮助您在这里进行自己的计算，提供了一个空格字符的宽度。这个值是从字体中得出的，如果可能的话。否则将取回退字体的值。

没有努力组织文本，就像发生在TextPage上一样（块、行、范围和字符的层次结构）。字符只是一个接一个地顺序提取，并放入一个范围中。每当范围的任何特征发生变化时，便开始一个新的范围。因此，您可能会发现具有不同origin.y值的字符在同一个范围内（这意味着它们将出现在不同的行中）。您不能假定范围字符按任何特定顺序排序-您必须自己理解信息，考虑span["dir"]、span["wmode"]等。
Ligatures are represented like this:
MuPDF 处理以下连字：“fi”、“ff”、“fl”、“ft”、“st”、“ffi”和“ffl”（通常只使用前 3 个）。如果页面包含例如连字“fi”，您会发现以下两个字符项相互紧随其后：
(102, glyph, (x, y), (x0, y0, x1, y1))  # 102 = ord("f")
(105, -1, (x, y), (x0, y0, x0, y1))     # 105 = ord("i"), empty bbox!
这意味着第一个连字字符的边界框是包含完整复合字形的区域。后续的连字组件可以通过它们的字形值 -1 以及宽度为零的边界框来识别。

您可能想用一个表示连字本身的字符元组替换这两个或三个字符的元组。使用以下连字与 Unicode 的映射：

"ff" -> 0xFB00

"fi" -> 0xFB01

"fl" -> 0xFB02

"ffi" -> 0xFB03

"ffl" -> 0xFB04

"ft" -> 0xFB05

"st" -> 0xFB06

所以你可能想用以下单个元组替换上面的两个示例元组： (0xFB01, glyph, (x, y), (x0, y0, x1, y1))（通常不需要在相应的字体中查找0xFB01的正确glyph id，但你可以执行 font.has_glyph(0xFB01) 并使用其返回值）。
在 v1.19.3 中变更： 类似于其他文本提取方法，字符和跨度的边界框包围了字符四边形。要恢复四边形，请按照recover_quad()、recover_char_quad() 或 recover_span_quad() 中解释的方法进行操作，参见字典输出的结构。对于书写方向，请使用 None 或 span["dir"]。

在 v1.21.1 中更改： 如果适用，OCG 的名称显示在 "layer" 中。

Page.wrap_contents()#

确保页面的所谓图形状态是平衡的，并且新的内容可以正确插入。

在 PyMuPDF 的 1.24.1 及更高版本中，该方法得到了改进，并根据需要自动执行，因此您不再需要关注此问题。

我们不鼓励使用 Page.clean_contents() 来实现这一点。

Page.is_wrapped#

指示页面所谓的图形状态是否平衡。如果 False，则在插入新内容时应执行 Page.wrap_contents()（仅在 overlay=True 模式下相关）。在较新的版本（1.24.1+）中，此检查和相应的调整会自动执行 - 因此您不必再担心这个问题。

Return type:

布尔值

Page.get_text_blocks(flags=None)#

已弃用的包装器 TextPage.extractBLOCKS()。请改用 Page.get_text() 和“blocks”选项。

Return type:

列表[元组]

Page.get_text_words(flags=None, delimiters=None)#

已弃用的包装器，用于 TextPage.extractWORDS()。请改用 Page.get_text() 和“words”选项。

Return type:

列表[元组]

Page.get_displaylist()#

通过列表设备运行页面并返回其显示列表。

Return type:

显示列表

Returns:

页面的显示列表。

Page.get_contents()#

仅限PDF：检索页面的xref对象的contents列表。可能为空或包含多个整数。如果页面已被清理（Page.clean_contents()），则最多只会有一个条目。每个/Contents对象的“源”可以通过使用此列表中的一个项，单独通过Document.xref_stream()读取。与此相对，Page.read_contents()方法遍历此列表并将相应的源连接成一个bytes对象。

Return type:

列表[int]

Page.set_contents(xref)#

仅限PDF：让页面的 /Contents 键指向此xref。任何之前使用的内容对象将被忽略，并可以通过垃圾回收移除。

Page.clean_contents(sanitize=True)#

在 v1.17.6 中更改

仅限PDF：清理并连接与此页面关联的所有 contents 对象。“清理”包括语法修正、标准化和内容流的“美化”。如果sanitize为真，contents 和 resources 对象之间的差异也将得到修正。更多详情请参见 Page.get_contents()。

在版本 1.16.0 中更改该方法不再隐式清理注解。请单独使用 Annot.clean_contents()。

Parameters:

sanitize (bool) – (在v1.17.6中新增) 如果为true，则资源与内容对象中实际使用之间的同步是同步的。例如，如果一个字体在页面的任何文本中实际上没有被使用，那么它将从 /Resources/Font 对象中删除。

警告

这是一个复杂的函数，可能会生成大量的新数据并使旧数据失效。不建议与增量保存选项一起使用。还需注意，生成的单例新/Contents对象是未压缩的。因此您应该使用选项“deflate=True, garbage=3”保存到新文件。

不再使用此方法来确保在 PDF 页面上的正确插入。从 PyMuPDF 版本 1.24.2 开始，这将自动处理。

Page.read_contents()#

在版本 1.17.0 中新增。 返回与页面关联的所有 contents 对象的连接 – 不进行清理或其他修改。每当需要完整解析此源而无需担心存在多少个单独的内容对象时，请使用此方法。

Return type:

字节

Annot.clean_contents(sanitize=True)#

清理与该注释相关的 contents 数据流。这是与 Page.clean_contents() 执行的相同类型的操作——只是限制在该注释上。

Document.get_char_widths(xref=0, limit=256)#
返回文档中存在的字体的字符字形及其宽度列表。字体必须通过其PDF交叉引用编号 xref 指定。这个函数会自动从 Page.insert_text() 和 Page.insert_textbox() 调用。因此，您很少需要自己执行此操作。

Parameters:

xref (int) – 嵌入在PDF中的字体的交叉引用号。要找到字体 xref，可以使用例如 doc.get_page_fonts(pno) 的页码 pno，并取返回列表条目的第一个条目。

limit (int) – 限制返回条目的数量。对于仅支持1字节字符的所有字体（所谓的“简单字体”，通过此方法检查），默认值为256。所有 PDF Base 14 Fonts 都是简单字体。

Return type:

列表

Returns:

一个limit元组的列表。每个字符c在这个列表中都有一个索引为ord(c)的条目(g, w)。元组的条目g（整数）是字符的字形ID，而浮点数w是其标准化宽度。某些fontsize的实际宽度可以计算为w * fontsize。对于简单字体，g条目可以安全忽略。在所有其他情况下，g是图形表示c的基础。

这个函数计算一个名为 text 的字符串的像素宽度：
def pixlen(text, widthlist, fontsize):
    try:
        return sum([widthlist[ord(c)] for c in text]) * fontsize
    except IndexError:
        raise ValueError:("max. code point found: %i, increase limit" % ord(max(text)))

Document.is_stream(xref)#

1.14.14 版本中新功能

仅限PDF: 检查由 xref 表示的对象是否是 stream 类型。如果不是PDF，或者数字在有效的xref范围之外，则返回 False。

Parameters:

xref (int) – xref 编号。

Returns:

如果对象定义后面有用关键字对 stream、 endstream 包裹的数据，那么为真。

Document.get_new_xref()#

将xref增加一个条目并返回该数字。然后可以用它来插入一个新对象。

Return type:

int :返回: 新的 xref 项目的数量。请注意，只有在 PDF 的交叉引用表中创建了一个新的条目。在这一点上，尚不存在与之关联的 PDF 对象。要创建一个（空的）对象，使用这个号码请使用 doc.update_xref(xref, "<<>>")。

Document.xref_length()#

返回xref表的长度。

Return type:

整型

Returns:

在 xref 表中的条目数量。

recover_quad(line_dir, span)#

计算通过Page.get_text()的“dict”或“rawdict”选项提取的文本范围的四边形。

Parameters:

line_dir (tuple) – line["dir"] 所属线的方向。使用 None 表示来自 Page.get_texttrace() 的跨度。

span (dict) – 跨度。

Returns:

span的Quad，可用于文本标记注释（‘高亮’等）。

recover_char_quad(line_dir, span, char)#

计算通过Page.get_text()的“rawdict”选项提取的文本字符的四边形。

Parameters:

line_dir (tuple) – line["dir"] 所有者线的方向。使用 None 表示来自 Page.get_texttrace() 的跨度。

跨度 (dict) – 跨度。

char (dict) – 字符。

Returns:

字符的Quad，可用于文本标记注释（‘高亮’等）。

recover_span_quad(line_dir, span, chars=None)#

计算通过Page.get_text()的“rawdict”选项提取的字符子集的四边形。

Parameters:

line_dir (元组) – line["dir"] 所拥有线的方向。对于来自 Page.get_texttrace() 的跨度，请使用 None。

span (dict) – 跨度。

chars (list) – 要考虑的字符。如果给定，所选的提取选项必须是“rawdict”。

Returns:

所选字符的四元组，可用于文本标记注释（‘高亮’等）。

recover_line_quad(line, spans=None)#

计算通过Page.get_text()的“dict”或“rawdict”选项提取的文本行的一部分跨度的四边形。

Parameters:

line (dict) – 该行。

spans (list) – line["spans"] 的子列表。如果省略，将返回整个行四元组。

Returns:

所选行范围的 Quad 可用于文本标记注释（‘高亮’，等）。

get_tessdata(tessdata=None)#

检测Tesseract语言支持文件夹。

此函数用于通过Tesseract启用OCR，即使语言支持文件夹没有直接指定或在环境变量TESSDATA_PREFIX中指定。

如果被设置，我们直接返回它。

否则如果已设置，我们返回 os.environ['TESSDATA_PREFIX']。

否则，我们会搜索Tesseract的安装并返回其语言支持文件夹。

否则我们会引发一个异常。

INFINITE_QUAD()#

INFINITE_RECT()#

INFINITE_IRECT()#

返回（唯一的）无限矩形 Rect(-2147483648.0, -2147483648.0, 2147483520.0, 2147483520.0)，以及 IRect 和 Quad 的对应物。它是可能的最大矩形：所有有效的矩形都包含在其中。

EMPTY_QUAD()#

EMPTY_RECT()#

EMPTY_IRECT()#

返回“标准”的空和无效矩形 Rect(2147483520.0, 2147483520.0, -2147483648.0, -2147483648.0) 或四边形。它的左上角和右下角点值与无限矩形相比是颠倒的。例如，它将用于在 page.get_text("dict") 字典中指示空的边界框。然而，空或无效矩形有无限多个。

Do you have any feedback on this page?

本软件按原样提供，不作任何明示或暗示的担保。该软件根据许可证分发，除非按照该许可证的条款明确授权，否则不得复制、修改或分发。有关许可信息，请参阅artifex.com或联系Artifex Software Inc.，地址：39 Mesa Street, Suite 108A, San Francisco CA 94129, United States以获取更多信息。