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

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

DocumentWriter

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

此类仅用于 PDF。

• 新功能在 v1.21.0 中添加

此类表示一个实用程序，可以输出各种 PyMuPDF 支持的文档类型。

在 PyMuPDF 中仅用于输出由 Story DOM 填充的 PDF 文档。

在将来也可能使用 DocumentWriter 来处理其他文档类型。

类 API

class DocumentWriter

__init__(self, path, options=None)

创建一个文档写入器对象，传递一个 Python 文件指针或文件路径。还可以传递保存文件时使用的选项。

这个类也可以用作 Python 上下文管理器。

参数：

• 路径 –
  输出文件。这可以是字符串文件名，也可以是任何 Python 文件指针。
  注意
  通过使用 io.BytesIO() 对象作为文件指针，文档写入器可以在内存中创建一个 PDF。随后，此 PDF 可以重新打开以进行输入，并进一步操作。这个技术被几个示例脚本在 Stories recipes 中使用。
  
• options (str) – 指定输出 PDF 的保存选项。典型的是 “compress” 或 “clean”。更多可能的值可以从 mutool convert CLI 实用程序的帮助输出中获得。
  

begin_page(mediabox)

开始一个给定尺寸的新输出页面。

参数：

mediabox (rect_like) – 指定页面大小的矩形。在此方法之后，输出操作可以将内容写入页面。

end_page()

完成一个页面。这会刷新任何挂起的数据并将页面附加到输出文档。

close()

关闭输出文件。这个方法是必需的，以写入任何挂起的数据。

有关使用示例，请参阅 Story 部分。

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

此软件按原样提供，不提供任何形式的保证，无论是明示的还是暗示的。本软件受许可证限制分发，未经授权不得复制、修改或分发。请参阅 artifex.com 上的许可信息，或联系 Artifex Software Inc.，39 Mesa Street，Suite 108A，San Francisco CA 94129，美国以获取更多信息。

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

字体

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

• v1.16.18 中新增

此类表示 MuPDF 中定义的字体（fz_font_s 结构）。它对于新类 TextWriter 和新的 Page.write_text() 是必需的。目前，它与方法 Page.insert_text() 或 Page.insert_textbox() 中使用字体的方式无关。

字体对象还包含有用的一般信息，如字体 bbox、定义的字形数、字形名称或单个字形的 bbox。

类 API

class Font

__init__(self, fontname=None, fontfile=None,

fontbuffer=None, script=0, language=None, ordering=-1, is_bold=0,

is_italic=0, is_serif=0)

字体构造函数。大量参数用于定位最接近要求的字体。并非所有参数都是必需的 - 请参见下面的伪代码，解释了参数的评估逻辑。

参数：

• fontname (str) –
  是 PDF Base 14 Fonts 之一或 CJK 字体名称。还可能是一些其他名称，如（注意正确拼写）：“Arial”，“Times”，“Times Roman”。
  (在 v1.17.5 中更改)
  如果你安装了 pymupdf-fonts，还有新的“保留”字体名称可用，这些名称在 fitz_fonts 和后面的表中列出。
  
• fontfile (str) – 你系统中某处字体文件的文件名 [1]。
  
• fontbuffer (bytes*,bytearray,*io.BytesIO) – 内存中加载的字体文件 [1]。
  
• script (in) – UCDN 脚本编号。目前在 PyMuPDF 中支持的数字为 24，以及 32 至 35。
  
• language (str) – 其中一个值为“zh-Hant”（繁体中文）、“zh-Hans”（简体中文）、“ja”（日语）和“ko”（韩语）。否则，所有来自子集 1、2、3 和 5 的 ISO 639 代码也可能是文档的唯一来源。
  
• ordering (int) – 用于选择 CJK 字体的备选选择器。
  
• is_bold (bool) – 寻找粗体字体。
  
• is_italic (bool) – 寻找斜体字体。
  
• is_serif (bool) – 寻找衬线字体。
  

返回：

成功时是 MuPDF 字体。这是确定适当字体的整体检查顺序：

注意

