PyMuPDF 1.24.4 中文文档（十三）（1）-阿里云开发者社区

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

附录 2：关于嵌入式文件的考虑

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

本章提供了关于 PyMuPDF 中嵌入式文件支持的一些背景信息。

总体

从版本 1.4 开始，PDF 支持将任意文件作为 PDF 文档文件的一部分（“嵌入式文件流”）嵌入其中（参见章节“7.11.4 嵌入式文件流”，第 103 页的 Adobe PDF 参考手册）。

在许多方面，这与 ZIP 文件或 MS Windows 中的 OLE 技术中的概念相似。然而，PDF 嵌入式文件不支持像 ZIP 格式那样的目录结构。一个嵌入式文件可以包含自身的嵌入式文件。

这个概念的优点在于，嵌入式文件位于 PDF 的保护伞之下，从其权限/密码保护和完整性方面受益：PDF 可能引用或甚至依赖的所有数据都可以捆绑到其中，因此形成一个单一的、一致的信息单元。

除了嵌入式文件外，PDF 1.7 还添加了集合到其支持范围中。这是一种高级的存储和展示嵌入式文件元信息（即任意和可扩展属性）的方式。

MuPDF 支持

在 MuPDF 版本 1.11 中添加对集合（portfolio）和*/EmbeddedFiles*的初始支持后，此支持在版本 1.15 中再次被删除。

作为结果，命令行实用程序mutool不再提供访问嵌入式文件的功能。

由于 PyMuPDF 在其 1.11.0 版本中响应地实现了*/EmbeddedFiles* API，因此在其 1.16.0 版本开始，不得不改变方向（我们从未发布过与 MuPDF v1.15.x 兼容的 PyMuPDF）。

我们现在正在维护我们自己的代码库，支持嵌入式文件。该代码仅使用基本的 MuPDF 字典和数组函数。

PyMuPDF 支持

我们继续支持旧的 API，关于嵌入式文件的所有内容，只做了轻微的、表面上的变化。

还有一个新功能，可以提供 PDF 中所有已注册嵌入数据名称列表，Document.embfile_names()。

对本页有任何反馈吗？

本软件按原样提供，不带任何明示或暗示的保证。此软件根据许可证分发，未经授权许可，不得复制、修改或分发。有关更多信息，请参阅artifex.com上的许可信息或联系 Artifex Software Inc.，39 Mesa Street，Suite 108A，San Francisco CA 94129，美国。

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

[外链图片转存中…(img-Qb7tttpJ-1718851590733)]

总体

从版本 1.4 开始，PDF 支持将任意文件嵌入作为 PDF 文档文件的一部分（“嵌入文件流”），详见第 7.11.4 章节，“7.11.4 嵌入文件流”页，Adobe PDF 参考手册。

在许多方面，这与 ZIP 文件或 MS Windows 中的 OLE 技术中发现的概念相似。但是，PDF 嵌入文件不支持像 ZIP 格式那样的目录结构。一个嵌入文件可以包含其自身的嵌入文件。

此概念的优势在于嵌入文件位于 PDF 的总称之下，从而受益于其权限/密码保护和完整性方面：PDF 可能引用的或甚至可能依赖的所有数据都可以捆绑到其中，形成一个单一、一致的信息单元。

除了嵌入文件外，PDF 1.7 还扩展了对 collections 的支持范围。这是一种存储和展示嵌入文件元信息（即任意和可扩展属性）的高级方式。

MuPDF 支持

在 MuPDF 版本 1.11 中添加了对 collections（文件集合）和 /EmbeddedFiles 的初始支持后，该支持在版本 1.15 中被再次取消。

因此，cli 实用程序 mutool 不再提供对嵌入文件的访问。

作为其 1.11.0 版本中响应的 /EmbeddedFiles API 的一部分，PyMuPDF 被迫在其 1.16.0 版本中改变方向（我们从未发布过与 MuPDF v1.15.x 兼容的 PyMuPDF）。

现在我们正在维护支持嵌入文件的自有代码库。该代码仅使用基本的 MuPDF 字典和数组功能。

PyMuPDF 支持

我们继续支持关于嵌入文件的完整旧 API，仅有轻微的表现变化。

还有一个新功能，它提供了 PDF 中所有注册嵌入数据名称列表，Document.embfile_names()。

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

