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

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

示例

这里有些例子，说明了一些可实现的效果。所有图片显示了一些文本，由某个矩阵控制并相对于固定参考点（红点）插入。

1. Identity 矩阵执行无操作。

1. 缩放矩阵 Matrix(2, 0.5) 在水平方向拉伸 2 倍，在垂直方向收缩 0.5 倍。

1. 属性Matrix.e 和 Matrix.f 水平和垂直移动。接下来向右移动 10，向下移动 20。

1. 负 Matrix.a 会导致左右翻转。

1. 负 Matrix.d 会导致上下翻转。

1. 属性Matrix.b沿 x 轴向上/向下倾斜。

1. 属性Matrix.c沿 y 轴向左/向右倾斜。

1. 矩阵 Matrix(beta) 对正角度 beta 进行逆时针旋转。

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

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

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

大纲

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

大纲（或“书签”），是文档的属性。如果不是None，它代表文档的第一个大纲项。其属性反过来定义此项的特征，并指向“水平”或向下方向的其他大纲项。通过跟随这些“指针”，可以恢复所有大纲项的完整树状结构，例如传统目录（TOC）。

类 API

class Outline

down

同级别下面的下一个大纲项。如果该项没有子项，则为None。

类型：

大纲

next

同级别的下一个大纲项。如果这是其级别中的最后一个，则为None。

类型：

大纲

page

书签指向的页面号码（基于 0）。

类型：

整数

title

项目的标题作为字符串或None。

类型：

字符串

is_open

指示器显示子大纲是否应展开（True）或折叠（False）。这些信息由 PDF 阅读器软件解释。

类型：

布尔

is_external

一个布尔值，指定目标是否在当前文档之外（True）。

类型：

布尔

uri

指定链接目标的字符串。此属性的含义应与属性is_external一起评估：

• is_external 为 true：uri 指向当前 PDF 之外的某个目标，可以是互联网资源（uri 以“http://”或类似方式开头）、另一个文件（uri 以“file:”或“file://”开头）或其他服务，比如电子邮件地址（uri 以“mailto:”开头）。
  
• is_external 为 false：uri 将为None或指向内部位置。对于 PDF 文档，这应该是*#nnnn*，表示基于 1 的页码nnnn，或命名位置。其他文档类型的格式不同，例如 XPS 文档中的“…/FixedDoc.fdoc#PG_2_LNK_1”表示第 2 页（基于 1）。
  

类型：

字符串

dest

链接目标详细信息对象。

类型：

linkDest

你对这个页面有什么反馈？

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

此文档覆盖所有 1.24.4 版本及以下版本。

页面

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

代表文档页面的类。页面对象通过Document.load_page()或通过像doc[n]这样的文档索引创建 - 它没有独立的构造函数。

文档和其页面之间存在父子关系。如果文档关闭或删除，所有现存的页面对象（及其各自的子对象）将变得不可用（“孤立”）：如果正在使用页面的属性或方法，则会引发异常。

几个页面方法具有方便使用的文档对应项。本章末尾将找到一个简介。

注意

在本章中，我们多次使用术语坐标。理解其基本概念并确保对坐标系部分感到自在至关重要。

修改页面

只有对 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 提供的“注释”图标的 20 x 20 矩形的左上角点。
  
• text (str) – 注释文本。双击或悬停图标时将显示。可以包含任何拉丁字符。
  
• icon (str) – 选择“Note”（默认）、“Comment”、“Help”、“Insert”、“Key”、“NewParagraph”、“Paragraph”中的一个作为体现文本的视觉符号[4]。（自 v1.16.0 起新功能）
  

返回类型：

注释

返回：

