PyMuPDF-1-24-4-中文文档-十一-

PyMuPDF 1.24.4 中文文档（十一）

原文：https://pymupdf.readthedocs.io/en/latest/

小部件

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

此类仅适用于 PDF。

此类表示 PDF 表单字段，也称为“小部件”。在整个文档中，我们将这些术语视为同义词。字段技术上是 PDF 注释的一种特殊情况，允许权限受限的用户在 PDF 中输入信息。主要用于填写表单。

与注释类似，小部件存在于 PDF 页面上。与注释类似，页面上的第一个小部件可通过Page.first_widget访问，后续小部件可通过Widget.next属性访问。

（从版本 1.16.0 中更改） MuPDF 不再将小部件视为一般注释的子集。因此，Page.first_annot 和 Annot.next() 将仅返回非小部件注释，如果页面上仅存在表单字段，则返回None。反之，Page.first_widget 和 Widget.next() 将仅显示小部件。这一设计决策纯粹是 MuPDF 内部的技术性选择；从技术上讲，链接、注释和字段有很多共同之处，并继续在(Py-)MuPDF 内共享它们的大部分代码。

类 API

class Widget

button_states()

新版本 1.18.15 中更改

返回按钮字段可能具有的“开/关”（即选中/未选中或已点击/未点击）状态的名称。虽然“关”状态通常也命名为如此，但“开”状态通常会根据功能上下文命名，例如“是”、“女”等。

此方法有助于查找这些情况下field_value的可能值。

返回：

字典，包含按钮小部件的“开”和“关”在正常和按下外观的名称。以下示例显示“已选择”的值为“男”：

>>> print(field.field_name, field.button_states())
Gender Second person {'down': ['Male', 'Off'], 'normal': ['Male', 'Off']} 

on_state()
  • 新版本 1.22.2 中新增

返回复选框和单选按钮的“ON”状态的值。对于复选框，始终是值“是”。对于单选按钮，这是选择/激活按钮的值。

返回：

设置按钮为“已选择”的值。对于非复选框和非单选按钮字段，始终返回None。对于复选框，返回True。对于单选按钮，在以下示例中返回值为“男”：

>>> print(field.field_name, field.button_states())
Gender Second person {'down': ['Male', 'Off'], 'normal': ['Male', 'Off']}
>>> print(field.on_state())
Male

因此，对于复选框和单选按钮，推荐的设置“已选择”或检查状态的方法如下：

>>> field.field_value = field.on_state()
>>> field.field_value == field.on_state()
True 

update()

对任何小部件进行更改后，必须使用此方法存储到 PDF 中[1]。

reset()

将字段的值重置为其默认值（如果定义了默认值），或将其删除。不要忘记随后执行update()。

next

指向页面上的下一个表单字段。最后一个小部件返回None。

border_color

最多由 4 个浮点数组成的列表，定义字段的边框颜色。默认值为None，导致边框样式和边框宽度被忽略。

border_style

定义字段边框的线条样式。参见Annot.border。默认为“s”（“实线”）– 连续线。在创建小部件时，只有第一个字符（大写或小写）将被视为有效。

border_width

浮点数，定义边框线的宽度。默认为 1。

border_dashes

整数列表/元组，定义边框线的虚线属性。仅在border_style == “D”并且提供了border_color时才有意义。

choice_values

定义列表框和组合框的有效选择的 Python 字符串序列。对于这些小部件类型，此属性是强制性的，必须包含至少两个项目。对于其他类型将被忽略。

field_name

必需的字符串，定义字段的名称。不会检查是否重复。

field_label

可选的字符串，包含“备用”字段名称。通常用于任何注释、字段使用帮助等。默认为字段名称。

field_value

字段的值。

field_flags

整数，定义字段的大量属性。更改此属性时请小心，因为可能会更改字段类型。

field_type

必需的整数，定义字段类型。取值范围为 0 到 6。更新小部件时不能更改。

field_type_string

描述（并源自）字段类型的字符串。

fill_color

由最多 4 个浮点数定义的字段背景颜色。

button_caption

按钮类型字段的标题字符串。

is_signed

布尔值，指示签名字段的签名状态，否则为None。

rect

包含字段的矩形。

text_color

由1, 3 或 4 个浮点数组成的列表，定义文本颜色。默认值为黑色([0, 0, 0])。

text_font

定义要使用的字体的字符串。无效值的默认值和替换为“Helv”。有关有效字体引用名称，请参见下表。

text_fontsize

定义文本fontsize的浮点数。默认值为零，这会使 PDF 查看器软件动态选择适合注释矩形和文本量的大小。

text_maxlen

定义文本字符的最大数量的整数。PDF 查看器将（应）不接受更长的文本。

text_type

定义可接受文本类型（例如数字、日期、时间等）的整数。目前仅供参考，创建或更新小部件时将被忽略。

xref

小部件的 PDF xref。

script
  • 版本 1.16.12 中的新内容

与小部件关联的操作的 JavaScript 文本（Unicode），或None。这是唯一支持的按钮类型小部件的脚本动作。

script_stroke
  • 版本 1.16.12 中的新内容

用户在文本字段或组合框中键入键盘按键或修改滚动列表框中的选择时执行的 JavaScript 文本（Unicode）。如果不存在则为None。

script_format
  • 版本 1.16.12 中的新内容

在格式化字段以显示其当前值之前执行的 JavaScript 文本（unicode）。此操作可以在格式化之前修改字段的值。如果不存在，则为无。

script_change
  • 版本 1.16.12 中的新功能

字段值更改时执行的 JavaScript 文本（unicode）。此操作可以检查新值的有效性。如果不存在，则为无。

script_calc
  • 版本 1.16.12 中的新功能

另一个字段的值更改时重新计算此字段值时执行的 JavaScript 文本（unicode）。如果不存在，则为无。

script_blur
  • 版本 1.22.6 中的新功能

焦点从此字段移开时执行的 JavaScript 文本（unicode）。如果不存在，则为无。

script_focus
  • 版本 1.22.6 中的新功能

聚焦此字段时执行的 JavaScript 文本（unicode）。如果不存在，则为无。

注释

  1. 添加或更改上述脚本之一时，

只需将适当的 JavaScript 源代码放入小部件属性中。要删除脚本，请将相应属性设置为无。

  1. 按钮字段仅支持script。

其他脚本条目将自动设置为无。

  1. 值得一看的是这个手册，其中包含有关 Adobe 各种字段类型的标准脚本的大量信息。例如，如果要添加表示日期的文本字段，可以存储以下脚本。它们将确保与模式兼容的日期格式，并在支持的查看器中显示日期选择器：

    widget.script_format = 'AFDate_FormatEx("mm/dd/yyyy");'
widget.script_stroke = 'AFDate_KeystrokeEx("mm/dd/yyyy");'

小部件的标准字体

小部件使用自己的资源对象/DR。小部件资源对象必须至少包含一个/Font对象。小部件字体与页面字体独立。我们目前支持以下固定参考名称使用的 14 个 PDF 基本字体，或者使用任何已存在的字段字体名称。在指定新的或更改的小部件的文本字体时，要么选择第一列中的一个（支持大写和小写），要么选择已存在的表单字体之一。在后一种情况下，拼写必须完全匹配。

要查找已存在的字段字体，请检查列表Document.FormFonts。

参考 基本 14 字体名称
CoBI Courier-BoldOblique
CoBo Courier-Bold
CoIt Courier-Oblique
Cour Courier
HeBI Helvetica-BoldOblique
HeBo Helvetica-Bold
HeIt Helvetica-Oblique
Helv Helvetica （默认）
Symb Symbol
TiBI Times-BoldItalic
TiBo Times-Bold
TiIt Times-Italic
TiRo Times-Roman
ZaDb ZapfDingbats

通常可以为每个小部件自由选择任何字体。但是，我们建议对复选框使用ZaDb（“ZapfDingbats”）和fontsize 0：典型的查看器在单击时会在字段的矩形中放置正确大小的勾号。

支持的小部件类型

PyMuPDF 支持创建和更新许多小部件类型，但不是全部。

  • 文本（PDF_WIDGET_TYPE_TEXT）

  • 按钮（PDF_WIDGET_TYPE_BUTTON）

  • 复选框（PDF_WIDGET_TYPE_CHECKBOX）

  • 下拉框（PDF_WIDGET_TYPE_COMBOBOX）

  • 列表框（PDF_WIDGET_TYPE_LISTBOX）

  • 单选按钮（PDF_WIDGET_TYPE_RADIOBUTTON）：PyMuPDF 目前不支持创建（互相连接的）单选按钮组，设置一个按钮会自动取消设置组中的其他按钮。小部件对象也不反映按钮组的存在。然而：支持一致地选择（或取消选择）单选按钮。这包括正确设置维护在所属按钮组中的值。选择单选按钮可以通过分配True或field.on_state()给字段值来完成。取消选择按钮应该通过分配False来完成。

  • 签名（PDF_WIDGET_TYPE_SIGNATURE）只读。

脚注

你对本页面有什么反馈吗？

本软件按原样提供，不附带任何明示或暗示的保证。本软件在许可下分发，除非在该许可的条款下明确授权，否则不得复制、修改或分发本软件。请参阅artifex.com上的许可信息，或联系美国加利福尼亚州旧金山 Mesa Street 39 号 108A 单元的 Artifex Software Inc. 了解更多信息。