此软件按原样提供，没有明示或暗示的任何保证。此软件在许可下分发，未经授权不得复制、修改或分发。有关详细信息，请参阅artifex.com，或联系美国加利福尼亚州旧金山 Mesa 街 39 号 108A 室的 Artifex Software 公司。

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

[外链图片转存中…(img-t7xYWJxx-1718851590734)]

附录 3：各种技术信息

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

本节涉及各种技术主题，它们并非必然相关。

图像变换矩阵

从版本 1.18.11 开始，一些文本和图像提取方法返回图像变换矩阵：Page.get_text() 和 Page.get_image_bbox()。

变换矩阵包含关于图像如何转换以适应某文档页面上的矩形（其“边界框”=“bbox”）的信息。通过检查页面上图像的 bbox 和此矩阵，可以确定例如图像是否以缩放或旋转的方式显示在页面上。

图像尺寸与页面上其 bbox 之间的关系如下：

使用原始图像的宽度和高度，

定义图像矩形 imgrect = pymupdf.Rect(0, 0, width, height)
定义“缩小矩阵” shrink = pymupdf.Matrix(1/width, 0, 0, 1/height, 0, 0)。

使用其缩小矩阵转换图像矩形将导致单位矩形：imgrect * shrink = pymupdf.Rect(0, 0, 1, 1)。
使用图像变换矩阵“transform”，以下步骤将计算出 bbox：

imgrect = pymupdf.Rect(0, 0, width, height)
shrink = pymupdf.Matrix(1/width, 0, 0, 1/height, 0, 0)
bbox = imgrect * shrink * transform

检查矩阵乘积 shrink * transform 将显示有关使图像矩形适应页面 bbox 所发生的一切信息：旋转、边缘缩放和原点平移。让我们看一个例子：

>>> imginfo = page.get_images()[0]  # get an image item on a page
>>> imginfo
(5, 0, 439, 501, 8, 'DeviceRGB', '', 'fzImg0', 'DCTDecode')
>>> #------------------------------------------------
>>> # define image shrink matrix and rectangle
>>> #------------------------------------------------
>>> shrink = pymupdf.Matrix(1 / 439, 0, 0, 1 / 501, 0, 0)
>>> imgrect = pymupdf.Rect(0, 0, 439, 501)
>>> #------------------------------------------------
>>> # determine image bbox and transformation matrix:
>>> #------------------------------------------------
>>> bbox, transform = page.get_image_bbox("fzImg0", transform=True)
>>> #------------------------------------------------
>>> # confirm equality - permitting rounding errors
>>> #------------------------------------------------
>>> bbox
Rect(100.0, 112.37525939941406, 300.0, 287.624755859375)
>>> imgrect * shrink * transform
Rect(100.0, 112.375244140625, 300.0, 287.6247253417969)
>>> #------------------------------------------------
>>> shrink * transform
Matrix(0.0, -0.39920157194137573, 0.3992016017436981, 0.0, 100.0, 287.6247253417969)
>>> #------------------------------------------------
>>> # the above shows:
>>> # image sides are scaled by same factor ~0.4,
>>> # and the image is rotated by 90 degrees clockwise
>>> # compare this with pymupdf.Matrix(-90) * 0.4
>>> #------------------------------------------------

PDF 基础 14 字体

所有 PDF 阅读器必须支持以下 14 种内置字体名称。它们作为一个字典提供，将它们的全名及其小写缩写映射到完整的字体基本名称。在 PyMuPDF 中需要提供字体名称时，可以使用字典中的任何键或值：

In [2]: pymupdf.Base14_fontdict
Out[2]:
{'courier': 'Courier',
'courier-oblique': 'Courier-Oblique',
'courier-bold': 'Courier-Bold',
'courier-boldoblique': 'Courier-BoldOblique',
'helvetica': 'Helvetica',
'helvetica-oblique': 'Helvetica-Oblique',
'helvetica-bold': 'Helvetica-Bold',
'helvetica-boldoblique': 'Helvetica-BoldOblique',
'times-roman': 'Times-Roman',
'times-italic': 'Times-Italic',
'times-bold': 'Times-Bold',
'times-bolditalic': 'Times-BoldItalic',
'symbol': 'Symbol',
'zapfdingbats': 'ZapfDingbats',
'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',
'tibo': 'Times-Bold',
'tiit': 'Times-Italic',
'tibi': 'Times-BoldItalic',
'symb': 'Symbol',
'zadb': 'ZapfDingbats'}