创建的注释。描边颜色为黄色 = (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 之一——不支持右对齐。（自 v1.17.0 起新功能）
  
• rotate (int) – 文本方向。可接受的值为 0、90、270，无效条目将被设为零。
  

返回类型：

注释

返回：

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

显示/隐藏历史记录

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（sequence）- 包含一个或多个列表的列表，每个子列表都包含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()相同的规则适用于此方法内部调用的Page.apply_redactions() - 替换文本将是垂直居中的，如果这是 CJK 或 PDF Base 14 Fonts 之一。（在 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") 

• fontsize（float） - 用于替换文本的fontsize。如果文本太大而无法容纳，则将尝试进行多次插入，逐渐减小fontsize至不低于 4。如果文本仍然无法容纳，则根本不会进行文本插入。（在 v1.16.12 中新增）
  
• align（int） - 替换文本的水平对齐方式。查看insert_textbox()获取可用值。如果使用 PDF 内置字体（CJK 或 PDF Base 14 Fonts）则垂直对齐方式（大约）居中。（在 v1.16.12 中新增）
  
• fill（sequence） - 应用遮挡后矩形的填充颜色。默认为white = (1, 1, 1)，如果指定None也是如此。要完全取消填充颜色，请指定False。在这种情况下，矩形保持透明。（在 v1.16.12 中新增）
  
• text_color（sequence） - 替换文本的颜色。默认为black = (0, 0, 0)。（在 v1.16.12 中新增）
  
• cross_out（bool） - 向注释矩形添加两条对角线。（在 v1.17.2 中新增）
  

返回类型：

Annot

返回：

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

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

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

仅适用于 PDF：删除页面上任何遮挡矩形中包含的所有内容。

此方法应用然后从页面中删除所有遮挡。

参数：

• images（int） - 如何编辑重叠的图像。默认值（2）会消除重叠的像素。PDF_REDACT_IMAGE_NONE | 0表示忽略，PDF_REDACT_IMAGE_REMOVE | 1完全删除任何与任何遮挡注释重叠的图像。选项PDF_REDACT_IMAGE_REMOVE_UNLESS_INVISIBLE | 3仅删除实际可见的图像。（在 v1.16.12 中新增）
  
• 图形 (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参数可以帮助防止这种情况。
  
• 遮罩是在 PDF 中替换单个单词或仅物理删除它们的简单方法。使用某些文本提取或搜索方法定位单词“secret”，并为每个出现插入遮罩，使用“xxxxxx”作为替换文本。

• 如果替换文本比原始文本更长，请谨慎 – 这可能导致外观尴尬，换行或根本没有新文本。
  
• 由于多种原因，新文本可能不会像旧文本一样精确地位于同一行上 – 尤其是如果替换字体不是 CJK 或 PDF 基础 14 字体之一。
  

显示/隐藏历史记录 * 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（列表） – 一个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()）。但这不是必须的：您可以自由地“标记”任何内容。

标准（仅边框 – 不支持填充颜色）的颜色根据注释类型选择：黄色用于高亮显示，红色用于删除线，绿色用于下划线，洋红色用于波浪下划线。

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

注意

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

>>> # prefer quads=True in text searching for annotations!
>>> quads = page.search_for("pymupdf", quads=True)
>>> page.add_highlight_annot(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 新增）
  

返回类型：

注释 或 None （自 v1.16.14 更改）。

返回：

创建的注释。如果quads为空列表，则不创建注释（自 v1.16.14 更改）。

注意

您可以使用参数start，stop和clip来突出显示两个红点之间的连续行（从 v1.16.14 开始）。利用clip进一步减少所选行的边界框，从而处理例如多列页面。以下是在具有三个文本列的页面上创建的多行高亮显示示例，通过相应设置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)

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

参数：

• clip (rect_like) – 指定要考虑的页面矩形内的区域，忽略其余部分。默认为整个页面。
  
• strategy (str) –
  请求一个表格检测策略。有效值为“lines”，“lines_strict”和“text”。
  默认为**“lines”**，它使用页面上的所有矢量图形来检测网格线。
  策略**“lines_strict”**会忽略没有边框的矩形矢量图形。有时单个文本片段具有背景颜色，这可能导致错误的列或行。此策略会忽略它们，从而增加检测精度。
  如果指定了**“text”**，则使用文本位置生成“虚拟”列和/或行边界。使用min_words_*来请求考虑其坐标的单词数量。
  使用参数vertical_strategy和horizontal_strategy 代替以更精细地处理尺寸。
  
• horizontal_lines (sequence*[floats]*) – 行的 y 坐标。如果提供，将不会尝试识别额外的表格行。这会影响表格检测。
  
• vertical_lines (sequence*[floats]*) – 列的 x 坐标。如果提供，将不会尝试识别额外的表格列。这会影响表格检测。
  
• min_words_vertical (int) – 对于垂直策略选项“text”很重要：至少必须有这么多单词重合才能建立虚拟列边界。
  
• min_words_horizontal (int) – 仅对水平策略选项“text”有效：至少有这么多单词重合才能确定一个虚拟行的边界。
  
• snap_tolerance (float) – 如果两条水平线的 y 值之差不超过此值，则将它们捕捉到一起。垂直线同理。默认值为 3。可以使用snap_x_tolerance和snap_y_tolerance分别指定各个维度的值。
  
• join_tolerance (float) – 如果两条线的终点和起点之差不超过此值（点），则将它们连接成一条线。默认值为 3。可以使用join_x_tolerance和join_y_tolerance分别指定各个维度的值。
  
• edge_min_length (float) – 如果线段长度不超过此值（点），则忽略该线段。默认值为 3。
  
• intersection_tolerance (float) – 将线段组合成单元格边框时，正交线段必须在此值（点）以内才被视为相交。默认值为 3。可以使用intersection_x_tolerance和intersection_y_tolerance分别指定各个维度的值。
  
• text_tolerance (float) – 如果字符之间的距离不大于此值（点），则将它们组合成单词。默认值为 3。可以使用text_x_tolerance和text_y_tolerance分别指定各个维度的值。
  
• add_lines (tuple*,list) – 指定一组“线条”（即point_like对象的对）作为额外的*“虚拟”矢量图形。这些线条可能有助于表格和/或单元格的检测，并且不会影响检测策略的其他方面。与horizontal_lines和vertical_lines参数不同，这些线条不会阻止以其他方式检测行或列。这些线条在连接、捕捉、相交、最小长度和包含在clip矩形内等方面将被像“真实”矢量图形一样处理。同样，与任何坐标轴不平行的线条将被忽略。
  

返回：

一个具有以下重要属性的TableFinder对象：

• cells: 页面上所有被识别为表格单元格的边界框列表（跨所有表格）。每个单元格是一个rect_like元组(x0, y0, x1, y1)或None。
  
• tables: Table对象的列表。如果页面没有表格，则为空列表[]。可以通过tabs.tables[n]或更简洁的方式tabs[n]来访问单个表格。但是TableFinder对象本身也是其表格的序列。这意味着如果tabs是一个TableFinder对象，则表格“n”可以通过tabs.tables[n]和tabs[n]两种方式获取。
  
• Table对象具有以下属性：

• bbox: 表的边界框，表示为元组(x0, y0, x1, y1)。
  
• cells: 表格单元格的边界框（元组列表）。一个单元格也可以是None。
  
• extract(): 此方法返回每个表格单元格的文本内容，作为字符串列表的列表。
  
• to_markdown(): 此方法返回一个以Markdown 格式（与 Github 兼容）的字符串作为表。支持的查看器可以将字符串呈现为表格。此输出对于 LLM/RAG feeds 的小令牌大小特别有益。Pandas 数据框（见下面的to_pandas()方法）提供了一个等效的 Markdown 表输出，但对于人眼更易读。
  
• to_pandas(): 此方法将表格作为pandas DataFrame返回。DataFrame 是非常多才多艺的对象，允许大量的表操作方法和输出到几乎 20 种众所周知的格式，其中包括 Excel 文件、CSV、JSON、Markdown 格式化的表格等等。DataFrame.to_markdown()生成一个适用于 Github 的 Markdown 格式，优化了人类的可读性。但是，该方法还需要安装包 tablutate)，除了 pandas 本身之外。
  
• header: 包含表头信息的TableHeader对象。
  
• col_count: 包含表格列数的整数。
  
• row_count: 包含表格行数的整数。
  
• rows: 一个包含两个属性的TableRow对象列表，bbox是行的边界框，cells是包含在此行中的表格单元格的列表。
  

• TableHeader对象具有以下属性：

• bbox: 标题的边界框。
  
• cells: 包含各列名称的边界框列表。
  
• names: 包含每个单元框文本的字符串列表。它们代表列名 - 在将表导出为 pandas 数据框、Markdown 等时使用。
  
• external: 一个布尔值，指示标题边界框是否位于表格主体之外（True）或不是。表头从不由TableFinder逻辑识别。因此，如果external为真，则标题单元格不是由TableFinder识别的任何单元格的一部分。如果external == False，则第一行是表头。
  

请查看这些Jupyter 笔记本，其中涵盖了标准情况，如一页上的多个表格或跨多页连接表片段。

显示/隐藏历史记录 * 版本 1.23.0 中的新功能

• 版本 1.23.19 中的更改：新增参数add_lines。

重要提示

还有PDF2DOCX 提取表格方法，如果您更喜欢，也可以进行表格提取。

add_stamp_annot(rect, stamp=0)

仅适用于 PDF：例如，向文档添加“橡皮图章”注释，以指示文档的预期用途（“草稿”，“机密”等）。

参数：

• rect (rect_like) – 放置注释的矩形区域。
  
• stamp (int) – 印章文本的标识号。有关可用印章，请参阅印章注释图标。
  

注意

• 印章的文本和其边界线将自动调整大小，并水平和垂直居中在给定的矩形中。Annot.rect会自动计算以适应给定的宽度，通常会比此参数小。
  
• 选择的字体是“Times Bold”，文本将是大写。
  
• 可以使用Annot.set_opacity()更改外观，并通过设置“stroke”颜色（不支持“fill”颜色）。
  
• 可用于创建水印图像：在临时 PDF 页面上创建一个透明度较低的印章注释，然后使用alpha=True从中创建一个像素图（可能还要旋转它），丢弃临时 PDF 页面，并使用insert_image()将像素图插入到目标 PDF 中。
  

add_widget(widget)

仅适用于 PDF：向页面添加 PDF 表单字段（“小部件”）。这也将 PDF 转换为表单 PDF。由于小部件有大量不同的选项可用，我们开发了一个新类 Widget，其中包含可能的 PDF 字段属性。它必须用于表单字段的创建和更新。

Parameters:

widget (Widget) – 必须事先创建的 Widget 对象。

Returns:

一个小部件注释。

delete_annot(annot)

• 现在移除还包括任何绑定的‘弹出’或响应注释以及相关对象（自 v1.16.6 起更改）。

仅适用于 PDF：从页面中删除注释并返回下一个注释。

Parameters:

annot (Annot) – 要删除的注释。

Return type:

Annot

Returns:

被删除的注释后面的注释。请记住，物理删除需要保存到带有垃圾> 0 的新文件中。

delete_widget(widget)

仅适用于 PDF：从页面中删除字段并返回下一个字段。

Parameters:

widget (Widget) – 要删除的小部件。

Return type:

Widget

Returns:

被删除的注释后面的小部件。请记住，物理删除需要保存到带有垃圾> 0 的新文件中。

显示/隐藏历史记录（自 v1.18.4 起新增）

delete_link(linkdict)

仅适用于 PDF：从页面中删除指定的链接。参数必须是get_links()的原始项，参见 get_links()条目的描述。这是因为字典的“xref”键标识要删除的 PDF 对象。

Parameters:

linkdict (dict) – 要删除的链接。

insert_link(linkdict)

仅适用于 PDF：在此页面上插入新链接。参数必须是由get_links()提供的格式的字典，参见 get_links()条目描述。

参数：

linkdict (dict) – 待插入的链接。

update_link(linkdict)

仅适用于 PDF：修改指定的链接。参数必须是get_links()的（修改后的）原始条目，参见 get_links()条目描述。这是因为字典的“xref”键，该键标识要更改的 PDF 对象的原因。

参数：

linkdict (dict) – 待修改的链接。

警告

如果更新/插入 URI 链接（"kind": LINK_URI），请确保以诸如"http://"，"https://"，"file://", "ftp://"，"mailto:"等消除歧义的字符串开始"uri"键的值。否则，根据您的浏览器或其他“消费者”软件的不同假设，可能会导致意外的默认行为。

get_label()

仅适用于 PDF：返回页面的标签。

返回类型：

str

返回：

类似“vii”的标签字符串，用于罗马编号，如果未定义则为空。

显示/隐藏历史 * v1.18.6 中新增

get_links()

检索页面的所有链接。

返回类型：

列表

返回：

一组字典。有关字典条目的描述，请参阅 get_links()条目描述。如果打算更改页面的链接，请始终使用此方法或Page.links()方法。

links(kinds=None)

返回页面链接的生成器。结果等同于Page.get_links()的条目。

参数：

kinds (sequence) – 一个整数序列，用于按下选择一个或多个链接种类。默认为所有链接。示例：*kinds=(pymupdf.LINK_GOTO,)*将仅返回内部链接。

返回类型：

生成器

返回：

每次迭代的Page.get_links()的条目。

显示/隐藏历史 * v1.16.4 中新增

annots(types=None)

返回页面注释的生成器。

参数：

types (sequence) – 一个整数序列，用于按下选择一个或多个注释类型。默认为所有注释。示例：types=(pymupdf.PDF_ANNOT_FREETEXT, pymupdf.PDF_ANNOT_TEXT)将仅返回“FreeText”和“Text”注释。

返回类型：

生成器

返回：

每次迭代的注释。

警告

你不能安全地更新注释在这个生成器内部。这是因为大多数注释更新需要通过page = doc.reload_page(page)重新加载页面。为了避免此限制，请首先制作注释的交叉引用号列表，然后再对这些号码进行迭代：

In [4]: xrefs = [annot.xref for annot in page.annots(types=[...])]
In [5]: for xref in xrefs:
   ...:     annot = page.load_annot(xref)
   ...:     annot.update()
   ...:     page = doc.reload_page(page)
In [6]: 

显示/隐藏历史 * v1.16.4 中新增

widgets(types=None)

返回页面表单字段的生成器。

参数：

types (sequence) – 一个整数序列，用于选择一个或多个小部件类型。默认为所有表单字段。例如：types=(pymupdf.PDF_WIDGET_TYPE_TEXT,) 将仅返回文本字段。

返回类型:

generator

返回:

为每次迭代生成一个 Widget。

显示/隐藏历史记录 * 从 v1.16.4 版新增

write_text(rect=None, writers=None, overlay=True, color=None, opacity=None, keep_proportion=True, rotate=0, oc=0)

仅适用于 PDF：将一个或多个 TextWriter 对象的文本写入页面。

参数:

• rect (rect_like) – 文本放置的位置。如果省略，则使用文本编写器的矩形联合。
  
• writers (sequence) – 一个非空元组/列表，包含一个或多个 TextWriter 对象。
  
• opacity (float) – 设置透明度，覆盖文本编写器中的值。
  
• color (sequ) – 设置文本颜色，覆盖文本编写器中的值。
  
• overlay (bool) – 将文本放置在前景或背景。
  
• keep_proportion (bool) – 保持纵横比。
  
• rotate (float) – 以任意角度旋转文本。
  
• oc (int) – xref 的一个OCG或OCMD。（从 v1.18.4 版开始新增）
  

注意

参数 overlay, keep_proportion, rotate 和 oc 的含义与Page.show_pdf_page()中的含义相同。

显示/隐藏历史记录 * 从 v1.16.18 版新增

insert_text(point, text, fontsize=11, fontname='helv', fontfile=None, idx=0, color=None, fill=None, render_mode=0, border_width=1, encoding=TEXT_ENCODING_LATIN, rotate=0, morph=None, stroke_opacity=1, fill_opacity=1, overlay=True, oc=0)

仅适用于 PDF：从point_like point 开始插入文本。参见Shape.insert_text()。

显示/隐藏历史记录 * 从 v1.18.4 版更改

insert_textbox(rect, buffer, fontsize=11, fontname='helv', fontfile=None, idx=0, color=None, fill=None, render_mode=0, border_width=1, encoding=TEXT_ENCODING_LATIN, expandtabs=8, align=TEXT_ALIGN_LEFT, charwidths=None, rotate=0, morph=None, stroke_opacity=1, fill_opacity=1, oc=0, overlay=True)

仅适用于 PDF：将文本插入到指定的rect_like rect 中。参见Shape.insert_textbox()。

显示/隐藏历史记录 * 从 v1.18.4 版更改

insert_htmlbox(rect, text, *, css=None, scale_low=0, archive=None, rotate=0, oc=0, opacity=1, overlay=True)

仅适用于 PDF： 将文本插入到指定的矩形中。此方法与Page.insert_textbox()和TextWriter.fill_textbox()方法相似，但功能更强大。通过让 Story 对象执行所有必要的处理来实现这一点。

• 参数text可以像其他方法中一样是一个字符串。但它将被解释为 HTML 源码，因此也可能包含 HTML 语言元素，包括样式。css参数可用于传递额外的样式指令。
  
• 自动换行在单词边界生成。软连字符 "­"（或 ­）可用于引起连字和因此可能导致换行。但是，只有通过 HTML 标签
才能实现强制换行 - "\n"会被忽略并被视为空格。
  
• 通过此方法可以实现以下内容：

• 样式效果如粗体、斜体、文本颜色、文本对齐、字体大小或字体切换。
  
• 文本可以包含任意语言 – 包括从右到左 的语言。
  
• 印度文字（Devanagari）及亚洲的其他几种文字都有高度复杂的连字系统，其中两个或更多 Unicode 字符共同生成一个字形。本文使用软件包HarfBuzz 处理这些情况，并产生正确的输出。
  
• 可以通过 HTML 标签 包含图像 – Story 会处理适当的布局。这是插入图像的替代选项，与Page.insert_image()相比。
  
• HTML 表格（标签 ）可以包含在文本中，并将得到适当处理。
  
• 当存在时，链接会自动生成。
  
• 如果内容不适合矩形框，则开发人员有两个选择：
• 或者只是关于此的通知（并接受无操作，就像其他文本框插入方法一样），
  
• 或（scale_low=0 - 默认值）缩小内容直至适合。
  

参数：

• rect（rect_like） – 页面上接收文本的矩形。
  
• text（str*,*Story) – 要写入的文本。可以包含混合的纯文本和带有样式指令的 HTML 标签。或者，可以指定一个 Story 对象（在这种情况下，将省略内部 Story 生成步骤）。Story 必须具备所有所需的样式和存档信息。
  
