PyMuPDF 1.24.4 中文文档（十一）（5）

PyMuPDF 1.24.4 中文文档（十一）（4）https://developer.aliyun.com/article/1559464

功能

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

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

某些功能提供详细访问 PDF 结构的方法。其他是精简版、高性能版的其他功能，提供更多信息。

其他一些是方便的、通用的工具。

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”。

返回类型：

元组

返回：

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

paper_rect(s)

方便函数，返回已知纸张格式的 矩形。

参数：

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

返回类型：

矩形

返回：

pymupdf.Rect(0, 0, 宽度, 高度)，其中 宽度, 高度=pymupdf.paper_size(s)。

>>> import pymupdf
>>> pymupdf.paper_rect("letter-l")
pymupdf.Rect(0.0, 0.0, 792.0, 612.0)
>>> 

sRGB_to_pdf(srgb)

v1.17.4 新增

方便函数，为给定的 sRGB 颜色整数返回 PDF 颜色三元组 (红, 绿, 蓝)，如 Page.get_text() 中的字典 “dict” 和 “rawdict”。

参数：

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

返回：

一个元组 (红, 绿, 蓝)，其中每个项为浮点数，范围在 0 <= item <= 1，表示相同的颜色。例如 sRGB_to_pdf(0xff0000) = (1, 0, 0) (红色)。

sRGB_to_rgb(srgb)

v1.17.4 新增

方便函数，为给定的 sRGB 颜色整数返回颜色 (红, 绿, 蓝)。

参数：

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

返回：

一个由整数项目组成的元组（红，绿，蓝），表示相同的颜色，范围为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。

返回类型：

整数

返回：

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。

返回类型：

字符串

返回：

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

注意

包fontTools的agl子包提供了类似的功能。

adobe_glyph_names()

新功能在 v1.18.0 中

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

返回类型：

列表

返回：

字符串列表。

注意

包fontTools的agl子包提供了类似的功能。

adobe_glyph_unicodes()

新功能在 v1.18.0 中

返回一个 Unicode 列表，以便存在于Adobe Glyph List中的字形名称。

返回类型：

列表

返回：

整数列表。

注意

包fontTools的agl子包提供了类似的功能。

css_for_pymupdf_font(fontcode, *, CSS=None, archive=None, name=None)

新功能在 v1.21.0 中

与“Story”应用程序一起使用的实用函数。

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

包 pymupdf-fonts 中的字体命名约定是“fontcode”，其中后缀“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 定义，并将“notos”字体族名称（如果提供了“name”则为其值）分配给它们。相关字体缓冲区被放置/添加到提供的存档中。

要在 Python API 中使用字体对 Story 进行设置，执行.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 源码。

参数：

• fontcode (str) – 在包 pymupdf-fonts 中的字体代码之一（通常）表示字体系列的常规版本。
• 
  
• CSS (str) – 任何已存在的 CSS 源码，或 None。该函数将其新定义附加到此处。这是在创建 Story 时必须使用的 user_css 字符串。
• 
  
• archive – Archive，必须。所有“fontcode”找到的字体二进制文件（最多四个）将被添加到存档中。这是在创建 Story 时必须使用的 Archive。
• 
  
• name (str) – “fontcode”字体应被找到的名称。如果省略，将使用“fontcode”。
• 
  

返回类型：

str

返回：

修改后的 CSS，其中包含每个字体变体的附加 @font-face 语句。与“fontcode”相关联的字体缓存将被添加到“archive”中。该函数将自动查找最多 4 个字体变体。所有 pymupdf 字体（除数学或音乐等特殊用途外）都具有常规、粗体、斜体和粗斜体变体。要查看当前可用的字体代码，请检查 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 = pymupdf.Font("fimo") 定义 Font - 就像你可以用内置字体“Helvetica”和朋友们做的那样。

TESSDATA_PREFIX

• 新增于 v1.19.4
• 
  

复制 os.environ["TESSDATA_PREFIX"] 以方便检查是否集成了 Tesseract OCR 支持。

如果此属性为 None，则说明未安装 Tesseract-OCR，或者环境变量未设置为指向 Tesseract 语言支持文件夹。

注意

现在在尝试 OCR 函数之前会检查此变量。这可以防止 MuPDF 输出冗长的消息。

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
• 
  

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

参数：

• text (str) – 文本字符串。
• 
  
• fontname (str) – 字体名称。必须是 PDF 基础 14 字体 或 CJK 字体之一，由其“保留”字体名称（请参见 Page.insert_font() 中的表格）。
• 
  
• fontsize (float) – 字体大小。
• 
  
• encoding (int) – 要使用的编码。除了 0 = 拉丁字母、1 = 希腊字母和 2 = 西里尔字母（俄语）之外，还有 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© for c in text]) > pymupdf.get_text_length(text)。因此要么（1）做同样的事情，要么（2）在计算中使用像 pymupdf.get_text_length(text + “’”) 这样的方法。

get_pdf_str(text)