与其义务相反，并非所有 PDF 阅读器都正确和完全支持这些字体——这对于 Symbol 和 ZapfDingbats 尤为明显。此外，字形（视觉）图像将针对每个阅读器具体展现。

要查看这些字体如何使用，包括CJK 内置字体，请参阅 Page.insert_font() 中的表格。

Adobe PDF 参考

Adobe 发布的这本 PDF 参考手册经常在本文档中引用。可以从这里查看和下载。

注意

长时间以来，一个较旧的版本也可以在这里找到。似乎在 2021 年 10 月从网站上移除了该链接。早期（1.19.*之前）的 PyMuPDF 文档版本曾引用过这个文档。我们已经努力替换了上述当前规范的引用。

在 PyMuPDF 中使用 Python 序列作为参数

当 PyMuPDF 对象和方法需要 Python 列表数值时，其他 Python 序列类型 也是允许的。如果 Python 类具有 __getitem__() 方法，则称其实现了 序列协议。

这基本上意味着，在这些情况下，你可以互换使用 Python list 或 tuple，甚至 array.array、numpy.array 和 bytearray 类型。

例如，在以下任何一种方式中指定序列 "s"

s = [1, 2] – 一个列表
s = (1, 2) – 一个元组
s = array.array("i", (1, 2)) – 一个 array.array
s = numpy.array((1, 2)) – 一个 numpy 数组
s = bytearray((1, 2)) – 一个 bytearray

这将使其在以下示例表达式中可用：

pymupdf.Point(s)
pymupdf.Point(x, y) + s
doc.select(s)

与所有几何对象 Rect、IRect、Matrix 和 Point 类似。

因为所有 PyMuPDF 几何类本身都是序列的特殊情况（Quad 除外——见下文），它们可以自由地在可以使用数字序列的地方使用，例如作为 list()、tuple()、array.array() 或 numpy.array() 的参数传递给函数。查看以下代码片段，看看这样做的效果。

>>> import pymupdf, array, numpy as np
>>> m = pymupdf.Matrix(1, 2, 3, 4, 5, 6)
>>>
>>> list(m)
[1.0, 2.0, 3.0, 4.0, 5.0, 6.0]
>>>
>>> tuple(m)
(1.0, 2.0, 3.0, 4.0, 5.0, 6.0)
>>>
>>> array.array("f", m)
array('f', [1.0, 2.0, 3.0, 4.0, 5.0, 6.0])
>>>
>>> np.array(m)
array([1., 2., 3., 4., 5., 6.])

注意

Quad 是一个 Python 序列对象，长度为 4。然而，它的项是point_like类型的——而不是数字。因此，上述说明不适用。

确保 PyMuPDF 中重要对象的一致性

PyMuPDF 是 C 库 MuPDF 的 Python 绑定。尽管 MuPDF 的创建者已经投入了大量精力来近似一种面向对象的行为，但他们显然无法克服 C 语言在这方面的基本缺陷。

另一方面，Python 以非常清晰的方式实现了面向对象模型。PyMuPDF 与 MuPDF 之间的接口代码由两个基本文件组成：pymupdf.py 和 fitz_wrap.c。它们由优秀的 SWIG 工具为每个新版本创建。

当你使用 PyMuPDF 的对象或方法之一时，将导致执行一些代码在 pymupdf.py 中，进而调用一些用 fitz_wrap.c 编译的 C 代码。

因为SWIG会尽力保持 Python 和 C 级别同步，如果严格遵循一定的规则，一切都会正常工作。例如：永远不要访问在关闭（或删除或设置为 None）拥有的文档之后的页面对象。或者，不那么明显的是：在执行文档方法 select()、delete_page()、insert_page() … 等之后，永远不要访问页面或其任何子元素（链接或注释）。

但仅仅不再访问失效的对象是不够的：它们应该被完全主动删除，以释放 C 级别资源（即分配的内存）。

这些规则的原因在于文档与其页面之间以及页面与其链接/注释之间存在层次化的二级一对多关系。为了保持一致的状态，任何上述操作都必须导致完全重置 - 在Python和同步在 C 中。

SWIG无法知道这一点，因此也不执行它。

因此，所需的逻辑已经内置到 PyMuPDF 本身中，如下所示。

