PyMuPDF 1.24.4 中文文档（八）（3）

PyMuPDF 1.24.4 中文文档（八）（2）https://developer.aliyun.com/article/1559656

光学字符识别 (OCR) 技术可用于从页面始终以光栅图像格式包含文本数据的文档中提取文本数据。使用此方法进行页面的 OCR 以进行文本提取。

如果使用此方法，MuPDF 将为包含 OCRed 文本的页面调用 Tesseract-OCR。否则，这是一个普通的 TextPage 对象。

参数：

• flags (int) – 控制可用于后续文本提取和搜索的内容的指示位 – 请参阅 Page.get_text() 的参数。
  
• language (str) – 期望的语言。如果期望多种语言，则使用 “+” 分隔的值，例如 “eng+spa” 表示英语和西班牙语。
  
• dpi (int) – 所需分辨率，以每英寸点数为单位。影响识别质量（和执行时间）。
  
• full (bool) – 是否对整个页面进行 OCR 处理，还是仅对显示的图像进行处理。
  
• tessdata (str) – Tesseract 的语言支持文件夹 tessdata 的名称。如果省略，必须通过环境变量 TESSDATA_PREFIX 提供此信息。可以通过函数 get_tessdata() 确定。
  

注意

此方法不支持 clip 参数 – OCR 将始终对完整页面矩形进行处理。

返回：

一个 TextPage。执行时间可能比 Page.get_textpage() 长得多。

对于完整页面的 OCR，所有文本将使用来自 Tesseract 的 “GlyphlessFont”。对于部分 OCR，普通文本将保留其属性，只有来自图像的文本才会使用 GlyphlessFont。

注意

仅当 Page.get_text() 的参数指定此方法的输出时，OCRed 文本才可供 PyMuPDF 的文本提取和搜索使用。

这个 Jupyter 笔记本演示了如何使用 OCR 提取文本页的示例。

显示/隐藏历史记录 * 新增于 v.1.19.0

• 改动 v1.19.1：支持对页面进行完整和部分 OCR 处理。

get_drawings(extended=False)

返回页面的矢量图形。这些是绘制线条、矩形、四边形或曲线的指令，包括颜色、透明度、线宽和虚线等属性。替代术语包括“线稿”和“图纸”。

返回：

一个字典列表。每个字典条目包含一个或多个彼此相关的单个绘制命令：它们具有相同的属性（颜色、虚线等）。在 PDF 中称为“路径”，因此我们在这里采用了这个名称，但该方法适用于所有文档类型。

用于填充、描边和填充-描边路径的路径字典已设计为与类 形状 兼容。以下是关键字：

键 "opacity" 已被新键 "fill_opacity" 和 "stroke_opacity" 替换。现在与 Shape.finish() 的相应参数兼容。 (v1.18.17 中更改)

对于除组或剪辑之外的路径，键 "type" 取以下值之一：

• “f” – 这是一个仅填充的路径。仅适用于此操作的键值有意义，不适用的键具有 None 值："color"、"lineCap"、"lineJoin"、"width"、"closePath"、"dashes"，应被忽略。
  
• “s” – 这是一个仅描边的路径。类似于前面的，键 "fill" 存在，值为 None。
  
• “fs” – 这是一个执行合并填充和描边操作的路径。
  

path["items"] 中的每个项目是以下之一：

• ("l", p1, p2) - 从 p1 到 p2 的线条（点 对象）。
  
• ("c", p1, p2, p3, p4) - 由 p1 到 p4 的三次贝塞尔曲线（p2 和 p3 是控制点）。所有对象均为 点 类型。
  
• ("re", rect, orientation) - 一个 矩形。现在检测到同一路径中的多个矩形（在 v1.18.17 中更改）。整数 orientation 是 1 或 -1，指示封闭区域是否向左旋转（1 = 逆时针），或向右 [7]（在 v1.19.2 中更改）。
  
• ("qu", quad) - 一个 四边形。检测到 3 或 4 行连续表示一个 四边形（在 v1.19.2 中更改）。（v1.18.17 中新增）
  

使用类 Shape，您应该能够在普通情况下以高保真度重新创建原始图纸在单独的（PDF）页面上。请参阅对限制的以下评论。编码草案可在章节 FAQ 的 “Extractings Drawings” 中找到。

指定 extended=True 显著改变了输出。最重要的是，新增了字典类型：“clip” 和 “group”。现在所有路径将按照层级结构组织，这由新的整数键“level”编码，即层级水平。每个组或剪辑都建立了一个新的层次结构，适用于所有后续具有更高级别值的路径。（新增于 v1.22.0）

任何具有比其前任更小的级别值的路径将终止（至少）前一个层次结构级别的范围。与前一个剪辑级别相同的 “clip” 路径将终止该剪辑的范围。组也是如此。这可以通过以下示例最好解释：

+------+------+--------+------+--------+
| line | lvl0 | lvl1   | lvl2 |  lvl3  |
+------+------+--------+------+--------+
|  0   | clip |        |      |        |
|  1   |      | fill   |      |        |
|  2   |      | group  |      |        |
|  3   |      |        | clip |        |
|  4   |      |        |      | stroke |
|  5   |      |        | fill |        |  ends scope of clip in line 3
|  6   |      | stroke |      |        |  ends scope of group in line 2
|  7   |      | clip   |      |        |
|  8   | fill |        |      |        |  ends scope of line 0
+------+------+--------+------+--------+ 

第 0 行的剪辑适用于包括第 7 行在内的行。第 2 行的组适用于第 3 到第 5 行，第 3 行的剪辑仅适用于第 4 行。

“stroke” 在第 4 行受第 2 行的 “group” 和第 3 行的 “clip” 控制（而第 3 行的 “clip” 又是第 0 行的子集）。

• “clip” 字典。其值（最重要的是 “scissor”）在后续具有更高级别值的字典中仍然有效 / 适用。

• 
  
• “group” 字典。其值在后续具有更高级别值的字典有效（适用）。任何级别相等或更低的字典将终止该组。

注

该方法基于 Page.get_cdrawings() 的输出 – 更快速，但需要更多处理注意力。

显示/隐藏历史记录 * 新增于 v1.18.0

• 在 v1.18.17 中更改
  
• 在 v1.19.0 中更改：添加 “seqno” 键，删除 “clippings” 键
  
• 在 v1.19.1 中更改：“color” / “fill” 键现在总是 RGB 元组或 None。这解决了由于奇异颜色空间引起的问题。
  
• Changed in v1.19.2: 添加了一个关于 “orientation” 的指示器的 “re” 项。
  
• Changed in v1.22.0: 添加新键 "layer"，其包含路径的可选内容组的名称（或者 None）。
  
• Changed in v1.22.0: 添加参数 extended，以便返回剪切和组路径。
  

get_cdrawings(extended=False)

提取页面上的矢量图形。除了遵循技术上的差异外，在功能上等效于 Page.get_drawings()，但速度更快：

• 每种路径类型仅包含相关的键，例如：笔画路径没有 "fill" 颜色键。参见方法 Page.get_drawings() 的注释。
  