使用通常的保留名称“helv”、“tiro”等，您将创建具有预期名称“Helvetica”、“Times-Roman”等的字体。 然而，与Page.insert_font()及其相关方法相比，

• 字体文件将始终嵌入到您的 PDF 中，
• 
  
• 希腊文和西里尔文字符无需encoding参数即可支持。

使用 ordering >= 0 或字体名称“cjk”、“china-t”、“china-s”、“japan”或“korea”将始终创建相同的“通用”字体“Droid Sans Fallback Regular”。该字体支持所有中文、日文、韩文和拉丁文字符，包括希腊文和西里尔文。这是一种无衬线字体。

实际上，您几乎永远不需要另一种非衬线字体，除非是**“Droid Sans Fallback Regular”**。 但是，该字体文件相对较大，会增加约 1.65 MB（压缩后）到您的 PDF 文件大小。如果不需要 CJK 支持，请继续指定“helv”、“tiro”等，您将仅需大约 35 KB 的压缩空间。

如果您确定有混合的 CJK 和拉丁文本，请考虑只使用Font("cjk")，因为它支持所有内容，同时显著提高执行速度（最多三倍）：MuPDF 总是能够在这种单一字体中找到任何字符，从不需要检查回退。

但是，如果您使用其他字体，您仍将自动能够编写 CJK 字符：MuPDF 检测到此情况，并自动回退到通用字体（当然这也将被嵌入到您的 PDF 中）。

(v1.17.5 中新增) 可选地，如果安装了pymupdf-fonts，则会提供一些新的“保留”字体名称代码。“Fira Mono” 是一种等宽无衬线字体集，FiraGO 是另一种不带衬线的“通用”字体集，支持所有拉丁文（包括西里尔文和希腊文），以及泰文、阿拉伯文、希伯来文和天城文，但不支持任何 CJK  语言。FiraGO 字体的大小仅为“Droid Sans Fallback”大小的四分之一（压缩为 400 KB vs. 1.65 MB） – 并且 提供粗体、斜体、粗斜体权重 – 这是通用字体所不具备的。

“Space Mono” 是来自 Google Fonts 的另一款精致小巧的等宽字体，支持扩展拉丁字符并提供全部 4 种重要权重。

下表将字体名称代码映射到相应的字体。有关软件包的当前内容，请参阅其文档：

has_glyph(chr, language=None, script=0, fallback=False)

检查 Unicode chr 是否存在于字体中或（选项）某些回退字体中。可用于检查输出中是否会出现任何“TOFU”符号。

参数：

• chr (int) – 字符的 Unicode（即ord()）。
  
• 语言 (str) – 语言 – 目前未使用。
  
• 脚本 (int) – UCDN 脚本编号。
  
• 回退 (bool) – (v1.17.5 中新增) 在回退字体中执行扩展搜索或限制于当前字体（默认）。
  

返回：

(1.17.7 中更改) 字形编号。零表示未找到字形。

valid_codepoints()

• 新增于 v1.17.5

返回一个由该字体支持的 Unicode 数组。

返回：

一个长度最多为Font.glyph_count的array.array [2]。即此数组中每个项目的*chr()*在字体中都有一个字形，而不使用回退字体。这是支持的字形的示例显示：

>>> import pymupdf
>>> font = pymupdf.Font("math")
>>> vuc = font.valid_codepoints()
>>> for i in vuc:
 print("%04X %s (%s)" % (i, chr(i), font.unicode_to_glyph_name(i)))
0000
000D   (CR)
0020   (space)
0021 ! (exclam)
0022 " (quotedbl)
0023 # (numbersign)
0024 $ (dollar)
0025 % (percent)
...
00AC ¬ (logicalnot)
00B1 ± (plusminus)
...
21D0 ⇐ (arrowdblleft)
21D1 ⇑ (arrowdblup)
21D2 ⇒ (arrowdblright)
21D3 ⇓ (arrowdbldown)
21D4 ⇔ (arrowdblboth)
...
221E ∞ (infinity)
... 

注意

