函数#

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

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

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

函数	简短描述
`Annot.apn_bbox`	仅限 PDF: 外观对象的 bbox（边界框）
`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: 设置外观对象的 bbox（边界框）
`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()`	从 sRGB 整数返回 (R, G, B) 颜色元组
`unicode_to_glyph_name()`	从 unicode 返回字形名称
`get_tessdata()`	定位 Tesseract-OCR 安装的语言支持文件
`colors_pdf_dict()`	返回颜色名称的字典。
`colors_wx_list()`	返回颜色名称的列表。
`fitz_fontdescriptors`	可用补充字体的字典
`PYMUPDF_MESSAGE`	PyMuPDF 消息的输出目标。
`pdfcolor`	包含近 500 个 PDF 格式 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”（纵向）后缀。没有后缀时默认为纵向。

参数:

s (str) – 上述任何格式名称，不区分大小写，例如 "A4" 或 "letter-l"。

返回类型:

tuple

返回值:

纸张格式的 (width, height)。对于未知格式，返回 (-1, -1)。示例: pymupdf.paper_size("A4") 返回 (595, 842)，pymupdf.paper_size("letter-l") 返回 (792, 612)。

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

参数:

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

返回类型:

Rect

返回值:

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* 参数。

参数:

text (str) – 目标文本规范；详情请参阅环境变量 PYMUPDF_MESSAGE 的描述。

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

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

path (str) – 写入文件。

path_append (str) – 追加写入文件。

pylogging – 写入 Python 的 logging 系统。

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

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

pylogging_name (str) – 使用指定的 logger 名称写入 Python 的 logging 系统。仅在 pylogging_logger 为 None 时使用。默认为 pymupdf。

如果任何 pylogging* 参数不为 None，我们将写入 Python 的日志记录系统。

sRGB_to_pdf(srgb)#

v1.17.4 新增

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

参数:

srgb (int) – RRGGBB 格式的整数，其中每个颜色分量是 range(255) 中的一个整数。

返回值:

一个元组 (red, green, blue)，包含在 0 <= item <= 1 区间的浮点项，表示相同的颜色。示例：sRGB_to_pdf(0xff0000) = (1, 0, 0)（红色）。

sRGB_to_rgb(srgb)#

v1.17.4 新增

方便函数，返回给定 sRGB 颜色整数的颜色（红、绿、蓝）。

参数:

srgb (int) – RRGGBB 格式的整数，其中每个颜色分量是 range(255) 中的一个整数。

返回值:

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

glyph_name_to_unicode(name)#

v1.18.0 新增

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

参数:

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

返回类型:

int

返回值:

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

注意

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

unicode_to_glyph_name(ch)#

v1.18.0 新增

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

参数:

ch (int) –
例如通过 ord("ß") 给定的 unicode。该函数基于 Adobe Glyph List。

返回类型:

str

返回值:

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

注意

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

adobe_glyph_names()#

v1.18.0 新增

返回在 Adobe Glyph List 中定义的字形名称列表。

返回类型:

list

返回值:

字符串列表。

注意

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

adobe_glyph_unicodes()#

v1.18.0 新增

返回在 Adobe Glyph List 中存在字形名称的 unicode 列表。

返回类型:

list

返回值:

整数列表。

注意

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

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

用于“Story”应用的实用函数。

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

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

例如，字体代码“notos”指代以下字体:

“notos” - “Noto Sans Regular”

“notosit” - “Noto Sans Italic”

“notosbo” - “Noto Sans Bold”

“notosbi” - “Noto Sans Bold Italic”

该函数创建（最多）四个 CSS @font-face 定义，并将其 font-family 名称统一设置为“notos”（或如果提供了“name”值则使用该值）。相关的字体缓冲区被放置/添加到提供的 archive 中。

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

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

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

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

参数:

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

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

archive – Archive，强制。为“fontcode”找到的所有字体二进制文件（即最多四个）都将添加到 archive 中。这是创建 Story 时必须用作 Archive 的 archive。

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

返回类型:

str

返回值:

修改后的 CSS，附加了 fontcode 每种字体变体的 @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 项。每个子矩形都可以通过其行和列索引进行寻址。

参数:

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

cols (int) – 所需的列数。

rows (int) – 所需的行数。

返回值:

一个由大小相等的 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) 距离相同的点。
参数:

p1 (point_like) – 线段的起点。

p2 (point_like) – 线段的终点。

返回类型:

Matrix

返回值:
一个结合了旋转和平移的矩阵
>>> p1 = pymupdf.Point(1, 1)
>>> p2 = pymupdf.Point(4, 5)
>>> abs(p2 - p1)  # distance of points
5.0
>>> m = pymupdf.planish_line(p1, p2)
>>> p1 * m
Point(0.0, 0.0)
>>> p2 * m
Point(5.0, -5.960464477539063e-08)
>>> # distance of the resulting points
>>> 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#

如果在导入 PyMuPDF 时存在于 os.environ 中，则设置 PyMuPDF 消息的输出目标。否则，消息将发送到 sys.stdout。

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

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

如果值以 path: 开头，则剩余文本为文件的路径，消息将写入其中。如果文件已存在，则会被截断。

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

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

level= 设置日志级别。

name= 设置 logger 名称（默认为 pymupdf）。

其他项被忽略。

其他前缀将导致错误。

另请参阅 set_messages()。

pdfcolor#

v1.19.6 新增

包含约 500 个 PDF 格式的 RGB 颜色，以颜色名称为键。要查看其中内容，显然可以查看 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’ 表示本地时间 2017 年 5 月 1 日 12:15:25，位于 UTC 子午线西侧 4 小时时区。

返回类型:

str

返回值:

当前本地 PDF 时间戳。

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

版本 1.14.7 新增

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

参数:

text (str) – 文本字符串。

fontname (str) – 字体名称。必须是 PDF Base 14 字体或 CJK 字体之一，通过其“保留”字体名称标识（参见 Page.insert_font() 中的表格）。

fontsize (float) – fontsize。

encoding (int) – 要使用的编码。除了 0 = Latin，还有 1 = Greek 和 2 = Cyrillic (Russian) 可用。仅与 Base-14 字体“Helvetica”、“Courier”和“Times”及其变体相关。请确保与相应的文本插入中使用相同的值。

返回类型:

float

返回值:

字符串将具有的点长度（例如在 Page.insert_text() 中使用时）。

注意

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

注意

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

警告

如果您使用此函数确定 (Page 或 Shape) 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 兼容字符串：如果文本包含 code points ord(c) > 255，则将其转换为带 BOM 的 UTF-16BE 十六进制字符串，用“<>”括起来，如。否则，它将返回用（圆）括号括起来的字符串，将 ASCII 范围外的任何字符替换为某个特殊代码。此外，每个“(”、“)”或反斜杠都会用反斜杠转义。

参数:

text (str) – 要转换的对象

返回类型:

str

返回值:

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

image_profile(stream)#
v1.16.7 新增

v1.19.5 变更: 如果存在 EXIF 数据，也返回从中提取的自然图像方向。

v1.22.5 变更: 错误情况下总是返回 None，而不是空字典。

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

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

返回类型:

dict

返回值:
不会引发任何异常。如果发生错误，返回 None。否则，包含以下项：
In [2]: pymupdf.image_profile(open("nur-ruhig.jpg", "rb").read())
Out[2]:
{'width': 439,
'height': 501,
'orientation': 0,  # natural orientation (from EXIF)
'transform': (1.0, 0.0, 0.0, 1.0, 0.0, 0.0),  # orientation matrix
'xres': 96,
'yres': 96,
'colorspace': 3,
'bpc': 8,
'ext': 'jpeg',
'cs-name': 'DeviceRGB'}
与 orientation 中编码的 **Exif** 信息以及相应的 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) 创建 pixmap。这些方法在返回结果之前会自动将特殊图像转换为 PNG 格式。

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

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

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

返回将页面文本输出组成有效文档所需的头部字符串。

参数:

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

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

返回类型:

str

ConversionTrailer(output)#

返回将页面文本输出组成有效文档所需的尾部字符串。参见 Page.get_text() 获取示例。

参数:

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

返回类型:

str

Document.del_xml_metadata()#

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

Document.xml_metadata_xref()#

如果存在 XML 元数据 xref，则返回该 xref – 也可参阅 Document.del_xml_metadata()。您可以使用它通过 Document.xref_stream() 检索内容，然后使用某些 XML 软件进行处理。

返回类型:

int

返回值:

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

Page.run(dev, transform)#

通过设备运行页面。

参数:

dev (Device) – Device 对象，通过 Device 构造函数之一获得。

transform (Matrix) – 应用于页面的变换。如果不希望进行变换，请将其设置为 Identity。

Page.get_bboxlog(layers=False)#

v1.19.0 新增

v1.22.0 变更: 可选择返回适用于边界框的 OCG 名称。

返回值:

包围文本、图像或绘图对象的矩形列表。每个项是一个元组 (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 与前一个项的 bbox 相交或包含前一个项的 bbox，则前一个项可能会被（部分）覆盖/隐藏。

因此，此列表可用于检测此类情况。此列表中项的索引等于 Page.get_drawings() 和 Page.get_texttrace() 返回的字典中 "seqno" 的值。

Page.get_texttrace()#
v1.18.16 新增

v1.19.0 变更: 添加了键“seqno”。

v1.19.1 变更: 描边和填充颜色现在总是 RGB 或 GRAY

v1.19.3 变更: 如果 dir != (1, 0)，跨度和字符的 bbox 也正确。

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 值永远不会包含 superscript 标志位：上标的检测是在 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 创建的。对于这种情况，没有等效的跨度类型。相反，相应的文本由两个连续的跨度表示 – 除了它们的类型分别是 0 和 1 之外，它们在所有其他方面都相同。您有责任处理这种情况 - 在 Page.get_text() 中，MuPDF 会为您处理。

为了数据紧凑性，此处提供了字符的 unicode 编号。使用内置函数 chr() 获取字符本身。

跨度文本的 alpha / 不透明度值，0 <= opacity <= 1，0 表示不可见文本，1 (100%) 表示完全不透明。根据 span["type"]，将此值分别解释为填充不透明度或描边不透明度。

（v1.19.0 变更）此值等于或接近“rawdict”中 char["bbox"] 的值。特别是，bbox 的高度值总是按请求“小字形高度”计算的。

（v1.19.0 新增）这是所有字符 bbox 的并集。

（v1.19.0 新增）枚举构成页面外观的命令。可用于确定文本是否被“稍后”绘制的对象或某些对象有效隐藏。因此，如果存在具有更高序列号的绘图或图像，其 bbox 与此文本跨度的（部分）重叠，则可以假定此类对象隐藏了相应的文本。如果不同的文本跨度是一次性创建的，则它们的序列号相同。

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

以下是 page.get_texttrace() 与 page.get_text("rawdict") 相比的异同点列表：
与“rawdict”提取相比，该方法**速度快达两倍**。取决于文本量。

返回的数据**大小显著减小** – 尽管提供了更多信息。

可以**检测到**额外的文本**不可见性类型**：opacity = 0 或 type > 1 或与具有更高序列号对象的 bbox 重叠。

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

span["chars"] **不包含空格**，**除非**文档创建者显式编码了它们。它们**永远不会被生成**，不像 Page.get_text() 方法那样。为了帮助您在此处进行自己的计算，提供了空格字符的宽度。此值尽可能从字体中获取。否则，取回退字体的值。

不像 TextPage 那样对文本进行组织（块、行、跨度和字符的层次结构）。字符只是按顺序一个接一个地提取，并放入一个跨度中。只要跨度的任何特征发生变化，就会开始一个新的跨度。因此，您可能会在同一个跨度中找到 origin.y 值不同的字符（这意味着它们会出现在不同的行中）。您不能假设跨度中的字符按任何特定顺序排序 – 您必须自己理解这些信息，同时考虑 span["dir"]、span["wmode"] 等。
连字（Ligatures）表示如下：
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!
这意味着第一个连字字符的 bbox 是包含完整、复合字形的区域。随后的连字组件可通过其字形值 -1 和宽度为零的 bbox 来识别。

您可能希望将这些 2 或 3 个字符的元组替换为一个代表连字本身的元组。使用以下连字到 unicode 的映射：

"ff" -> 0xFB00

"fi" -> 0xFB01

"fl" -> 0xFB02

"ffi" -> 0xFB03

"ffl" -> 0xFB04

"ft" -> 0xFB05

"st" -> 0xFB06

因此，您可能希望将上面的两个示例元组替换为以下单个元组：(0xFB01, glyph, (x, y), (x0, y0, x1, y1))（通常无需在相应字体中查找 0xFB01 的正确字形 ID，但您可以执行 font.has_glyph(0xFB01) 并使用其返回值）。
v1.19.3 变更: 与其他文本提取方法类似，字符和跨度的 bbox 包围了字符的 quads。要恢复 quads，请遵循 Structure of Dictionary Outputs 中解释的相同方法 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+）中，此检查和相应的调整会自动执行 – 因此您无需再担心此问题。

返回类型:

bool

Page.get_text_blocks(flags=None)#

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

返回类型:

list[tuple]

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

TextPage.extractWORDS() 的已弃用包装器。请改用 Page.get_text() 并带上“words”选项。

返回类型:

list[tuple]

Page.get_displaylist()#

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

返回类型:

DisplayList

返回值:

页面的显示列表。

Page.get_contents()#

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

返回类型:

list[int]

Page.set_contents(xref)#

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

Page.clean_contents(sanitize=True)#

v1.17.6 变更

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

版本 1.16.0 变更注释不再被此方法隐式清理。请单独使用 Annot.clean_contents()。

参数:

sanitize (bool) – （v1.17.6 新增）如果为 true，则同步 resources 及其在 contents 对象中的实际使用。例如，如果某个字体实际上未用于页面的任何文本，则将从 /Resources/Font 对象中删除该字体。

警告

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

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

Page.read_contents()#

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

返回类型:

bytes

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() 中自动调用。因此，您很少需要自己执行此操作。

参数:

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

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

返回类型:

list

返回值:

一个包含 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。

参数:

xref (int) – xref 编号。

返回值:

如果对象定义后跟着由关键字对 stream, endstream 包围的数据，则为 True。

Document.get_new_xref()#

将 xref 增加一个条目并返回该编号。然后可以使用此编号插入新对象。

返回类型:

int :返回: 新 xref 条目的编号。请注意，这只会在 PDF 的交叉引用表中创建一个新条目。此时，尚未有与该编号关联的 PDF 对象。要使用此编号创建（空）对象，请使用 doc.update_xref(xref, "<<>>")。

Document.xref_length()#

返回 xref 表的长度。

返回类型:

int

返回值:

xref 表中的条目数量。

recover_quad(line_dir, span)#

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

参数:

line_dir (tuple) – 所属行的 line["dir"]。对于从 Page.get_texttrace() 获取的跨度，使用 None。

span (dict) – 跨度。

返回值:

跨度的 Quad，可用于文本标记注释（如“Highlight”等）。

recover_char_quad(line_dir, span, char)#

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

参数:

line_dir (tuple) – 所属行的 line["dir"]。对于从 Page.get_texttrace() 获取的跨度，使用 None。

span (dict) – 跨度。

char (dict) – 字符。

返回值:

字符的 Quad，可用于文本标记注释（如“Highlight”等）。

recover_span_quad(line_dir, span, chars=None)#

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

参数:

line_dir (tuple) – 所属行的 line["dir"]。对于从 Page.get_texttrace() 获取的跨度，使用 None。

span (dict) – 跨度。

chars (list) – 要考虑的字符。如果提供了此参数，则选择的提取选项必须是“rawdict”。

返回值:

选定字符的 Quad，可用于文本标记注释（如“Highlight”等）。

recover_line_quad(line, spans=None)#

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

参数:

line (dict) – 行。

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

返回值:

选定行跨度的 Quad，可用于文本标记注释（如“Highlight”等）。

get_tessdata(tessdata=None)#

检测 Tesseract 语言支持文件夹。

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

如果设置了 <tessdata>，我们直接返回它。

否则，如果设置了 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") 字典中的空边界框。然而，存在无限多的空矩形或无效矩形。

colors_pdf_dict()#

返回一个字典，将小写颜色名称映射到 (red, green, blue) 元组，其中 red、green、blue 是范围在 0..1 的浮点数。

colors_wx_list()#

返回一个 (colorname, red, green, blue) 元组列表，其中 colorname 为大写，red、green、blue 为范围在 0..255 的整数。

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