• 坐标以 point_like、rect_like 和 quad_like 的 元组 形式给出 — 而不是作为 Point、Rect、Quad 对象。
  

如果性能是一个问题，请考虑使用这种方法：与 1.18.17 之前的版本相比，你应该看到更短的响应时间。我们已经看到以前需要 2 秒的页面，现在只需 200 毫秒就可以用这种方法。

显示/隐藏历史记录 * 新增于 v1.18.17

• Changed in v1.19.0: 删除了 “clippings” 键，添加了 “seqno” 键。
  
• Changed in v1.19.1: 总是生成 RGB 颜色元组。
  
• Changed in v1.22.0: 添加了新键 "layer"，其包含路径的可选内容组的名称（或者 None）。
  
• Changed in v1.22.0: 添加参数 extended，以便返回剪切路径。
  

get_fonts(full=False)

仅适用于 PDF：返回页面引用的字体列表。是 Document.get_page_fonts() 的包装器。

get_images(full=False)

仅适用于 PDF：返回页面引用的图像列表。是 Document.get_page_images() 的包装器。

get_image_info(hashes=False, xrefs=False)

返回页面上显示的所有图像的元信息字典列表。这对于所有文档类型都适用。从技术上讲，这是 Page.get_text() 的字典输出的子集：图像二进制内容和页面上的任何文本都被忽略。

参数：

• hashes (bool) – 对每个遇到的图像计算 MD5 哈希码，从而允许识别图像重复。这会将键 "digest" 添加到输出中，其值是一个 16 字节的 bytes 对象。 (新增于 v1.18.13)
  
• xrefs (bool) – 仅适用于 PDF。 尝试查找每个图像的 xref。意味着 hashes=True。向字典添加 "xref" 键。如果未找到，则值为 0，这意味着图像是“内联”的或无法检测到的。请注意，此选项由于至少为每个具有 xref 的图像计算两次 MD5 哈希码，因此具有扩展的响应时间。 (新增于 v1.18.13)
  

返回类型：

list[dict]

返回：

一个字典列表。这包括仅显示在页面上的图像的信息 - 包括 “内联图像”。与 Page.get_text() 中包含的图像不同，不会加载图像的二进制内容，这大大减少了内存使用量。字典布局类似于 page.get_text("dict") 中的图像块的布局。

同一图像的多个出现始终会被报告。您可以通过比较它们的 digest 值来检测重复项。

显示/隐藏历史记录 * v1.18.11 中的新功能

• 在 v1.18.13 中更改：添加了图像 MD5 哈希码计算和 xref 搜索。

get_xobjects()

PDF only: 返回页面引用的 Form XObjects 的列表。Document.get_page_xobjects() 的包装器。

get_image_rects(item, transform=False)

PDF only: 返回嵌入图像的边界框和变换矩阵。这是一个改进版本的 Page.get_image_bbox()，具有以下区别：

• 对于图像被调用的方式（由页面或其 Form XObjects 之一），没有限制。结果始终是完整且正确的。
  
• 结果是 Rect 或 (Rect, Matrix) 对象的列表 - 取决于 transform。每个列表项代表页面上图像的一个位置。多个出现可能无法通过 Page.get_image_bbox() 检测到。
  
• 该方法调用 Page.get_image_info() 并且 xrefs=True，因此响应时间比 Page.get_image_bbox() 明显更长。
  

参数：

• item (list*,str,*int) – 列表 Page.get_images() 的一个项目，或者这样一个项目的引用 name 条目 (item[7])，或者图像的 xref。
  
• transform (bool) – 还返回用于将图像矩形转换为页面上的边界框的矩阵。如果为 true，则返回元组 (bbox, matrix)。
  

返回类型：

列表

返回：

页面上每个图像出现的边界框及相应的转换矩阵。如果项目不在页面上，则返回空列表[]。

显示/隐藏历史 v1.18.13 中的新功能

get_image_bbox(item, transform=False)

仅 PDF：返回嵌入图像的边界框和转换矩阵。

参数：

• item（list*,*str）- Page.get_images() 列表的项，指定 full=True，或此类项的引用 name 条目，即 item[-3]（或 item[7]）。
  
• transform（bool）- 返回用于将图像矩形转换为页面上的边界框的矩阵（v1.18.11 中的新功能）。默认为仅使用边界框。如果为 true，则返回一个元组(bbox, matrix)。
  

返回类型：

矩形 或 (矩形, 矩阵)

返回：

图像的边界框- 可选地也包括其转换矩阵。

显示/隐藏历史 * (在 v1.16.7 中更改)：如果页面实际上不显示此图像，则现在返回一个无限矩形。在以前的版本中，会引发异常。形式上无效的参数仍会引发异常。

• (在 v1.17.0 中更改)：仅考虑页面直接引用的图像。这意味着会忽略嵌入的 PDF 页面中出现的图像，并引发异常。
  
• (在 v1.18.5 中更改)：移除了 v1.17.0 中引入的限制：可以指定页面图像列表的任何项。
  
• (在 v1.18.11 中更改)：部分重新实施限制：仅考虑那些直接由页面引用或由页面直接引用的 Form XObject 引用的图像。
  
• (在 v1.18.11 中更改)：可选地将转换矩阵与边界框一起作为元组(bbox, transform)返回。
  

注意

1. 请注意，Page.get_images() 可能包含“无效”条目，即页面未显示的图像。这不是错误，而是由 PDF 创建者意图。在这种情况下不会引发异常，而是返回一个无限矩形。您可以通过在此方法之前执行Page.clean_contents() 来避免发生这种情况。
   
2. 图像的“转换矩阵”定义为矩阵，满足表达式 bbox / transform == pymupdf.Rect(0, 0, 1, 1) 为真，详情请参阅：图像转换矩阵。
   

显示/隐藏历史 * 在 v1.18.11 中更改：返回图像转换矩阵

get_svg_image(matrix=pymupdf.Identity, text_as_path=True)

从页面创建一个 SVG 图像。当前仅支持全页图像。

参数：

• matrix（matrix_like）- 一个矩阵，默认为 Identity。
  
• text_as_path (bool) – 控制文本的表示方式。True 将每个字符输出为一系列基本绘制命令，这会导致在浏览器中显示更精确的文本，但对于面向文本的页面输出非常大。对于 False，显示质量取决于当前系统上是否存在引用的字体。对于缺失字体，互联网浏览器将退回到一些默认值 – 导致不愉快的外观。如果您希望解析 SVG 文本，请选择 False。（新于 v1.17.5）
  

返回：

包含图像的 UTF-8 编码字符串。由于 SVG 具有 XML 语法，它可以保存在文本文件中，标准扩展名为 .svg。

注意

对于 PDF 文件，您可以通过修改页面的 CropBox 在使用该方法之前绕过“仅全页图像”限制。

get_pixmap(*, matrix=pymupdf.Identity, dpi=None, colorspace=pymupdf.csRGB, clip=None, alpha=False, annots=True)

从页面创建一个像素图。这可能是创建 Pixmap 最常用的方法。