此方法仅对具有 CMAP（字符映射、字符映射、/ToUnicode PDF 键）的字体返回有意义的数据。否则，此数组长度为 1，并且仅包含零。

glyph_advance(chr, language=None, script=0, wmode=0)

计算字符字形的“宽度”（视觉表示）。

参数：

• chr (int) – 字符的 Unicode 编号。使用*ord()*而不是字符本身。即使某个字体不支持字符，这通常也应该工作，因为在必要时会检查备用字体。
  
• wmode (int) – 写入模式，0 = 水平，1 = 垂直。
  

其他参数目前未使用。

返回：

表示字形宽度相对于fontsize 1的浮点数。

glyph_name_to_unicode(name)

返回给定字形名称的 Unicode 值。如果要输出特定符号，可以与chr()结合使用。

参数：

name (str) – 字形的名称。

返回：

如果名称未知，则返回 Unicode 整数，或 65533 = 0xFFFD。例如：font.glyph_name_to_unicode("Sigma") = 931，font.glyph_name_to_unicode("sigma") = 963。请参阅Adobe Glyph List发布的字形名称及其 Unicode 编号列表。例如：

>>> font = pymupdf.Font("helv")
>>> font.has_glyph(font.glyph_name_to_unicode("infinity"))
True 

glyph_bbox(chr, language=None, script=0)

字形相对于fontsize 1 的矩形。

参数：

chr (int) – 字符的*ord()*值。

返回：

一个矩形。

unicode_to_glyph_name(ch)

显示字符字形的名称。

参数：

ch (int) – 字符的 Unicode 编号。使用*ord()*而不是字符本身。

返回：

表示字形名称的字符串。例如，font.glyph_name(ord("#")) = "numbersign"。对于无效的代码，“.notfound”将返回。

注意

(自 v1.18.0 起更改) 此方法及Font.glyph_name_to_unicode()不再依赖于字体，而是从Adobe Glyph List中获取信息。也可作为pymupdf.unicode_to_glyph_name()和相应的pymupdf.glyph_name_to_unicode()使用。

text_length(text, fontsize=11)

计算 Unicode 字符串的长度（以点为单位）。

注意

对于仅限 Base-14 字体的功能与get_text_length()存在功能上的重叠。

参数：

• text (str) – 文本字符串，UTF-8 编码。
  
• fontsize (float) – fontsize。
  

返回类型：

浮点数

返回：

存储在 PDF 中时以点为单位的字符串长度。如果字体中不包含某个字符，则会自动在备用字体中查找。

注意

该方法最初是基于调用Font.glyph_advance()在 Python 中实现的。出于性能原因，它在 v1.18.14 中已重写为 C。现在，为了计算单个字符的宽度，您可以选择使用以下任一方法而无需性能惩罚：

1. font.glyph_advance(ord("Ä")) * fontsize
   
2. font.text_length("Ä", fontsize=fontsize)
   

对于多字符字符串，该方法与之前的实现相比具有巨大的性能优势：每个字符约为 0.5 微秒，而第二个及后续字符仅需 12.5 纳秒。

char_lengths(text, fontsize=11)

v1.18.14 中的新功能

Unicode 字符串中字符长度的点序列。

参数：

• 文本（str） – 一个文本字符串，UTF-8 编码。
  
• 字号（float） – 字号.
  

返回类型：

元组（tuple）

返回：

存储在 PDF 中时字符串的字符长度点。它的工作方式类似于Font.text_length()，分解为单个字符。以下是正确的（允许舍入误差）：font.text_length(text) == sum(font.char_lengths(text))。

>>> font = pymupdf.Font("helv")
>>> text = "PyMuPDF"
>>> font.text_length(text)
50.115999937057495
>>> pymupdf.get_text_length(text, fontname="helv")
50.115999937057495
>>> sum(font.char_lengths(text))
50.115999937057495
>>> pprint(font.char_lengths(text))
(7.336999952793121,  # P
5.5,                 # y
9.163000047206879,   # M
6.115999937057495,   # u
7.336999952793121,   # P
7.942000031471252,   # D
6.721000015735626)   # F 

buffer