本文档覆盖了所有版本直到 1.24.4。

Discord logo

小部件的标准字体

小部件使用自己的资源对象/DR。小部件资源对象必须至少包含一个/Font对象。小部件字体独立于页面字体。我们目前支持使用以下固定参考名称的 14 种 PDF 基本字体，或者任何现有字段字体的名称。在指定新的或更改的小部件的文本字体时，要么选择第一张表列中的一个（支持大小写），要么选择已经存在的表单字体之一。在后一种情况下，拼写必须完全匹配。

要找出已经存在的字段字体，请检查列表Document.FormFonts。

参考 Base14 字体名称
CoBI Courier-BoldOblique
CoBo Courier-Bold
CoIt Courier-Oblique
Cour Courier
HeBI Helvetica-BoldOblique
HeBo Helvetica-Bold
HeIt Helvetica-Oblique
Helv Helvetica （默认）
Symb Symbol
TiBI Times-BoldItalic
TiBo Times-Bold
TiIt Times-Italic
TiRo Times-Roman
ZaDb ZapfDingbats

通常，你可以为每个小部件自由选择任何字体。然而，我们建议对于复选框使用ZaDb（“ZapfDingbats”）和fontsize 0：典型的查看器会在单击字段的矩形时放置一个正确大小的勾号。

支持的小部件类型

PyMuPDF 支持创建和更新许多小部件类型，但不是所有类型都支持。

  • 文本框（PDF_WIDGET_TYPE_TEXT）

  • 按钮（PDF_WIDGET_TYPE_BUTTON）

  • 复选框（PDF_WIDGET_TYPE_CHECKBOX）

  • 下拉框（PDF_WIDGET_TYPE_COMBOBOX）

  • 列表框（PDF_WIDGET_TYPE_LISTBOX）

  • 单选按钮（PDF_WIDGET_TYPE_RADIOBUTTON）：PyMuPDF 目前不支持创建（相互连接的）单选按钮组，其中设置一个按钮会自动取消组中的其他按钮。小部件对象也不反映按钮组的存在。然而，可以一致地选择（或取消选择）单选按钮。这包括正确设置所属按钮组中维护的值。选择单选按钮可以通过将 True 或 field.on_state() 分配给字段值来完成。取消选择按钮应通过分配 False 来完成。

  • 签名（PDF_WIDGET_TYPE_SIGNATURE）只读。

脚注

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

本软件按“原样”提供，不带任何明示或默示的保证。此软件根据许可分发，除非根据许可条款明确授权，否则不得复制、修改或分发。有关详细信息，请参阅 artifex.com 的许可信息或联系美国旧金山 CA 94129 Mesa 街 39 号 108A 套房的 Artifex Software Inc.。

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

Discord logo

Xml

原文：pymupdf.readthedocs.io/en/latest/xml-class.html

  • 新增于 v1.21.0

这代表一个 HTML 或 XML 节点。它是一个辅助类，用于访问 Story 对象的 DOM（文档对象模型）内容。

不需要直接构建 Xml 对象：在创建 Story 后，直接获取 Story.body —— 它是一个 Xml 节点 —— 并用它来浏览故事的 DOM 结构。

| 方法 / 属性 | 描述 | |
| --- | --- |
| add_bullet_list() | 添加一个ul标签 - 项目列表，上下文管理器。 |
| add_codeblock() | 添加一个pre标签，上下文管理器。 |
| add_description_list() | 添加一个dl标签，上下文管理器。 |
| add_division() | 添加一个div标签（从“section”改名），上下文管理器。 |
| add_header() | 添加一个标题标签（从h1到h6），上下文管理器。 |
| add_horizontal_line() | 添加一个hr标签。 |
| add_image() | 添加一个img标签。 |
| add_link() | 添加一个a标签。 |
| add_number_list() | 添加一个ol标签，上下文管理器。 |
| add_paragraph() | 添加一个p标签。 |
| add_span() | 添加一个span标签，上下文管理器。 |
| add_subscript() | 添加下标文本（sub标签） - 内联元素，视为文本。 |
| add_superscript() | 添加上标文本（sup标签） - 内联元素，视为文本。 |
| add_code() | 添加代码文本（code标签） - 内联元素，视为文本。 |
| add_var() | 添加代码文本（code标签） - 内联元素，视为文本。 |
| add_samp() | 添加代码文本（code标签） - 内联元素，视为文本。 |
| add_kbd() | 添加代码文本（code标签） - 内联元素，视为文本。 |
| add_text() | 添加文本字符串。换行符 n 被视为br标签。 |
| append_child() | 添加一个子节点。 |
| clone() | 复制此节点。 |
| create_element() | 创建具有给定标签名的新节点。 |
| create_text_node() | 为当前节点创建直接文本。 |
| find() | 查找具有给定属性的子节点。 |
| find_next() | 重复以相同条件执行的上一个“find”。 |
| insert_after() | 在当前节点之后插入一个元素。 |
| insert_before() | 在当前节点之前插入一个元素。 |
| remove() | 移除此节点。 |
| set_align() | 使用 CSS 样式规范设置对齐方式。仅适用于块级标签。 |
| set_attribute() | 将任意键设置为某个值（可以为空）。 |
| set_bgcolor() | 设置背景颜色。仅适用于块级标签。 |
| set_bold() | 打开或关闭粗体或设置为某个字符串值。 |
| set_color() | 设置文本颜色。 |
| set_columns() | 设置列数。参数可以是任何有效的数字或字符串。 |
| set_font() | 设置字体系列，例如“sans-serif”。 |
| set_fontsize() | 设置字体大小。可以是浮点数或有效的 HTML/CSS 字符串。 |
| set_id() | 设置id。会执行唯一性检查。 |
| set_italic() | 打开或关闭斜体或设置为某个字符串值。 |
| set_leading() | 设置块级文本之间的间距（-mupdf-leading），仅适用于块级节点。 |
| set_lineheight() | 设置行高。像 1.5 这样的浮点数，它设置为1.5 * fontsize。 |
| set_margins() | 设置边距，可以是浮点数或具有最多 4 个值的字符串。 |
| set_pagebreak_after() | 在此节点之后插入分页符。 |
| set_pagebreak_before() | 在此节点之前插入分页符。 |
| set_properties() | 一次设置任意或所有所需的属性。 |
| add_style() | 设置（添加）不被自身set_方法支持的“style”。 |
| add_class() | 设置（添加）“class”属性。 |
| set_text_indent() | 为第一个文本块行设置缩进。仅适用于块级节点。 |
| tagname | 可以是 HTML 标签名，如p，或者是None（如果是文本节点）。 |
| text | 节点的文本或None（如果是标签节点）。 |
| is_text | 检查节点是否为文本。 |
| first_child | 包含此节点下一级的第一个节点（或 None）。 |
| last_child | 包含此节点下一级的最后一个节点（或 None）。 |
| next | 同级别中的下一个节点（或 None）。 |
| previous | 同级别中的上一个节点。 |
| root | DOM 的顶级节点，因此其标签名为 html。 |

Class API

class Xml

add_bullet_list()

添加一个 ul 标签 - 无序列表，上下文管理器。查看 ul。

add_codeblock()

添加一个 pre 标签，上下文管理器。查看 pre。

add_description_list()

添加一个 dl 标签，上下文管理器。查看 dl。

add_division()

添加一个 div 标签，上下文管理器。查看 div。

add_header(value)

添加一个标题标签（从 h1 到 h6 之一），上下文管理器。查看 headings。

参数：

value (int) – 一个值 1 - 6。

add_horizontal_line()

添加一个 hr 标签。查看 hr。

add_image(name, width=None, height=None)

添加一个 img 标签。这会在 DOM 中包含指定名称的图像。

参数：

  • name (str) – 图像的文件名。这 必须是 Story 构造函数的 Archive 参数的某个条目的成员名称。

  • width – 如果提供，可以是绝对值（int），或者像“30%”这样的百分比字符串。百分比值指的是在 Story.place() 中指定 where 矩形的宽度。如果提供了此值，并且省略了 height，则图像将按比例缩放。

  • height – 如果提供，可以是绝对值（int），或者像“30%”这样的百分比字符串。百分比值指的是在 Story.place() 中指定 where 矩形的高度。如果提供了此值，并且省略了 width，则图像将保持其宽高比。

add_link(href, text=None)

添加一个 a 标签 - 内联元素，被视为文本。

参数：

  • href (str) – URL 的目标。

  • text (str) – 要显示的文本。如果省略，则显示 href 的文本。

add_number_list()

添加一个 ol 标签，上下文管理器。

add_paragraph()

添加一个 p 标签，上下文管理器。

add_span()

添加一个 span 标签，上下文管理器。查看 span

add_subscript(text)

添加“下标”文本 (sub 标签) - 内联元素，被视为文本。

add_superscript(text)

添加“上标”文本 (sup 标签) - 内联元素，被视为文本。

add_code(text)

添加“代码”文本 (code 标签) - 内联元素，被视为文本。

add_var(text)

添加“变量”文本 (var 标签) - 内联元素，被视为文本。

add_samp(text)

添加“示例输出”文本 (samp 标签) - 内联元素，被视为文本。

add_kbd(text)

添加“键盘输入”文本（kbd 标签） - 内联元素，视为文本处理。

add_text(text)

添加一个文本字符串。换行 n 将被视为 br 标签。

