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

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

参数：

• 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对象的列表。如果页面没有表格，则为[]。单个表格可以作为此列表的项找到。但TableFinder对象本身也是其表格的序列。这意味着如果tabs是一个TableFinder对象，则表格“n”可以通过tabs.tables[n]或更短的tabs[n]交付。
  
• Table对象具有以下属性：

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

• TableHeader 对象具有以下属性：

• bbox: 头部的边界框。
  
• cells: 包含各列名称的边界框列表。
  
• names: 包含每个单元边界框文本的字符串列表。它们代表列名 - 在将表格导出到 pandas DataFrames、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）- 图章文本的 id 号。有关可用图章，请参见图章注释图标。
  

注意

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

add_widget(widget)

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

参数：

widget（小部件）- 一个小部件对象，必须事先创建。

返回：

一个小部件注释。

delete_annot(annot)

• 现在的移除将包括任何绑定的“弹出”或响应注释以及相关对象（在 v1.16.6 中更改）。

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

参数：

annot（注释）- 要删除的注释。

返回类型：

注释

返回值：

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

delete_widget(widget)

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

参数：

widget（小部件）- 要删除的小部件。

返回类型：

小部件

返回：

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

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

delete_link(linkdict)

仅限 PDF：删除页面上指定的链接。参数必须是 get_links() 的原始条目，请参见获取链接条目的描述。其原因在于字典的 “xref” 键，该键标识要删除的 PDF 对象。

参数：

linkdict（dict）- 要删除的链接。

insert_link(linkdict)

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

参数：

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

update_link(linkdict)

仅适用于 PDF：修改指定的链接。参数必须是由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’注释。

返回类型：

生成器

返回：

每次迭代的 Annot。

注意

您不能安全地更新注释，因为大多数注释更新需要通过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,) 仅返回“文本”字段。

返回类型：

生成器

返回：

每次迭代的 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 对象或单个 TextWriter。
  
• opacity (float) – 设置透明度，覆盖文本编写器中的相应值。
  
• color (sequ) – 设置文本颜色，覆盖文本编写器中的相应值。
  
• overlay (bool) – 将文本放置在前景或背景中。
  
• keep_proportion (bool) – 保持纵横比。
  
• rotate (float) – 将文本按任意角度旋转。
  