• 新增于版本 v1.17.6

二进制字体文件内容的副本。

返回类型：

字节（bytes）

flags

包含各种字体属性的字典，每个属性都表示为布尔值。以 Helvetica 为例：

>>> pprint(font.flags)
{'bold': 0,
'fake-bold': 0,
'fake-italic': 0,
'invalid-bbox': 0,
'italic': 0,
'mono': 0,
'opentype': 0,
'serif': 1,
'stretch': 0,
'substitute': 0} 

返回类型：

字典（dict）

name

返回类型：

字符串（str）

字体名称。可能是“”或“(null)”。

bbox

字体边界框。这是其字形边界框的最大值。

返回类型：

矩形

glyph_count

返回类型：

整数（int）

字体中定义的字形数。

ascender

• 新增于版本 v1.18.0

字体的上升值，详见此处。请注意，这与严格的定义有所不同：我们的值包括基线以上的所有内容 - 而不仅仅是大写字母“A”和小写字母“a”之间的高度差异。

返回类型：

浮点数（float）

descender

• 新增于版本 v1.18.0

字体的下降值，详见此处。此值始终为负，并且是某些字形在基线以下延伸的部分，例如“g”或“y”。因此，值上升值 - 下降值是每个字体字形适合的总高度。这至少对大多数字体是正确的 - 如常规字体等等，总会有例外。

返回类型：

浮动（float）

is_writable

• 新增于版本 v1.18.0

指示此字体是否可以与 TextWriter 一起使用。

返回类型：

布尔值（bool）

脚注

对本页有何反馈？

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

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

Identity

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

Identity 是一个矩阵，它不执行任何操作 - 用于当语法要求矩阵但实际上不需要进行任何转换时使用。它的形式为pymupdf.Matrix(1, 0, 0, 1, 0, 0)。

Identity 是一个常量，“不可变”对象。因此，其所有矩阵属性都是只读的，并且其方法被禁用。

如果你需要一个可变的单位矩阵作为起点，请使用以下语句之一：

>>> m = pymupdf.Matrix(1, 0, 0, 1, 0, 0)  # specify the values
>>> m = pymupdf.Matrix(1, 1)              # use scaling by factor 1
>>> m = pymupdf.Matrix(0)                 # use rotation by zero degrees
>>> m = pymupdf.Matrix(pymupdf.Identity)     # make a copy of Identity 

对本页面有任何反馈吗？

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

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

IRect

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

IRect 是一个矩形边界框，与 Rect 非常相似，唯一的区别是所有角坐标都是整数。IRect  用于指定像素区域，例如在渲染期间接收图像数据。否则，例如，关于矩形的空值和有效性的考虑也适用于这个类。方法和属性具有相同的名称，并且在许多情况下通过重用相应的  Rect 对应项来实现。

类 API

class IRect

__init__(self)

__init__(self, x0, y0, x1, y1)

__init__(self, irect)

__init__(self, sequence)

构造函数的重载。还请参阅下面的示例以及 Rect 类的示例。

如果指定了另一个 irect，将创建一个 新副本。

如果指定了序列，它必须是包含 4 个数字的 Python 序列类型（参见 使用 Python 序列作为 PyMuPDF 中的参数）。非整数数字将被截断，非数值将引发异常。

其他参数指整数坐标。

get_area([unit])

计算矩形的面积，并且没有参数时等于 abs(IRect)。与空矩形一样，无限矩形的面积也是零。

参数：

unit (str) – 指定所需单位：“px”（像素，默认）、“in”（英寸）、“cm”（厘米）或“mm”（毫米）的平方。

返回类型：

浮点数

intersect(ir)

计算当前矩形与 ir 的交集（共同的矩形区域），并替换当前矩形。如果任一矩形为空，则结果也为空。如果任一矩形为无限，则另一个被视为结果 - 因此如果两个矩形均为无限，则结果也为无限。

参数：

ir (rect_like) – 第二个矩形。

contains(x)