set_align(value)

设置文本对齐方式。仅适用于块级标签。

参数：

value - Text Alignment 或 text-align 值之一。

set_attribute(key, value=None)

设置一个任意的键到某个值（可能为空）。

参数：

  • key（str）- 属性的名称。

  • value（str）- 属性的（可选）值。

get_attributes()

检索当前节点的所有属性作为字典。

返回：

节点的属性及其值的字典。

get_attribute_value(key)

获取 key 属性值。

参数：

key（str）- 属性的名称。

返回：

一个带有 key 值的字符串。

remove_attribute(key)

从节点中删除属性 key。

参数：

key（str）- 属性的名称。

set_bgcolor(value)

设置背景颜色。仅适用于块级标签。

参数：

value - RGB 值如 (255, 0, 0)（表示“红色”）或有效的 background-color 值。

set_bold(value)

设置文本的粗体开启或关闭，或设置为某个字符串值。

参数：

value - True，False 或有效的 font-weight 值。

set_color(value)

设置接下来文本的颜色。

参数：

value - RGB 值如 (255, 0, 0)（表示“红色”）或有效的 color 值。

set_columns(value)

设置列数。

参数：

value - 一个有效的 columns 值。

注意

当前版本忽略 - 在未来的 MuPDF 版本中支持。

set_font(value)

设置字体系列。

参数：

value（str）- 例如“sans-serif”。

set_fontsize(value)

设置接下来文本的字体大小。

参数：

value - 浮点数或有效的 font-size 值。

set_id(unqid)

设置一个 id。这用作 DOM 中节点的唯一标识。使用它可以轻松定位节点以检查或修改它。会执行唯一性检查。

参数：

unqid（str）- 节点的 id 字符串。

set_italic(value)

设置接下来文本的斜体开启或关闭，或设置为某个字符串值。

参数：

value - True，False 或一些有效的 font-style 值。

set_leading(value)

设置块级文本间距（-mupdf-leading），仅适用于块级节点。

参数：

value（float）- 距离上一个块的距离（以点为单位）。

set_lineheight(value)

设置行的高度。

参数：

value - 一个类似 1.5 的浮点数（设置为 1.5 * fontsize），或一些有效的 line-height 值。

set_margins(value)

设置边距。

参数：

value - 浮点数或包含最多 4 个值的字符串。参见 CSS 文档。

set_pagebreak_after()

在此节点之后插入分页符。

set_pagebreak_before()

在此节点之前插入分页符。

set_properties(align=None, bgcolor=None, bold=None, color=None, columns=None, font=None, fontsize=None, indent=None, italic=None, leading=None, lineheight=None, margins=None, pagebreak_after=False, pagebreak_before=False, unqid=None, cls=None)

一次性设置所有所需属性。参数值的含义等同于相应的set_方法的值。

注意

此方法设置的属性直接附加到节点，而每个set_方法生成一个新的span，该span具有相应的属性。因此，要“全局”设置某些属性以供body使用，必须使用此方法。

add_style(value)

设置不受其自身set_方法支持的某些样式属性。

参数：

value（str） – 任何有效的 CSS 样式值。

add_class(value)

设置（添加）某些“class”属性。

参数：

value（str） – 类名。必须已在 DOM 的 HTML 或 CSS 源中定义。

set_text_indent(value)

设置首个文本块行的缩进。仅适用于块级节点。

参数：

value – 有效的text-indent值。请注意，负值不起作用。

append_child(node)

追加子节点。这是其他方法（如Xml.add_paragraph()）使用的底层方法。

参数：

node – 要追加的 Xml 节点。

create_text_node(text)

为当前节点创建直接文本。

参数：

text（str） – 要追加的文本。

返回类型：

Xml

返回：

创建的元素。

create_element(tag)

使用给定标签创建新节点。这是其他方法（如Xml.add_paragraph()）使用的底层方法。

参数：

tag（str） – 元素标签。

返回类型：

Xml

返回：

创建的元素。要实际将其绑定到 DOM，请使用Xml.append_child()。

insert_before(elem)

在此节点之前插入给定元素elem。

参数：

elem – 某个 Xml 元素。

insert_after(elem)

在此节点之后插入给定元素elem。

参数：

elem – 某个 Xml 元素。

clone()

创建此节点的副本，随后可附加（使用Xml.append_child()）或插入（使用其中之一Xml.insert_before()、Xml.insert_after()）到此 DOM 中。

返回：

当前节点的克隆（Xml）。

remove()

从 DOM 中删除此节点。

debug()

出于调试目的，以简化形式打印此节点的结构。

find(tag, att, match)

在当前节点下，查找具有给定tag、属性att和值match的第一个节点。

参数：

  • tag（str） – 限制搜索到此标签。可能为None以进行无限制搜索。

  • att（str） – 检查此属性。可能为None。

  • match（str） – 要匹配的期望属性值。可能为None。

返回类型：

Xml。

返回：

如果未找到任何内容，则为None，否则为第一个匹配节点。

find_next(tag, att, match)

继续前一个Xml.find()（或find_next()）相同值的搜索。

返回类型：

Xml。

返回：

如果没有更多发现，则为None，否则为下一个匹配节点。

tagname

HTML 标签名称如p或None如果是文本节点。

text

节点的文本或None如果是标签节点。

is_text

检查是否为文本节点。

first_child

包含此节点下一级的第一个节点（或None）。

last_child

包含此节点下一级的最后一个节点（或None）。

next

相同级别的下一个节点（或None）。

previous

相同级别的上一个节点。

root

DOM 的顶级节点，因此具有标签名html。

设置文本属性

在 HTML 标签中，标签可以嵌套，这样最内层的文本继承其父标签的属性。例如 <p>。

为了达到相同的效果，像Xml.set_bold()和Xml.set_italic()这样的方法每个都会在当前节点下方打开一个临时的span，具有所需的属性。

另外，这些方法返回其父节点，因此它们可以彼此连接。

上下文管理器支持

将节点添加到 DOM 的标准方法是这样的：

body = story.body
para = body.add_paragraph()  # add a paragraph
para.set_bold()  # text that follows will be bold
para.add_text("some bold text")
para.set_italic()  # text that follows will additionally be italic
para.add_txt("this is bold and italic")
para.set_italic(False).set_bold(False)  # all following text will be regular
para.add_text("regular text")

被标记为“上下文管理器”的方法可以方便地以这种方式使用：

body = story.body
with body.add_paragraph() as para:
   para.set_bold().add_text("some bold text")
   para.set_italic().add_text("this is bold and italic")
   para.set_italic(False).set_bold(False).add_text("regular text")
   para.add_text("more regular text")

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

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

此文档涵盖所有版本直到 1.24.4。

Discord logo

设置文本属性

在 HTML 标签中，标签可以嵌套，这样最内层的文本继承其父标签的属性。例如 <p>。

为了达到相同的效果，像Xml.set_bold()和Xml.set_italic()这样的方法每个都会在当前节点下方打开一个临时的span，具有所需的属性。

另外，这些方法返回其父节点，因此它们可以彼此连接。

上下文管理器支持

将节点添加到 DOM 的标准方法是这样的：

body = story.body
para = body.add_paragraph()  # add a paragraph
para.set_bold()  # text that follows will be bold
para.add_text("some bold text")
para.set_italic()  # text that follows will additionally be italic
para.add_txt("this is bold and italic")
para.set_italic(False).set_bold(False)  # all following text will be regular
para.add_text("regular text")

被标记为“上下文管理器”的方法可以方便地以这种方式使用：

body = story.body
with body.add_paragraph() as para:
   para.set_bold().add_text("some bold text")
   para.set_italic().add_text("this is bold and italic")
   para.set_italic(False).set_bold(False).add_text("regular text")
   para.add_text("more regular text")

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

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

此文档涵盖所有版本直到 1.24.4。

Discord logo

几何对象的运算代数

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

类 Point, IRect, Rect, Quad 和 Matrix 的实例统称为“几何”对象。

它们都是 Python 序列的特例，请参阅 Using Python Sequences as Arguments in PyMuPDF 了解更多背景。

我们已经为这些类定义了运算符，可以用它们（几乎）像普通数字一样进行加法、减法、乘法、除法等操作。

本章是可能性的概要。

一般说明

  1. 运算符可以是二进制的（即涉及两个对象）或一元的。

  2. 二进制操作的结果类型可以是左操作数类的新对象或 bool。

  3. 一元操作的结果要么是相同类的新对象，要么是 bool，要么是 float。

  4. 二进制运算符 +, -, , / 对所有类都定义了。它们大致*做您所期望的事情 - 除了，第二个操作数 …

    • 可能始终是一个数字，然后对第一个数字的每个组件执行操作，
    • 可能始终是相同长度的数值序列（2、4 或 6） - 我们称这样的序列为 point_like, rect_like, quad_like 或 matrix_like。

  5. 矩形支持附加的二进制操作：交集（操作符 “&”）、并集（操作符 “|”）和包含检查。

  6. 二进制运算符完全支持原地操作，因此像 a /= b 这样的表达式如果 b 是数值或“a_like”则是有效的。

一元操作

Oper. 结果
bool(OBJ) 当 OBJ 的所有组件都为零时，为 false。
abs(OBJ) 矩形区域 - 对于其他类型，等于 norm(OBJ)。
norm(OBJ) 组件平方的平方根（欧几里德范数）
+OBJ OBJ 的新副本
-OBJ 具有否定组件的 OBJ 的新副本
~m 矩阵“m”的逆，如果不可逆则为零矩阵