• css（str） – 可选的包含额外 CSS 指令的字符串。如果text是一个 Story，则此参数将被忽略。
  
• scale_low（float） – 如果需要，将内容缩小以适应目标矩形。这设置了缩小限制。默认为 0，无限制。值为 1 表示不允许缩小。例如，0.2 的值意味着最多缩小 80%。
  
• archive（Archive） – 指向可以找到图像或非标准字体的位置的 Archive 对象。如果text引用图像或非标准字体，则需要此参数。如果text是一个 Story，则此参数将被忽略。
  
• rotate（int） –值为 0、90、180、270 之一。根据此值，文本将被填充：
• 0: 从左上到右下。
  
• 90: 从左下到右上。
  
• 180: 从右下到左上。
  
• 270: 从右上到左下。
  
  
• oc（int）– OCG / OCMD 的交叉引用或 0。有关详细信息，请参阅 Page.show_pdf_page()。
  
• opacity（float）– 设置内容的填充和描边不透明度。只考虑 0 <= opacity < 1 的值。
  
• overlay（bool）– 将文本放在其他内容前面。有关详细信息，请参阅 Page.show_pdf_page()。
  

返回：

一对浮点数 (spare_height, scale)。

• spare_height：如果内容未适合，则为 -1，否则为 >= 0。这是未使用的（仍可用）矩形条的高度。仅在 scale = 1（未进行缩放）时为正。
  