所有参数均为 仅限关键字。

参数：

• matrix (matrix_like) – 默认为 Identity。
  
• dpi (int) – x 和 y 方向的期望分辨率。如果不为 None，则忽略 "matrix" 参数。（新于 v1.19.2）
  
• colorspace (str 或 Colorspace) – 所需的颜色空间，为“GRAY”、“RGB”或“CMYK”之一（大小写不敏感）。或指定一个预定义的颜色空间：csGRAY、csRGB 或 csCMYK。
  
• clip (irect_like) – 限制渲染到页面矩形的交集。
  
• alpha (bool) –是否添加 alpha 通道。如果您不真正需要透明度，请始终接受默认值 False。这将节省大量内存（在 RGB 情况下为 25% … 且像素图通常非常大！），并减少处理时间。还要注意图像渲染的重要差异：使用 True 时，像素图的样本区域将预先清除为 0x00，这将导致页面空白处为透明。使用 False 时，像素图的样本将预先清除为 0xff，导致页面空白处为白色。 显示/隐藏历史记录 自 v1.14.17 版本更改 默认 alpha 值现在为 False。

• 生成时使用 alpha=True

• 生成时使用 alpha=False

• 
  
• annots (bool) – (自版本 1.16.0 起新增) 是否渲染注释或者抑制它们的显示。您可以单独为注释创建像素图。
  

返回类型：

Pixmap

返回：

页面的像素图。用于精细控制生成的图像，到目前为止最重要的参数是matrix。例如，您可以使用**Matrix(xzoom,  yzoom)**来增加或减少图像分辨率。如果缩放> 1，则在该方向上会获得更高的分辨率：zoom=2  将使该方向上的像素数量加倍，从而生成 2  倍大的图像。非正值将水平翻转，垂直翻转。类似地，矩阵还允许您旋转或剪切，并且您可以通过例如矩阵乘法组合效果。请参阅矩阵部分以了解更多信息。 注意

• 如果alpha=True，像素图将具有*“预乘”*像素。要了解一些背景知识，例如，请查找“预乘 alpha” 这里。
  
• 该方法将尊重任何页面旋转，并且不会超出clip和Page.cropbox的交集。如果您需要页面的媒介框（如果这是一个不同的矩形），您可以使用以下类似的片段来实现这一点：

In [1]: import pymupdf
In [2]: doc=pymupdf.open("demo1.pdf")
In [3]: page=doc[0]
In [4]: rotation = page.rotation
In [5]: cropbox = page.cropbox
In [6]: page.set_cropbox(page.mediabox)
In [7]: page.set_rotation(0)
In [8]: pix = page.get_pixmap()
In [9]: page.set_cropbox(cropbox)
In [10]: if rotation != 0:
   ...:     page.set_rotation(rotation)
   ...:
In [11]: 

显示/隐藏历史记录 * 在 v1.19.2 中更改：添加了参数 dpi 的支持。

annot_names()

仅 PDF：返回注释，小部件和链接名称列表。从技术上讲，这些是页面*/Annots数组中找到的每个 PDF 对象的/NM*值。

返回类型：

列表

显示/隐藏历史记录 * 新增于 v1.16.10

annot_xrefs()

仅 PDF：返回注释，小部件和链接的:dataxref编号列表 - 从技术上讲，是在页面的*/Annots*数组中找到的所有条目。

返回类型：

列表

返回：

一个项目的列表*(xref, type)*其中 type 是注释类型。使用类型来区分链接，字段和注释，请参见注释类型。

显示/隐藏历史记录 * 新增于 v1.17.1

load_annot(ident)

仅 PDF：返回由ident标识的注释。这可以是其唯一名称（PDF /NM键），或其xref。

参数：

ident（str*,*int） - 注释名称或 xref。

返回类型：

注释

返回：

注释或None。

注意

方法Page.annot_names()，Page.annot_xrefs()分别提供名称或 xrefs 列表，可以从中选择一个项目，并通过此方法加载。

显示/隐藏历史记录 * 新增于 v1.17.1

load_widget(xref)

仅 PDF：返回由xref标识的字段。

参数：

xref（int） - 字段的 xref。

返回类型：

小部件

返回：

字段或None。

注意

这类似于类似方法Page.load_annot() - 只是这里仅支持 xref 作为标识符。

显示/隐藏历史记录 * 新增于 v1.19.6

load_links()

返回页面上的第一个链接。与属性first_link的同义词。

返回类型：

链接

返回：

页面上的第一个链接（或None）。

set_rotation(rotate)

仅限 PDF：设置页面的旋转。

参数：

rotate (int) – 指定所需旋转的角度的整数。必须是 90 的整数倍。值将被转换为 0、90、180、270 中的一个。

remove_rotation()

仅限 PDF：将页面旋转设置为 0，同时保持外观和页面内容。

返回：

用于实现此变更所使用的反转矩阵。如果页面未旋转（旋转为 0），将返回 Identity。该方法会自动重新计算页面上存在的任何注释、链接和小部件的矩形。

当与例如Page.show_pdf_page()一起使用时，此方法可能非常有用。

show_pdf_page(rect, docsrc, pno=0, keep_proportion=True, overlay=True, oc=0, rotate=0, clip=None)

仅限 PDF：显示另一个 PDF 的页面作为矢量图像（否则类似于Page.insert_image()）。这是一个多功能的方法。例如，您可以使用它

• 创建现有 PDF 文件的“n-up”版本，将多个输入页面组合成一个输出页面（参见示例combine.py），
  
• 创建“分色”PDF 文件，即每个输入页面分割成部分，每部分创建一个单独的输出页面（参见posterize.py），
  
• 包括基于 PDF 的矢量图像，如公司标志、水印等，参见svg-logo.py，它在每一页上放置一个基于 SVG 的标志（需要额外的软件包处理 SVG 到 PDF 的转换）。
  

参数：

• rect (rect_like) – 在当前页面上放置图像的位置。必须是有限的，并且其与页面的交集不能为空。
  
• docsrc (文档) – 包含页面的源 PDF 文档。必须是不同的文档对象，但可以是同一文件。
  
• pno (int) – 要显示的页码（从 0 开始，在-∞ < pno < docsrc.page_count范围内）。
  
• keep_proportion (bool) – 是否保持宽高比（默认）。如果为 false，则所有 4 个角都始终定位在目标矩形的边界上 - 无论旋转值如何。一般来说，这将提供扭曲和/或非矩形的图像。
  
• overlay (bool) – 将图像放在前景（默认）或背景中。
  
• oc (int) – （xref）使得可见性依赖于此OCG / OCMD （必须在目标 PDF 中定义）[9]。 （v1.18.3 中的新功能）
  
• rotate (float) – 显示经某个角度旋转的源矩形。支持任意角度（在 v1.14.11 中更改）。 （v1.14.10 中的新功能）
  
• clip (rect_like) – 选择要显示的源页面的部分。默认为整个页面，否则必须是有限的，并且其与源页面的交集不能为空。
  

注意