如果页面“失去”其所属的文档或者正在被删除本身，那么其当前存在的所有注释和链接在 Python 中将变得不可用，并且它们的 C 级别对应物将被删除和释放。
如果文档被关闭（或删除或设置为 None），或者其结构发生变化，那么所有当前存在的页面及其子页面将变得不可用，并且相应的 C 级别删除将发生。“结构变化”包括方法如 select()、delete_page()、insert_page()、insert_pdf() 等：所有这些操作都将导致对象删除的级联效应。

程序员通常不会意识到这些情况。但是，如果试图访问失效的对象，则会引发异常。

无效的对象不能像 Python 语句 del page 或 page = None 等直接删除。而是必须调用它们的 del 方法。

所有页面、链接和注释都有属性 parent，指向拥有的对象。这是可以在应用程序级别检查的属性：如果 obj.parent == None，则对象的父对象已经不存在，对其属性或方法的任何引用都将引发异常，指示其处于“孤立”状态。

一个示例会话：

>>> page = doc[n]
>>> annot = page.first_annot
>>> annot.type                    # everything works fine
[5, 'Circle']
>>> page = None                   # this turns 'annot' into an orphan
>>> annot.type
<... omitted lines ...>
RuntimeError: orphaned object: parent is None
>>>
>>> # same happens, if you do this:
>>> annot = doc[n].first_annot     # deletes the page again immediately!
>>> annot.type                    # so, 'annot' is 'born' orphaned
<... omitted lines ...>
RuntimeError: orphaned object: parent is None

这展示了级联效应：

>>> doc = pymupdf.open("some.pdf")
>>> page = doc[n]
>>> annot = page.first_annot
>>> page.rect
pymupdf.Rect(0.0, 0.0, 595.0, 842.0)
>>> annot.type
[5, 'Circle']
>>> del doc                       # or doc = None or doc.close()
>>> page.rect
<... omitted lines ...>
RuntimeError: orphaned object: parent is None
>>> annot.type
<... omitted lines ...>
RuntimeError: orphaned object: parent is None

注意

不包括在上述关系之外的对象。例如，如果通过 toc = doc.get_toc() 创建目录，然后关闭或更改文档，则变量 toc 不能也不会以任何方式改变。您有责任根据需要刷新这些变量。

方法设计 Page.show_pdf_page()

目的和能力

该方法在当前页面的指定矩形内显示另一 PDF 文档的（“源”）页面的图像。

与 Page.insert_image() 相反，此显示为基于矢量的，因此在缩放级别上保持准确。
就像 Page.insert_image() 一样，显示的尺寸根据给定的矩形进行调整。

目前支持以下显示变体：

布尔参数"保持比例"控制是否保持宽高比（默认）。

矩形参数"剪辑"限制了源页面矩形的可见部分。默认为整个页面。

浮点数"旋转"以任意角度（度数）旋转显示。如果角度不是 90 的整数倍，则如果"保持比例"也为真，则可能只有 4 个角中的 2 个位置在目标边界上。
布尔参数"覆盖"控制是否将图像放置在当前页面内容的顶部（前景，默认）或不（背景）。

使用案例包括（但不限于）以下内容：

使用相同的图像“邮戳”公司 logo 或水印一系列当前文档页面。
组合任意输入页面到一个输出页面以支持“小册子”或双面打印（称为“4-up”，“n-up”）。
将（大型）输入页面分割成多个任意片段。这也称为“海报化”，因为例如可以水平和垂直分割 A4 页面，将 4 个片段放大到单独的 A4 页面，从而得到原始页面的 A2 版本。

技术实现

这是使用 PDF “表单 XObject” 完成的，参见 Adobe PDF References 第 8.10 节第 217 页。在执行Page.show_pdf_page()时，将执行以下操作：

源文档中源页面的资源和内容对象被复制到目标文档，共同创建一个新的表单 XObject，具有以下属性。该对象的 PDF xref编号由该方法返回。

/BBox 等于源页面的/Mediabox。

/Matrix 等于单位矩阵。

/资源 等同于源页面的内容。这包括对层级嵌套的其他对象（包括字体、图像等）进行“深复制”。此处涉及的复杂性由 MuPDF 的嫁接技术函数[1]覆盖。

这是一种流对象类型，其流是源页面内容对象的组合数据的精确副本。