制作 PDF 兼容的字符串：如果文本包含的代码点 ord© > 255，它将转换为带 BOM 的 UTF-16BE 的十六进制字符字符串，包含在“<>”括号中，例如 <feff…>。否则，将返回用圆括号括起来的字符串，替换 ASCII 范围之外的任何字符为一些特殊代码。并且每个“（”、“）”或反斜杠都被反斜杠转义。

参数：

text（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 中的任意一种格式。

返回类型：

字典

返回：

从不会引发异常。在错误情况下返回 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'} 

与 Exif 信息编码在 orientation 中有以下关系，相应地在 transform 矩阵中类似于（摘自 MuPDF 文档，ccw = 逆时针）：

1. 未定义
2. 
   
3. 0 度逆时针旋转。（Exif = 1）
4. 
   
5. 90 度逆时针旋转。（Exif = 8）
6. 
   
7. 180 度逆时针旋转。（Exif = 3）
8. 
   
9. 270 度逆时针旋转。（Exif = 6）
10. 
    
11. 在 X 轴上翻转。（Exif = 2）
12. 
    
13. 先在 X 轴上翻转，然后逆时针旋转 90 度。（Exif = 5）
14. 
    
15. 先在 X 轴上翻转，然后逆时针旋转 180 度。（Exif = 4）
16. 
    
17. 先在 X 轴上翻转，然后逆时针旋转 270 度。（Exif = 7）
18. 
    

注意

• 对于一些“奇特”的图像（如传真编码、原始格式等），此方法无法使用。但你仍然可以在 PyMuPDF 中处理这些图像，例如通过 Document.extract_image() 或者通过 Pixmap(doc, xref) 创建像素图。这些方法在返回结果之前会自动将奇特的图像转换为 PNG 格式。
• 
  
• 也可以通过它们的xref获取嵌入在 PDF 中的图像的属性。在这种情况下，请确保提取原始流：pymupdf.image_profile(doc.xref_stream_raw(xref))。
• 
  
• 图像由Page.get_text()的图像块以“dict”或“rawdict”选项返回，也得到支持。

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

返回页文本输出的有效文档标头字符串。

参数：

• output（str） – 文档类型。与*get_text()*的输出参数相同。
• 
  
• filename（str） – 可选的任意输出类型“json”和“xml”中使用的名称。
• 
  

返回类型：

str

ConversionTrailer(output)

返回页文本输出的有效文档尾字符串。参见Page.get_text()的示例。

参数：

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

返回类型：

str

Document.del_xml_metadata()

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

Document.xml_metadata_xref()

如果存在，则返回 PDF 的基于 XML 的元数据的xref。还参见Document.del_xml_metadata()以检索内容，可以通过Document.xref_stream()检索并使用某些 XML 软件进行处理。

返回类型：

int

返回：

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

Page.run(dev, transform)

通过设备运行页面。

参数：

• dev（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" – 显示渐变
• 
  

项目顺序表示了构建页面外观所执行的命令的顺序。因此，如果项目的边界框与之前项目的边界框相交或包含，则可能（部分）覆盖/隐藏之前的项目。

因此，可以使用此列表来检测此类情况。列表中项目的索引等于由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)，则跨度和字符边界框现在也是正确的。
• 
  
• 在 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. 标有“(1)”的上述信息与 TextPage 中解释的含义和值相同。

• 请注意，字体flags值永远不会包含上标标志位：上标的检测是在 MuPDF 的 TextPage 代码中完成的 – 它不是任何字体的属性。
• 
  
• 还要注意，文本颜色编码为常规浮点数元组 0 <= f <= 1 – 而不是 sRGB 格式。根据span["type"]，将其解释为填充颜色或描边颜色。
• 
  

2. 有 3 种文本跨度类型：

• 0: 填充文本 – 等同于 PDF 文本渲染模式 0（0 Tr，PDF 中的默认值），只显示每个字符的“内部”。
• 
  
• 1: 笔画文本 – 等同于1 Tr，只显示字符边框。
• 
  
• 3: 忽略的文本 – 等同于3 Tr（隐藏文本）。
• 
  

3. 在此上下文中，线宽仅对处理span["type"] != 0的情况很重要：它决定了字符边界线的厚度。此值可能根本不会随文本数据提供。在这种情况下，将生成一个值为fontsize的 5%（span["size"] * 0,05）。通常，PDF 中的“人为”粗体文本由2 Tr创建。对于这种情况没有等效的跨度类型。相反，相应的文本由两个连续的跨度表示 – 它们在每个方面都是相同的，除了它们的类型，分别是 0 和 1。处理此类情况是你的责任 – 在Page.get_text()中，MuPDF 为你处理这个问题。
4. 
   
5. 为了数据紧凑性，在此提供了字符的 Unicode。使用内置函数chr()获取字符本身。
6. 
   
7. 跨度文本的 alpha / 不透明值为 0 <= opacity <= 1，0 表示不可见文本，1（100%）表示不透明。根据 span["type"]，将此值解释为 填充 不透明度或 描边 不透明度。
8. 
   