二进制运算

对于每个几何对象“a”和每个数字“b”，运算 “a ° b” 和 “a °= b” 对于运算符 *+, -, , / 总是定义的。相应的操作仅对“a”的每个组件执行。如果第二个操作数不是数字，则定义如下：

Oper. 结果
a+b, a-b 组件级别的执行，“b”必须是“a_like”。
a*m, a/m “a”可以是点、矩形或矩阵，但“m”必须是matrix_like。“a/m” 被视为 “a~m”（参见下面的非可逆矩阵的注释）。如果“a”是点或矩形，那么执行“a.transform(m)”*。如果“a”是一个矩阵，则进行矩阵串联。
a&b 交集矩形： “a”必须是一个矩形，“b”rect_like。提供包含在两个操作数中的最大矩形。
a|b 并集矩形： “a”必须是一个矩形，“b”可以是point_like或rect_like。提供包含两个操作数的最小矩形。
b in a 如果“b”是一个数字，那么将返回b in tuple(a)。如果“b”是point_like、rect_like或quad_like，则“a”必须是一个矩形，返回a.contains(b)。
a == b 如果bool(a-b)为False（“b”可能是“a-like”），则True。

注意

请注意与通常算术的重要差异：

矩阵乘法是不可交换的，即通常情况下我们有m*n != n*m对于两个矩阵。此外，还存在一些不可逆的非零矩阵，例如m = Matrix(1, 0, 1, 0, 1, 0)。如果你尝试使用运算符“/”除以这些矩阵之一，将会收到ZeroDivisionError异常，例如对于表达式pymupdf.Identity / m。但如果你形式化为pymupdf.Identity * ~m，结果将是pymupdf.Matrix()（空矩阵）。

诚然，这代表了一种不一致性，我们正在考虑移除它。目前，您可以选择避免异常并检查~m是否为空矩阵，或者通过使用pymupdf.Identity / m接受潜在的ZeroDivisionError。

注意

  • 根据这些约定，所有通常的代数规则都适用。例如，任意使用括号(在同一类对象之间！) 是可能的：如果 r1、r2 是矩形，m1、m2 是矩阵，你可以这样做(r1 + r2) * m1 * m2。

  • 对于同一类的所有对象，a + b + c == (a + b) + c == a + (b + c)是成立的。

  • 对于矩阵，还有以下真理：(m1 + m2) * m3 == m1 * m3 + m2 * m3（分配性质）。

  • 但矩阵应用的顺序很重要： 如果 r 是一个矩形，m1、m2 是矩阵，那么 - 小心！：

    • r * m1 * m2 == (r * m1) * m2 != r * (m1 * m2)

一些示例

数字操作

对于通常的算术操作，数字始终被允许作为第二个操作数。此外，您可以形成"x in OBJ"，其中 x 是一个数字。它被实现为"x in tuple(OBJ)"：

>>> pymupdf.Rect(1, 2, 3, 4) + 5
pymupdf.Rect(6.0, 7.0, 8.0, 9.0)
>>> 3 in pymupdf.Rect(1, 2, 3, 4)
True
>>>

下面将创建文档页面矩形的左上角四分之一：

>>> page.rect
Rect(0.0, 0.0, 595.0, 842.0)
>>> page.rect / 2
Rect(0.0, 0.0, 297.5, 421.0)
>>>

下面是连接两点p1和p2的线段的中点：

>>> p1 = pymupdf.Point(1, 2)
>>> p2 = pymupdf.Point(4711, 3141)
>>> mp = (p1 + p2) / 2
>>> mp
Point(2356.0, 1571.5)
>>>

“like”对象的操作

二元操作的第二个操作数总是可以“像”左操作数那样。在这个上下文中，“像”表示“相同长度的数字序列”。通过上面的例子：

>>> p1 + p2
Point(4712.0, 3143.0)
>>> p1 + (4711, 3141)
Point(4712.0, 3143.0)
>>> p1 += (4711, 3141)
>>> p1
Point(4712.0, 3143.0)
>>>

要将矩形向右移动 5 个像素，请执行以下操作：

>>> pymupdf.Rect(100, 100, 200, 200) + (5, 0, 5, 0)  # add 5 to the x coordinates
Rect(105.0, 100.0, 205.0, 200.0)
>>>

点、矩形和矩阵可以用矩阵进行变换。在 PyMuPDF 中，我们将其视为“乘法”（或“除法”），其中第二个操作数可能是“类似”于矩阵。此上下文中的除法意味着“与倒置矩阵的乘法”：

>>> m = pymupdf.Matrix(1, 2, 3, 4, 5, 6)
>>> n = pymupdf.Matrix(6, 5, 4, 3, 2, 1)
>>> p = pymupdf.Point(1, 2)
>>> p * m
Point(12.0, 16.0)
>>> p * (1, 2, 3, 4, 5, 6)
Point(12.0, 16.0)
>>> p / m
Point(2.0, -2.0)
>>> p / (1, 2, 3, 4, 5, 6)
Point(2.0, -2.0)
>>>
>>> m * n  # matrix multiplication
Matrix(14.0, 11.0, 34.0, 27.0, 56.0, 44.0)
>>> m / n  # matrix division
Matrix(2.5, -3.5, 3.5, -4.5, 5.5, -7.5)
>>>
>>> m / m  # result is equal to the Identity matrix
Matrix(1.0, 0.0, 0.0, 1.0, 0.0, 0.0)
>>>
>>> # look at this non-invertible matrix:
>>> m = pymupdf.Matrix(1, 0, 1, 0, 1, 0)
>>> ~m
Matrix(0.0, 0.0, 0.0, 0.0, 0.0, 0.0)
>>> # we try dividing by it in two ways:
>>> p = pymupdf.Point(1, 2)
>>> p * ~m  # this delivers point (0, 0):
Point(0.0, 0.0)
>>> p / m  # but this is an exception:
Traceback (most recent call last):
  File "<pyshell#6>", line 1, in <module>
  p / m
  File "... /site-packages/fitz/pymupdf.py", line 869, in __truediv__
  raise ZeroDivisionError("matrix not invertible")
ZeroDivisionError: matrix not invertible
>>>

作为特殊情况，矩形支持额外的二元操作：

  • 交集 – 矩形状的公共区域，操作符 “&”

  • 包含 – 扩展以包括点状或矩形状，操作符 “|”

  • 包含性检查 – 检查点状或矩形状是否在内部

这里是一个创建包含给定点的最小矩形的示例：

>>> # first define some point-likes
>>> points = []
>>> for i in range(10):
 for j in range(10):
 points.append((i, j))
>>>
>>> # now create a rectangle containing all these 100 points
>>> # start with an empty rectangle
>>> r = pymupdf.Rect(points[0], points[0])
>>> for p in points[1:]:  # and include remaining points one by one
 r |= p
>>> r  # here is the to be expected result:
Rect(0.0, 0.0, 9.0, 9.0)
>>> (4, 5) in r  # this point-like lies inside the rectangle
True
>>> # and this rect-like is also inside
>>> (4, 4, 5, 5) in r
True
>>>

您对此页面有何反馈？

本软件按现状提供，没有任何明示或暗示的保证。此软件根据许可分发，未经明确授权，不得复制、修改或分发。请参考 artifex.com 获取许可信息或联系美国加利福尼亚州旧金山 Mesa 街 39 号 108A 号 Artifex Software Inc. 了解更多信息。

此文档覆盖所有版本，直至 1.24.4。

Discord logo

一般备注

  1. 操作符可以是二元（即涉及两个对象）或一元。

  2. 二元操作的结果类型要么是左操作数类的新对象，要么是布尔值。

  3. 一元操作的结果要么是同类的新对象，要么是布尔值或浮点数。

  4. 二元运算符 *+, -, , / 对所有类别都有定义。它们 大致 做您期望的事情 – 除了第二个操作数…

    • 可能始终是一个数字，然后对第一个组件的每个组件执行操作，
    • 可以始终是相同长度的数字序列（2、4 或 6）– 我们分别称这些序列为point_like、rect_like、quad_like或matrix_like。

  5. 矩形支持额外的二元操作：交集（操作符 “&”）、并集（操作符 “|”）和包含性检查。

  6. 二元操作符完全支持原地操作，因此像 a /= b 这样的表达式在 b 是数值或“类似于 a”的情况下是有效的。

一元操作

Oper. Result
bool(OBJ) 如果 OBJ 的所有组件都为零，则为假
abs(OBJ) 矩形面积 – 对于其他类型等于 norm(OBJ)
norm(OBJ) 组件平方的平方根（欧几里得范数）
+OBJ OBJ 的新副本
-OBJ 带有反转分量的 OBJ 的新副本
~m “m” 的逆矩阵，如果不可逆则为零矩阵

二进制运算