此表单 XObject 仅在显示源页面时执行一次。后续显示相同的源页面将跳过此步骤，并且仅为该对象创建“指针”形式的表单 XObject（在下一步中完成）。

然后创建第二个表单 XObject，目标页面使用它来调用显示。这个对象具有以下属性：

/BBox 等于源页面的 /CropBox（或 "clip"）。

/Matrix 表示 /BBox 到目标矩形的映射。

/XObject 通过固定名称 fullpage 引用前面的 Form XObject。

这个对象的流包含一个固定的语句：/fullpage Do。

如果方法的 "oc" 参数被指定，其值将被赋予此 Form XObject 作为 /OC。

现在修改目标页面的 resources 和 contents 对象如下。

在 /Resources 的 /XObject 字典中增加一个条目，名称为 fzFrm（选择 n 使得此条目在页面上是唯一的）。

根据 "overlay"，在页面的 /Contents 数组之前或之后添加一个新对象，包含语句 q /fzFrm Do Q。

这种设计方法确保：

（潜在的大型）源页面只复制一次到目标 PDF。每个目标页面只创建小的 “指针” Form XObjects 对象来显示源页面。
每个引用的目标页面可以有自己的 "oc" 参数，用于单独控制源页面的可见性。 ## 重定向错误和警告消息

自 MuPDF 版本 1.16 起，错误和警告消息可以通过官方插件重定向。

PyMuPDF 会将错误消息放置在 sys.stderr 中，并以字符串 “mupdf:” 作为前缀。警告则会被内部存储，并可以通过 pymupdf.TOOLS.mupdf_warnings() 访问。还有一个函数可以清空这个存储。 ## 坐标

这是文档中最常用的术语之一。坐标通常指一对数字 (x, y)，用于表示某个位置，比如矩形的角落（Rect），一个 Point 等等。这两个值通常是浮点数，但有些对象，比如图像，只允许它们为整数。

要实际找到坐标的位置，我们还需要知道 x 和 y 的参考点 - 换句话说，我们必须知道 (0, 0) 的位置在哪里。一旦知道了 (0, 0)（“原点”），我们称之为 “坐标系统”。

文档处理中存在多个坐标系统。例如，PDF 页面和由其创建的图像的坐标系统是不同的。因此，我们需要方法来转换一个坐标系统到另一个（偶尔也需要反向转换）。这就是 Matrix 的任务。它是一个数学函数，类似于可以“乘”以点或矩形的因子，从而给出另一个坐标系统中相应的点/矩形。变换矩阵的逆矩阵可用于恢复变换。就像乘以某个因子，比如 3，可以通过将结果除以 3（或乘以 1/3）来恢复。

坐标和图像

图像具有整数坐标的坐标系。原点 (0, 0) 是左上角。x 值必须在 range(width) 范围内，y 值必须在 range(height) 范围内。因此，如果我们向下移动，y 值会增加。每个图像只有有限数量的坐标，即 width * height。图像中的位置也称为“像素”。

图像的打印尺寸（以厘米或英寸为单位）取决于附加信息：分辨率。分辨率以 DPI（每英寸点数或每英寸像素数）来衡量。因此，要找出某个图像的打印尺寸，我们必须将其宽度和高度分别除以相应的 DPI 值（宽度和高度可能有单独的 DPI 值），得到相应的英寸数。

原点、点大小和 Y 轴

在 PDF 中，页面的原点 (0, 0) 位于其 左下角。而在 MuPDF 中，页面的原点 (0, 0) 位于其 左上角。

[外链图片转存中…(img-REgxR6q0-1718851590735)]

坐标是浮点数，并以 points 为单位，其中：

一点等于 1/72 英寸。

典型的文档页面大小包括 ISO A4 和 Letter。Letter 页面的尺寸为 8.5 x 11 英寸，对应 612 x 792 点。在 PDF 坐标系统中，Letter 页面的左上角因此具有坐标 (0, 792)，因为y 轴向上。现在我们知道我们的文档大小，MuPDF 坐标系统的右下角坐标将是 (612, 792)（对于 PDF，此坐标将是 (612, 0)）。