与方法Document.insert_pdf()相比，此方法不复制注释、小部件或链接，因此这些内容不包含在目标中[6]。但是所有其它资源（文本、图像、字体等）将被导入到当前的 PDF 中。因此，它们将出现在文本提取和get_fonts()以及get_images()列表中，即使它们不在由 clip 给出的可见区域内。

示例：显示相同源页面，旋转 90 度和 -90 度：

>>> doc = pymupdf.open()  # new empty PDF
>>> page=doc.new_page()  # new page in A4 format
>>>
>>> # upper half page
>>> r1 = pymupdf.Rect(0, 0, page.rect.width, page.rect.height/2)
>>>
>>> # lower half page
>>> r2 = r1 + (0, page.rect.height/2, 0, page.rect.height/2)
>>>
>>> src = pymupdf.open("PyMuPDF.pdf")  # show page 0 of this
>>>
>>> page.show_pdf_page(r1, src, 0, rotate=90)
>>> page.show_pdf_page(r2, src, 0, rotate=-90)
>>> doc.save("show.pdf") 

显示/隐藏历史记录*在 v1.14.11 中更改：参数 reuse_xref 已被弃用。将源矩形定位于目标矩形的中心。现在支持任何旋转角度。

• 在 v1.18.3 中更改：新增参数 oc。

new_shape()

仅限 PDF：为页面创建一个新的形状对象。

返回类型：

Shape

返回：

一个新的 Shape，用于复合绘图。详见那里的描述。

search_for(needle, *, clip=None, quads=False, flags=TEXT_DEHYPHENATE | TEXT_PRESERVE_WHITESPACE | TEXT_PRESERVE_LIGATURES | TEXT_MEDIABOX_CLIP, textpage=None)

在页面上搜索 needle。是TextPage.search()的包装器。

参数：

• needle（str） – 要搜索的文本。可能包含空格。忽略大小写，但仅适用于 ASCII 字符：例如，如果 needle 是 “compétences”，则 “COMPÉTENCES” 将不会被找到，但是 “compÉtences” 将会被找到。德语重音符号等也是如此。
  
• clip（rect_like） – 仅在此区域内搜索。（在 v1.18.2 中新增）
  
• quads（bool） – 返回 Quad 对象而不是 Rect。
  
• flags（int） – 控制底层 TextPage 提取的数据。默认情况下保留连字和空白，并检测连字[8]。
  
• textpage – 使用之前创建的 TextPage。这将显著减少执行时间**。**如果指定了，则忽略‘flags’和‘clip’参数。如果省略，则将创建一个临时文本页。(在 v1.19.0 中新增)
  

返回类型：

列表

返回：

Rect 或 Quad 对象的列表，每个对象通常包围一个needle的出现。**但是：**如果needle的某些部分跨越多行，则为每个这些部分生成一个单独的项。因此，如果 needle = "search string"，可能会生成两个矩形。

显示/隐藏历史记录在 v1.18.2 中的更改：

• 列表长度不再有限制（移除了 hit_max 参数）。
  
• 如果一个词在换行处被连字符分隔，仍然会被找到。例如，“method”将被找到，即使在换行处作为“meth-od”出现，也会返回两个矩形：一个围绕“meth”（没有连字符）和另一个围绕“od”。
  

注意

该方法支持多行文本标记注释：您可以使用完整的返回列表作为一个单一的参数来创建注释。

注意

• 有一个棘手的方面：搜索逻辑将连续的多次出现的needle视为一个整体：假设needle是“abc”，并且页面包含“abc”和“abcabc”，那么仅会返回两个矩形，一个是“abc”，第二个是“abcabc”。
  
• 您始终可以使用Page.get_textbox()来检查每个矩形周围实际包含的文本。
  

注意

支持在指定"needle"字符串时使用正则表达式是一个反复要求的功能：**这是不可能的。**如果你需要这方面的功能，首先提取所需格式的文本，然后通过与某些正则表达式模式匹配来选择结果。以下是匹配单词的示例：

>>> pattern = re.compile(r"...")  # the regex pattern
>>> words = page.get_text("words")  # extract words on page
>>> matches = [w for w in words if pattern.search(w[4])] 

列表matches将包含与给定模式匹配的单词。同样的方法，您可以从page.get_text("dict")的输出中选择span["text"]。

显示/隐藏历史记录 * 于 v1.18.2 中更改：添加`clip`参数。移除`hit_max`参数。添加默认的“去连字符化”。

• 于 v1.19.0 中更改：添加 TextPage 参数。

set_mediabox(r)

仅适用于 PDF：通过在页面对象定义中设置mediabox来更改物理页面尺寸。

参数：

r（类似于矩形）— 新的mediabox值。

注意

此方法还会移除页面的其他（可选的）矩形（cropbox、ArtBox、TrimBox 和 Bleedbox），以防止出现不一致的情况。这将导致它们假定其默认值。

注意

对于非空页面，这可能会产生不良影响，因为所有内容的位置都取决于此值，因此位置会发生变化，甚至可能会消失。

显示/隐藏历史记录 * 新增于 v1.16.13

• 于 v1.19.4 中更改：移除所有其他矩形定义。

set_cropbox(r)

仅适用于 PDF：更改页面的可见部分。

参数：

r（类似于矩形）— 页面的新可见区域。请注意，这必须在未旋转的坐标中指定，不能是空的，也不能是无限的，并且完全包含在Page.mediabox中。

在执行后**(如果页面未旋转)**，Page.rect将等于该矩形，但如果有必要，将其移至左上角位置（0, 0）。示例会话：

>>> page = doc.new_page()
>>> page.rect
pymupdf.Rect(0.0, 0.0, 595.0, 842.0)
>>>
>>> page.cropbox  # cropbox and mediabox still equal
pymupdf.Rect(0.0, 0.0, 595.0, 842.0)
>>>
>>> # now set cropbox to a part of the page
>>> page.set_cropbox(pymupdf.Rect(100, 100, 400, 400))
>>> # this will also change the "rect" property:
>>> page.rect
pymupdf.Rect(0.0, 0.0, 300.0, 300.0)
>>>
>>> # but mediabox remains unaffected
>>> page.mediabox
pymupdf.Rect(0.0, 0.0, 595.0, 842.0)
>>>
>>> # revert CropBox change
>>> # either set it to MediaBox
>>> page.set_cropbox(page.mediabox)
>>> # or 'refresh' MediaBox: will remove all other rectangles
>>> page.set_mediabox(page.mediabox) 

set_artbox(r)

set_bleedbox(r)

set_trimbox(r)

仅适用于 PDF：在页面对象中设置相应的矩形。有关这些对象的含义，请参见 Adobe PDF 参考手册，第 77 页。参数和限制与Page.set_cropbox()相同。

显示/隐藏历史记录 * 新增于 v1.19.4

rotation

页面以度数表示的旋转角度（非 PDF 类型始终为 0）。这是 PDF 文件中的值的副本。PDF 文档说明如下：

“显示或打印页面时，页面应顺时针旋转的角度。该值必须是 90 的倍数。默认值：0。”

在 PyMuPDF 中，我们确保此属性始终为 0、90、180 或 270 中的一个。