检查 x 是否包含在矩形内。它可以是 rect_like、point_like 或数字。如果 x 是空矩形，则始终为真。反之，如果矩形为空，则始终为 False；如果 x 不是空矩形且不是数字，则始终为 False；如果 x 是数字，则检查它是否是四个组件之一。x in irect 和 irect.contains(x) 是等效的。

参数：

x (IRect 或 矩形 或 点 或 整数) – 要检查的对象。

返回类型：

布尔值

intersects(r)

检查矩形和 rect_like “r” 是否包含共同非空的 IRect。如果其中任一方为无限或空，则始终为 False。

参数：

r (rect_like) – 要检查的矩形。

返回类型：

布尔值

torect(rect)

• 版本 1.19.3 中的新功能

计算将此矩形转换为给定矩形的矩阵。参见 Rect.torect()。

参数：

rect (rect_like) – 目标矩形。不得为空或无限。

返回类型：

矩阵

返回：

一个矩阵 mat，使得 self * mat = rect。例如，可用于在页面和位图坐标之间进行转换。

morph(fixpoint, matrix)

• 版本 1.17.0 中的新功能

在使用固定点应用矩阵后返回一个新的四边形。

参数：

• fixpoint (point_like) – 固定点。
  
• matrix (matrix_like) – 矩阵。
  

返回：

返回一个新的 Quad。这是同名 quad 方法的包装器。如果是无限的，则返回无限的 quad。

norm()

• 版本 1.16.0 中的新功能

返回矩形作为四个数字向量的欧几里得范数。

normalize()

使矩形变为有限。通过移动矩形的角来实现。在此之后，右下角确实位于左上角的东南方。更多详细信息请参见 矩形。

top_left

tl

等于 Point(x0, y0)。

类型：

点

top_right

tr

等于 Point(x1, y0)。

类型：

点

bottom_left

bl

等于 Point(x0, y1)。

类型：

点

bottom_right

br

等于 Point(x1, y1)。

类型：

点

rect

与浮点坐标相同的 矩形。

类型：

矩形

quad

四边形 Quad(irect.tl, irect.tr, irect.bl, irect.br)。

类型：

四边形

width

包含边界框的宽度。等于 abs(x1 - x0)。

类型：

整数

height

包含边界框的高度。等于 abs(y1 - y0)。

类型：

整数

x0

左角的 X 坐标。

类型：

整数

y0

顶角的 Y 坐标。

类型：

整数

x1

右角的 X 坐标。

类型：

整数

y1

底角的 Y 坐标。

类型：

整数

is_infinite

True 表示矩形无限，False 表示相反。

类型：

布尔值

is_empty

True 表示矩形为空，False 表示相反。

类型：

布尔值

注意

• 此类符合 Python 序列协议，因此也可以通过它们的索引访问组件。还可参考 在 PyMuPDF 中使用 Python 序列作为参数。
  
• 矩形可以与算术运算符一起使用 – 请参阅章节 几何对象的运算代数。
  

对此页面有任何反馈吗？

本软件按原样提供，不提供任何明示或暗示的保证。本软件在许可下分发，并且除非在该许可条款明确授权的情况下，不得复制、修改或分发。有关详细信息，请参阅artifex.com，或联系 Artifex Software Inc., 39 Mesa Street, Suite 108A, San Francisco CA 94129, United States。

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

链接

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

表示指向某处的指针（本文档、其他文档、互联网）。每个文档页面存在链接，并且它们在起始链接开始时是前向链接的，通过页面.first_link属性访问。

链接与其页面之间存在父子关系。如果页面对象变得不可用（关闭文档、任何文档结构更改等），则它的每个现有链接对象也会如此 – 访问链接属性或方法时会引发异常，表明对象是“孤立”的。

类 API

class Link

set_border(border=None, width=0, style=None, dashes=None)

仅限于 PDF：更改边框宽度和虚线属性。

(在版本 1.16.9 中更改) 允许在不使用字典的情况下指定。如果border不是字典，则使用直接参数。

参数：

• 边框 (dict) – 由border属性返回的字典，具有键“width” (float)、“style” (str)和“dashes” (sequence)。省略的键将保持相应属性不变。例如，要删除虚线，请使用：“dashes”: []。如果虚线不是空序列，则“style”将自动设置为“D”（虚线）。
  