理论上，PDF 页面上有无限多的坐标位置。然而，实际上，前 5 位小数足以保证合理的精度。
在 MuPDF 中，支持多种文档格式 - PDF 只是其中之一。图像也作为 MuPDF 中的文档进行支持（通常一页）。这也是为什么 MuPDF 使用坐标系，其原点 (0, 0) 是任何文档页面的 左上角 点。y 轴向下，与图像类似。在 MuPDF 中，坐标始终是浮点数，如 PDF 中一样。
例如，在 MuPDF（因此 PyMuPDF）中，矩形 Rect(0, 0, 100, 100) 是一个边长为 100 点的正方形（约为 1.39 英寸或 3.53 厘米）。其左上角是原点。为了在 PDF 和 MuPDF 之间切换坐标系，每个 Page 对象都有一个 Page.transformation_matrix。其逆矩阵可用于计算矩形的 PDF 坐标。通过这种方式，我们可以方便地确定在 MuPDF 中的 Rect(0, 0, 100, 100) 与 PDF 中的 Rect(0, 692, 100, 792) 是相同的。参见以下代码片段：

>>> page = doc.new_page(width=612, height=792)  # make new Letter page
>>> ptm = page.transformation_matrix
>>> # the inverse matrix of ptm is ~ptm
>>> pymupdf.Rect(0, 0, 100, 100) * ~ptm
Rect(0.0, 692.0, 100.0, 792.0)

脚注

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

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

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

[外链图片转存中…(img-Jmn2OXk1-1718851590735)] ## 图像变换矩阵

从版本 1.18.11 开始，某些文本和图像提取方法返回图像变换矩阵：Page.get_text() 和 Page.get_image_bbox()。

变换矩阵包含关于如何将图像变换以适应文档页面上的矩形（其“边界框” = “bbox”）的信息。通过检查页面上图像的 bbox 和此矩阵，可以确定例如图像是否以缩放或旋转的方式显示在页面上。

图像尺寸与其页面上的 bbox 之间的关系如下：

使用原始图像的宽度和高度，

定义图像矩形 imgrect = pymupdf.Rect(0, 0, width, height)
定义“缩放矩阵” shrink = pymupdf.Matrix(1/width, 0, 0, 1/height, 0, 0)。

使用其缩放矩阵转换图像矩形，将得到单位矩形： imgrect * shrink = pymupdf.Rect(0, 0, 1, 1)。
使用图像的 变换矩阵 “transform”，以下步骤将计算 bbox：

imgrect = pymupdf.Rect(0, 0, width, height)
shrink = pymupdf.Matrix(1/width, 0, 0, 1/height, 0, 0)
bbox = imgrect * shrink * transform

检查矩阵乘积 shrink * transform 将显示有关将图像矩形调整到页面上的 bbox 的所有信息：旋转、其边缘的缩放和原点的平移。让我们看一个例子：

>>> imginfo = page.get_images()[0]  # get an image item on a page
>>> imginfo
(5, 0, 439, 501, 8, 'DeviceRGB', '', 'fzImg0', 'DCTDecode')
>>> #------------------------------------------------
>>> # define image shrink matrix and rectangle
>>> #------------------------------------------------
>>> shrink = pymupdf.Matrix(1 / 439, 0, 0, 1 / 501, 0, 0)
>>> imgrect = pymupdf.Rect(0, 0, 439, 501)
>>> #------------------------------------------------
>>> # determine image bbox and transformation matrix:
>>> #------------------------------------------------
>>> bbox, transform = page.get_image_bbox("fzImg0", transform=True)
>>> #------------------------------------------------
>>> # confirm equality - permitting rounding errors
>>> #------------------------------------------------
>>> bbox
Rect(100.0, 112.37525939941406, 300.0, 287.624755859375)
>>> imgrect * shrink * transform
Rect(100.0, 112.375244140625, 300.0, 287.6247253417969)
>>> #------------------------------------------------
>>> shrink * transform
Matrix(0.0, -0.39920157194137573, 0.3992016017436981, 0.0, 100.0, 287.6247253417969)
>>> #------------------------------------------------
>>> # the above shows:
>>> # image sides are scaled by same factor ~0.4,
>>> # and the image is rotated by 90 degrees clockwise
>>> # compare this with pymupdf.Matrix(-90) * 0.4
>>> #------------------------------------------------

PDF 基本 14 字体

下列 14 个内置字体名称 必须由每个 PDF 查看器 应用程序支持。它们可用作字典，将它们的全名和其缩写（小写）映射到完整的字体基本名称。在 PyMuPDF 中需要提供 字体名称 时，可以使用字典中的任何 键或值：