• scale：缩放因子，0 < scale <= 1。
  

请参阅此部分的示例中的菜谱：如何使用 HTML 文本填充框。

显示/隐藏历史记录 * v1.23.8 中新增；仅限基准再次。

• 新增于 v1.23.9：opacity 参数。

绘图方法

draw_line(p1, p2, color=(0,), width=1, dashes=None, lineCap=0, lineJoin=0, overlay=True, morph=None, stroke_opacity=1, fill_opacity=1, oc=0)

仅限 PDF：从 p1 到 p2 绘制一条直线（point_like s）。参见 Shape.draw_line()。

显示/隐藏历史记录 * v1.18.4 中的更改

draw_zigzag(p1, p2, breadth=2, color=(0,), width=1, dashes=None, lineCap=0, lineJoin=0, overlay=True, morph=None, stroke_opacity=1, fill_opacity=1, oc=0)

仅限 PDF：从 p1 到 p2 绘制一条锯齿线（point_like s）。参见 Shape.draw_zigzag()。

显示/隐藏历史记录 * v1.18.4 中的更改

draw_squiggle(p1, p2, breadth=2, color=(0,), width=1, dashes=None, lineCap=0, lineJoin=0, overlay=True, morph=None, stroke_opacity=1, fill_opacity=1, oc=0)