• width (float) – 见上文。
  
• style (str) – 见上文。
  
• 虚线 (sequence) – 见上文。
  

set_colors(colors=None, stroke=None)

仅限于 PDF：更改“描边”颜色。

注意

在 PDF 中，链接在技术上是注解的一种子类型，不支持填充颜色。然而，为了保持一致的 API，我们允许指定一个fill=参数，就像所有的注解一样，但会忽略警告。

(在版本 1.16.9 中更改) 允许直接设置颜色。如果colors不是字典，则使用这些参数。

参数：

• 颜色（dict） - 包含颜色规格的字典。有关接受的字典键和值，请参阅下文。最实用的方法应该是首先复制颜色属性，然后根据需要修改此字典。
  
• 描边（sequence） - 见上文。
  

set_flags(flags)

新功能在 v1.18.16 中

设置链接注释的 PDF /F 属性。详见Annot.set_flags()。如果不是 PDF，此方法无效。

flags

新功能在 v1.18.16 中

返回链接注释的标志，一个整数（详见Annot.flags）。如果不是 PDF，则为零。

colors

仅适用于 PDF：包含两个浮点数元组的字典，范围为 0 <= float <= 1，指定描边和填充颜色。如果不是 PDF，则返回 None。如上所述，对于链接，填充颜色始终为 None。描边颜色用于链接矩形的边框。元组的长度隐含确定了颜色空间：1 = 灰度，3 = RGB，4 = CMYK。因此 (1.0, 0.0, 0.0) 代表 RGB 颜色红色。每个浮点数 f 的值通过计算 f = i / 255 映射到范围 0 到 255 的整数值 i。

返回类型：

字典

border

仅适用于 PDF：包含边框特性的字典。对于非 PDF，它将为 None，如果不存在边框信息，则为空字典。可以出现以下键：

• 宽度 - 以点为单位指定边框厚度的浮点数。如果未指定宽度，则值为 -1.0。
  
• 虚线 - 一系列整数，指定线条虚线模式。[] 表示没有虚线，[n] 表示等长的 on-off 长度为 n 点，更长的列表将被解释为指定交替 on-off 长度值。详见 Adobe PDF 参考手册第 126 页获取更多细节。
  
• 样式 - 1 字节边框样式：S（实线）= 围绕注释的实线矩形，D（虚线）= 围绕链接的虚线矩形，虚线模式由 dashes 条目指定，B（斜角）= 一个模拟的凸出矩形，看起来高于页面表面，I（镂空）= 一个模拟的凹陷矩形，看起来低于页面表面，U（下划线）= 注释矩形底部的单线。
  

返回类型：

字典

rect

可以在未转换坐标中点击的区域。

类型：

矩形

is_external

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

类型：

布尔值

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 的）。
  

类型：

str

xref

指定 PDF xref 的整数。如果不是 PDF，则为零。

类型：

int

next

下一个链接或 None。

类型：

Link

dest

链接目标细节对象。

类型：

linkDest

对本页面有任何反馈吗？

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

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

linkDest

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

表示大纲条目或链接的 dest 属性的类。描述这些条目指向的目标。

注意

在 MuPDF v1.9.0 之前，此类存在于 MuPDF 内部，并在版本 1.10.0 中删除。为了向后兼容，PyMuPDF 仍在维护它，尽管它的某些属性实际上不再由 MuPDF 可用的数据支持。

类 API

class linkDest

dest

如果 linkDest.kind 是 LINK_GOTOR 并且 linkDest.page 是 -1，则目标目的地名称。

类型：

字符串

fileSpec

如果 linkDest.kind 是 LINK_GOTOR 或 LINK_LAUNCH，则包含此链接指向的文件名和路径。

类型：

字符串

flags

描述目标的不同方面的有效性和含义的位域。尽可能地，链接目标被构造，以便例如 linkDest.lt 和 linkDest.rb 可以被视为定义一个边界框。但是标志指示哪些值实际上是指定的，请参阅链接目标标志。