In [2]: pymupdf.Base14_fontdict
Out[2]:
{'courier': 'Courier',
'courier-oblique': 'Courier-Oblique',
'courier-bold': 'Courier-Bold',
'courier-boldoblique': 'Courier-BoldOblique',
'helvetica': 'Helvetica',
'helvetica-oblique': 'Helvetica-Oblique',
'helvetica-bold': 'Helvetica-Bold',
'helvetica-boldoblique': 'Helvetica-BoldOblique',
'times-roman': 'Times-Roman',
'times-italic': 'Times-Italic',
'times-bold': 'Times-Bold',
'times-bolditalic': 'Times-BoldItalic',
'symbol': 'Symbol',
'zapfdingbats': 'ZapfDingbats',
'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',
'tibo': 'Times-Bold',
'tiit': 'Times-Italic',
'tibi': 'Times-BoldItalic',
'symb': 'Symbol',
'zadb': 'ZapfDingbats'}

与他们的义务相反，不是所有的 PDF 查看器都正确和完全支持这些字体 – 这对于 Symbol 和 ZapfDingbats 尤其如此。此外，字形（视觉）图像将针对每个阅读器具体化。

要查看这些字体如何使用，包括 内置 CJK 字体，请查看 Page.insert_font() 中的表格。

Adobe PDF 参考

Adobe 发布的此 PDF 参考手册经常在本文档中引用。可以从此处查看和下载。

注意

长期以来，旧版本还可以在此链接下找到。看起来在 2021 年 10 月从网站上撤下了。早期（1.19.* 之前）版本的 PyMuPDF 文档曾参考过此文档。我们已经努力将对当前规范的引用替换为上面的规范。

在 PyMuPDF 中使用 Python 序列作为参数

当 PyMuPDF 对象和方法需要一个 Python 列表的数值时，其他 Python 序列类型 也是允许的。如果 Python 类有一个 __getitem__() 方法，则称其实现了 序列协议。

这基本上意味着，你可以在这些情况下可以互换使用 Python 列表或元组，甚至 array.array、numpy.array 和 bytearray 类型。

例如，在以下任何一种方式中指定序列 "s"

s = [1, 2] – 一个列表
s = (1, 2) – 一个元组
s = array.array("i", (1, 2)) – 一个 array.array
s = numpy.array((1, 2)) – 一个 numpy 数组
s = bytearray((1, 2)) – 一个 bytearray

将使其在以下示例表达式中可用：

pymupdf.Point(s)
pymupdf.Point(x, y) + s
doc.select(s)

同样地，所有几何对象 Rect、IRect、Matrix 和 Point 也是如此。

因为所有的 PyMuPDF 几何类本身都是序列的特殊情况，所以它们（除了 Quad – 见下文）可以自由地用在可以使用数值序列的地方，例如作为 list()、tuple()、array.array() 或 numpy.array() 的参数。查看以下代码片段以查看其工作原理。

>>> import pymupdf, array, numpy as np
>>> m = pymupdf.Matrix(1, 2, 3, 4, 5, 6)
>>>
>>> list(m)
[1.0, 2.0, 3.0, 4.0, 5.0, 6.0]
>>>
>>> tuple(m)
(1.0, 2.0, 3.0, 4.0, 5.0, 6.0)
>>>
>>> array.array("f", m)
array('f', [1.0, 2.0, 3.0, 4.0, 5.0, 6.0])
>>>
>>> np.array(m)
array([1., 2., 3., 4., 5., 6.])

注意

四边形也是 Python 序列对象，长度为 4。然而，其项是point_like，而不是数字。因此，上述评论不适用。

PyMuPDF 1.24.4 中文文档（十三）（2）https://developer.aliyun.com/article/1559480

PyMuPDF 1.24.4 中文文档（十三）（1）

附录 2：关于嵌入式文件的考虑

总体

MuPDF 支持

PyMuPDF 支持

总体

MuPDF 支持

PyMuPDF 支持

附录 3：各种技术信息

图像变换矩阵

目的和能力

技术实现

坐标和图像

原点、点大小和 Y 轴

PDF 基本 14 字体

Adobe PDF 参考

在 PyMuPDF 中使用 Python 序列作为参数

热门文章

最新文章

相关课程

相关电子书