类型：

整型

cropbox_position

包含 PDF 文档中页面的 /CropBox 的左上角点，否则为 Point(0, 0)。

类型：

点

cropbox

对于 PDF 文档，页面的 /CropBox 始终返回未旋转的页面矩形。对于非 PDF 文档，这将始终等于页面矩形。

注意

在 PDF 中，/MediaBox、/CropBox 和页面矩形之间的关系有时可能令人困惑，请查阅词汇表获取 MediaBox 的详细信息。

类型：

矩形

artbox

bleedbox

trimbox

页面的 /ArtBox、/BleedBox、/TrimBox。如果未提供，则默认为 Page.cropbox。

类型：

矩形

mediabox_size

包含 PDF 页面的 Page.mediabox 的宽度和高度，否则包含 Page.rect 的右下坐标。

类型：

点

mediabox

页面的 mediabox，否则 Page.rect。

类型：

矩形

注意

对于大多数 PDF 文档和所有其他文档类型，page.rect == page.cropbox == page.mediabox 为真。然而，对于某些 PDF，可见页面是 mediabox 的真子集。此外，如果页面被旋转，其 Page.rect 可能不等于 Page.cropbox。在这些情况下，上述属性有助于正确定位页面元素。

transformation_matrix

此矩阵将 PDF 空间中的坐标转换为 MuPDF 空间中的坐标。例如，在 PDF 中，/Rect [x0 y0 x1 y1] 中的 (x0, y0) 指定了矩形的左下角点，而在 MuPDF 的系统中，(x0, y0) 指定了左上角。将 PDF 坐标乘以此矩阵将得到（Py-）MuPDF 矩形版本。显然，反向矩阵将再次生成 PDF 矩形。

类型：

矩阵

rotation_matrix

derotation_matrix

这些矩阵可用于处理旋转的 PDF 页面。向 PDF 页面添加或插入任何内容时，始终使用未旋转页面的坐标。这些矩阵有助于在两种状态之间进行转换。例如：如果页面顺时针旋转 90 度，则 A4 页面左上角点(0, 0)的坐标是多少？

>>> page.set_rotation(90)  # rotate an ISO A4 page
>>> page.rect
Rect(0.0, 0.0, 842.0, 595.0)
>>> p = pymupdf.Point(0, 0)  # where did top-left point land?
>>> p * page.rotation_matrix
Point(842.0, 0.0)
>>> 

类型：

矩阵

first_link

包含页面的第一个 链接（或 None）。

类型：

链接

first_annot

包含页面的第一个 注释（或 None）。

类型：

注释

first_widget

包含页面的第一个 小部件（或 None）。

类型：

小部件

number

页面编号。

类型：

整数

parent

拥有的文档对象。

类型：

Document

rect

包含页面的矩形。与Page.bound()的结果相同。

类型：

Rect

xref

页面的 PDFxref。如果不是 PDF，则为零。

类型：

Rect

• get_links() 条目的描述
  

每个Page.get_links()列表项都是一个包含以下键的字典：

• kind：（必需）指示链接类型的整数。这是LINK_NONE、LINK_GOTO、LINK_GOTOR、LINK_LAUNCH或LINK_URI之一。有关这些名称的值和含义，请参阅链接目标类型。
  
• from：（必需）描述页面可见表示中的“热点”位置的 Rect（光标通常会变成手形图像）。
  
• page：指示目标页面的基于 0 的整数。对于LINK_GOTO和LINK_GOTOR必需，否则忽略。
  
• to：要么是pymupdf.Point，指定提供页面上的目标位置，默认为pymupdf.Point(0, 0)，或者是一个符号（间接）名称。如果指定了间接名称，则需要page = -1并且该名称必须在 PDF 中定义，以使其有效。对于LINK_GOTO和LINK_GOTOR必需，否则忽略。
  
• file：指定目标文件的字符串。对于LINK_GOTOR和LINK_LAUNCH必需，否则忽略。
  
• uri：指定目标互联网资源的字符串。对于LINK_URI必需，否则忽略。你应该确保该字符串以一个明确的子字符串开头，以区分 URL 的子类型，比如"http://"、"https://"、"file://"、"ftp://"、"mailto:"等。否则你的浏览器会试图解释文本，并对预期的 URL 类型产生不必要或意外的推断。
  
• xref：指定链接对象的 PDFxref的整数。不要更改此条目。对于链接的删除和更新是必需的，否则忽略。对于非 PDF 文档，如果任何链接不受 MuPDF 支持，则此条目包含*-1*。对于get_links()列表中的所有条目，如果任何链接不受 MuPDF 支持，则也为-1。参见支持链接的注意事项。
  

MuPDF 在v1.10a中对链接的支持已有所更改。这些更改影响了LINK_GOTO和LINK_GOTOR链接类型。

阅读（涉及get_links()方法和first_link属性链）

如果 MuPDF 检测到一个指向另一个文件的链接，则将提供LINK_GOTOR或LINK_LAUNCH链接类型之一。在LINK_GOTOR目标详情的情况下，可能会给出页面号码（最终包括位置信息）或间接目标。

如果给定了间接目标，则通过 page = -1 指示，并且 link.dest.dest 将包含此名称。 get_links() 列表中的字典将其作为 to 值包含此信息。

内部链接始终 是 LINK_GOTO 类型。如果内部链接指定了间接目标，则始终会解析并返回结果的直接目标。名称永远不会对内部链接返回，并且未定义的目标将导致忽略该链接。

写作

PyMuPDF 通过构造和写入适当的 PDF 对象 source 来编写（更新，插入）链接。这使得可以为 LINK_GOTOR 和 LINK_GOTO 链接类型（PDF 1.2 之前的文件格式 不受支持）指定间接目标。

警告

如果 LINK_GOTO 间接目标指定了未定义的名称，则 MuPDF / PyMuPDF 以后可能无法找到/重新读取此链接。其他阅读器将会检测到它，但会标记为错误。

总体上，间接 LINK_GOTOR 目标当然无法检查其有效性，因此始终会被接受。

示例：如何在同一文档中插入指向另一页的链接

1. 确定应放置链接的当前页面的矩形。这可能是图像或某些文本的 bbox。
   
2. 确定链接应放置在当前页面上的目标页面号（“pno”，基于 0），以及 Point 在其上的位置。
   
3. 创建一个字典 d = {"kind": pymupdf.LINK_GOTO, "page": pno, "from": bbox, "to": point}。
   
4. 执行 page.insert_link(d)。
   

Document 和 Page 的同源方法

这是对 Document 和 Page 级别同源方法的概述。

页面号 “pno” 是一个基于 0 的整数 -∞ < pno < page_count。

注意

大多数文档方法（左列）仅出于方便而存在，并只是：Document[pno]. 的包装器。因此它们在每次执行时加载并且丢弃页面。

然而，前两种方法的工作方式不同。它们只需要页面的对象定义语句 - 页面本身将不会被加载。例如 Page.get_fonts() 是一个反向包装器，并定义如下：page.get_fonts == page.parent.get_page_fonts(page.number)。