类型：

整数

isMap

此标志指定在解析 URI 时是否跟踪鼠标位置。默认值：False。

类型：

布尔值

isUri

指定此目标是否为互联网资源（而不是例如 URI 格式中的本地文件规范）。

类型：

布尔值

kind

指示此目标的类型，例如本文档中的位置、URI、文件启动、操作或另一个文件中的位置。查看链接目标种类以查看名称和数值。

类型：

整数

lt

目标的左上角 Point。

类型：

Point

named

此目的地是执行某些命名操作的引用（例如 JavaScript，请参见 Adobe PDF References）。提供的标准操作包括 NextPage、PrevPage、FirstPage 和 LastPage。

类型：

字符串

newWindow

如果为 true，则应在新窗口中启动目标。

类型：

布尔

page

页面号码（在此文档或目标文档中），此目的地指向。仅在 linkDest.kind 为 LINK_GOTOR 或 LINK_GOTO 时设置。如果 linkDest.kind 为 LINK_GOTOR，可能为 -1。在这种情况下，linkDest.dest 包含目标文档中的目的地的名称。

类型：

整数

rb

此目的地的右下角 点。

类型：

点

uri

此目的地指向的 URI 的名称。

类型：

字符串

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

此软件按原样提供，不附带任何明示或暗示的担保。此软件根据许可分发，除非在许可条款明确授权的情况下，不得复制、修改或分发。有关详细信息，请参阅 artifex.com 的许可信息或联系位于美国加利福尼亚州旧金山 Mesa 街 39 号 108A 套房的 Artifex Software Inc.。

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

矩阵

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

Matrix 是 MuPDF 中用于图像变换的行优先 3x3 矩阵（与 Adobe PDF References  中规定的相应概念一致）。使用矩阵，你可以以多种方式操作页面的渲染图像：（部分）页面可以通过设置仅六个浮点值中的一些或全部来旋转、缩放、翻转、剪切和移动。

由于所有点或像素都存在于二维空间中，该矩阵的一个列向量是一个恒定的单位向量，仅剩下的六个元素用于操作。这六个元素通常用 [a, b, c, d, e, f] 表示。以下是它们在矩阵中的位置：

请注意：

• 下面的方法仅是便利函数 – 它们所做的一切也可以通过直接操作这六个数值来实现。
• 
  
• 所有操作可以组合在一起 – 你可以构造一个矩阵，同时进行旋转 和 剪切 和 缩放 和 平移等操作。然而，如果你选择这样做，请务必查看下面的 备注 或者参考 Adobe PDF References。

类 API

class Matrix

__init__(self)

__init__(self, zoom-x, zoom-y)

__init__(self, shear-x, shear-y, 1)

__init__(self, a, b, c, d, e, f)

__init__(self, matrix)

__init__(self, degree)

__init__(self, sequence)

重载的构造函数。

如果没有参数，将创建零矩阵 Matrix(0.0, 0.0, 0.0, 0.0, 0.0, 0.0)。

zoom- 和 shear- 分别指定缩放或剪切值（浮点数），并创建缩放或剪切矩阵。

对于“矩阵”，将制作一个 新副本 的另一个矩阵。

浮点数“degree”指定了一个逆时针旋转的旋转矩阵的创建。

“序列”必须是任何 Python 序列对象，具有确切的 6 个浮点数条目（参见在 PyMuPDF 中将 Python 序列作为参数使用）。

pymupdf.Matrix(1, 1) 和 pymupdf.Matrix(pymupdf.Identity) 创建可修改版本的 Identity 矩阵，其外观类似 [1, 0, 0, 1, 0, 0]。

norm()

• 版本 1.16.0 中的新功能

返回作为向量的矩阵的欧几里德范数。

prerotate(deg)

将矩阵修改以执行逆时针旋转正deg度，否则顺时针旋转。单位矩阵的元素将按以下方式更改：

[1, 0, 0, 1, 0, 0] -> [cos(deg), sin(deg), -sin(deg), cos(deg), 0, 0]。

参数：