仅限 PDF：从 p1 到 p2 绘制一条波浪线（point_like s）。参见 Shape.draw_squiggle()。

显示/隐藏历史记录 * v1.18.4 中的更改

draw_circle(center, radius, color=(0,), fill=None, width=1, dashes=None, lineCap=0, lineJoin=0, overlay=True, morph=None, stroke_opacity=1, fill_opacity=1, oc=0)

仅限 PDF：在 中心（point_like）周围绘制一个半径为 radius 的圆。参见 Shape.draw_circle()。

显示/隐藏历史记录 * v1.18.4 中的更改

draw_oval(quad, color=(0,), fill=None, width=1, dashes=None, lineCap=0, lineJoin=0, overlay=True, morph=None, stroke_opacity=1, fill_opacity=1, oc=0)

仅限 PDF：在给定的 rect_like 或 quad_like 内绘制椭圆（椭圆）。参见 Shape.draw_oval()。

显示/隐藏历史记录 * v1.18.4 中的更改

draw_sector(center, point, angle, color=(0,), fill=None, width=1, dashes=None, lineCap=0, lineJoin=0, fullSector=True, overlay=True, closePath=False, morph=None, stroke_opacity=1, fill_opacity=1, oc=0)

仅限 PDF：绘制一个圆形扇形，可选择将弧连接到圆心（如馅饼片）。参见 Shape.draw_sector()。

显示/隐藏历史记录 * v1.18.4 中的更改

draw_polyline(points, color=(0,), fill=None, width=1, dashes=None, lineCap=0, lineJoin=0, overlay=True, closePath=False, morph=None, stroke_opacity=1, fill_opacity=1, oc=0)