脚注

对此页面有任何反馈意见吗？

该软件按原样提供，不附带任何明示或暗示的担保。该软件在许可下分发，并且未经许可不得复制、修改或分发。有关许可信息，请参阅artifex.com，或联系位于美国加利福尼亚州旧金山 94129 Mesa 街 108A 号的 Artifex Software Inc.获取更多信息。

此文档涵盖所有 1.24.4 版本。

修改页面

仅适用于 PDF 文档的更改页面属性和添加或更改页面内容。

简而言之，这就是您可以使用 PyMuPDF 做的事情：

• 修改页面旋转和页面的可见部分（“裁剪框”）。
  
• 插入图像、其他 PDF 页面、文本和简单的几何对象。
  
• 添加注释和表单字段。
  

注意

方法需要坐标（点、矩形），以将内容放置在所需位置。请注意，这些坐标必须始终相对于未旋转的页面（自 v1.17.0 起）。反之亦然：除了Page.rect和Page.bound()（反映页面旋转时），方法和属性返回的所有坐标都适用于未旋转的页面。

例如，Page.get_image_bbox()的返回值不会因为您执行Page.set_rotation()而改变。对Page.get_text()返回的坐标、注释矩形等也是如此。如果您想找出对象在旋转坐标中的位置，请使用Page.rotation_matrix将坐标乘以其值。同样，它的逆矩阵是Page.derotation_matrix，在与其他阅读器进行接口时可能表现出不同的行为时可以使用。

注意

如果您在页面上添加或更新注释、链接或表单字段，并且随后需要立即处理它们（即在离开页面之前），您应该使用Document.reload_page()重新加载页面，以便引用这些新的或更新的项目。

通常建议重新加载页面，尽管并非在所有情况下都严格要求。但是，与 MuPDF 相比，PyMuPDF 在某些注释和小部件类型上具有扩展功能。将来可能还会添加更多这些扩展功能。

重新加载页面确保所有更改都已完全应用于 PDF 结构，因此您可以安全地创建位图或成功迭代注释、链接和表单字段。

类 API

class Page

bound()

确定页面的矩形。与属性 Page.rect 相同。对于 PDF 文档，这通常也与 mediabox 和 cropbox 重合，但并非总是如此。例如，如果页面被旋转，则此方法将反映此旋转 – 但 Page.cropbox 不会改变。

返回类型：

Rect

add_caret_annot(point)

仅限 PDF：添加一个插入符号。插入符注释通常用作视觉符号，用于指示页面上的文本编辑。

参数：

point (point_like) – 包含 MuPDF 提供的图标的 20 x 20 矩形的左上角点。

返回类型：

Annot

返回：

创建的注释。描边颜色为蓝色 = (0, 0, 1)，不支持填充颜色。

显示/隐藏历史记录 * v1.16.0 新增功能

add_text_annot(point, text, icon='Note')

仅限 PDF：添加一个评论图标（“便笺”），并附带文本。只有图标可见，附带的文本会被隐藏，但可以通过许多 PDF 查看器通过悬停鼠标在符号上来可视化。

参数：

• point (point_like) – 包含 MuPDF 提供的“note”图标的 20 x 20 矩形的左上角点。
  
• text (str) – 注释文本。双击或悬停在图标上时显示。可以包含任何拉丁字符。
  
• icon (str) – 选择“Note”（默认）、“Comment”、“Help”、“Insert”、“Key”、“NewParagraph”、“Paragraph”之一，作为体现文本的视觉符号 [4]。（v1.16.0 新增功能）
  

返回类型：

Annot

返回：

创建的注释。描边颜色为黄色 = (1, 1, 0)，不支持填充颜色。

add_freetext_annot(rect, text, fontsize=12, fontname='helv', border_color=None, text_color=0, fill_color=1, rotate=0, align=TEXT_ALIGN_LEFT)

仅限 PDF：在给定矩形中添加文本。

参数：

• rect（rect_like）- 文本应插入的矩形区域。文本会自动换行，以适应框的宽度。超出框的部分将不可见。
  
• text（str）- 文本内容。可以包含任何混合的拉丁、希腊、西里尔、中文、日文和韩文字符。相应的所需字体会自动确定。（自 v1.17.0 版新增）
  
• fontsize（float）- fontsize。默认为 12。
  
• fontname（str）- 字体名称。默认为“Helv”。接受的替代名称包括“Cour”、“TiRo”、“ZaDb”和“Symb”。名称可以缩写为前两个字符，如“Co”代表“Cour”。也接受小写。粗体或斜体变体的字体不被接受（自  v1.16.0 版更改）。用户贡献的脚本提供了这一限制的变通方法 - 见章节“使用按钮和 JavaScript”中的部分  FAQ。现在，实际使用的字体是按字符级别确定的，所有必需的字体（或子字体）都会自动包含。因此，您很少需要关心此参数，并让其默认（除非坚持对非  CJK 文本部分使用衬线字体）。（自 v1.17.0 版新增）
  
• text_color（sequence、float）- 文本颜色。默认为黑色。（自 v1.16.0 版新增）
  
• fill_color（sequence、float）- 填充颜色。默认为白色。（自 v1.16.0 版新增）
  
• text_color - 文本颜色。默认为黑色。
  
• border_color（sequence、float）- 边框颜色。默认为 None。（自 v1.19.6 版新增）
  
• align（int）- 文本对齐方式，可选值为 TEXT_ALIGN_LEFT、TEXT_ALIGN_CENTER、TEXT_ALIGN_RIGHT - 不支持justify。（自 v1.17.0 版新增）
  
• rotate（int）- 文本方向。可接受的值为 0、90、270，无效条目将设为零。
  

返回类型：

注释

返回：

创建的注释。颜色属性只能通过 Annot.update() 的特殊参数进行更改。在那里，您还可以设置与文本颜色不同的边框颜色。

显示/隐藏历史记录 * 从 v1.19.6 版更改：添加了边框颜色参数

add_file_annot(pos, buffer, filename, ufilename=None, desc=None, icon='PushPin')

仅限 PDF：在指定位置添加带有“PushPin”图标的文件附件注释。

参数：

• pos（point_like）- 包含 MuPDF 提供的“PushPin”图标的 18x18 矩形的左上角点。
  
• buffer（bytes、bytearray、BytesIO）-
  要存储的数据（实际文件内容、任何数据等）。
  从 v1.14.13 版开始更改：现在还支持 io.BytesIO。
  
• filename（str）- 与数据关联的文件名。
  
• ufilename（str）- 文件名的可选 PDF Unicode 版本。默认为文件名。
  
• desc（str）- 文件的可选描述。默认为文件名。
  
• icon（str）- 选择一个“PushPin”（默认）、“Graph”、“Paperclip”、“Tag”作为附加数据的可视符号[4]。（自 v1.16.0 版新增）
  

返回类型：

注释

返回值：

创建的注释。描边颜色黄色 =（1，1，0），不支持填充颜色。

add_ink_annot(list)

仅限 PDF：添加一个“自由手绘”涂鸦注释。