deg (浮点数) – 以度为单位的旋转角度（使用基于π = 180 度的传统表示法）。

prescale(sx, sy)

修改矩阵以按缩放因子 sx 和 sy 进行缩放。仅对属性a至d有影响：[a, b, c, d, e, f] -> [asx, bsx, csy, dsy, e, f]。

参数：

• sx (浮点数) – X 方向的缩放因子。有关影响，请参阅属性a的描述。
  
• sy (浮点数) – Y 方向的缩放因子。有关影响，请参阅属性d的描述。
  

preshear(sx, sy)

修改矩阵以执行剪切操作，即将矩形转换为平行四边形（菱形）。仅对属性a至d有影响：[a, b, c, d, e, f] -> [csy, dsy, asx, bsx, e, f]。

参数：

• sx (浮点数) – X 方向的剪切效果。参见属性c。
  
• sy (浮点数) – Y 方向的剪切效果。参见属性b。
  

pretranslate(tx, ty)

修改矩阵以执行沿 x 轴和/或 y 轴的移动/平移操作。仅对属性e和f有影响：[a, b, c, d, e, f] -> [a, b, c, d, txa + tyc, txb + tyd]。

参数：

• tx (浮点数) – X 方向的平移效果。参见属性e。
  
• ty (浮点数) – Y 方向的平移效果。参见属性f。
  

concat(m1, m2)

计算矩阵乘积 m1 * m2 并将结果存储在当前矩阵中。m1或m2中的任何一个可以是当前矩阵。请注意，矩阵乘法不可交换。因此，m1，m2的顺序很重要。

参数：

• m1 (矩阵) – 第一个（左）矩阵。
  
• m2 (矩阵) – 第二个（右）矩阵。
  

invert(m=None)

计算m的逆矩阵并将结果存储在当前矩阵中。如果m不可逆（“退化”），返回1。在这种情况下，当前矩阵不会更改。如果m可逆，则返回0，并且当前矩阵将替换为m的逆矩阵。

参数：

m (矩阵) – 要求取逆的矩阵。如果未提供，则将使用当前矩阵。

返回类型：

整数

a

在 X 方向的缩放**(宽度)。例如，值为 0.5 会使宽度**缩小一半。如果 a < 0，还将进行左右翻转。

类型：

浮点数

b

导致剪切效果：每个Point(x, y)将变为Point(x, y - b*x)。因此，水平线将会“倾斜”。

类型：

浮点数

c

导致剪切效果：每个Point(x, y)将变为Point(x - c*y, y)。因此，垂直线将会“倾斜”。

类型：

浮点数

d

在 Y 方向的缩放 （高度）。例如，值为 1.5 会将高度拉伸 50%。如果 d < 0，还会发生上下翻转。

类型：

浮点数

e

导致水平移位效果：每个Point(x, y)将变为Point(x + e, y)。正（负）的e值将使其向右（向左）移动。

类型：

浮点数

f

导致垂直移位效果：每个Point(x, y)将变为Point(x, y - f)。正（负）的f值将使其向下（向上）移动。

类型：

浮点数

is_rectilinear

直角坐标意味着不存在错切，并且任何旋转都是 90 度的整数倍。通常用于确认变换前后（轴对齐的）矩形仍然是轴对齐的矩形。

类型：

布尔

注意

• 该类遵循 Python 序列协议，因此也可以通过它们的索引访问组件。还请参阅在 PyMuPDF 中使用 Python 序列作为参数。
  
• 矩阵可以像普通数字一样使用算术运算符：它们可以相加、相减、相乘或相除 – 见章节几何对象的运算代数。
  
• 矩阵乘法是不可交换的 – 改变乘法顺序通常会改变结果。因此很快会不清楚转换会产生哪个结果。
  

例子

下面是一些说明一些可实现效果的例子。所有图片显示一些文本，根据某些矩阵的控制插入到固定参考点（红点）下。

1. 身份矩阵不执行任何操作。

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 Street 39 号的 Artifex Software Inc. 以获取更多信息。

此文档涵盖了所有版本，包括 1.24.4。

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