仅适用于 PDF：绘制由一系列point_like s 定义的多条连接线。参见Shape.draw_polyline()。

显示/隐藏历史记录 * 在 v1.18.4 版本中更改

draw_bezier(p1, p2, p3, p4, color=(0,), fill=None, width=1, dashes=None, lineCap=0, lineJoin=0, overlay=True, closePath=False, morph=None, stroke_opacity=1, fill_opacity=1, oc=0)

仅适用于 PDF：从p1到p4绘制一个立方贝塞尔曲线，控制点为p2和p3（均为point_like s）。参见Shape.draw_bezier()。

显示/隐藏历史记录 * 在 v1.18.4 版本中更改

draw_curve(p1, p2, p3, color=(0,), fill=None, width=1, dashes=None, lineCap=0, lineJoin=0, overlay=True, closePath=False, morph=None, stroke_opacity=1, fill_opacity=1, oc=0)

仅适用于 PDF：这是*draw_bezier()*的特例。参见Shape.draw_curve()。

显示/隐藏历史记录 * 在 v1.18.4 版本中更改

draw_rect(rect, color=(0,), fill=None, width=1, dashes=None, lineCap=0, lineJoin=0, overlay=True, morph=None, stroke_opacity=1, fill_opacity=1, radius=None, oc=0)

仅适用于 PDF：绘制矩形。参见Shape.draw_rect()。

显示/隐藏历史记录 * 在 v1.18.4 版本中更改

• 在 v1.22.0 版本中更改：添加了radius参数。

draw_quad(quad, color=(0,), fill=None, width=1, dashes=None, lineCap=0, lineJoin=0, overlay=True, morph=None, stroke_opacity=1, fill_opacity=1, oc=0)

仅适用于 PDF：绘制四边形。参见Shape.draw_quad()。

显示/隐藏历史记录 * 在 v1.18.4 版本中更改

insert_font(fontname='helv', fontfile=None, fontbuffer=None, set_simple=False, encoding=TEXT_ENCODING_LATIN)

仅适用于 PDF：添加新字体以供文本输出方法使用，并返回其xref。如果文件中尚未存在，将添加字体定义。支持内置Base14_Fonts和 CJK 字体。字体也可以提供为文件路径或包含字体文件图像的内存区域。

参数：

• fontname（str） –
  输出文本时用于引用此字体的名称。一般来说，您在这里有“自由”选择（但请参考 Adobe PDF 参考手册，第 16 页，第 7.3.5 节，了解构建合法 PDF 名称的正式描述）。然而，如果它与Base14_Fonts或 CJK 字体之一匹配，fontfile 和 fontbuffer 将被忽略。
  换句话说，您不能通过fontfile / fontbuffer 插入字体并给它一个保留的fontname。
  注意
  可以在任意大小写混合的情况下指定保留字体名称，并匹配正确的内置字体定义：字体名称“helv”，“Helv”，“HELV”，“Helvetica”等均导致相同的字体定义“Helvetica”。但从页面的角度来看，这些是不同的引用。在页面上使用不同的编码变体（拉丁文、希腊文、西里尔文）时，可以利用这一事实。
  
• fontfile（str） – 字体文件的路径。如果使用，fontname 必须与所有保留名称不同。
  
• fontbuffer (bytes/bytearray) – 字体文件的内存映像。如果使用，fontname 必须与所有保留名称不同。此参数通常与Font.buffer结合使用，用于支持/可用于 Font 的字体。
  
• set_simple (int) – 仅适用于fontfile / fontbuffer的情况：强制将其视为“简单”字体，即仅使用字符代码至 255。
  
• encoding (int) – 仅适用于“Helvetica”、“Courier”和“Times”系列的Base14_Fonts。选择可用编码之一：Latin（0）、Cyrillic（2）或 Greek（1）。对于“Symbol”和“ZapfDingBats”，只使用默认值（0 = Latin）。
  

Rytpe：

int

返回：

安装字体的xref。

注

内置字体不会导致字体文件的包含。因此生成的 PDF 文件将保持较小。但是，您的 PDF 查看器软件负责生成适当的外观 -  并且关于每个软件如何处理这些外观可能存在差异。对于 CJK 字体尤其如此。但是在某些情况下，Symbol 和 ZapfDingbats  处理不正确。以下是字体名称及其对应的安装基本字体名称：

Base-14 字体 [1]

字体名称	已安装基本字体	备注
helv	Helvetica	普通
heit	Helvetica-Oblique	斜体
hebo	Helvetica-Bold	粗体
hebi	Helvetica-BoldOblique	粗斜体
cour	Courier	普通
coit	Courier-Oblique	斜体
cobo	Courier-Bold	粗体
cobi	Courier-BoldOblique	粗斜体
tiro	Times-Roman	普通
tiit	Times-Italic	斜体
tibo	Times-Bold	粗体
tibi	Times-BoldItalic	粗斜体
symb	Symbol	[3]
zadb	ZapfDingbats	[3]

CJK 字体 [2]（中国、日本、韩国）

字体名称	已安装基本字体	备注
china-s	Heiti	简体中文
china-ss	Song	简体中文（Serif）
china-t	Fangti	繁体中文
china-ts	Ming	繁体中文（Serif）
japan	Gothic	日本
japan-s	Mincho	日本（Serif）
korea	Dotum	韩文
korea-s	Batang	韩文（Serif）