参数：

list（序列） - 一个包含一个或多个列表的列表，每个列表包含point_like项目。这些子列表中的每个项目都被解释为 Point 通过它连接线绘制的点。因此，单独的子列表代表单独的绘图线条。

返回类型：

注释

返回值：

默认外观中创建的注释黑色 =（0，0，0），线宽 1。不支持填充颜色。

add_line_annot(p1, p2)

仅限 PDF：添加一个线条注释。

参数：

• p1（point_like） - 线的起点。
  
• p2（point_like） - 线的终点。
  

返回类型：

注释

返回值：

创建的注释。用红色线条（描边）颜色绘制，红色 =（1，0，0），线宽为 1。不支持填充颜色。注释矩形会自动创建以容纳两个点，每个点都由半径为 3 * 线宽的圆圈包围，以便为任何线条末端符号腾出空间。

add_rect_annot(rect)

add_circle_annot(rect)

仅限 PDF：添加一个矩形或圆形注释。

参数：

rect（rect_like） - 绘制圆形或矩形的矩形，必须是有限且非空的。如果矩形不是等边的，则绘制椭圆。

返回类型：

注释

返回值：

创建的注释。用红色线条（描边）颜色绘制，红色 =（1，0，0），线宽 1，支持填充颜色。

消除

add_redact_annot(quad, text=None, fontname=None, fontsize=11, align=TEXT_ALIGN_LEFT, fill=(1, 1, 1), text_color=(0, 0, 0), cross_out=True)

仅限 PDF：添加一个消除注释。消除注释标识要从文档中删除的内容。添加这样的注释是两个步骤中的第一步。它显示了在随后的步骤中将被删除的内容，即Page.apply_redactions()。

参数：

• quad（quad_like，rect_like） - 指定要删除的（矩形）区域，始终等于注释矩形。这可以是rect_like或quad_like对象。如果指定了四边形，则采用外围矩形。
  
• text（str） - 应用消除（因此删除旧内容后）放置在矩形中的文本。 （在 v1.16.12 中新增）
  
• fontname（str） -当给出text时要使用的字体，否则将被忽略。适用于Page.insert_textbox()的相同规则也适用于 PDF 基本 14 字体中的 CJK 或垂直居中的文本。 （在 v1.16.12 中新增）注意

• 对于现有页面的字体，请使用其引用名称作为fontname（这是其在Page.get_fonts()条目中的item[4]）。
  
• 对于新的非内置字体，请按以下步骤进行：

page.insert_text(point,  # anywhere, but outside all redaction rectangles
    "something",  # some non-empty string
    fontname="newname",  # new, unused reference name
    fontfile="...",  # desired font file
    render_mode=3,  # makes the text invisible
)
page.add_redact_annot(..., fontname="newname") 

• 字体大小（float） – 用于替换文本的字体大小。如果文本太大无法容纳，将尝试多次插入，逐渐减小字体大小至不小于 4。如果仍无法容纳，则根本不会进行文本插入。（新功能，v1.16.12 版）
  
• 对齐（int） – 替换文本的水平对齐方式。有关可用值，请参阅insert_textbox()。如果使用 PDF 内置字体（CJK 或 PDF 基础 14 字体），垂直对齐（大约）居中。（新功能，v1.16.12 版）
  
• 填充（sequence） – 在应用编辑后的矩形的填充颜色。默认为白色 = (1, 1, 1)，如果指定None，也将采用此颜色。若要完全禁用填充颜色，请指定False。在这种情况下，矩形保持透明。（新功能，v1.16.12 版）
  
• 文本颜色（sequence） – 替换文本的颜色。默认为黑色 = (0, 0, 0)。（新功能，v1.16.12 版）
  
• 划掉（bool） – 向注释矩形添加两条对角线。（新功能，v1.17.2 版）
  

返回类型：

Annot

返回：

创建的注释。其标准外观类似于红色矩形（无填充颜色），可选显示两条对角线。现在可以通过Annot.update()设置和应用颜色、线宽、虚线、不透明度和混合模式，就像处理其他注释一样。（在 v1.17.2 中有所更改）

显示/隐藏历史记录

apply_redactions(images=PDF_REDACT_IMAGE_PIXELS | 2, graphics=PDF_REDACT_LINE_ART_IF_TOUCHED | 2, text=PDF_REDACT_TEXT_REMOVE | 0)

仅 PDF：删除页面上任何编辑矩形中包含的所有内容。

此方法应用并然后删除页面上的所有编辑。

参数：

• 图像（int） – 如何编辑重叠图像。默认值（2）消除重叠像素。PDF_REDACT_IMAGE_NONE | 0忽略，PDF_REDACT_IMAGE_REMOVE | 1完全移除与任何编辑注释重叠的图像。选项PDF_REDACT_IMAGE_REMOVE_UNLESS_INVISIBLE | 3仅移除实际可见的图像。
  
• 图形（int） - 如何编辑重叠的矢量图形（也称为“线条艺术”或“绘图”）。默认值（2）会删除任何重叠的矢量图形。PDF_REDACT_LINE_ART_NONE | 0 忽略，PDF_REDACT_LINE_ART_IF_COVERED | 1 删除完全包含在编辑注释中的图形。在删除线条艺术时，请注意，描边的矢量图形（即类型“s”或“sf”）的包围矩形要比人们预期的要大：首先，必须在每个方向上至少添加路径线宽的 50％ 才能真正包含所有的绘图。如果提供了所谓的“斜角限制”（请参见 PDF 规范的第 121 页），则扩展值为miter * width / 2。因此，当让所有默认设置（宽度 = 1，斜角 = 10）时，编辑矩形在每个方向上至少应大出 5 点。
  
• 文本（int） - 是否编辑重叠的文本。默认值PDF_REDACT_TEXT_REMOVE | 0 删除所有边界框与任何编辑矩形重叠的字符。这符合编辑注释的原始法律/数据保护意图。然而，其他用例可能需要在编辑矢量图形或图像时保留文本。这可以通过设置 text=True|PDF_REDACT_TEXT_NONE | 1 来实现。这不符合编辑注释的数据保护意图。请自行承担风险。
  

返回：

如果至少处理了一个编辑注释，则返回 True，否则返回 False。

注意

• 包含在编辑矩形中的文本将会被物理删除，不再显示在页面上（假设使用适当的垃圾选项执行 Document.save()，且不再出现在例如文本提取或其他任何地方。所有的编辑注释也将被删除。其他注释不受影响。
  
• 所有重叠的链接都将被删除。如果链接的矩形覆盖了文本，则只删除文本的重叠部分。相似的情况也适用于被链接矩形覆盖的图像。
  
• 默认选项 PDF_REDACT_IMAGE_PIXELS（在 v1.18.0 中更改）将图像的重叠部分涂成空白。选项 0 不触及任何图像，而选项 1 将删除任何与重叠重叠的图像。
  
• 对于选项 images=PDF_REDACT_IMAGE_REMOVE，仅删除了本页对图像的引用 - 不一定删除了图像本身。只有当不再完全引用图像时（假设适当的垃圾收集选项），图像才会从文件中完全删除。
  