9. (v1.19.0 更改) 此值与“rawdict”中的 char["bbox"] 相等或接近。特别是，边界框 高度 值总是按照请求 “小字形高度” 计算。
10. 
    
11. (v1.19.0 新增) 这是所有字符边界框的并集。
12. 
    
13. (v1.19.0 新增) 枚举构建页面外观的命令。可用于查找文本是否被稍后绘制的对象有效地隐藏，或者 覆盖 了某个对象。因此，如果有一个绘图或图像具有更高的序列号，其边界框与此文本跨度重叠（部分），则可以假设该对象隐藏了相应的文本。如果一次创建了多个文本跨度，则不同文本跨度具有相同的序列号。
14. 
    
15. (v1.22.0 新增) 可选内容组（OCG）的名称（如果适用）或 None。
16. 
    

这里列出了 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"] 等来理解信息。
• 
  
• 连字表示如下：

• 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 中更改： 与其他文本提取方法类似，字符和跨度的边界框包围字符四边形。要恢复四边形，请按照 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+）中，此检查和相应的调整将自动执行 - 因此您不再需要担心这个问题。

返回类型：

布尔值

Page.get_text_blocks(flags=None)

废弃的TextPage.extractBLOCKS()的包装器。改用Page.get_text()并选择“blocks”选项。

返回类型：

列表[元组]

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

废弃的TextPage.extractWORDS()的包装器。改用Page.get_text()并选择“words”选项。

返回类型：

列表[元组]

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)

• 1.17.6 版本中更改
• 
  

仅限 PDF：清理并连接与此页面关联的所有contents对象。 “清理”包括语法修正、标准化和对内容流进行“漂亮打印”。如果 sanitize 为 true，则还将纠正contents和resources对象之间的差异。更多细节请参阅Page.get_contents()。

1.16.0 版本中更改 不再默认由此方法隐式清理注释。请单独使用Annot.clean_contents()。

参数：

sanitize (bool) – (1.17.6 版本中新增) 如果为 true，则资源和其在内容对象中的实际使用之间的同步是同步的。例如，如果某个字体实际上并未用于页面的任何文本，则它将从/Resources/Font对象中删除。

警告

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

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

Parameters:

• xref (int) – PDF 中嵌入的字体的交叉引用编号。要找到字体的 xref，请使用例如 doc.get_page_fonts(pno) 的页面号 pno 并取返回列表条目的第一个条目。
• 
  
• limit (int) – 限制返回条目的数量。对于仅支持 1 字节字符（通过此方法检查的所谓“简单字体”）的所有字体，默认强制执行 256。所有的 PDF 基本 14 字体 都是简单字体。
• 
  

Return type:

列表

Returns:

一个 limit 元组列表。每个字符 c 在此列表中具有 (g, w) 的条目，其索引为 ord©。元组的 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 包装的数据，则返回 True。

Document.get_new_xref()

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

Return type:

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

Document.xref_length()

返回 xref 表的长度。

Return type:

int

Returns:

xref 表中的条目数量。

recover_quad(line_dir, span)

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

Parameters:

• line_dir (tuple) – 拥有线的 line["dir"]。对于从 Page.get_texttrace() 获得的跨度，使用 None。
• 
  
• span (dict) – 这个跨度。
• 
  

Returns:

选择跨度的四边形，可用于文本标记注释（“高亮”等）。

recover_char_quad(line_dir, span, char)

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

参数：

• line_dir (tuple) – 所属行的line["dir"]。对于从Page.get_texttrace()获取的跨度，请使用None。
• 
  
• span (dict) – 范围。
• 
  
• char (dict) – 字符。
• 
  

返回：

字符的四边形，可用于文本标记注释（“高亮”等）。

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”。
• 
  

返回：

选择字符的四边形，可用于文本标记注释（“高亮”等）。

recover_line_quad(line, spans=None)

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

参数：

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

返回：

选择行跨度的四边形，可用于文本标记注释（“高亮”等）。

get_tessdata()

返回 Tesseract 语言支持文件夹的名称。如果环境变量TESSDATA_PREFIX未设置，请使用此函数。

返回：

如果未设置os.getenv("TESSDATA_PREFIX")，则为False。否则，如果已安装 Tesseract-OCR，请定位tessdata的名称。如果未找到安装，则返回False。

文件夹名称可用作方法Page.get_textpage_ocr()、Pixmap.pdfocr_save()和Pixmap.pdfocr_tobytes()的参数。

INFINITE_QUAD()

INFINITE_RECT()

INFINITE_IRECT()

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

EMPTY_QUAD()

EMPTY_RECT()

EMPTY_IRECT()

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

是否对本页有任何反馈？

本软件按原样提供，不附带任何形式的保证，无论是明示的还是隐含的。本软件按许可分发，并且除非在该许可条款明确授权的情况下，不得复制、修改或分发。有关许可信息，请参考artifex.com，或联系美国加利福尼亚州旧金山 94129 市 39 Mesa Street, Suite 108A 的 Artifex Software Inc.获取更多信息。

这份文档涵盖了所有版本直到 1.24.4。