对于每个几何对象“a”和每个数“b”，对于运算符 +、-、、/*，操作“a ° b”和“a °= b”总是定义的。相应的操作简单地对“a”的每个分量执行。如果第二个操作数不是一个数，则定义如下：

Oper. Result
a+b, a-b 分量执行，要求“b”必须类似于“a”。
a*m, a/m “a” 可以是点、矩形或矩阵，但“m”必须是 matrix_like。“a/m” 被视为 “a~m”*（有关不可逆矩阵，请参阅下面的注释）。如果“a”是点或矩形，则执行 “a.transform(m)”。如果“a”是矩阵，则进行矩阵连接。
a&b 交集矩形： “a” 必须是矩形，“b” 是 rect_like。返回包含在两个操作数中的最大矩形。
a|b 并集矩形： “a” 必须是矩形，“b” 可能是 point_like 或 rect_like。返回包含两个操作数的最小矩形。
b in a 如果“b”是一个数字，则返回 b in tuple(a)。如果“b”是 point_like、rect_like 或 quad_like，则“a”必须是矩形，返回 a.contains(b)。
a == b 如果 bool(a-b) 为 False，则为 True（“b” 可能类似于“a”）。

注意

请注意与通常算术的一个重要区别：

矩阵乘法是非交换的，即一般来说我们有 m*n != n*m。此外，存在一些不可逆的非零矩阵，例如 m = Matrix(1, 0, 1, 0, 1, 0)。如果尝试除以任何这些矩阵，将会收到一个使用运算符 “/” 的 ZeroDivisionError 异常，例如对于表达式 pymupdf.Identity / m。但如果使用 pymupdf.Identity * ~m 这种形式，结果将会是 pymupdf.Matrix()（即零矩阵）。

诚然，这代表了一种不一致性，我们正在考虑移除它。暂时，您可以选择避免异常并检查是否 ~m 是零矩阵，或者接受通过使用 pymupdf.Identity / m 可能引发的 ZeroDivisionError。

注意

  • 在这些约定下，所有常规的代数规则都适用。例如，任意使用括号 （同一类对象之间！） 是可能的：如果 r1、r2 是矩形，m1、m2 是矩阵，您可以执行 (r1 + r2) * m1 * m2。

  • 对于同一类对象的所有对象，a + b + c == (a + b) + c == a + (b + c) 是成立的。

  • 对于矩阵的加法来说，以下等式成立：(m1 + m2) * m3 == m1 * m3 + m2 * m3（分配性质）。

  • 但是应注意应用矩阵的顺序： 如果 r 是一个矩形，m1、m2 是矩阵，则 – 注意！：

    • r * m1 * m2 == (r * m1) * m2 != r * (m1 * m2)

一些示例

使用数字进行操作

对于通常的算术操作，数字始终允许作为第二个操作数。此外，您可以制定 "x in OBJ"，其中 x 是一个数字。它实现为 "x in tuple(OBJ)"：

>>> pymupdf.Rect(1, 2, 3, 4) + 5
pymupdf.Rect(6.0, 7.0, 8.0, 9.0)
>>> 3 in pymupdf.Rect(1, 2, 3, 4)
True
>>>

创建文档页面矩形的左上角四分之一：

>>> page.rect
Rect(0.0, 0.0, 595.0, 842.0)
>>> page.rect / 2
Rect(0.0, 0.0, 297.5, 421.0)
>>>

以下将提供连接两点 p1 和 p2 的线的中点：

>>> p1 = pymupdf.Point(1, 2)
>>> p2 = pymupdf.Point(4711, 3141)
>>> mp = (p1 + p2) / 2
>>> mp
Point(2356.0, 1571.5)
>>>

使用“类似”对象进行操作

二元操作的第二个操作数始终可以“类似”于左操作数。在此上下文中，“类似”表示“具有相同长度的数字序列”。使用上述示例：

>>> p1 + p2
Point(4712.0, 3143.0)
>>> p1 + (4711, 3141)
Point(4712.0, 3143.0)
>>> p1 += (4711, 3141)
>>> p1
Point(4712.0, 3143.0)
>>>

要将矩形向右移动 5 个像素，请执行以下操作：

>>> pymupdf.Rect(100, 100, 200, 200) + (5, 0, 5, 0)  # add 5 to the x coordinates
Rect(105.0, 100.0, 205.0, 200.0)
>>>

点、矩形和矩阵可以使用矩阵进行变换。在 PyMuPDF 中，我们将其视为“乘法”（或“除法”），其中第二个操作数可以“类似”于矩阵。在此上下文中，“除法”表示“与倒置矩阵的乘法”：

>>> m = pymupdf.Matrix(1, 2, 3, 4, 5, 6)
>>> n = pymupdf.Matrix(6, 5, 4, 3, 2, 1)
>>> p = pymupdf.Point(1, 2)
>>> p * m
Point(12.0, 16.0)
>>> p * (1, 2, 3, 4, 5, 6)
Point(12.0, 16.0)
>>> p / m
Point(2.0, -2.0)
>>> p / (1, 2, 3, 4, 5, 6)
Point(2.0, -2.0)
>>>
>>> m * n  # matrix multiplication
Matrix(14.0, 11.0, 34.0, 27.0, 56.0, 44.0)
>>> m / n  # matrix division
Matrix(2.5, -3.5, 3.5, -4.5, 5.5, -7.5)
>>>
>>> m / m  # result is equal to the Identity matrix
Matrix(1.0, 0.0, 0.0, 1.0, 0.0, 0.0)
>>>
>>> # look at this non-invertible matrix:
>>> m = pymupdf.Matrix(1, 0, 1, 0, 1, 0)
>>> ~m
Matrix(0.0, 0.0, 0.0, 0.0, 0.0, 0.0)
>>> # we try dividing by it in two ways:
>>> p = pymupdf.Point(1, 2)
>>> p * ~m  # this delivers point (0, 0):
Point(0.0, 0.0)
>>> p / m  # but this is an exception:
Traceback (most recent call last):
  File "<pyshell#6>", line 1, in <module>
  p / m
  File "... /site-packages/fitz/pymupdf.py", line 869, in __truediv__
  raise ZeroDivisionError("matrix not invertible")
ZeroDivisionError: matrix not invertible
>>>

作为特殊情况，矩形支持附加的二元操作：

  • 交集 – 矩形类的公共区域，操作符 “&”

  • 包含 – 扩展以包含点状或矩形状，操作符 “|”

  • 包含检查 – 点状或矩形状是否在内部

这是一个创建包围给定点的最小矩形的示例：

>>> # first define some point-likes
>>> points = []
>>> for i in range(10):
 for j in range(10):
 points.append((i, j))
>>>
>>> # now create a rectangle containing all these 100 points
>>> # start with an empty rectangle
>>> r = pymupdf.Rect(points[0], points[0])
>>> for p in points[1:]:  # and include remaining points one by one
 r |= p
>>> r  # here is the to be expected result:
Rect(0.0, 0.0, 9.0, 9.0)
>>> (4, 5) in r  # this point-like lies inside the rectangle
True
>>> # and this rect-like is also inside
>>> (4, 4, 5, 5) in r
True
>>>

您对本页有何反馈？

本软件按“原样”提供，不提供任何明示或暗示的担保。本软件在许可下分发，并且除非在该许可条款明确授权下，否则不得复制、修改或分发。请参阅 artifex.com 上的许可信息或联系美国加利福尼亚州旧金山 Mesa 街 39 号 108A 室的 Artifex Software Inc. 获取更多信息。

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

Discord logo

使用数字进行操作

对于通常的算术操作，数字始终允许作为第二个操作数。此外，您可以制定 "x in OBJ"，其中 x 是一个数字。它实现为 "x in tuple(OBJ)"：

>>> pymupdf.Rect(1, 2, 3, 4) + 5
pymupdf.Rect(6.0, 7.0, 8.0, 9.0)
>>> 3 in pymupdf.Rect(1, 2, 3, 4)
True
>>>

创建文档页面矩形的左上角四分之一：

>>> page.rect
Rect(0.0, 0.0, 595.0, 842.0)
>>> page.rect / 2
Rect(0.0, 0.0, 297.5, 421.0)
>>>

以下将提供连接两点 p1 和 p2 的线的中点：

>>> p1 = pymupdf.Point(1, 2)
>>> p2 = pymupdf.Point(4711, 3141)
>>> mp = (p1 + p2) / 2
>>> mp
Point(2356.0, 1571.5)
>>>

使用“类似”对象进行操作

二元操作的第二个操作数始终可以“类似”于左操作数。在此上下文中，“类似”表示“具有相同长度的数字序列”。使用上述示例：

>>> p1 + p2
Point(4712.0, 3143.0)
>>> p1 + (4711, 3141)
Point(4712.0, 3143.0)
>>> p1 += (4711, 3141)
>>> p1
Point(4712.0, 3143.0)
>>>

要将矩形向右移动 5 个像素，请执行以下操作：

>>> pymupdf.Rect(100, 100, 200, 200) + (5, 0, 5, 0)  # add 5 to the x coordinates
Rect(105.0, 100.0, 205.0, 200.0)
>>>

点、矩形和矩阵可以通过矩阵进行转换。在 PyMuPDF 中，我们将其视为“乘法”（或“除法”），其中第二个操作数可能“类似”于一个矩阵。在这种情况下，“除法”意味着“乘以倒置矩阵”：

>>> m = pymupdf.Matrix(1, 2, 3, 4, 5, 6)
>>> n = pymupdf.Matrix(6, 5, 4, 3, 2, 1)
>>> p = pymupdf.Point(1, 2)
>>> p * m
Point(12.0, 16.0)
>>> p * (1, 2, 3, 4, 5, 6)
Point(12.0, 16.0)
>>> p / m
Point(2.0, -2.0)
>>> p / (1, 2, 3, 4, 5, 6)
Point(2.0, -2.0)
>>>
>>> m * n  # matrix multiplication
Matrix(14.0, 11.0, 34.0, 27.0, 56.0, 44.0)
>>> m / n  # matrix division
Matrix(2.5, -3.5, 3.5, -4.5, 5.5, -7.5)
>>>
>>> m / m  # result is equal to the Identity matrix
Matrix(1.0, 0.0, 0.0, 1.0, 0.0, 0.0)
>>>
>>> # look at this non-invertible matrix:
>>> m = pymupdf.Matrix(1, 0, 1, 0, 1, 0)
>>> ~m
Matrix(0.0, 0.0, 0.0, 0.0, 0.0, 0.0)
>>> # we try dividing by it in two ways:
>>> p = pymupdf.Point(1, 2)
>>> p * ~m  # this delivers point (0, 0):
Point(0.0, 0.0)
>>> p / m  # but this is an exception:
Traceback (most recent call last):
  File "<pyshell#6>", line 1, in <module>
  p / m
  File "... /site-packages/fitz/pymupdf.py", line 869, in __truediv__
  raise ZeroDivisionError("matrix not invertible")
ZeroDivisionError: matrix not invertible
>>>

作为特殊功能，矩形支持额外的二元操作：

  • 交集 – 矩形类的公共区域，操作符 “&”

  • 包含 – 扩展以包含一个点或矩形，操作符 “|”

  • 包含性检查 – 检查一个点或矩形是否在内部

这里是创建包围给定点的最小矩形的示例：

>>> # first define some point-likes
>>> points = []
>>> for i in range(10):
 for j in range(10):
 points.append((i, j))
>>>
>>> # now create a rectangle containing all these 100 points
>>> # start with an empty rectangle
>>> r = pymupdf.Rect(points[0], points[0])
>>> for p in points[1:]:  # and include remaining points one by one
 r |= p
>>> r  # here is the to be expected result:
Rect(0.0, 0.0, 9.0, 9.0)
>>> (4, 5) in r  # this point-like lies inside the rectangle
True
>>> # and this rect-like is also inside
>>> (4, 4, 5, 5) in r
True
>>>

对本页有任何反馈吗？

此软件按原样提供，没有任何明示或暗示的保证。此软件根据许可分发，并且未经明确授权不得复制、修改或分发。请参阅许可信息，位于 artifex.com 或联系美国加利福尼亚州旧金山 Mesa 街 39 号 108A 室的 Artifex Software Inc. 获取更多信息。

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

Discord 标志

低级功能和类

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

包含多个供有经验用户使用的功能和类。用于特殊需求或性能要求。

  • 功能

  • 设备

  • 共同工作：DisplayList 和 TextPage

你对本页面有任何反馈吗？

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

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

Discord logo

功能

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

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

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

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

函数 简要说明
Annot.apn_bbox 仅适用于 PDF：外观对象的边界框
Annot.apn_matrix 仅适用于 PDF：外观对象的矩阵
Page.is_wrapped 检查是否存在内容换行
adobe_glyph_names() Adobe 字形列表中定义的字形名称列表
adobe_glyph_unicodes() Adobe 字形列表中定义的 Unicode 列表
Annot.clean_contents() 仅适用于 PDF：清除注释的 contents 对象
Annot.set_apn_bbox() 仅适用于 PDF：设置外观对象的边界框
Annot.set_apn_matrix() 仅适用于 PDF：设置外观对象的矩阵
ConversionHeader() get_text 方法的返回头注字符串
ConversionTrailer() get_text 方法的返回尾注字符串
Document.del_xml_metadata() 仅适用于 PDF：删除 XML 元数据
Document.get_char_widths() 仅适用于 PDF：返回字体的字形宽度列表
Document.get_new_xref() 仅适用于 PDF：创建并返回新的 xref 条目
Document.is_stream() 仅适用于 PDF：检查 xref 是否为流对象
Document.xml_metadata_xref() 仅适用于 PDF：返回 XML 元数据的 xref 编号
Document.xref_length() 仅适用于 PDF：返回 xref 表的长度
EMPTY_IRECT() 返回（标准）空/无效矩形
EMPTY_QUAD() 返回（标准）空/无效四边形
EMPTY_RECT() 返回（标准）空/无效矩形
get_pdf_now() 返回当前时间戳的 PDF 格式
get_pdf_str() 返回 PDF 兼容字符串
get_text_length() 返回给定字体和fontsize的字符串长度
glyph_name_to_unicode() 从字形名称返回 Unicode
image_profile() 返回基本图像属性的字典
INFINITE_IRECT() 返回（唯一存在的）无限矩形
INFINITE_QUAD() 返回（唯一存在的）无限四边形
INFINITE_RECT() 返回（唯一存在的）无限矩形
make_table() 将矩形分割为子矩形
Page.clean_contents() 仅限 PDF：清理页面的contents对象
Page.get_bboxlog() 包围文本、绘图或图像对象的矩形列表
Page.get_contents() 仅限 PDF：返回内容xref号的列表
Page.get_displaylist() 创建页面的显示列表
Page.get_text_blocks() 提取文本块为 Python 列表
Page.get_text_words() 提取文本单词为 Python 列表
Page.get_texttrace() 低级文本信息
Page.read_contents() 仅限 PDF：获取完整的、连接的/Contents 源
Page.run() 通过设备运行页面
Page.set_contents() 仅限 PDF：设置页面的contents为某些xref
Page.wrap_contents() 用堆叠命令包装内容
css_for_pymupdf_font() 为包 pymupdf_fonts 中的字体创建 CSS 源
paper_rect() 返回已知纸张格式的矩形
paper_size() 返回已知纸张格式的宽度、高度
paper_sizes() 预定义纸张尺寸的字典
planish_line() 将一条线映射到 x 轴的矩阵
recover_char_quad() 计算字符（"rawdict"）的四边形
recover_line_quad() 计算线段子集的四边形
recover_quad() 计算跨度（"dict"、"rawdict"）的四边形
recover_span_quad() 计算子集 span 字符的四元组
sRGB_to_pdf() 从 sRGB 整数返回 PDF RGB 颜色三元组
sRGB_to_rgb() 从 sRGB 整数返回 (R, G, B) 颜色三元组
unicode_to_glyph_name() 返回 unicode 的字形名称
get_tessdata() 定位 Tesseract-OCR 安装的语言支持
fitz_fontdescriptors 可用补充字体的字典
TESSDATA_PREFIX os.environ["TESSDATA_PREFIX"] 的副本
pdfcolor 包含近 500 种 PDF 格式 RGB 颜色的字典。 
paper_size(s)

方便函数，返回已知纸张格式代码的宽度和高度。这些值以像素为单位，标准分辨率为 72 像素 = 1 英寸。

当前定义的格式包括 ‘A0’ 至 ‘A10’，‘B0’ 至 ‘B10’，‘C0’ 至 ‘C10’，‘Card-4x6’，‘Card-5x7’，‘Commercial’，‘Executive’，‘Invoice’，‘Ledger’，‘Legal’，‘Legal-13’，‘Letter’，‘Monarch’ 和 ‘Tabloid-Extra’，每种都可以是纵向或横向。

必须提供作为字符串的格式名称（大小写 不 敏感），可选后缀为 “-L”（横向）或 “-P”（纵向）。无后缀默认为纵向。

参数：

s (str) – 大小写不敏感的上述任何格式名称，如 “A4” 或 “letter-l”。

返回类型：

元组

返回：

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

paper_rect(s)

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

参数：

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

返回类型：

矩形

返回：

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

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

sRGB_to_pdf(srgb)

v1.17.4 新增

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

参数：

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

返回：

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

sRGB_to_rgb(srgb)

v1.17.4 新增

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

参数：

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

返回：

一个由整数项目组成的元组（红，绿，蓝），表示相同的颜色，范围为range(256)。示例sRGB_to_pdf(0xff0000) = (255, 0, 0)（红色）。

glyph_name_to_unicode(name)

新功能在 v1.18.0 中

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

参数：

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

返回类型：

整数

返回：

Unicode。无效的name条目返回0xfffd (65533)。

注意

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

unicode_to_glyph_name(ch)

新功能在 v1.18.0 中

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

参数：

ch (int) –

由例如ord("ß")给出的 Unicode。该函数基于Adobe Glyph List。

返回类型：

字符串

返回：

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

注意

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

adobe_glyph_names()

新功能在 v1.18.0 中

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

返回类型：

列表

返回：

字符串列表。

注意

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

adobe_glyph_unicodes()

新功能在 v1.18.0 中

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

返回类型：

列表

返回：

整数列表。

注意

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

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

新功能在 v1.21.0 中

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

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

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

例如，字体代码“notos”指的是字体

  • “notos” - “Noto Sans Regular”
  • “notosit” - “Noto Sans Italic”
  • “notosbo” - “Noto Sans Bold”
  • “notosbi” - “Noto Sans Bold Italic”

该函数创建（最多）四个 CSS @font-face 定义，并将“notos”字体族名称（如果提供了“name”则为其值）分配给它们。相关字体缓冲区被放置/添加到提供的存档中。

要在 Python API 中使用字体对 Story 进行设置，执行.set_font(fontcode)（或者如果提供了“name”则为其名称）。根据需要自动选择正确的字体重量或样式。

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

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

期望并返回包含新的 CSS 定义的 CSS 源码。

参数：

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

返回类型：

str

返回：

修改后的 CSS，其中包含每个字体变体的附加 @font-face 语句。与“fontcode”相关联的字体缓存将被添加到“archive”中。该函数将自动查找最多 4 个字体变体。所有 pymupdf 字体（除数学或音乐等特殊用途外）都具有常规、粗体、斜体和粗斜体变体。要查看当前可用的字体代码，请检查 pymupdf.fitz_fontdescriptors.keys()。这将显示类似于 dict_keys(['cascadia', 'cascadiai', 'cascadiab', 'cascadiabi', 'figbo', 'figo', 'figbi', 'figit', 'fimbo', 'fimo', 'spacembo', 'spacembi', 'spacemit', 'spacemo', 'math', 'music', 'symbol1', 'symbol2', 'notosbo', 'notosbi', 'notosit', 'notos', 'ubuntu', 'ubuntubo', 'ubuntubi', 'ubuntuit', 'ubuntm', 'ubuntmbo', 'ubuntmbi', 'ubuntmit'])。

这是使用“Noto Sans”字体替代“Helvetica”的完整代码片段：

arch = pymupdf.Archive()
CSS = pymupdf.css_for_pymupdf_font("notos", name="sans-serif", archive=arch)
story = pymupdf.Story(user_css=CSS, archive=arch) 

make_table(rect, cols=1, rows=1)

新版本为 v1.17.4

方便函数，将矩形分割为相等大小的子矩形。返回一个包含 rows 列表的列表，每个列表包含 cols 个 Rect 项。然后可以通过其行和列索引访问每个子矩形。

参数：

  • rect (rect_like) – 要分割的矩形。
  • cols (int) – 所需的列数。
  • rows (int) – 所需的行数。

返回：

一个包含等大小的 Rect 对象列表，其并集等于 rect。以下是由 cell = pymupdf.make_table(rect, cols=4, rows=3) 创建的 3x4 表格的布局：

_images/img-make-table.jpg

planish_line(p1, p2)
  • 新版本为 1.16.2。

返回一个映射从 p1 到 p2 的线到 x 轴的矩阵，使得 p1 变为 (0,0)，p2 成为距离 (0,0) 相同距离的点。

参数：

  • p1 (point_like) – 线的起点。
  • p2 (point_like) – 线的终点。

返回类型：

Matrix

返回：

一个结合了旋转和平移的矩阵：

>>> p1 = pymupdf.Point(1, 1)
>>> p2 = pymupdf.Point(4, 5)
>>> abs(p2 - p1)  # distance of points
5.0
>>> m = pymupdf.planish_line(p1, p2)
>>> p1 * m
Point(0.0, 0.0)
>>> p2 * m
Point(5.0, -5.960464477539063e-08)
>>> # distance of the resulting points
>>> abs(p2 * m - p1 * m)
5.0

_images/img-planish.png

paper_sizes()

预定义纸张格式的字典。用作 paper_size() 的基础。

fitz_fontdescriptors
  • 新增于 v1.17.5

从存储库 pymupdf-fonts 获取可用字体的字典。项目以其保留字体名称为键，并提供信息，如下所示：

In [2]: pymupdf.fitz_fontdescriptors.keys()
Out[2]: dict_keys(['figbo', 'figo', 'figbi', 'figit', 'fimbo', 'fimo',
'spacembo', 'spacembi', 'spacemit', 'spacemo', 'math', 'music', 'symbol1',
'symbol2'])
In [3]: pymupdf.fitz_fontdescriptors["fimo"]
Out[3]:
{'name': 'Fira Mono Regular',
'size': 125712,
'mono': True,
'bold': False,
'italic': False,
'serif': True,
'glyphs': 1485}

如果未安装 pymupdf-fonts，则字典为空。

字典键可用于通过例如 font = pymupdf.Font("fimo") 定义 Font - 就像你可以用内置字体“Helvetica”和朋友们做的那样。

TESSDATA_PREFIX
  • 新增于 v1.19.4

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

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

注意

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

pdfcolor
  • 新增于 v1.19.6

包含大约 500 种 PDF 格式的 RGB 颜色，以颜色名称为键。要查看其中内容，可以显然查看 pymupdf.pdfcolor.keys()。

示例：

  • pymupdf.pdfcolor["red"] = (1.0, 0.0, 0.0)
  • pymupdf.pdfcolor["skyblue"] = (0.5294117647058824, 0.807843137254902, 0.9215686274509803)
  • pymupdf.pdfcolor["wheat"] = (0.9607843137254902, 0.8705882352941177, 0.7019607843137254)
get_pdf_now()

返回当前本地时间戳的便捷函数，以 PDF 兼容格式，例如 D:20170501121525-04’00’ 表示本地日期时间 2017 年 5 月 1 日 12:15:25，在 UTC 子午线西边 4 小时的时区。

返回类型：

str

返回：

当前本地 PDF 时间戳。

get_text_length(text, fontname='helv', fontsize=11, encoding=TEXT_ENCODING_LATIN)
  • 新增于版本 1.14.7

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

参数：

  • text (str) – 文本字符串。
  • fontname (str) – 字体名称。必须是 PDF 基础 14 字体 或 CJK 字体之一，由其“保留”字体名称（请参见 Page.insert_font() 中的表格）。
  • fontsize (float) – 字体大小。
  • encoding (int) – 要使用的编码。除了 0 = 拉丁字母、1 = 希腊字母和 2 = 西里尔字母（俄语）之外，还有 Base-14 字体“Helvetica”、“Courier”和“Times”及其变体可用。确保在相应的文本插入中使用相同的值。

返回类型：

float

返回：

字符串在点数上的长度（例如，在 Page.insert_text() 中使用时）。

注意

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

注意

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

警告

如果你使用此函数来确定（Page 或者 Shape）insert_textbox 方法所需的矩形宽度，要注意它们基于字符级计算。由于舍入效应，这将导致一个略大的数字：sum([pymupdf.get_text_length(c) for c in text]) > pymupdf.get_text_length(text)。因此要么（1）做同样的事情，要么（2）在计算中使用像 pymupdf.get_text_length(text + “’”) 这样的方法。

get_pdf_str(text)

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

参数：

text（str）– 要转换的对象

返回类型：

字符串

返回：

PDF 兼容的字符串，包含在 () 或 <> 中。

image_profile(stream)
  • 新增于 v1.16.7
  • 在 v1.19.5 中更改：如果存在，还返回从 EXIF 数据中提取的自然图像方向。
  • 在 v1.22.5 中更改：错误情况下始终返回 None 而不是空字典。

显示作为内存区域提供的图像的重要属性。其主要目的是避免使用其他 Python 包来确定它们。

参数：

stream（bytes|bytearray|BytesIO|file）– 一个在内存中的图像或者已打开的文件。在内存中的图像可以是 bytes、bytearray 或者 io.BytesIO 中的任意一种格式。

返回类型：

字典

返回：

从不会引发异常。在错误情况下返回 None。否则，返回以下项目：

In [2]: pymupdf.image_profile(open("nur-ruhig.jpg", "rb").read())
Out[2]:
{'width': 439,
'height': 501,
'orientation': 0,  # natural orientation (from EXIF)
'transform': (1.0, 0.0, 0.0, 1.0, 0.0, 0.0),  # orientation matrix
'xres': 96,
'yres': 96,
'colorspace': 3,
'bpc': 8,
'ext': 'jpeg',
'cs-name': 'DeviceRGB'}

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

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

注意

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

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

参数：

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

返回类型：

str

ConversionTrailer(output)

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

参数：

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

返回类型：

str

Document.del_xml_metadata()

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

Document.xml_metadata_xref()

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

返回类型：

int

返回：

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

Page.run(dev, transform)

通过设备运行页面。

参数：

  • dev（Device） – 设备，从一个 Device 构造器获取。
  • transform（Matrix） – 应用于页面的转换。如果不需要转换，请将其设置为 Identity。
Page.get_bboxlog(layers=False)
  • v1.19.0 中的新内容
  • v1.22.0 中的更改：可选择还返回适用于边界框的 OCG 名称。

返回：

包围文本、图像或绘图对象的矩形列表。每个项都是元组(type, (x0, y0, x1, y1))，其中第二个元组包含矩形坐标，type 是以下值之一。如果layers=True，则还有第三项包含 OCG 名称或None：(type, (x0, y0, x1, y1), None)。

  • "fill-text" – 普通文本（无字符边框）
  • "stroke-text" – 仅显示字符边框的文本
  • "ignore-text" – 不应显示的文本（例如 OCR 文本层使用）
  • "fill-path" – 使用填充颜色进行绘制（无边框）
  • "stroke-path" – 带有边框的绘图（无填充颜色）
  • "fill-image" – 显示图片
  • "fill-shade" – 显示渐变

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

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

Page.get_texttrace()
  • 新增于 v1.18.16
  • 在 v1.19.0 中更改：添加了键“seqno”。
  • 在 v1.19.1 中更改：描边和填充颜色现在始终是 RGB 或 GRAY
  • 在 v1.19.3 中更改：如果dir != (1, 0)，则跨度和字符边界框现在也是正确的。
  • 在 v1.22.0 中更改：新增字典键“layer”。

返回页面的低级文本信息。该方法适用于所有文档类型。结果是一个带有以下内容的 Python 字典列表：

{
   'ascender': 0.83251953125,          # font ascender (1)
   'bbox': (458.14019775390625,        # span bbox x0 (7)
            749.4671630859375,         # span bbox y0
            467.76458740234375,        # span bbox x1
            757.5071411132812),        # span bbox y1
   'bidi': 0,                          # bidirectional level (1)
   'chars': (                          # char information, tuple[tuple]
               (45,                    # unicode (4)
               16,                     # glyph id (font dependent)
               (458.14019775390625,    # origin.x (1)
               755.3758544921875),     # origin.y (1)
               (458.14019775390625,    # char bbox x0 (6)
               749.4671630859375,      # char bbox y0
               462.9649963378906,      # char bbox x1
               757.5071411132812)),    # char bbox y1
               ( ... ),                # more characters
            ),
   'color': (0.0,),                    # text color, tuple[float] (1)
   'colorspace': 1,                    # number of colorspace components (1)
   'descender': -0.30029296875,        # font descender (1)
   'dir': (1.0, 0.0),                  # writing direction (1)
   'flags': 12,                        # font flags (1)
   'font': 'CourierNewPSMT',           # font name (1)
   'linewidth': 0.4019999980926514,    # current line width value (3)
   'opacity': 1.0,                     # alpha value of the text (5)
   'layer': None,                      # name of Optional Content Group (9)
   'seqno': 246,                       # sequence number (8)
   'size': 8.039999961853027,          # font size (1)
   'spacewidth': 4.824785133358091,    # width of space char
   'type': 0,                          # span type (2)
   'wmode': 0                          # writing mode (1)
}

细节：

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

这里列出了 page.get_texttrace() 与 page.get_text("rawdict") 的相似之处和不同之处：

  • 与“rawdict”提取相比，该方法的速度最多 快两倍。这取决于文本的数量。
  • 返回的数据大小大为显著较小 - 尽管它提供了更多信息。
  • 可以检测到更多类型的文本 不可见性：不透明度 = 0 或类型 > 1 或具有更高序列号的对象的边界框重叠。
  • 如果 MuPDF 对于未识别字符返回 Unicode 0xFFFD（65533），你仍然可以从字形 ID 推断所需信息。
  • span["chars"] 中不包含空格，除非文档创建者已明确编码它们。它们不会像 Page.get_text() 方法中那样被生成。为了帮助你进行自己的计算，这里提供了空格字符的宽度。该值是从字体中获取的，否则将采用备用字体的值。
  • 文本不会像 TextPage 那样进行组织（块、行、跨度和字符的层次结构）。字符只是按顺序逐个提取并放入一个跨度中。每当跨度的特征发生变化时，就会启动一个新的跨度。因此，在同一个跨度中可能会找到具有不同 origin.y 值的字符（这意味着它们将显示在不同的行中）。你不能假设跨度字符按任何特定顺序排序 - 你必须根据 span["dir"]、span["wmode"] 等来理解信息。
  • 连字表示如下：

    • MuPDF 处理以下连字：“fi”、“ff”、“fl”、“ft”、“st”、“ffi” 和 “ffl”（只有前 3 个通常被使用）。例如，如果页面包含连字“fi”，则会在彼此相邻的两个字符项后找到它们：

    • (102, glyph, (x, y), (x0, y0, x1, y1))  # 102 = ord("f")
(105, -1, (x, y), (x0, y0, x0, y1))     # 105 = ord("i"), empty bbox!

    • 这意味着第一个连字字符的 bbox 是包含完整复合字形的区域。后续连字组件可通过其字形值-1 和零宽度的 bbox 识别。

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

      • "ff" -> 0xFB00
      • "fi" -> 0xFB01
      • "fl" -> 0xFB02
      • "ffi" -> 0xFB03
      • "ffl" -> 0xFB04
      • "ft" -> 0xFB05
      • "st" -> 0xFB06

      因此，您可能希望用以下单个元组替换上述两个示例元组：(0xFB01, glyph, (x, y), (x0, y0, x1, y1))（通常不需要在相应字体中查找 0xFB01 的正确字形 id，但您可以执行font.has_glyph(0xFB01)并使用其返回值）。

  • 在 v1.19.3 中更改： 与其他文本提取方法类似，字符和跨度的边界框包围字符四边形。要恢复四边形，请按照 Dictionary Outputs 的结构中解释的相同方法，使用recover_quad()、recover_char_quad()或recover_span_quad()。使用None或span["dir"]表示书写方向。
  • 在 v1.21.1 中更改： 如适用，OCG 的名称将显示在"layer"中。
Page.wrap_contents()

确保页面的所谓图形状态平衡，并且可以正确插入新内容。

在 PyMuPDF 的版本 1.24.1+中，该方法得到了改进，并且根据需要自动执行，因此您不再需要关注它。

在大多数情况下，此方法使Page.clean_contents()的使用过时。该方法的优点是处理时间占用较小，并且对增量保存的数据大小影响较小。

Page.is_wrapped

指示页面的所谓图形状态是否平衡。如果为False，则在插入新内容时应执行Page.wrap_contents()（仅在overlay=True模式下有效）。在更新的版本（1.24.1+）中，此检查和相应的调整将自动执行 - 因此您不再需要担心这个问题。

返回类型：

布尔值

Page.get_text_blocks(flags=None)

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

返回类型：

列表[元组]

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

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

返回类型：

列表[元组]

Page.get_displaylist()

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

返回类型：

DisplayList

返回：

页面的显示列表。

Page.get_contents()

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

返回类型：

list[int]

Page.set_contents(xref)

仅限 PDF：让页面的/Contents键指向此 xref。任何先前使用的 contents 对象都将被忽略，并可以通过垃圾收集来删除。

Page.clean_contents(sanitize=True)
  • 1.17.6 版本中更改

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

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

参数：

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

警告

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

Page.read_contents()

1.17.0 版本中新增. 返回与页面关联的所有contents对象的连接 - 不进行清理或其他修改。每当需要在不必关心有多少个单独的 contents 对象存在的情况下解析此源时，请使用此方法。

返回类型：

bytes

Annot.clean_contents(sanitize=True)

清理与注释关联的contents流。这是与Page.clean_contents()执行的相同类型的操作 - 只是限制于此注释。

Document.get_char_widths(xref=0, limit=256)

返回文档中存在的字体的字符字形和宽度的列表。必须通过其 PDF 交叉引用编号 xref 指定字体。此函数会自动从 Page.insert_text() 和 Page.insert_textbox() 中调用。因此，你很少需要自己执行此操作。

Parameters:

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

Return type:

列表

Returns:

一个 limit 元组列表。每个字符 c 在此列表中具有 (g, w) 的条目，其索引为 ord(c)。元组的 g（整数）是字符的字形 id，浮点数 w 是其归一化宽度。某个 fontsize 的实际宽度可以计算为 w * fontsize。对于简单字体，g 条目总是可以安全忽略的。在所有其他情况下，g 是图形表示 c 的基础。

此函数计算名为 text 的字符串的像素宽度：

def pixlen(text, widthlist, fontsize):
    try:
        return sum([widthlist[ord(c)] for c in text]) * fontsize
    except IndexError:
        raise ValueError:("max. code point found: %i, increase limit" % ord(max(text))) 

Document.is_stream(xref)
  • 新于版本 1.14.14

仅限 PDF：检查由 xref 表示的对象是否为 stream 类型。如果不是 PDF 或者编号超出有效的 xref 范围，则返回 False。

Parameters:

xref (int) – xref 编号。

Returns:

如果对象定义后跟有关键词对 stream、endstream 包装的数据，则返回 True。

Document.get_new_xref()

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

Return type:

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

Document.xref_length()

返回 xref 表的长度。

Return type:

int

Returns:

xref 表中的条目数量。

recover_quad(line_dir, span)

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

Parameters:

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

Returns:

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

recover_char_quad(line_dir, span, char)

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

参数：

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

返回：

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

recover_span_quad(line_dir, span, chars=None)

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

参数：

  • line_dir (tuple) – 所属行的line["dir"]。对于从Page.get_texttrace()获取的跨度，请使用None。
  • span (dict) – 范围。
  • chars (list) – 要考虑的字符。如果给定，则所选的提取选项必须为“rawdict”。

返回：

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

recover_line_quad(line, spans=None)

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

参数：

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

返回：

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

get_tessdata()

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

返回：

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

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

INFINITE_QUAD()

INFINITE_RECT()

INFINITE_IRECT()

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

EMPTY_QUAD()

EMPTY_RECT()

EMPTY_IRECT()

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

是否对本页有任何反馈？

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

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

Discord logo

posted @   绝不原创的飞龙  阅读(108)  评论(0)  编辑  收藏  举报
相关博文：
· PyMuPDF-1-24-4-中文文档-八-
· PyMuPDF-1-24-4-中文文档-十-
· python之pdf转换操作 PyMuPDF库学习
· PyMuPDF使用
· Python处理PDF——PyMuPDF的安装与使用
阅读排行：
· 分享4款.NET开源、免费、实用的商城系统
· 全程不用写代码，我用AI程序员写了一个飞机大战
· MongoDB 8.0这个新功能碉堡了，比商业数据库还牛
· 记一次.NET内存居高不下排查解决与启示
· 白话解读 Dapr 1.15：你的「微服务管家」又秀新绝活了
点击右上角即可分享
微信分享提示