• 对于选项 images=PDF_REDACT_IMAGE_PIXELS，将创建一个 PNG 格式的新图像，页面将使用该图像替代原始图像。原始图像在此过程中不会被删除或替换，因此其他页面可能仍然显示原始图像。此外，新修改的 PNG 图像目前未压缩存储。在选择正确的垃圾收集方法和保存期间的压缩选项时，请牢记这些方面。
  
• 文本删除是按字符进行的：如果字符的 bbox 与红色区域矩形有非空重叠（在 MuPDF v1.17 中更改），则删除该字符。根据字体属性和/或所选行高，可能会删除不需要的文本部分。在文本搜索之前，使用Tools.set_small_glyph_heights()并传入True参数可能有助于防止这种情况发生。
  
• 红 action 是替换 PDF 中单词的简单方法，或者只是物理上将它们删除。使用某些文本提取或搜索方法找到单词“secret”，并插入使用“xxxxxx”作为替换文本的遮挡。

• 如果替换的内容比原始内容长，请小心，这可能导致外观尴尬，换行或根本没有新文本。
  
• 由于一些原因，新文本可能不会像旧文本那样精确地位于同一行上——特别是如果替换字体不是 CJK 或 PDF Base 14 Fonts 之一。
  

显示/隐藏历史记录 * v1.16.11 中的新功能

• 在 v1.16.12 中更改：以前的mark参数已经消失。相反，各自的矩形将填充红色注释的个别fill颜色。如果注释中提供了text，那么将调用insert_textbox()来插入它。
  
• 在 v1.18.0 中更改：增加了处理与遮挡区域重叠的图像的选项。
  
• 在 v1.23.27 中更改：增加了删除图形的选项。
  
• 在 v1.24.2 中更改：增加了keep_text选项以保留文本不变。
  

add_polyline_annot(points)

add_polygon_annot(points)

仅适用于 PDF：添加一个由线连接给定点的注释。多边形的第一个和最后一个点会自动连接，这不会发生在折线上。矩形会自动创建为包含点的最小矩形，每个点周围都有半径为 3（= 3 * 线宽）的圆。以下展示了一个已修改颜色和线端的“折线”。

参数：

points（list）– 一个point_like对象列表。

返回类型：

注释

返回：

创建的注释。它以黑色线条绘制，线宽为 1，无填充颜色但支持填充颜色。使用注释的方法进行任何更改，以实现类似于这样的效果：

add_underline_annot(quads=None, start=None, stop=None, clip=None)

add_strikeout_annot(quads=None, start=None, stop=None, clip=None)

add_squiggly_annot(quads=None, start=None, stop=None, clip=None)

add_highlight_annot(quads=None, start=None, stop=None, clip=None)

仅适用于 PDF：这些注释通常用于标记先前某种方式定位过的文本（例如通过Page.search_for()）。但这不是必须的：你可以自由地“标记”任何东西。

每种注释类型都选择标准的（仅支持描边 – 不支持填充颜色）颜色：用于高亮的黄色，用于删除线的红色，用于下划线的绿色，以及用于波浪线的品红色。

所有这四种方法都将参数转换为 Quad 对象列表。然后，注释矩形将被计算为包围所有这些四边形。

注意

search_for() 返回一个 Rect 或 Quad 对象列表。这样的列表可以直接用作这些注释类型的参数，并将为搜索字符串的所有出现提供一个共同的注释：

>>> # prefer quads=True in text searching for annotations!
>>> quads = page.search_for("pymupdf", quads=True)
>>> page.add_highlight_annot(quads) 

注意

显然，文本标记注释需要知道要标记的区域的顶部、底部、左侧和右侧是什么。如果参数是 quads，则此信息由四边形点序列提供。相比之下，矩形提供的信息要少得多 – 这可以从一个矩形的四个角形成的 24 个不同的四边形这一事实中看出来。

因此，我们强烈建议使用 quads 选项进行文本搜索，以确保正确的注释。类似的考虑也适用于使用 Page.get_text() 的 “dict” / “rawdict” 选项提取的文本段标记。有关如何在这种情况下计算四边形的详细信息，请参见 FAQ 中的 “如何标记非水平文本” 部分。

参数：

• quads（rect_like、quad_like、list、tuple） – 要标记的位置 – 矩形或四边形。 （在 v1.14.20 中已更改）列表或元组必须由 rect_like 或 quad_like 项目组成（或两者的混合）。每个项目必须是有限的、凸的和非空的（适用时）。如果要使用以下参数，请将此参数设置为 None（在 v1.16.14 中已更改）。反之亦然：如果不是 None，则剩余参数必须为 None。
  
• start（point_like） – 从此点开始标记文本。默认为 clip 的左上点。如果 quads 为 None，必须提供。（自 v1.16.14 新增）
  
• stop（point_like） – 在此点停止标记文本。默认为 clip 的右下点。如果 quads 为 None，必须使用。（自 v1.16.14 新增）
  
• clip（rect_like） – 仅考虑与此区域相交的文本行。默认为页面矩形。仅在提供 start 和 stop 时使用。（自 v1.16.14 新增）
  

返回类型：

Annot 或 None（在 v1.16.14 中已更改）。

返回：

创建的注释。如果 quads 是空列表，则不会创建任何注释（在 v1.16.14 中已更改）。

注意

您可以使用参数 start、stop 和 clip 来突出显示两个红点之间的连续线（从 v1.16.14 开始）。利用 clip 进一步减少所选行的边界框，从而处理例如多列页面。以下是在具有三个文本列的页面上创建的多行突出显示。

cluster_drawings(clip=None, drawings=None, x_tolerance=3, y_tolerance=3)

根据它们的几何邻近性对集群矢量图形（同义词为线框图或绘图）进行聚类。该方法遍历Page.get_drawings()的输出，并连接那些 path["rect"] 之间距离小于某些容差值的路径。结果是一系列矩形，每个矩形都包围着像表格（带有网格线）、饼图、条形图等的东西。

参数：

• clip (rect_like) – 仅考虑此区域内的路径。默认为整个页面。
  
• drawings (list) – （可选）提供先前生成的Page.get_drawings()的输出。如果为 None，则执行该方法。
  
• x_tolerance (float) –
  

find_tables(clip=None, strategy=None, vertical_strategy=None, horizontal_strategy=None, vertical_lines=None, horizontal_lines=None, snap_tolerance=None, snap_x_tolerance=None, snap_y_tolerance=None, join_tolerance=None, join_x_tolerance=None, join_y_tolerance=None, edge_min_length=3, min_words_vertical=3, min_words_horizontal=1, intersection_tolerance=None, intersection_x_tolerance=None, intersection_y_tolerance=None, text_tolerance=None, text_x_tolerance=None, text_y_tolerance=None, add_lines=None)

查找页面上的表格并返回相关信息的对象。通常，许多参数的默认值将足够使用。只有在极端情况下才需要调整。

PyMuPDF 1.24.4 中文文档（八）（4）https://developer.aliyun.com/article/1559659