• oc (int) – OCG 或 OCMD 的 xref。 (新增于 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" 将被忽略并被视为空格。
  
• 使用此方法可以实现以下目标：

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

参数：

• 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 文本：如何填充一个框中的 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）。参见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）。参见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绘制一条波浪线（波浪形、波浪状）。参见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：在center（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定义的连接线。参见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：使用控制点p2和p3（都是point_like）从p1到p4绘制三次贝塞尔曲线。参见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 References，第 16 页，第 7.3.5 节，以了解构建合法 PDF 名称的正式描述）。但如果匹配Base14_Fonts中的一个或 CJK 字体中的一个，fontfile和fontbuffer 将被忽略。
  换句话说，您不能通过fontfile / fontbuffer插入字体，并且同时给出保留的fontname。
  注意
  保留的字体名称可以以任何大小写混合的方式指定，并且仍然匹配正确的内置字体定义：字体名称“helv”、“Helv”、“HELV”、“Helvetica”等都导致相同的字体定义“Helvetica”。但从 Page 的角度来看，这些是不同的引用。在页面上使用同一字体的不同编码变体（拉丁文、希腊文、西里尔文），您可以利用这一事实。
  
• fontfile (str) – 字体文件的路径。如果使用，fontname 必须与所有保留名称不同。
  
• fontbuffer (bytes/bytearray) – 字体文件的内存映像。如果使用，fontname 必须与所有保留名称都不同。此参数通常与 Font 中支持/可用的字体的 Font.buffer 一起使用。
  
• set_simple (int) – 仅适用于 fontfile / fontbuffer 情况：强制将字体视为 “简单” 字体，即只使用字符代码到 255。
  
• encoding (int) – 仅适用于 “Helvetica”，“Courier” 和 “Times” 字体组中的 Base14_Fonts。选择可用编码之一 拉丁（0），西里尔（2）或希腊（1）。只对 “Symbol” 和 “ZapfDingBats” 使用默认值（0 = 拉丁）。
  

类型：

int

返回：

已安装字体的xref。

注意

内置字体不会导致字体文件的包含。因此，生成的 PDF 文件将保持较小。但是，您的 PDF 查看器软件负责生成适当的外观 -  以及它们是否或如何执行此操作存在差异。对于 CJK 字体特别如此。但是某些情况下也会不正确地处理符号和 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	简体中文（衬线）
china-t	Fangti	繁体中文
china-ts	Ming	繁体中文（衬线）
japan	Gothic	日语
japan-s	Mincho	日语（衬线）
korea	Dotum	韩语
korea-s	Batang	韩语（衬线）

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 支持的所有格式 – 请参阅 Supported Input Image Formats）。
  
• 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 处的图像。这略微误导：实际上，图像被用上述Page.replace_image()替换为小型透明的 Pixmap。然而，可见效果是等效的。

参数：

xref (整数) – 图像的xref。

这是一个**全局替换：**图像将在整个文件中原来显示的地方消失。

如果您检查/提取页面的图像，如Page.get_images()、Page.get_image_info()或Page.get_text()等方法，将检测到替换的“虚拟”图像，如(45, 47, 1, 1, 8, 'DeviceGray', '', 'Im1', 'FlateDecode')，并且似乎也“覆盖”了页面上的相同边界框。

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

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

以各种格式检索页面的内容。通过选择输出选项 opt，这是多个 TextPage 方法的包装器，如下所示：

• “text” – TextPage.extractTEXT()，默认
  
• “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()
  

参数：

• opt（str） –
  一个字符串，表示所请求的格式之一。支持大小写混合。
  也接受“words”和“blocks”两个值（v1.16.3 中更改）。
  
• clip（类似矩形） – 将提取的文本限制在此矩形内。如果为 None，则取整个页面。对于选项“html”、“xhtml”和“xml”，没有效果。（v1.17.7 中新增）
  
• flags（int） – 指示位，控制是否包括图像以及如何处理文本与空格和连字。有关可用指示器，请参阅 Text Extraction Flags，有关默认设置，请参阅 Text Extraction Flags Defaults。（v1.16.2 中新增）
  
• textpage – 使用之前创建的 TextPage。这将大大减少执行时间：可减少 50%以上，最高可达  95%，具体取决于提取选项。如果指定了此参数，则“flags”和“clip”参数将被忽略，因为它们是仅针对 textpage  的属性。如果省略，则将创建一个新的临时 textpage。（v1.19.0 中新增）
  
• sort (bool) – 将输出按垂直方向、然后按水平方向的坐标排序。在许多情况下，这应该足以生成“自然”的阅读顺序。在(X)HTML 和 XML 上没有影响。输出选项**“words”**按单词的 bboxes 的(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。这些“word”字符串不会包含任何分隔字符。（在 v1.23.5 中新增）
  

返回类型：

str, list, dict

返回：

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

注意

1. 您可以将此方法用作从任何受支持的文档类型转换为 TEXT、HTML、XHTML 或 XML 文档的文档转换工具。
   
2. 通过clip参数决定文本的包含是在字符级别上进行的：如果其 bbox 包含在clip中，则字符成为输出的一部分（在 v1.18.2 中更改）。这与用于修订注释的算法有所不同：如果字符的 bbox 与任何修订注释相交，则会被移除。
   

显示/隐藏历史 * v1.19.0 中更改：添加 TextPage 参数

• v1.19.1 中更改：添加了sort参数
  
• v1.19.6 中更改：添加了用于每种方法定义默认标志的新常量。
  
• v1.23.5 中更改：添加delimiters参数
  

get_textbox(rect, textpage=None)

检索矩形中包含的文本。

参数：

• rect (类似矩形的) – 类似矩形的。
  
• 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 (类似矩形的) – 将提取的文本限制在此区域。（在 v1.17.7 中新增）
  

返回：

文本页面

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

• 自 v1.17.7 更改：引入clip参数。

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

光学字符识别（OCR）技术可用于提取文档中全部以光栅图像格式存在的文本数据。使用此方法对页面进行OCR以进行文本提取。

该方法返回包含经 OCR 处理的文本的文本页面。如果使用此方法，MuPDF 将调用 Tesseract-OCR。否则，这是一个普通的文本页面对象。

参数：

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

注意

该方法不支持裁剪参数 - OCR 将始终针对完整页面矩形进行。

返回：

一个文本页面。执行可能比Page.get_textpage()显著延长。

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

注意

OCR 处理的文本仅在PyMuPDF 的文本提取和搜索中可用，如果它们的文本页面参数指定了此方法的输出。

这篇Jupyter 笔记本演示了使用 OCR 文本页面的示例。

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

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

get_drawings(extended=False)

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

返回：

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

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

键	值
closePath	与形状中的参数相同。
颜色	笔画颜色（见形状）。
dashes	虚线规格（见形状）。
even_odd	区域重叠的填充颜色-与形状中的参数相同。
fill	填充颜色（见形状）。
项目	绘制命令列表：线条、矩形、四边形或曲线。
lineCap	数字 3 元组，在形状中输出时使用其最大值。
lineJoin	与形状中的参数相同。
fill_opacity	填充颜色的透明度（见形状）。 （新于 v1.18.17）
stroke_opacity	笔画颜色的透明度（见形状）。 （新于 v1.18.17）
rect	此路径覆盖的页面区域。仅供信息参考。
layer	适用的可选内容组的名称。 （新于 v1.22.0）
level	如果extended=True，则为层级。 （新于 v1.22.0）
seqno	构建页面外观时的命令编号。(新于 v1.19.0)
type	此路径的类型。（新于 v1.18.17）
width	笔画线宽度。（见形状）。

键"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 的 “提取图纸” 中可以找到一份编码草案。

指定 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 行。

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

• “clip” 字典。其值（最重要的是 “scissor”）只要后续的字典具有**更大的“level”**值，就保持有效/适用。

键	值
closePath	与“stroke”或“fill”字典中的相同
even_odd	与“stroke”或“fill”字典中的相同
items	与“stroke”或“fill”字典中的相同
rect	与“stroke”或“fill”字典中的相同
layer	与“stroke”或“fill”字典中的相同
level	与“stroke”或“fill”字典中的相同
scissor	裁剪矩形
type	“clip”
• 
  
• “group” 字典。其值保持有效（适用），只要后续的字典具有**更大的“level”**值。任何具有相等或更低级别的字典都会结束此组。

键	值
rect	与“stroke”或“fill”字典中的相同
layer	与“stroke”或“fill”字典中的相同
level	与“stroke”或“fill”字典中的相同
isolated	(bool) 此组是否为孤立组
knockout	(bool) 是否为“Knockout Group”
blendmode	BlendMode 的名称，默认为 “Normal”
opacity	在范围 [0, 1] 中的浮点值。
type	“group”
• 
  

注意

该方法基于 Page.get_cdrawings() 的输出——它速度更快，但需要对其输出进行更多处理。

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

• 在 v1.18.17 版中已更改
  
• 在 v1.19.0 版中已更改：添加了 “seqno” 键，删除了 “clippings” 键
  
• 在 v1.19.1 版中已更改： “color”/“fill” 键现在始终为 RGB 元组或 None。这解决了由于异国情调的颜色空间而引起的问题。
  
• v1.19.2 版本更改：为“re”项覆盖的区域的*“方向”*添加指示器。
  
• v1.22.0 版本更改：添加新键"layer"，其包含路径的可选内容组名称（或None）。
  
• 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 版本新增

• v1.19.0 版本更改：移除了“clippings”键，添加了“seqno”键。
  
• v1.19.1 版本更改：始终生成 RGB 颜色元组。
  
• v1.22.0 版本更改：添加新键"layer"，其包含路径的可选内容组名称（或None）。
  
• 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()的字典输出的子集：忽略了图像二进制内容和页面上的任何文本。

参数：

• 散列值 (bool) – 计算每个遇到的图像的 MD5 哈希码，从而识别图像重复。这将在输出中添加键"digest"，其值为一个 16 字节的bytes对象。（v1.18.13 版本新增）
  
• 交叉引用 (bool) – 仅适用于 PDF。尝试为每个图像找到xref。意味着hashes=True。将"xref"键添加到字典中。如果未找到，则值为 0，这意味着图像要么是“内联”的，要么无法检测到。请注意，此选项会导致响应时间延长，因为每个具有 xref 的图像至少会计算两次 MD5 哈希码。（v1.18.13 版本新增）
  

返回类型：

列表[字典]

返回：

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

Key	Value
number	块编号 (int)
bbox	页面上的图像 bbox，rect_like
width	原始图像宽度 (int)
height	原始图像高度 (int)
cs-name	色彩空间名称 (str)
colorspace	colorspace.n (int)
xres	x 轴方向的分辨率 (int)
yres	y 轴方向的分辨率 (int)
bpc	每分量的位数 (int)
size	图像占用的存储空间 (int)
digest	MD5 哈希码 (bytes)，如果 hashes 为 true
xref	图像的 xref 或 0（如果 xrefs 为 true）
transform	将图像矩形转换为 bbox 的矩阵，matrix_like

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

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

• 从 v1.18.13 版本开始更改：增加了图像的 MD5 哈希码计算和xref搜索。

get_xobjects()

仅适用于 PDF：返回页面引用的 Form XObjects 的列表。Document.get_page_xobjects() 的包装器。

get_image_rects(item, transform=False)

仅适用于 PDF：返回嵌入图像的边界框和转换矩阵。这是 Page.get_image_bbox() 的改进版本，具有以下区别：

• 图像如何被调用没有限制（通过页面或其一个 Form XObjects 之一）。结果始终完整且正确。
  
• 结果是一个列表，包含 Rect 或 (Rect, Matrix) 对象 – 根据 transform 参数而定。每个列表项表示页面上图像的一个位置。多个出现可能无法通过 Page.get_image_bbox() 检测到。
  
• 该方法调用 Page.get_image_info() 并因此比 Page.get_image_bbox() 响应时间明显更长。
  

参数：

• item (list*,str,*int) – 列表 Page.get_images() 的一项，或这种项（item[7]）的参考 name 条目，或图像 xref。
  
• transform (bool) – 也返回用于将图像矩形转换为页面上 bbox 的矩阵。如果为 true，则返回元组 (bbox, matrix)。
  

返回类型：

列表

返回：

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

显示/隐藏历史 新增于 v1.18.13

get_image_bbox(item, transform=False)

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

参数：

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

返回类型：

Rect 或 (Rect, Matrix)

返回：

图像的边界框 – 可选地还包括其变换矩阵。

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

• (Changed in v1.17.0): 仅考虑页面直接引用的图像。这意味着会忽略嵌入 PDF 页面中的图像并引发异常。
  
• (Changed in v1.18.5): 移除了 v1.17.0 中引入的限制：页面图像列表中的任意项都可以指定。
  
• (Changed in v1.18.11): 部分重新引入限制：只考虑直接由页面引用或由页面直接引用的 Form XObject 的图像。
  
• (Changed in 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，显示质量依赖于当前系统上引用字体的存在。对于缺少字体的情况，Internet 浏览器将退回到某些默认值 – 导致不愉快的外观。如果要解析 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”（不区分大小写）。或者指定 Colorspace，即预定义的之一：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，则会获得更高的分辨率：缩放=2  将在该方向上增加两倍像素数，从而生成两倍大的图像。非正值会水平或垂直翻转。类似地，矩阵还允许您旋转或剪切，并且可以通过矩阵乘法组合效果。详见  Matrix 章节了解更多。注意

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

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：返回一个列表，其中包含页面的*/Annots*数组中所有条目的:dataxref号。

返回类型：

列表

返回：

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

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

load_annot(ident)

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

参数：

ident (str*,*int) – 注释名称或交叉引用。

返回类型：

注释

返回：

注释或None。

注意

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

显示/隐藏历史记录 * 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) – 页码（从-∞ < pno < docsrc.page_count）为 0 开始。
  
• 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

返回：

一个新的 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 字符：例如，“COMPÉTENCES”将无法找到，如果 needle  是“compétences” – 然而，如果 needle 是“compÉtences”则可以。对于德语 umlauts 等也是如此。
  
• clip（rect_like） – 仅在此区域内进行搜索。（新增于 v1.18.2）
  
• quads（bool） – 返回对象类型为 Quad，而不是 Rect。
  
• flags（int） – 控制基础 TextPage 提取的数据。默认情况下保留连字和空格，并检测连字符 [8]。
  
• textpage – 使用先前创建的 TextPage。这显著减少了执行时间。如果指定，‘flags’和‘clip’参数将被忽略。如果省略，将创建一个临时的 textpage。（新增于 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`参数。添加默认值“dehyphenate”。

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

set_mediabox(r)

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

参数：

r (rect-like) – 页面的新mediabox值。

注意

该方法还会移除页面的其他（可选）矩形（cropbox、ArtBox、TrimBox 和 Bleedbox），以避免不一致的情况。这将导致它们恢复到默认值。

注意

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

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

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

set_cropbox(r)

仅限 PDF：更改页面的可见部分。

参数：

r (rect_like) – 页面的新可见区域。请注意，此处必须使用未旋转坐标指定，不能是空的，也不能是无限的，并且完全包含在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 之一。

类型：

int

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

PDF 页面的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

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

类型：

链接

first_annot

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

类型：

注释

first_widget

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

类型：

部件

number

页码。

类型：

int

parent

拥有的文档对象。

类型：

Document

rect

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

类型：

Rect

xref

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

类型：

Rect




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