insert_image(rect, *, alpha=-1, filename=None, height=0, keep_proportion=True, mask=None, oc=0, overlay=True, pixmap=None, rotate=0, stream=None, width=0, xref=0

仅限 PDF：将图像放置在给定的矩形内。该图像可能已存在于 PDF 中，也可能来自于位图、文件或内存区域。

参数：

• rect (rect_like) – 图像放置位置。必须是有限且非空的。
  
• alpha (int) – 已废弃且被忽略。
  
• filename (str) – 图像文件的名称（MuPDF 支持的所有格式 - 请参见支持的输入图像格式）。
  
• height (int) –
  
• keep_proportion (bool) – 保持图像的长宽比。
  
• mask（bytes、bytearray、io.BytesIO）— 内存中的图像——用作基础图像的图像蒙版（alpha 值）。当指定时，必须以文件名或流的形式提供基础图像——并且基础图像不能是已经具有蒙版的图像。
  
• oc（int）—（xref）使图像的可见性取决于此OCG或OCMD。在多次插入的第一次之后被忽略。该属性存储在生成的 PDF 图像对象中，因此控制整个 PDF 中图像的可见性。
  
• overlay— 请参阅公共参数。
  
• pixmap（Pixmap）— 包含图像的 pixmap。
  
• rotate（int）— 旋转图像。必须是 90 度的整数倍。正值逆时针旋转。如果需要按任意角度旋转，请先将图像转换为 PDF（Document.convert_to_pdf()），然后使用 Page.show_pdf_page()。
  
• stream（bytes、bytearray、io.BytesIO）— 内存中的图像（所有 MuPDF 支持的格式——请参阅支持的输入图像格式）。
  
• width（int）—
  
• xref（int）— PDF 中已存在的图像的xref。如果提供，则参数filename、Pixmap、stream、alpha 和 mask将被忽略。页面将简单地接收对现有图像的引用。
  

返回：

嵌入图像的xref。如果再次插入图像，则可以将其用作xref参数，以获得非常显著的性能提升。

此示例在文档的每一页上放置相同的图像：

>>> doc = pymupdf.open(...)
>>> rect = pymupdf.Rect(0, 0, 50, 50)       # put thumbnail in upper left corner
>>> img = open("some.jpg", "rb").read()  # an image file
>>> img_xref = 0                         # first execution embeds the image
>>> for page in doc:
 img_xref = page.insert_image(rect, stream=img,
 xref=img_xref,  2nd time reuses existing image
 )
>>> doc.save(...) 

注意

1. 该方法检测到同一图像的多次插入（如上例所示），并且仅在第一次执行时存储其数据。即使使用默认的xref=0，这也是正确的（尽管性能较差）。
   
2. 该方法无法检测到在打开文件之前是否已将相同的图像作为文件的一部分。
   
3. 您可以使用此方法为页面提供背景或前景图像，例如版权或水印。请记住，如果将水印放在前景中，则需要透明图像……
   
4. 图像可能以未压缩的形式插入，例如，如果使用了 Pixmap，或者图像具有 alpha 通道。因此，在保存文件时考虑使用deflate=True。此外，有多种方法可以控制图像的大小——即使透明度起作用。查看如何将图像添加到 PDF 页面。
   
5. 图像以其原始质量级别存储在 PDF 中。这可能比您的显示所需的要好得多。在插入之前考虑减小图像大小 – 例如，通过使用 pixmap 选项然后缩小或缩放它（参见 Pixmap 章节）。也可以使用 PIL 方法Image.thumbnail()来实现此目的。文件大小的节省可能非常显著。
   
6. 另一种有效的方法在多个页面上显示相同的图像是另一种方法：show_pdf_page()。请参阅Document.convert_to_pdf()获取可用于该方法的中间 PDF。
   

显示/隐藏历史记录 * 从 v1.14.1 版本开始更改：默认情况下，图像保持其宽高比。

• 从 v1.14.11 版本开始更改：增加keep_proportion，rotate参数。
  
• 从 v1.14.13 版本开始更改：
• 图像现在总是位于矩形的中心，即图像和矩形的中心点相等。
  
• 增加对stream作为io.BytesIO的支持。
  
• 从 v1.17.6 版本开始更改：插入矩形不再需要与页面的Page.cropbox有非空交集 [5]。
  
• 从 v1.18.1 版本开始更改：增加mask参数。
  
• 从 v1.18.3 版本开始更改：增加oc参数。
  
• 从 v1.18.13 版本开始更改：
• 允许将图像作为现有图像的 xref 提供。
  
• 增加xref参数。
  
• 返回存储图像的xref。
  
• 从 v1.19.3 版本开始更改：弃用并忽略alpha参数。
  

replace_image(xref, filename=None, pixmap=None, stream=None)

用另一张图像替换 xref 处的图像。

参数：

• xref (整数) – 图像的xref。
  
• filename – 新图像的文件名。
  
• pixmap – 新图像的 Pixmap。
  
• stream – 包含新图像的内存区域。
  

参数 filename，Pixmap，stream 的含义与Page.insert_image() 中相同，特别是这些参数中必须恰好提供一个。

这是一个全局替换： 新图像也将显示在文件中原来显示过的所有位置。

此方法主要用于技术目的。典型用途包括用较小的版本替换大图像，例如低分辨率、灰阶代替彩色等，或更改透明度。

显示/隐藏历史记录 * 在 v1.21.0 版本中新增

delete_image(xref)

删除 xref 处的图像。这有点误导：实际上，图像被用一个小的透明 Pixmap 替换，使用上述Page.replace_image()。但可见效果是等效的。

参数：

xref (整数) – 图像的xref。

This is a global replacement: the image will disappear wherever the old one has been displayed throughout the file.

If you inspect / extract a page’s images by methods like Page.get_images(), Page.get_image_info() or Page.get_text(), the replacing “dummy” image will be detected like so (45, 47, 1, 1, 8, 'DeviceGray', '', 'Im1', 'FlateDecode') and also seem to “cover” the same boundary box on the page.

Show/hide history * New in v1.21.0

get_text(option, *, clip=None, flags=None, textpage=None, sort=False, delimiters=None)

Retrieves the content of a page in a variety of formats. This is a  wrapper for multiple TextPage methods by choosing the output option opt as follows:

• “text” – TextPage.extractTEXT(), default
  
• “blocks” – TextPage.extractBLOCKS()
  
• “words” – TextPage.extractWORDS()
  
• “html” – TextPage.extractHTML()
  
• “xhtml” – TextPage.extractXHTML()
  
• “xml” – TextPage.extractXML()
  
• “dict” – TextPage.extractDICT()
  
• “json” – TextPage.extractJSON()
  
• “rawdict” – TextPage.extractRAWDICT()
  
• “rawjson” – TextPage.extractRAWJSON()
  

Parameters:

• opt (str) –
  A string indicating the requested format, one of the above. A mixture of upper and lower case is supported.
  Values “words” and “blocks” are also accepted (changed in v1.16.3).
  
• clip (rect-like) – restrict extracted text to this rectangle. If None, the full page is taken. Has no effect for options “html”, “xhtml” and “xml”. (New in v1.17.7)
  
• flags (int) – indicator bits to control whether to include images or how text should be handled with respect to white spaces and ligatures. See Text Extraction Flags for available indicators and Text Extraction Flags Defaults for default settings. (New in v1.16.2)
  
• textpage – use a previously created TextPage. This reduces execution time very significantly: by more than 50% and up to 95%, depending on the extraction option. If  specified, the ‘flags’ and ‘clip’ arguments are ignored, because they  are textpage-only properties. If omitted, a new, temporary textpage will  be created. (New in v1.19.0)
  
• sort（bool）– 按垂直、然后水平坐标对输出进行排序。在许多情况下，这应该足以生成“自然”的阅读顺序。对于(X)HTML 和 XML 没有影响。“words”输出选项按单词的 bbox 的(y1, x0)排序。类似的情况适用于“blocks”、“dict”、“json”、“rawdict”、“rawjson”：它们都按相应块 bbox 的(y1, x0)排序。如果指定为“text”，则内部使用“blocks”。（从 v1.19.1 版本开始）
  
• delimiters（str）– 使用这些字符作为额外的单词分隔符，配合“words”输出选项使用（否则被忽略）。默认情况下，所有空格（包括不间断空格0xA0）表示单词的起始和结束。现在你可以指定更多的字符来引起这种情况。例如，默认设置将把"john.doe@outlook.com"视为一个单词。如果你指定delimiters="@."，那么四个单词"john"、"doe"、"outlook"、"com"将被返回。其他可能的用途包括忽略标点符号字符delimiters=string.punctuation。（从 v1.23.5 版本开始）
  

返回类型：

str、list、dict

返回：

页面内容作为字符串、列表或字典。有关详细信息，请参阅相应的 TextPage 方法。

注意

1. 你可以将此方法用作从任何支持的文档类型到 TEXT、HTML、XHTML 或 XML 文档的文档转换工具。
   
2. 通过clip参数包含文本的决定是基于字符级别的：如果字符的边界框（bbox）包含在clip中，则该字符成为输出的一部分（在 v1.18.2 版本中更改）。这与用于编辑注释的算法有所偏差：如果字符的边界框与任何编辑注释相交，则该字符将被移除。
   

显示/隐藏历史记录 * 从 v1.19.0 版本开始：增加了 TextPage 参数

• 从 v1.19.1 版本开始：添加了sort参数
  
• 从 v1.19.6 版本开始：为每个方法定义默认标志的新常量。
  
• 从 v1.23.5 版本开始：增加了delimiters参数
  

get_textbox(rect, textpage=None)

检索包含在矩形中的文本。

参数：

• rect（rect-like）– 类似矩形。
  
• textpage – 要使用的 TextPage。如果省略，将创建一个新的临时文本页。
  

返回：

一个包含必要时插入换行符的字符串。它基于专用代码（从 v1.19.0 版本开始更改）。一个典型的用法是检查Page.search_for()的结果：

>>> rl = page.search_for("currency:")
>>> page.get_textbox(rl[0])
'Currency:'
>>> 

显示/隐藏历史记录 * 从 v1.17.7 版本开始

• 从 v1.19.0 版本开始：添加了 TextPage 参数

get_textpage(clip=None, flags=3)

创建一个用于该页面的 TextPage。

参数：

• flags（int）– 控制接下来的文本提取和搜索可用内容的指示位 – 参见Page.get_text()的参数。
  
• clip（rect-like）– 限制提取的文本到这个区域。（从 v1.17.7 版本开始）
  

返回：

TextPage

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

• 改动 v1.17.7：引入了 clip 参数。

get_textpage_ocr(flags=3, language='eng', dpi=72, full=False, tessdata=None)




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