PyMuPDF 1.24.4 中文文档（十三）

原文：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：

代码语言：javascript复制

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 所发生的一切信息：旋转、边缘缩放和原点平移。让我们看一个例子：

代码语言：javascript复制

>>> 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 种内置字体名称。它们作为一个字典提供，将它们的全名及其小写缩写映射到完整的字体基本名称。在 PyMuPDF 中需要提供字体名称时，可以使用字典中的任何键或值：

代码语言：javascript复制

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() 的参数传递给函数。查看以下代码片段，看看这样做的效果。

代码语言：javascript复制

>>> 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 本身中，如下所示。

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

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

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

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

一个示例会话：

代码语言：javascript复制

>>> 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 

这展示了级联效应：

代码语言：javascript复制

>>> 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 个位置在目标边界上。
• 布尔参数"覆盖"控制是否将图像放置在当前页面内容的顶部（前景，默认）或不（背景）。

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

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

技术实现

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

1. 源文档中源页面的资源和内容对象被复制到目标文档，共同创建一个新的表单 XObject，具有以下属性。该对象的 PDF xref编号由该方法返回。
   1. /BBox 等于源页面的/Mediabox。
   2. /Matrix 等于单位矩阵。
   4. /资源 等同于源页面的内容。这包括对层级嵌套的其他对象（包括字体、图像等）进行“深复制”。此处涉及的复杂性由 MuPDF 的嫁接技术函数[1]覆盖。
   6. 这是一种流对象类型，其流是源页面内容对象的组合数据的精确副本。

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

2. 然后创建第二个表单 XObject，目标页面使用它来调用显示。这个对象具有以下属性：
   1. /BBox 等于源页面的 /CropBox（或 "clip"）。
   3. /Matrix 表示 /BBox 到目标矩形的映射。
   5. /XObject 通过固定名称 fullpage 引用前面的 Form XObject。
   7. 这个对象的流包含一个固定的语句：/fullpage Do。
   9. 如果方法的 "oc" 参数被指定，其值将被赋予此 Form XObject 作为 /OC。
3. 现在修改目标页面的 resources 和 contents 对象如下。
4. 1. 在 /Resources 的 /XObject 字典中增加一个条目，名称为 fzFrm（选择 n 使得此条目在页面上是唯一的）。
   3. 根据 "overlay"，在页面的 /Contents 数组之前或之后添加一个新对象，包含语句 q /fzFrm<n> Do Q。

这种设计方法确保：

1. （潜在的大型）源页面只复制一次到目标 PDF。每个目标页面只创建小的 “指针” Form XObjects 对象来显示源页面。
2. 每个引用的目标页面可以有自己的 "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) 是相同的。参见以下代码片段：

代码语言：javascript复制

>>> 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：

代码语言：javascript复制

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 的所有信息：旋转、其边缘的缩放和原点的平移。让我们看一个例子：

代码语言：javascript复制

>>> 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 中需要提供 字体名称 时，可以使用字典中的任何 键或值：

代码语言：javascript复制

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() 的参数。查看以下代码片段以查看其工作原理。

代码语言：javascript复制

>>> 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 中重要对象的一致性

PyMuPDF 是 C 库 MuPDF 的 Python 绑定。尽管 MuPDF 的创建者已经付出了大量努力来模拟某种面向对象的行为，但他们确实无法克服 C 语言在这方面的基本缺陷。

另一方面，Python 非常清晰地实现了 OO 模型。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 中，如下所示。

1. 如果页面“丢失”其所属文档或本身被删除，则 Python 中所有当前存在的注释和链接将变为不可用，并且它们的 C 级对应物将被删除和释放。
2. 如果文档已关闭（或删除或设置为None），或者其结构已更改，则当前存在的所有页面及其子页面将变为不可用，并且将进行相应的 C 级删除。 "结构更改"包括诸如select()、delete_page()、insert_page()、*insert_pdf()*等方法：所有这些方法都会导致级联的对象删除。

程序员通常不会意识到这一点。然而，如果他试图访问无效的对象，将会引发异常。

无效的对象不能像使用 Python 语句del page或page = None等那样直接删除。相反，必须调用它们的*del*方法。

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

一个示例会话：

代码语言：javascript复制

>>> 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 

这显示了级联效应：

代码语言：javascript复制

>>> 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()一样，显示的大小根据给定的矩形调整。

当前支持以下显示变体：

• 布尔参数"keep_proportion"控制是否保持纵横比（默认）。
  • 矩形参数"clip"限制了源页面矩形的可见部分。默认为整个页面。
• 浮点数"rotation"将显示旋转一个任意角度（度）。如果角度不是 90 的整数倍，则如果也"keep_proportion"为真，则可能只有 4 个角中的 2 个位于目标边界上。
• 布尔参数"overlay"控制是否将图像放在当前页面内容的顶部（前景，默认）或不放置在顶部（背景）。

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

1. “盖章”一系列当前文档页面与相同的图像，如公司标志或水印。
2. 将任意输入页面组合成一个输出页面，以支持“手册”或双面打印（称为“4-up”、“n-up”）。
3. 将（大）输入页面分割成几个任意的片段。这也称为“海报化”，因为您可以将 A4 页面水平和垂直分割，并将 4 个片段放大到单独的 A4 页面上打印，最终得到您原始页面的 A2 版本。

技术实现

这是使用 PDF **“表单 XObject”**完成的，请参阅 Adobe PDF 参考手册第 217 页的 8.10 节。在执行Page.show_pdf_page()时，会发生以下事情：

1. 源文档中源页面的resources和contents对象与目标文档一起复制，共同创建一个新的Form XObject，具有以下属性。此对象的 PDF xref编号由该方法返回。
2. 1. /BBox等于源页面的/Mediabox
   3. /Matrix等于单位矩阵。
   5. /资源 等同于源页面。这涉及“深拷贝”层次嵌套的其他对象（包括字体、图像等）。这里涉及的复杂性由 MuPDF 的嫁接[1]技术函数来处理。
   7. 这是一个流对象类型，其流是源页面contents对象的组合数据的精确副本。

   这个 Form XObject 仅在显示的源页面中执行一次。后续显示相同的源页面将跳过此步骤，仅为此对象创建“指针”Form XObjects（在下一步中完成）。

3. 然后创建第二个Form XObject，目标页面用于调用显示。此对象具有以下属性：
4. 1. /BBox等于源页面的/CropBox（或"clip"）。
   3. /Matrix表示将/BBox映射到目标矩形。
   5. /XObject通过固定名称fullpage引用前一个 Form XObject。
   7. 此对象的流正好包含一个固定语句：/fullpage Do。
   9. 如果方法的"oc"参数已给出，则将其值分配给此 Form XObject 作为/OC。
5. 现在修改了目标页面的resources和contents对象如下。
6. 1. 在/资源的/XObject字典中添加一个条目，名称为fzFrm（n 选取得使该条目在页面上唯一）。
   3. 根据"overlay"，在页面的/Contents数组之前或之后添加一个新对象，其中包含语句q /fzFrm<n> Do Q。

此设计方法确保：

1. 只将（可能很大的）源页面复制一次到目标 PDF 中。每个目标页面仅创建小的“指针”Form XObjects 对象来显示源页面。
2. 每个引用的目标页面可以有自己的"oc"参数来单独控制源页面的可见性。

目的和能力

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

• 与 Page.insert_image() 相比，此显示是基于矢量的，因此在缩放级别上保持准确。
• 与 Page.insert_image() 类似，显示的大小调整为给定的矩形。

当前支持以下显示变体：

• 布尔参数"keep_proportion"控制是否保持纵横比（默认）。
  • 矩形参数"clip"限制源页面矩形的可见部分。默认为整个页面。
• 浮点数"rotation"按任意角度（度）旋转显示。如果角度不是 90 的整数倍，则如果也设置了"keep_proportion"为真，则只有目标边框上的 2 个角可能会定位。
• 布尔参数"overlay"控制是否将图像放在当前页面内容的顶部（前景，默认）或不放置在其上（背景）。

使用情况包括（但不限于）以下内容：

1. “标记”当前文档的一系列页面与相同的图像，比如公司标志或水印。
2. 将任意输入页面合并为一个输出页面，支持“小册子”或双面打印（称为“4-up”，“n-up”）。
3. 将（大型）输入页面分割成多个任意的片段。这也称为“分幅”，例如可以水平和垂直地分割 A4 页面，将 4 个片段放大到单独的 A4 页面上打印，最终得到原始页面的 A2 版本。

技术实施

这是使用 PDF **“Form XObjects”**完成的，请参阅 Adobe PDF References 第 8.10 节第 217 页。在执行Page.show_pdf_page()时，会发生以下事情：

1. 源文档中源页面的resources和contents对象被复制到目标文档，共同创建一个新的Form XObject，具有以下属性。此对象的 PDF xref编号由该方法返回。
2. 1. /BBox等于源页面的/Mediabox。
   3. /Matrix等于单位矩阵。
   5. /Resources等于源页面的资源。这涉及到层次嵌套的其他对象（包括字体、图像等）的“深复制”。这里涉及的复杂性由 MuPDF 的嫁接技术函数[1]覆盖。
   7. 这是一个流对象类型，其流是源页面contents对象的组合数据的精确副本。

   这个 Form XObject 仅在每次显示源页面时执行一次。后续显示相同的源页面将跳过此步骤，并仅创建指向此对象的“指针”Form XObjects（在下一步完成）。

3. 然后创建第二个Form XObject，目标页面使用它来调用显示。此对象具有以下属性：
4. 1. /BBox等于源页面的/CropBox（或"clip"）。
   3. /Matrix表示/BBox到目标矩形的映射。
   5. /XObject通过固定名称fullpage引用前面的 Form XObject。
   7. 此对象的流包含一个固定语句：/fullpage Do。
   9. 如果方法的"oc"参数给定，其值将分配给此 Form XObject 作为/OC。
5. 目标页面的 resources 和 contents 对象现在修改如下。
6. 1. 在 /Resources 的 /XObject 字典中添加一个条目，名称为 fzFrm（选择 n 使得此条目在页面上唯一）。
   3. 根据 "overlay"，在页面的 /Contents 数组前面或后面添加一个新对象，包含语句 q /fzFrm<n> Do Q。

这种设计方法确保了：

1. （可能很大的）源页面仅被复制一次到目标 PDF 中。每个目标页面只创建小的“指针”Form XObjects 对象来显示源页面。
2. 每个引用的目标页面可以有自己的 "oc" 参数，单独控制源页面的可见性。

重定向错误和警告消息

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

PyMuPDF 会将错误消息输出到 sys.stderr，前缀为字符串 “mupdf:”。警告会被内部存储，并可通过 pymupdf.TOOLS.mupdf_warnings() 访问。还存在一个函数可以清空此存储。

坐标

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

要实际找到坐标的位置，我们还需要知道 x 和 y 的参考点——换句话说，我们必须知道位置 (0, 0) 放置在哪里。一旦 (0, 0)（“原点”）确定，我们就谈论一个“坐标系统”。

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

坐标和图像

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

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

原点，点大小和 Y 轴

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

[外链图片转存中…(img-vmPvFaXc-1718851590736)]

坐标是浮点数，以**点（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中的矩形Rect(0, 0, 100, 100)（因此也适用于PyMuPDF），因此是一个边长为 100 点（= 1.39 英寸或 3.53 厘米）的正方形。它的左上角是原点。为了在PDF和MuPDF之间切换坐标系，每个 Page 对象都有一个Page.transformation_matrix。它的逆可以用来计算矩形的 PDF 坐标。通过这种方式，我们可以方便地发现在MuPDF中的Rect(0, 0, 100, 100)等同于PDF中的Rect(0, 692, 100, 792)。请参阅以下代码片段：

代码语言：javascript复制

>>> 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.，美国加利福尼亚州旧金山 Mesa 街 39 号 108A 套房。

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

[外链图片转存中…(img-x2zxKH5m-1718851590736)]

坐标与图像

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

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

原点、点大小和 Y 轴

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

[外链图片转存中…(img-06tkDkAF-1718851590736)]

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

• 一个点等于 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) 是相同的。参见以下代码片段：

代码语言：javascript复制

>>> 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 获取许可信息，或联系美国加利福尼亚州旧金山市 Mesa 街 39 号 108A 套房，Artifex Software Inc. 获取更多信息。

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

[外链图片转存中…(img-YkKEbmrz-1718851590736)]

附录 4：性能比较方法

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

本文记录了测量 PyMuPDF 性能的方法，以及用于比较的工具和示例文件。

下面的三个部分涉及不同的性能方面：

• 文档复制 - 这包括打开和解析 PDF 文件，然后将它们写入输出文件。因为相同的基本活动也用于合并 PDF 文件，所以结果也适用于这些用例。
• 文本提取 - 这从 PDF 中提取纯文本并将其写入输出文本文件。
• 页面渲染 - 这将 PDF 页面转换为看起来与页面相同的图像文件。这种能力是在 Python GUI 脚本中使用工具的基本前提条件，用于滚动文档。我们选择了中等质量（分辨率 150 DPI）的版本。

请注意，在所有情况下，实际处理 PDF 结构的速度并未直接测量：相反，时间记录还包括将文件写入操作系统文件系统的持续时间。这是不可避免的，因为除了 PyMuPDF 之外的工具不提供例如将图像创建步骤与将图像写入文件的后续步骤分离的选项。

因此，所有记录的时间都包括一个通用的面向操作系统的基本工作。因此，实际上每个工具的性能差异要比数字表明的大。

使用的文件

用于性能测试的八个文件集。每个文件我们都有以下信息：

• 文件的名称和下载链接。
• 大小以字节为单位。
• 文件中的总页数。
• 书签（目录条目）的总数。
• 文件中的总链接数。
• 每页的KB 大小。
• 每页文本大小是文件中的总文本量（以 KB 为单位），除以页数。
• 描述文件类型的备注。

名称	大小（字节）	页数	目录大小	链接数	KB/页	每页文本大小	备注
adobe.pdf	32,472,771	1,310	794	32,096	24	1,942	线性化，许多链接/书签
artifex-website.pdf	31,570,732	47	46	2,035	656	3,538	图形导向
db-systems.pdf	29,326,355	1,241	0	0	23	2,142
fontforge.pdf	8,222,384	214	31	242	38	1,058	文本和图形混合
pandas.pdf	10,585,962	3,071	536	16,554	3	1,539	很多页
pymupdf.pdf	6,805,176	478	276	5,277	14	1,937	文本导向
pythonbook.pdf	9,983,856	669	198	1,953	15	1,929
sample-50-MB-pdf-file.pdf	52,521,850	1	0	0	51,291	23,860	单页，图形导向，文件体积大

注意

adobe.pdf 和 pymupdf.pdf 明显是文本导向的，artifex-website.pdf 和 sample-50-MB-pdf-file.pdf 是图形导向的。其他文件则是两者的混合。

使用的工具

在每个部分中，一组固定的 PDF 文件正在被一组工具处理。然而，每个性能方面使用的工具集合因其支持的工具特性而有所不同。

所有工具都是跨平台的，或者至少可以在 Windows 和 Unix/Linux 上运行。

工具	描述
PyMuPDF	本手册的工具。
PDFrw	一个纯 Python 工具，被 rst2pdf 使用，具有与 ReportLab 的接口。
PyPDF2	一个功能丰富的纯 Python 工具集。
PDFMiner	一个纯 Python 工具，用于从 PDF 中提取文本和其他数据。
XPDF	一个带有多功能的命令行实用工具。
PikePDF	类似于 PDFrw 的 Python 包，但基于 C 库 QPDF。
PDF2JPG	专门用于将 PDF 页面渲染为 JPG 图像的 Python 包。

复制/连接/合并

PDF 文件的读取速度和其内容解析的快慢如何？纯粹的解析性能无法直接比较，因为批处理实用工具总是一次性执行请求的任务，从头到尾完全执行。PDFrw 也对解析采取了惰性策略，意味着它只解析文档中任何时刻需要的那些部分。

因此，为了找到问题的答案，我们测量使用每个工具将 PDF 文件复制到输出文件的时间，不做其他操作。

这些是每个工具使用的 Python 命令：

PyMuPDF

代码语言：javascript复制

import pymupdf
doc = pymupdf.open("input.pdf")
doc.save("output.pdf") 

PDFrw

代码语言：javascript复制

doc = PdfReader("input.pdf")
writer = PdfWriter()
writer.trailer = doc
writer.write("output.pdf") 

PikePDF

代码语言：javascript复制

from pikepdf import Pdf
doc = Pdf.open("input.pdf")
doc.save("output.pdf") 

PyPDF2

代码语言：javascript复制

pdfmerge = PyPDF2.PdfMerger()
pdfmerge.append("input.pdf")
pdfmerge.write("output.pdf")
pdfmerge.close() 

观察

这些是我们在秒内的运行时发现，同时附带与 PyMuPDF 相比的基础速率摘要：

名称	PyMuPDF	PDFrw	PikePDF	PyPDF2
adobe.pdf	1.75	5.15	22.37	374.05
artifex-website.pdf	0.26	0.38	1.41	2.81
db-systems.pdf	0.15	0.8	1.68	2.46
fontforge.pdf	0.09	0.14	0.28	1.1
pandas.pdf	0.38	2.21	2.73	70.3
pymupdf.pdf	0.11	0.56	0.83	6.05
pythonbook.pdf	0.19	1.2	1.34	37.19
sample-50-MB-pdf-file.pdf	0.12	0.1	2.93	0.08
总计	3.05	10.54	33.57	494.04

| 与 PyMuPDF 相比的速率 | 1.0 | 3.5 | 11.0 | 162 | ## 文本提取

以下表格显示了纯文本提取持续时间。所有工具都使用了它们的最基本功能 - 即没有布局重新排列等。

观察

这些是我们的运行时发现，以秒为单位，以及与 PyMuPDF 相比的基本速率摘要：

名称	PyMuPDF	XPDF	PyPDF2	PDFMiner
adobe.pdf	2.01	6.19	22.2	49.15
artifex-website.pdf	0.18	0.3	1.1	4.06
db-systems.pdf	1.57	4.26	25.75	42.19
fontforge.pdf	0.24	0.47	2.69	4.2
pandas.pdf	2.41	10.54	25.38	76.56
pymupdf.pdf	0.49	2.34	6.44	13.55
pythonbook.pdf	0.84	2.88	9.28	24.27
sample-50-MB-pdf-file.pdf	0.27	0.44	8.8	13.29
总计	8.01	27.42	101.64	227.27

| 与 PyMuPDF 相比的速率 | 1.0 | 3.42 | 12.69 | 28.37 | ## 页面渲染

我们已经测试了 PyMuPDF 在 150 DPI 分辨率下的渲染速度，与 pdf2jpg 和 XPDF 进行比较，

这些是每个工具的使用 Python 命令：

PyMuPDF

代码语言：javascript复制

def ProcessFile(datei):
print "processing:", datei
doc=pymupdf.open(datei)
for p in pymupdf.Pages(doc):
    pix = p.get_pixmap(dpi=150)
    pix.save("t-%s.png" % p.number)
    pix = None
doc.close()
return 

XPDF

代码语言：javascript复制

pdftopng.exe -r 150 file.pdf ./ 

PDF2JPG

代码语言：javascript复制

def ProcessFile(datei):
    print("processing:", datei)
    pdf2jpg.convert_pdf2jpg(datei, "images", pages="ALL", dpi=150)
    return 

观察

这些是我们的运行时发现，以秒为单位，以及与 PyMuPDF 相比的基本速率摘要：

名称	PyMuPDF	XPDF	PDF2JPG
adobe.pdf	51.33	98.16	75.71
artifex-website.pdf	26.35	51.28	54.11
db-systems.pdf	84.59	143.16	405.22
fontforge.pdf	12.23	22.18	20.14
pandas.pdf	138.74	241.67	202.06
pymupdf.pdf	22.35	39.11	33.38
pythonbook.pdf	30.44	49.12	55.68
sample-50-MB-pdf-file.pdf	1.01	1.32	5.22
总计	367.04	646	851.52
与 PyMuPDF 相比的速率	1.0	1.76	2.32

对此页面有任何反馈吗？

---

此软件按原样提供，不附带任何明示或暗示的担保。此软件根据许可证分发，未经授权不得复制，修改或分发。有关更多信息，请参阅artifex.com的许可信息，或联系美国加利福尼亚州旧金山 Mesa Street 39 号 108A 套房的 Artifex Software Inc。

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

[外链图片转存中…(img-v2kodKdJ-1718851590737)] ## 使用的文件

一组八个文件用于性能测试。对于每个文件，我们有以下信息：

• 文件名称 和下载 链接。
• 文件大小，以字节为单位。
• 文件中的总页数。
• 目录 中的总书签数。
• 链接 的总数。
• 每页的 KB 大小。
• 每页文字大小 是整个文件中的文本量（以 KB 为单位），除以页面数。
• 任何用于概括文件类型的 注释。

名称	大小（字节）	页数	目录大小	链接数	KB/页	文本大小/页	备注
adobe.pdf	32,472,771	1,310	794	32,096	24	1,942	线性化，许多链接 / 书签
artifex-website.pdf	31,570,732	47	46	2,035	656	3,538	以图形为导向
db-systems.pdf	29,326,355	1,241	0	0	23	2,142
fontforge.pdf	8,222,384	214	31	242	38	1,058	文本和图形的混合
pandas.pdf	10,585,962	3,071	536	16,554	3	1,539	很多页
pymupdf.pdf	6,805,176	478	276	5,277	14	1,937	以文本为导向
pythonbook.pdf	9,983,856	669	198	1,953	15	1,929
sample-50-MB-pdf-file.pdf	52,521,850	1	0	0	51,291	23,860	单页，以图形为导向，文件大小较大

注

adobe.pdf 和 pymupdf.pdf 明显以文本为导向，artifex-website.pdf 和 sample-50-MB-pdf-file.pdf 以图形为导向。其他文件则是文本和图形的混合。

使用的工具

在每个部分中，同一固定的 PDF 文件集被一组工具处理。然而，针对每个性能方面使用的工具集会有所不同，这取决于支持的工具功能。

所有工具都是平台无关的，或者至少可以在 Windows 和 Unix / Linux 上运行。

工具	描述
PyMuPDF	本手册的工具。
PDFrw	纯 Python 工具，被 rst2pdf 使用，具有与 ReportLab 的接口。
PyPDF2	具有大量功能集的纯 Python 工具。
PDFMiner	用于从 PDF 中提取文本和其他数据的纯 Python 工具。
XPDF	具有多个功能的命令行实用程序。
PikePDF	与 PDFrw 类似的 Python 包，但基于 C 库 QPDF。
PDF2JPG	专门用于将 PDF 页面呈现为 JPG 图像的 Python 包。

复制 / 连接 / 合并

读取 PDF 文件并解析其内容以进行进一步处理的速度有多快？由于批处理工具总是一次性执行所请求的任务，从头到尾完全完成，因此无法直接比较解析性能。 PDFrw 也具有惰性解析策略，这意味着它只解析在任何时刻都需要的文档部分。

因此，为了找到问题的答案，我们测量了使用每个工具将 PDF 文件复制到输出文件所需的时间，并且不做其他任何操作。

这些是每个工具使用的 Python 命令：

PyMuPDF

代码语言：javascript复制

import pymupdf
doc = pymupdf.open("input.pdf")
doc.save("output.pdf") 

PDFrw

代码语言：javascript复制

doc = PdfReader("input.pdf")
writer = PdfWriter()
writer.trailer = doc
writer.write("output.pdf") 

PikePDF

代码语言：javascript复制

from pikepdf import Pdf
doc = Pdf.open("input.pdf")
doc.save("output.pdf") 

PyPDF2

代码语言：javascript复制

pdfmerge = PyPDF2.PdfMerger()
pdfmerge.append("input.pdf")
pdfmerge.write("output.pdf")
pdfmerge.close() 

观察

这些是我们的运行时间发现，以秒为单位，以及与 PyMuPDF 比较的基准速率摘要：

名称	PyMuPDF	PDFrw	PikePDF	PyPDF2
adobe.pdf	1.75	5.15	22.37	374.05
artifex-website.pdf	0.26	0.38	1.41	2.81
db-systems.pdf	0.15	0.8	1.68	2.46
fontforge.pdf	0.09	0.14	0.28	1.1
pandas.pdf	0.38	2.21	2.73	70.3
pymupdf.pdf	0.11	0.56	0.83	6.05
pythonbook.pdf	0.19	1.2	1.34	37.19
sample-50-MB-pdf-file.pdf	0.12	0.1	2.93	0.08
总计	3.05	10.54	33.57	494.04
与 PyMuPDF 比较的速率	1.0	3.5	11.0	162

文本提取

以下表格显示了纯文本提取持续时间。所有工具均使用其最基本的功能 - 即没有布局重新排列等。

观察

这些是我们的运行时间发现，以秒为单位，以及与 PyMuPDF 比较的基准速率摘要：

名称	PyMuPDF	XPDF	PyPDF2	PDFMiner
adobe.pdf	2.01	6.19	22.2	49.15
artifex-website.pdf	0.18	0.3	1.1	4.06
db-systems.pdf	1.57	4.26	25.75	42.19
fontforge.pdf	0.24	0.47	2.69	4.2
pandas.pdf	2.41	10.54	25.38	76.56
pymupdf.pdf	0.49	2.34	6.44	13.55
pythonbook.pdf	0.84	2.88	9.28	24.27
sample-50-MB-pdf-file.pdf	0.27	0.44	8.8	13.29
总计	8.01	27.42	101.64	227.27
与 PyMuPDF 比较的速率	1.0	3.42	12.69	28.37

页面渲染

我们已经在分辨率为 150 DPI 的情况下测试了 PyMuPDF 与 pdf2jpg 和 XPDF 的渲染速度，

这些是每个工具使用的 Python 命令：

PyMuPDF

代码语言：javascript复制

def ProcessFile(datei):
print "processing:", datei
doc=pymupdf.open(datei)
for p in pymupdf.Pages(doc):
    pix = p.get_pixmap(dpi=150)
    pix.save("t-%s.png" % p.number)
    pix = None
doc.close()
return 

XPDF

代码语言：javascript复制

pdftopng.exe -r 150 file.pdf ./ 

PDF2JPG

代码语言：javascript复制

def ProcessFile(datei):
    print("processing:", datei)
    pdf2jpg.convert_pdf2jpg(datei, "images", pages="ALL", dpi=150)
    return 

观察

这些是我们的运行时间发现，以秒为单位，以及与 PyMuPDF 比较的基准速率摘要：

名称	PyMuPDF	XPDF	PDF2JPG
adobe.pdf	51.33	98.16	75.71
artifex-website.pdf	26.35	51.28	54.11
db-systems.pdf	84.59	143.16	405.22
fontforge.pdf	12.23	22.18	20.14
pandas.pdf	138.74	241.67	202.06
pymupdf.pdf	22.35	39.11	33.38
pythonbook.pdf	30.44	49.12	55.68
sample-50-MB-pdf-file.pdf	1.01	1.32	5.22
总计	367.04	646	851.52
与 PyMuPDF 比较的速率	1.0	1.76	2.32

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

---

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

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

[外链图片转存中…(img-h34TQaNr-1718851590737)]

变更日志

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

1.24.4 版本变更（2024-05-16）

• 修复 3418：重新引入的错误，文本对齐添加了 redact 注释。
• 修复 3472：insert_pdf 给出 SystemError。
• 其他：
  • 修复了 sysinstall 测试在新安装之前未能删除所有先前安装的失败。
  • 修复了utils.do_links()崩溃问题。
  • 更正了 TextPage 创建代码。
  • 统一各种诊断。
  • 修复了page_merge()中的错误。

1.24.3 版本变更（2024-05-09）

• 现在 Python 模块称为pymupdf。fitz仍支持向后兼容。
• 使用 MuPDF-1.24.2。
• 修复的问题：
  • 修复 3357：使用 page.get_text(“text”)时 PyMuPDF==1.24.0 会卡住。
  • 修复 3376：1.24.x 中消除的结果不如预期。
  • 修复 3379：get_text_blocks 返回值顺序与文档不匹配。
  • 修复 3381：内容流包含科学计数法中的浮点数。
  • 修复 3402：无法添加包含字段间计算 JavaScript 的小部件。
  • 修复 3414：缺少属性 set_dpi()。
  • 修复 3430：page.get_text()在 v1.24.2 上与某些 PDF 文件导致进程冻结。
• 其他：
  • 新/修改的方法：
    • Page.remove_rotation()：新功能，将页面旋转设置为零但保持外观。
  • 修复了检查 PDF 属性时的一些问题。
  • 修复了从 sdist 构建的 pip 构建（参见讨论3360：Alpine Linux Docker 构建失败“找不到匹配的分发版本 pymupdfb==1.24.1”）。

1.24.2 版本变更（2024-04-17）

• 从版本中删除了过时的经典实现（先前作为模块fitz_old可用）。
• 修复的问题：
  • 修复 3331：Document.pages()的类型提示错误。
  • 修复 3354：PyMuPDF==1.24.1：属性错误：‘Document’对象的属性‘metadata’没有 setter。
• 其他：
  • 新/修改的方法：
    • Document.bake()：新功能，使注释/字段内容永久化。
    • Page.cluster_drawings()：新功能，根据它们的几何接近性识别彼此属于的绘图项目（即矢量图形或线条艺术）。
    • Page.apply_redactions()：添加了新参数text。
    • Document.subset_fonts()：使用 MuPDF 的 pdf_subset_fonts() 替代 PyMuPDF 的代码。
  • Document 类现在支持以切片形式指定的页码。
  • 避免引起 MuPDF 的警告。

1.24.1 版本（2024-04-02）的变更

• 修复问题：
  • 修复 3278：apply_redactions 移动了一些未遮盖的文本。
  • 修复 3301：在分类链接为 LINK_URI 类型时更宽松。
  • 修复 3306：包含大写‘ET’的文本未显示为注释。
• 其他：
  • 使用 MuPDF-1.24.1。
  • 支持 ObjStm 压缩。方法 Document.save(), Document.ez_save() 和 Document.write() 现在支持新参数 use_objstm, compression_effort 和 preserve_metadata。

1.24.0 版本（2024-03-21）的变更

• 修复问题：
  • 修复 3281：准备元数据（pyproject.toml）未成功运行。
  • 修复 3279：PyMuPDF 不再在 Alpine Linux 中构建。
  • 修复 3257：apply_redactions() 删除了注释框外的文本。
  • 修复 3216：AttributeError：‘Annot’ 对象没有 ‘del’ 属性。
  • 修复 3207：get_drawings 的项缺少 h 路径操作符的行。
  • 修复 3201：合并 PDF 时存在内存泄漏。
  • 修复 3197：page.get_text() 对一些字符返回十六进制文本。
  • 修复 3196：在 1.23.25 版本与 1.20.2 版本中移除文本不起作用。
  • 修复 3172：PDF 的 45º 线条在 PNG 转换中消失。
  • 修复 3135：不要将警告记录到标准输出。
  • 修复 3125：get_pixmap 方法在一页上卡住且永远运行。
  • 修复 2964：页面生成的图像存在问题。
• 其他：
  • 使用 MuPDF-1.24.0。
  • 添加对遮盖矢量图形的支持。
  • 对表模块进行了几处修复。
    • 添加将表输出为 Markdown 字符串的新方法。
    • 解决计算表头对象中的错误： 现在我们允许空值作为单元格值，因为这将在需要时解决（例如在 pandas DataFrame 中）。 我们之前试图强制在所有标题单元格 bboxes 中使用 rect-like 元组，然而对于所有空列的表格来说，这是失败的。此修复使其生效，并在对应单元格字符串中构造空字符串。 现在在聚类图形的 bbox 中正确包括线条的起始 / 终止点。我们之前连接了线条的矩形 - 这没有效果，因为它总是空的。
  • 如果我们无法打开文档，则改进异常文本。
  • 使用新的 libclang 18 构建修复。

版本 1.23.26（2024-02-29）中的更改

• 修复问题：
  • 修复 3199：将 entry_points 添加到 setuptools 配置以提供命令行控制台脚本
  • 修复 3209：墨迹注释中的空顶点
• 其他：
  • 改进表格检测：
    • 改进检查空表格，修复确定表格标题时的错误。
    • 改进包围矢量图形矩形的计算。
    • 忽略更多无意义的“伪”表格
  • 安装命令行 ‘pymupdf’ 命令，运行 fitz/main.py。
  • 在非 Windows 系统上构建时，不要覆盖 MuPDF 的 config.h。
  • 修复 Story 构造函数的 Archive 参数以匹配文档 - 现在接受单个 Archive 构造函数参数。
  • 在构建时不包括 MuPDF 源代码；将在构建时自动下载。

版本 1.23.25（2024-02-20）中的更改

• 修复问题：
  • 修复 3182：Pixmap.invert_irect 参数类型错误
  • 修复 3186：extractText() 从 pdf 中提取的文本损坏
  • 修复 3191：.find_tables() 出现错误
• 其他：
  • 在构建时，能够直接指定 python-config，使用环境变量 PIPCL_PYTHON_CONFIG。

版本 1.23.24（2024-02-19）中的更改

• 修复问题：
  • 修复 3148：表格提取 - 垂直文本处理不正确
  • 修复 3179：表格检测：矢量图形簇分离不正确
  • 修复 3180：无法显示可选内容组：AttributeError: 模块 ‘fitz.mupdf’ 没有属性 ‘pdf_array_push_drop’
• 其他：
  • 能够使用 sudo pip install 而不是 venv 测试系统安装。

版本 1.23.23（2024-02-18）中的更改

• 修复问题：
  • 修复 3126：使用 pathlib.Path 初始化存档失败。
  • 修复 3131：调用注释的下一个属性会引发“没有属性 .parent”警告
  • 修复 3134：在 Page.get_pixmap 中使用 IRect 作为剪辑参数自 1.23.9 以来不再工作
  • 修复 3140：关闭文档后 PDF 文档仍在使用中。
  • 修复 3150：doc.select() 在此文档上挂起。
  • 修复 3163：使用 fitz.IRect 时出现 AssertionError。
  • 修复 3177：构造 Pixmap 时 Unrecognised args for Pixmap。
• 其他：
  • 通过使用新的 MuPDF 函数 pdf_rearrange_pages() 改进了 Document.select()。这是对所需操作更完整（且更快速）的实现，不仅会重新排列页面，还会对目录、链接到已删除页面的链接以及可选内容定义中受影响的条目进行相关更改。
  • TextWriter.appendv()：添加了 small_caps 参数。
  • 通过 MuPDF 主版本修复了一些 valgrind 错误。
  • 修复了使用 MuPDF 主版本构建时的 Document.insert_image()。

版本 1.23.22（2024-02-12）中的更改

• 修复的问题：
  • 修复 3143：doc.get_ocgs() 和 page.get_drawings() 之间 OCGs 名称解码差异。
  • 修复 3139：Pixmap 调整大小需要位置参数“clip” - 即使为 None。
• 其他：
  • 移除了 PyMuPDF 中对 MuPDF 函数 fz_image_size() 的使用。

版本 1.23.21（2024-02-01）中的更改

• 修复的问题：
• 其他：
  • 在 set_xml_metadata() 中修复了错误，PR 3112 https://github.com/pymupdf/PyMuPDF/pull/3112>_：修复 pdf_add_stream 元数据错误。
  • 修复了 TextPage 中缺少 .parent 成员的问题，从 Annot.get_textpage() 中。
  • 修复了 Page.add_widget() 中的错误。

版本 1.23.20（2024-01-29）中的更改

• Bug 修复：
  • 修复 3100：在 get_xml_metadata 中访问错误的内部属性。
• 其他：
  • 显著提高了 Document.get_toc() 的速度。

版本 1.23.19（2024-01-25）中的更改

• Bug 修复：
  • 修复 3087：在指定掩码时插入图像时出现异常。
  • 修复 3094：在 doc.delete_pages 中访问到错误的内部属性 TypeError: ‘<’ not supported between instances of ‘FzLocation’ and ‘int’。
• 其他：
  • 在查找表格时：
    • 允许在查找表格时添加用户定义的“虚拟”矢量图形。
    • 确认矢量图形的包围框是否在剪切矩形内。
    • 避免缓慢的矩形相交查找。
  • 添加了 Font.bbox 属性。

版本 1.23.18（2024-01-23）中的更改

• Bug 修复：
  • 修复 3081：doc.close() 未关闭文档。
• 其他：
  • 减小了 sdist 的大小，以适应 pypi.org（通过减小两个测试文件的大小）。
  • 修复了 Annot.file_info() 如果没有 Desc 项的问题。

版本 1.23.17（2024-01-22）的变更

• Bug 修复：
  • 修复 3062：page_rotation_reset 不会将页面返回到原始旋转。
  • 修复 3070：update_link()：AttributeError：‘Page’ 对象没有 ‘super’ 属性。
• 其他：
  • 修复了 Page.links() 中的 bug（PR #3075）。
  • 修复了 Page.get_bboxlog() 在使用层时的 bug。
  • 在脚本和测试中增加对超时的支持，例如 scripts/ 和 tests/run_compound.py。

版本 1.23.16（2024-01-18）的变更

• Bug 修复：
  • 修复 3058：从 CMYK JPEG 创建的 Pixmap 提供 RGB 格式。
• 其他：
  • 在表检测策略“lines_strict”中排除仅填充的矢量图形。
  • 修复了 sysinstall 测试失败的问题。
  • 在文档中，更新特征矩阵，增加有关文本编写的项目。

版本 1.23.15（2024-01-16）的变更

• Bug 修复：
  • 修复 3050：python3.9 中 pix.set_pixel 在 c.append( ord(i)) 方面存在问题。
• 其他：
  • 改进了 Page.find_tables() 的文档。

版本 1.23.14（2024-01-15）的变更

• Bug 修复：
  • 修复 3038：JM_pixmap_from_display_list > 断言错误：检查错误类型。
  • 修复 3039：在 PyMuPDF 中 doc.close() 不关闭文档的问题。
• 其他：
  • 确保在 Page.get_drawings() 中的“derotated pages” 中有效的 “re” 矩形。

版本 1.23.13（2024-01-15）的变更

• Bug 修复：
  • 修复 2979：在 to_pandas() 中出现列表索引超出范围。
  • 修复 3001：在一个文档上调用 find_tables() 会改变后续文档的边界框。
• 其他：
  • 修复了 Rect.height 和 Rect.width 以确保不返回负值。
  • 修复了 TextPage.extractIMGINFO() 返回的 dictkey_yres 值。

版本 1.23.12（2024-01-12）的变更

• • 修复 3027：Page.get_text 对于 ‘parent’ 抛出属性错误。

版本 1.23.11（2024-01-12）的变更

• 修复了一些 Pixmap 构建错误。
• 修复了 Pixmap.yres()。

版本 1.23.10（2024-01-12）的变更

• Bug 修复：
  • 修复 3020：无法调整 PixMap 的大小。
• 其他：
  • 修复了 Page.delete_image()。

版本 1.23.9（2024-01-11）的变更

• 默认使用新的 “rebased” 实现。
  • 可以通过 import fitz_old as fitz 使用旧的“经典”实现。
  • 欲了解更多有关我们为何转向基于 rebase 的实现，请参阅：github.com/pymupdf/PyMuPDF/discussions/2680
• 使用 MuPDF-1.23.9。
• Bug fixes (rebased implementation only):
  • 修复 2911: Page.derotation_matrix 返回元组而非 Matrix，基于 rebase 的实现
  • 修复 2919: Rebase 版本：在合并 PDF 时 resolve_names 中的 KeyError
  • 修复 2922: 允许插入命名目标链接的新功能未生效
  • 修复 2943: 在使用 apply_redactions() 时出现的 ZeroDivisionError: float division by zero
  • 修复 2950: 在测试期间使用 pip 调用出现问题
  • 修复 2954: 文本提取中替换的 Unicode 字符
  • 修复 2957: apply_redactions() 移动文本
  • 修复 2961: 将字符串作为页码传递时引发 IndexError 而非 TypeError。
  • 修复 2969: annot.next 抛出 AttributeError
  • 修复 2978: 1.23.9rc1: 模块 ‘fitz.mupdf’ 没有属性 ‘fz_copy_pixmap_rect’
  • 修复 2907: 在某些 PDF 中使用 Python 3.12 调用 clean_contents 时发生段错误
  • 修复 2905: SystemError: 返回了一个带有异常的结果
  • 修复 2742: 将同一源页面的三个副本插入一个目标页面时发生的段错误
• 其他：
  • 可选设置透明度到 Page.insert_htmlbox()。
  • 修复在 #2934 中提到的 add_redact_annot() 问题。
  • 修复 Page.rotation() 在非 PDF 文档中返回 0 而非抛出异常。
  • 修复内部四边形检测以应对任何 Python 序列。
  • 修复重置的 fitz.pymupdf_version_tuple - 之前设置为 mupdf 版本。
  • 改进对 Linux 系统安装的支持，包括在 Github 上定期进行测试。
  • 将 flake8 添加到 scripts/gh_release.py:test_packages 中。
  • 使用 MuPDF-1.23.8 中的新公共函数。
  • 改进 scripts/test.py 以帮助调查 MuPDF 问题。

1.23.8 版本变更（2023-12-19）

• Bug fixes (rebased implementation only):
  • 修复 2634: 对于旋转页面，get_toc 和 set_toc 的行为不一致
  • 修复 2861：在 PDF 合并期间的 getLinkDict 中出现 AttributeError。
  • 修复 2871：在 PDF 合并期间 getLinkDict 中出现 KeyError。
  • 修复 2886：在命名链接目标的 Skeleton 中出现错误。
• Bug 修复（重定位和经典实现）：
  • 修复 2885：pymupdf 查找表太慢。
• 其他：
  • 重定位实现：
    • Page.insert_htmlbox()：使用 Story 的新的、更强大的替代Page.insert_textbox()或TextWriter.fill_textbox()，新增。
    • Story.fit*()：用于将 Story 安装到扩展的矩形中的新方法。
    • Story.write_with_links()：新增对外部链接的支持。
    • Document.language()：修复为使用 MuPDF 的新mupdf.fz_string_from_text_language2()。
    • Document.subset_fonts() - 修复。
    • 修复了内部的Archive._add_treeitem()方法。
    • 修复了fitz_new.__doc__，内容包含了 PyMuPDF 和 Python 版本信息，以及操作系统名称。
    • 不再使用(*args, **kwargs)在 API 中，现在明确指定关键字参数。
    • 使用新的 MuPDF Python 异常类。
  • 修复了当button_states()指向间接对象时返回 None 的错误。
  • 修复了 pillow 测试不再忽略所有错误，并在测试时安装 pillow。
  • 添加了对fitz.css_for_pymupdf_font()的测试（使用包pymupdf-fonts）。
  • 简化了 Github Actions 的测试规范。
  • 更新了tests/README.md。

版本 1.23.7 (2023-11-30) 中的更改：

• 重定位实现中的 Bug 修复，在经典实现中未修复的。
  • 修复 2232：几何辅助类应支持关键字参数。
  • 修复 2788：在 pymupdf 1.23.6 中 get_toc 的问题。
  • 修复 2791：在 save() 中出现了小内存泄漏。
• Bug 修复（重定位和经典实现）：
  • 修复 2736：使用负值 mediabox 设置 cropbox 时失败。
  • 修复 2749：RuntimeError: 结构树中的循环。
  • 修复 2753：Story.write_with_links 将在 HTML 中的第一个“分页符”之后忽略所有内容。
  • 修复 2812：横向页面上的 find_tables 生成了反向文本。
  • 修复 2829: 尽管 #2345 已关闭，但仍打印 [cannot create /Annot for kind]
  • 修复 2841: 使用 scrub 时出现意外的 KeyError
• 使用 MuPDF-1.23.7。
• 其他：
  • rebase 实现：
    • 将 flake8 代码检查添加到测试套件，并进行了各种修复。
    • 在 Document 构造函数期间禁用诊断，以匹配经典实现。
  • 对于 2553 的额外修复：版本 >= 1.22 中的无效字符
  • 修复 MuPDF Bug 707324: 故事：HTML 表格行背景色重复打印错误
  • 添加了 scripts/test.py，用于 PyMuPDF git 检出的简单构建 测试。
  • 添加了 fitz.pymupdf_version_tuple，例如 (1, 23, 6)。
  • 恢复了误删除的对 2345 的修复：关闭 utils.py 中的打印语句
  • 在 mupdf_warnings() 返回的警告中包含任何尾随的 ... 重复 <N> 次... 文本（仅 rebase）。

1.23.6 版本变更（2023-11-06）

• Bug 修复：
  • 修复 2553: 版本 >= 1.22 中的无效字符
  • 修复 2608: 不正确的 utf32 文本提取（高低代理项被分割）
  • 修复 2710: page.rect 和文本位置错误 / 与旧版本不同
  • 修复 2774: 排序为 True 时，对 “?” 字符的错误编码
  • 修复 2775: fitz_new 与 python3.10 或更早版本不兼容
  • 修复 2777: 使用 fitz_new 时，Page.mediabox 的类型错误
• 其他：
  • 使用 MuPDF-1.23.5。
  • 添加了 Document.resolve_names()（仅 rebase 实现）。

1.23.5 版本变更（2023-10-11）

• Bug 修复：
  • 修复 2341: 处理 LINK_GOTO 中缩放部分的负值
  • 修复 2522: set_layer() 中的拼写错误 - NameError: name ‘f’ is not defined
  • 修复 2548: 在调用 fitz.Page.get_text_blocks 方法时，某些 PDF 中 Fitz 卡死
  • 修复 2596: save(garbage=3) 破坏了 get_pixmap() 的副作用
  • 修复 2635: “clean=True” 使 PDF 中的对象不可见
  • 修复 2637: Page.insert_textbox 在处理新行的最后一个词时出现错误
  • 修复 2699: 提取段落时与表格下方的问题
  • 修复 2703：角落情况下错误的字体大小计算（“page.get_texttrace()”）
  • 修复 2710：page.rect 和文本位置错误 / 与旧版本不同
  • 修复 2723：Python 3.12 wheel 何时可用？
  • 修复 2730：持久的 get_text() 格式化
• 其他：
  • 使用 MuPDF-1.23.4。
  • 修复了系统安装中的优化标志。
  • 修复了表格识别期间 clip 参数不起作用的问题
  • 支持 Pillow 模式“RGBa”
  • 支持额外的单词分隔符
  • 支持检查有效的 PDF 名称对象

版本 1.23.4（2023-09-26）中的更改

• 改进的构建说明。
• 修复了 rebased 实现中的 Tesseract。
• 改进了使用系统 MuPDF 的构建/安装。
• 修复了 Pyodide 构建。
• 修复了 _insert_image() 中的 rebased bug。
• Bug 修复：
  • 修复 2556：调用 get_cdrawings(extended=True) 时出现分段错误
  • 修复 2637：Page.insert_textbox 错误地处理最后一个字，如果它开始一个新行
  • 修复 2683：Windows sdist 构建失败 - 路径未加引号并使用 UNIX 的 which 命令
  • 修复 2691：Page.get_textpage_ocr() 在 rebased fitz_new 版本中的 bug
  • 修复 2692：Page.get_pixmap(clip=Rect()) 在 rebased fitz_new 版本中的 bug

版本 1.23.3（2023-08-31）中的更改

• 修复了 OCR 的 Tesseract 使用。

版本 1.23.2（2023-08-28）中的更改

• 修复 #2613：发布 1.23.0 不兼容 MacOS-arm64

版本 1.23.1（2023-08-24）中的更改

• 更新了 README 和包摘要描述。
• 修复了一些 Linux 安装上的问题，Python-3.10（以及可能的早期版本）中import fitz失败，出现ImportError: libcrypt.so.2: cannot open shared object file: No such file or directory。
• 修复了 MacOS arm64 上的incompatible architecture错误。
• 修复了 Poetry 关于缺少 wheels’ RECORD 文件中条目的安装警告。

版本 1.23.0（2023-08-22）中的更改

• 添加方法find_tables()到 Page 对象。 这允许在任何支持的文档页面上定位表格，并通过单元格提取表格内容。
• PyMuPDF 的新的“rebased”实现。 rebased 实现可用作 Python 模块fitz_new。它可以用作import fitz_new as fitz的直接替换。
• Python 独立的 MuPDF 库现在在第二个名为PyMuPDFb的 wheel 中，pip 将自动安装它。 这是为了节省空间在 pypi.org 上 - 一个完整的发布只需要一个PyMuPDFb wheel 对于每个操作系统。
• Bug 修复：
  • 修复 #2542：fitz.utils.scrub 属性错误，Annot 对象内没有 fileUpd 属性。
  • 修复 #2533：get_texttrace 返回了一个不正确的字符边界框。
  • 修复 #2537：在设置分组 RadioButton 时验证会抛出 RuntimeError：路径到 ‘V’ 具有间接引用。
• 其他变更：
  • 不再支持 Python-3.7。
  • 修复了错误的页面 / 注释 /Contents 清理。 我们需要将 pdf_filter_options::no_update 设置为零。
  • 添加了新的函数 get_tessdata()。
  • 处理问题 /Annot 数组。 在方法 Document.insert_pdf 中复制页面注释时，我们之前未检查 /Annots 数组成员的有效性。对于故障成员（如 null 或非字典项），这可能导致不必要的异常。此修复实现了更多的检查并跳过这些数组项。
  • 添加了额外的注释类型检查。 我们之前在获取/设置注释边框属性时未检查注释类型。现在根据 MuPDF 进行检查。
  • 增加了容错能力。 在源页面包含无效项 /Annots 数组时，避免方法 insert_pdf() 中的异常。
  • 对适用的注释返回空边框字典。 我们之前即使对于不适用的注释类型也返回了非空边框字典。现在在这些情况下返回空字典 {}。这要求注释 .update() 方法做出相应的更改，特别是对于虚线和边框宽度。
  • 将 set_rect 限制为适用的注释类型。 我们之前在 set_rect() 方法中未能充分排除不适用的注释类型。现在让 MuPDF 捕获不支持的注释，并在这些情况下返回 False。
  • 在 page.get_texttrace() 中错误地计算了字体大小。 计算字体大小时我们使用了最终文本转换矩阵，而应该使用 span->trm。这里进行了修正。
  • 更新以适应最新的 MuPDF 变更。 pdf_lookup_anchor() 已移除。
  • 更新 fill_textbox 以更好地尊重 rect.width。 fill_textbox 中的 norm_words 函数在其最后一个循环中存在 bug，当实际测量 n 个字符的宽度时，会附加 n 1 个字符。这导致当您尝试写入一个主要由“宽”字母（M，m，W，w…）组成的单词时，会导致写入的文本超出给定的矩形框。 修复仅仅将 n 1 替换为 n 的问题。
  • 在小部件中添加了 script_focus 和 script_blur 选项。

1.22.5 版本变更 (2023-06-21)：

• 本版本使用 MuPDF-1.22.2。
• 错误修复：
  • 修复 #2365：类型为“fs”绘图的字典值不正确。
  • 修复 #2391：更新同一复选框超过 1 次会自动取消选中。
  • 修复 #2400：同一行文本中的间隙未填充空格。
  • 修复 #2404：在版本 1.22.X 中，PDF 中的图像不会被覆盖。
  • 修复 #2430：错误地减少了 Py_None 的引用计数。
  • 修复 #2450：带有填充和描边操作的路径的空填充颜色和填充不透明度在版本 1.22.*中为空。
  • 修复 #2462：在“get_drawing(extended=True )”处出现错误。
  • 修复 #2468：尝试获取绘图时的解码错误。
  • 修复 #2710：页面矩形和文本位置与旧版本不同。
  • 修复 #2723：Python 3.12 的 wheel 何时可用？
• 新功能：
  • 更改：现在注释支持“云”边框。Annot.border属性新增了clouds项，方法Annot.set_border()支持相应的clouds参数。
  • 更改：现在，同一单选按钮组中的单选按钮小部件在标准定义的情况下始终会被一致更新。
  • 新增：在 PDF 可选内容中支持/Locked关键字。现在可以提取和设置/OCProperties内部的数组。
  • 新增：在 OCR 功能中新增参数tessdata的支持。新函数get_tessdata()可以定位语言支持文件夹，如果安装了 Tesseract。

版本 1.22.3（2023-05-10）中的更改

• 此版本使用MuPDF-1.22.0。
• 缺陷修复：
  • 修复 #2333：无法在表单中设置任何单选按钮组。

版本 1.22.2（2023-04-26）中的更改

• 此版本使用MuPDF-1.22.0。
• 缺陷修复：
  • 修复 #2369：在新版本中提取图像的错误。

版本 1.22.1（2023-04-18）中的更改

• 此版本使用MuPDF-1.22.0。
• 缺陷修复：
  • 修复 #2345：关闭 utils.py 中的打印语句。
  • 修复 #2348：提取图像返回扩展名“flate”而不是“png”。
  • 修复 #2350：无法通过添加标志 PDF_FIELD_IS_READ_ONLY 使小部件（复选框）只读。
  • 已修复 #2355：使用 get_toc 时出现 1.22.0 错误（AttributeError: ‘SwigPyObject’ 对象没有属性）

版本 1.22.0 中的变更 (2023-04-14)

• 此版本使用 MuPDF-1.22.0。
• 行为变更：
  • 现在文本提取包括与剪辑矩形重叠的字形；以前仅当它们完全包含在剪辑矩形内时才包括它们。
• Bug 修复：
  • 已修复 #1763：交互（智能表单）形式的 PDF 计算在 pymupdf 中无效
  • 已修复 #1995：在尝试时，长页 pdf 文件中的图像太高而导致 RuntimeError
  • 已修复 #2093：在应用消隐后，pdf 中的图像颜色变化
  • 已修复 #2108：消隐删除的文本比预期的多
  • 已修复 #2141：尝试获取块时，读取 JPX 标头失败
  • 已修复 #2144：替换图像引发错误
  • 已修复 #2146：错误处理“None”对象的引用计数
  • 已修复 #2161：支持直接添加图像作为页面
  • 已修复 #2168：page.add_highlight_annot(start=pointa, stop=pointb) 无效
  • 已修复 #2173：在 Pixmap 中使用的 Colorspace 被双重释放
  • 已修复 #2179：pixmap.tint_with() 的文档错误
  • 已修复 #2208：推动按钮小部件显示为复选框
  • 已修复 #2210：apply_redactions() 将 pdf 文本移动到删除后
  • 已修复 #2220：Page.delete_image() | 对象没有属性 is_image
  • 已修复 #2228：打开某些 pdf 花费太多时间
  • 已修复 #2238：Bug - 无法从最新版本 1.21.1 中提取数据
  • 已修复 #2242：如果回调函数原型错误，Python 在 Story.element_positions() 中会静默退出
  • 已修复 #2246：TextWriter 在错误的位置写入文本
  • 已修复 #2248：消隐内容后，剩余文本的位置发生变化
  • 已修复 #2250：文档：页面.rst 中的链接不明确或损坏
  • 已修复 #2251：在加载损坏的图像时，mupdf_display_errors 不适用于 Pixmap
  • 修复 #2270：Annot.get_text("words") - 不返回第一行单词
  • 修复 #2275：insert_image：文档中指出旋转是逆时针方向的
  • 修复 #2278：无法通过添加标志 PDF_FIELD_IS_READ_ONLY 将小部件（复选框）设置为只读
  • 修复 #2290：Page.get_text(“dict”) 和 Fitz.get_page_images() 返回的图像格式/数据不同
  • 修复 #2293：在我的系统上从 sdist 安装时出现 68 个测试失败的问题
  • 修复 #2300：树中存在过多的递归（父节点），导致程序终止
  • 修复 #2322：使用裁剪生成 add_highlight_annot 时出现“数字超出范围”的错误
• 其他：
  • 在所选按钮表单字段的底层注释对象中添加了键“/AS（是）”。
  • 删除了未使用的 Document 方法 has_xref_streams() 和 has_old_style_xrefs()，因为 MuPDF 中的相应方法已被删除。
  • 添加了新的 Document 方法和属性以获取/设置 /PageMode、/PageLayout 和 /MarkInfo。
  • 新的 Document 属性 version_count，其中包含增量保存的次数加一。
  • 新的 Document 属性 is_fast_webaccess，用于指示文档是否是线性化的。
  • DocumentWriter 现在是一个上下文管理器。
  • 添加了对 Pixmap JPEG 输出的支持。
  • 添加了支持绘制带圆角矩形的功能。
  • get_drawings(): 添加了可选的 extended 参数。
  • 修复了跟踪设备状态未正确初始化的问题；来自诸如 fitz.Page.get_texttrace() 等的数据可能会稍微更改，例如 linewidth 值。
  • 如果看起来我们正在使用包含无效的 fitz/ 目录的当前目录，则向 stderr 输出警告，因为这可能会破坏对 fitz 模块的导入。例如，如果尝试在当前目录是 PyMuPDF 检出时使用 fitz，就会发生这种情况。
• 文档：
  • 总体重构：
    • 引入了新的主页和新的目录。
    • 结构更新以包括新的关于部分。
    • 比较和性能图表。
    • 在附录中包含了性能方法。
    • 更新了 conf.py 以理解单个反引号作为代码。
    • 将双反引号转换为单反引号。
    • 删除了多余的文件。
  • 改进了 insert_file() 文档。
  • get_bboxlog(): 向 get_bboxlog() 添加了可选的 layers。
  • Page.get_texttrace(): 添加了新的字典键 layer，表示可选内容组的名称。
  • 在安装文档中提及了 Python venv 的使用。
  • 添加了对版本 1.21.1 的发行说明的遗漏修复 #2057。
  • 修复了许多指向 PyMuPDF-Utilities 存储库脚本的链接。
  • 避免了 changes.txt 和 docs/changes.rst 的重复。
• 构建：
  • 添加了 pyproject.toml 文件以改善使用 pip 等构建的过程。

版本 1.21.1 中的更改（2022-12-13）

• 本版本使用了MuPDF-1.21.1。
• 错误修复：
  • 修复 #2110: 如果占用多个对象，完全嵌入的字体仅部分提取
  • 修复 #2094: 矩形检测逻辑
  • 修复 #2088: 目标点未在 toc 中的命名链接中设置
  • 修复 #2087: 提取带有过滤器“[/FlateDecode/JPXDecode]”的图像
  • 修复 #2086: Document.save() 的 owner_pw 和 user_pw 存在缓冲区溢出漏洞
  • 修复 #2076: fitz.py 中的段错误
  • 修复 #2057: PyMuPDF 1.21.0 中 Document.save 的垃圾参数不起作用
  • 修复 #2051: 缺少 DPI 参数
  • 修复 #2048: TextPage 和 bbox 在最新版本 1.21.0 中的无效大小
  • 修复 #2045: SystemError: <built-in function Page_get_texttrace> 返回带有错误设置的结果。
  • 修复 #2039: 1.21.0 无法构建到系统 libmupdf 的问题
  • 修复 #2036: Archive::Archive 定义两次
• 其他
  • 在链接的 URI 字符串中忽略“&zoom=nan”。
  • 添加了新的页面工具方法 Page.replace_image() 和 Page.delete_image()。
• 文档：
  • #2040: 在 tests/README.md 中添加了关于使用非默认构建的 MuPDF 的测试失败的说明。
  • #2037: 在 docs/installation.rst 中提到在 Windows 上与 chocolatey.org 的不兼容性。
  • #2061: 修正了Annot.file_info的描述。
  • #2065: 显示如何插入内部 PDF 链接。
  • 改进了在没有 sdist 的情况下从源代码构建的描述。
  • 添加了关于运行测试的信息。
  • #2084: 修复了指向 PyMuPDF-Utilities 的损坏链接。

1.21.0 版本变更（2022-11-8）

• 本版本使用了MuPDF-1.21.0。
• 新功能：Stories。
• 为 Python-3.11 添加了 wheels。
• 错误修复：
  • 修复 #1701: 破损的自定义图像插入。
  • 修复 #1854: Document.delete_pages() 拒绝关键字参数。
  • 修复 #1868: 在 page.apply_redactions() 中的访问冲突错误。
  • 修复 #1909: 使用 fontname="Helvetica" 添加文本可能会静默失败。
  • 修复 #1913：draw_rect()：如果未指定颜色，则不会遵守宽度。
  • 修复 #1917：subset_fonts()：现在可以静音输出。
  • 修复 #1936：矩形检测可能不正确，导致输出错误。
  • 修复 #1945：在使用clean=True保存时出现分段错误。
  • 修复 #1965：pdfocr_save() 硬崩溃。
  • 修复 #1971：在使用get_drawings()时发生分段错误。
  • 修复 #1946：在get_text()文档中，block_no和block_type被错误地交换。
  • 修复 #2013：在删除小部件时出现 AttributeError: ‘Widget’ object has no attribute ‘_annot’。
• 核心代码的其他更改：
  • 修复了各种编译器警告和序列点错误。
  • 增加了对 Memento 构建的支持。
  • 修复了 Memento 在测试套件中检测到的内存泄漏问题。
  • 修复了在set_name()和set_rect()中处理异常的问题。
  • 允许使用最新的 MuPDF 进行构建，用于 PyMuPDF 主分支的定期测试。
  • 适应了设置某些注释类型的矩形时出现新的 MuPDF 异常。
  • 减少了 MuPDF 的 config.h 与 PyMuPDF 的 _config.h 之间的外观差异。
  • 适应了 MuPDF API 的各种更改。
• 其他：
  • 修复了文档中各种失效链接和拼写错误。
  • 提到在 MacOS 上安装swig-python以解决＃875。
  • 增加了（未经测试的）macos-arm64 的 wheel。

版本 1.20.2 中的变更

• 此版本使用了MuPDF-1.20.3。
• 修复 #1787。修复了 Unix 系统上的链接问题。
• 修复 #1824。在应用重叠透明图像的修正时导致 SegFault。（在MuPDF-1.20.3中已修复。）
• 文档改进：
  • 在docs/installation.rst中改进了有关从源代码构建的信息。
  • 澄清了内存分配设置 pyJM_MEMORY` in ``docs/tools.rst。
  • 修复了在docs/app3.rst中对 PDF 参考手册的链接。
  • 在 OpenBSD 上修复了 HTML 文档的构建问题。
  • 将旧的docs/faq.rst移动到单独的docs/recipes-*文件中。
• 移除了一些未使用的文件和目录。
  • installation/
  • docs/wheelnames.txt

版本 1.20.1 中的变更

• 修复 #1724。修复了在 FreeBSD 上的构建问题。
• 修复 #1771。linkDest() 中对re.match()的调用存在问题，这在 1.20.0 中引入。
• 修复 #1751。get_drawings()和get_cdrawings()之前总是以closePath=False返回。
• 修复 #1645。默认的自由文本注释文本颜色现在是黑色。
• 改进了 sphinx 生成的文档：
  • 使用增强的 readthedocs 主题。
  • 将.txt文件重命名为.rst后缀。

---

1.20.0 版本变更

本次发布使用了MuPDF-1.20.0，发布日期为 2022-06-15。

• 适应了新的 MuPDF 链接 URI 格式，从#<int>,<int>,<int>更改为#page=<int>&zoom=<float>,<float>,<float>。

• 在tests/test_insertpdf.py中，使用新的参考输出joined-1.20.pdf。我们还检查新的输出值是否与旧的大致相同。
• 修复 #1738。pdf_graft_map泄漏问题。还修复了一个由于不正确释放底层 fz_document 而导致的 SEGV 问题。
• 修复 #1733。修复了Annotation.get_pixmap()的所有权。

构建/发布流程的变更：

• 如果 pip 从源代码构建，因为没有合适的轮子可用，我们不再要求预先安装 MuPDF。相反，所需的 MuPDF 源代码已嵌入 sdist，并自动构建为 PyMuPDF。
• 对setup.py进行了各种更改，以根据需要下载所需的 MuPDF 发布版。有关详细信息，请参阅 setup.py 开头的注释。
• 添加了.github/workflows/build_wheels.yml来控制在 Github 上构建轮子。

---

1.19.6 版本变更

• 修复 #1620。由Page.get_textpage()创建的 TextPage 现在将正确释放（去除内存泄漏）。
• 修复 #1601。现在应更简洁和易于解释地报告文档打开错误。在此过程中，添加了两个 PyMuPDF 特定的 Python 异常：
  • EmptyFileError - 当尝试从空文件或零长度内存创建文档 (fitz.open()) 时引发。
  • FileDataError - 当 MuPDF 遇到不可恢复的文档结构问题时引发。
• 添加 Page.load_widget()，给定 PDF 字段的 xref。
• 添加 词典pdfcolor，其中包含约 500 种 PDF 颜色值，以小写颜色名称作为键。
• 添加 代数功能到 Quad 类。这些对象现在也可以相互加减，并且可以乘以数字和矩阵。
• 新增 新常量，定义更舒适处理的默认文本提取标志。它们的命名约定类似于TEXTFLAGS_WORDS用于page.get_text("words")。参见文本提取标志默认值。
• 更改 Page.annots() 和 Page.widgets()，以检测和防止在迭代器循环中（通过Document.reload_page()）非法重新加载页面。这将降低解释器。记录了在适当设计的循环内进行注释和小部件大规模更新的干净方式。
• 更改 几个内部实用函数，使其成为独立的（“SWIG 内联”），而不是 Tools 类的一部分。这样做，除其他外，提高了几何对象创建的性能。
• 更改 Document.update_stream() 以始终接受流更新 - 无论 xref 后面的字典对象是否已经是流。因此，以前的new参数现在被忽略，并将在 v1.20.0 中删除。

---

版本 1.19.5 变更

• 修正 #1518。有限“修复”：在某些情况下，矩形和四边形未正确编码以支持通过 Shape 重新绘制。
• 修正 #1521。这背后的最终原因与问题＃1510 相同。
• 修正 #1513。某些可选内容功能不支持非 ASCII 字符。
• 修正 #1510。支持更多软蒙版图像子类型。
• 修正 #1507。免疫大纲链中的"null"对象。
• 修正 重新打开#1417。（“打开的文件太多”）。这是由于对 MuPDF 的fz_drop_document()调用不足导致的。这也修复了#1550。
• 修正 在错误设置文本跨度原点point_like方面的几个未记录问题。
• 修正 在文本翻转（而不仅仅是旋转）时，方法Page.get_texttrace()计算字符 bbox 时的未记录错误。
• 新增 到image_properties()返回的字典项：orientation和transform报告自然图像方向（EXIF 数据）。
• 新增 方法Document.xref_copy()。它可以使目标 PDF 对象成为源对象的精确副本。

---

版本 1.19.4 变更

• 修复 #1505。免疫循环轮廓项。
• 修复 #1484。现在在所有情况下正确返回 CropBox 坐标。
• 修复 #1479。
• 修复 #1474。现在正确删除 TextPage 对象。
• 新增 Page 方法和属性用于 PDF /ArtBox, /BleedBox, /TrimBox。
• 新增 全局属性 TESSDATA_PREFIX，用于轻松检查 OCR 支持。
• 更改 Document.xref_set_key()，使字典键如果设置为值 "null" 将被物理删除。
• 更改 Document.extract_font() 可选择返回字典（而非元组）。

---

版本 1.19.3 中的变更

此补丁版本对 Pixmap 进行了一些重要修复和一些小改进。

• 修复 #1351。回滚了在 v1.18.15 中引入的导致内存增长的代码。
• 修复 #1417。开发了一种解决使用 Document.insert_pdf() 时文件句柄增长问题的方法。
• 修复 #1418。开发了一种解决使用 Document.insert_pdf() 时内存增长问题的方法。
• 修复 #1430。开发了一种解决文档页面大量位图生成问题的方法。
• 修复 #1433。解决了 PyMuPDF 文本处理中某些 Type 3 字体的 bbox 错误。
• 新增 Pixmap.color_topusage() 用于确定最常用颜色的份额。解决了 #1397。
• 新增 Pixmap.warp()，从位图内部的任意凸四边形生成新位图。
• 新增 Annot.irt_xref 和 Annot.set_irt_xref() 用于查询或设置注释的 /IRT（“响应于”）属性。实现 #1450。
• 新增 Rect.torect() 和 IRect.torect()，用于计算将矩形转换为给定其他矩形的矩阵。
• 更改 Pixmap.color_count() 还会返回每种颜色的计数。
• 修改 Page.get_texttrace() 方法，以便在 span["dir"] != (1, 0) 时也返回正确的跨度和字符边界框。

---

版本 1.19.2 变更

此补丁版本对 Page.get_drawings() 进行了轻微改进，同时修复了一些重要问题。

• 修复 #1388。修复了插入或更新注释时的间歇性内存损坏问题。
• 修复 #1375。修正了由 Page.get_text() 的 “words” 和 “dict” 选项返回的行号不一致的问题。
• 修复 #1364。现在 recover_span_quad() 中对 "rawdict" 跨度的检查已正常工作。
• 修复 #1342。修正了 Page.show_pdf_page() 中矩形无限性检查的问题。
• 修改 Page.get_drawings() 和 Page.get_cdrawings() 方法，以返回矩形覆盖的区域方向指示器。这实现了 #1355。此外，矩形和四边形的识别率显著提高。
• 修改 所有文本搜索和提取方法，将新的 flags 选项 TEXT_MEDIABOX_CLIP 默认设置为打开状态。该位控制自动抑制所有完全位于页面媒体框外的字符（在文档类型支持的范围内）。这消除了需要使用 clip=page.rect 或类似选项来省略可见区域外文本的需求。
• 新增 "dpi" 参数到 Page.get_pixmap() 和 Annot.get_pixmap() 方法。当给定时，忽略 "matrix" 参数，创建一个具有所需每英寸点数的 Pixmap。
• 新增 属性 Pixmap.is_monochrome 和 Pixmap.is_unicolor，允许快速检查位图属性。解决了 #1397 的问题。
• 新增 方法 Pixmap.color_count() 以确定位图中唯一颜色的数量。
• 新增 PDF 文档方法 Document.update_stream() 的布尔参数 "compress"。解决了 #1408 的问题。

---

版本 1.19.1 变更

这是支持 MuPDF v1.19.0 的第一个补丁版本。除了一个 bug 修复外，还包括 OCR 支持的重要改进以及对提取文本进行排序到标准阅读顺序“从左上到右下”的选项。

• 修复了#1328。再次返回正确的“words”文本提取的(x0, y0)坐标。
• 更改了Page.get_textpage_ocr()：现在支持参数dpi来控制 OCR 质量。还可以选择是对整页进行 OCR 还是仅对页面显示的图像进行 OCR。
• 更改了Page.get_drawings()和Page.get_cdrawings()，以自动将颜色转换为 RGB 颜色元组。实现了#1332。类似的更改也应用于Page.get_texttrace()。
• 更改了Page.get_text()以支持参数sort。如果设置为True，输出将方便地排序。

---

1.19.0 版本的变更

这是支持 MuPDF 1.19.*的第一个版本，发布于 2021-10-05。与前一个版本 1.18.*相比，引入了许多新功能。

PyMuPDF 现在已经支持了集成的 Tesseract OCR 支持，这在 MuPDF v1.18.0 中已经存在。

• 受支持的图片可以通过它们的 Pixmap 进行 OCR，生成带有文本层的 1 页 PDF。
• 所有支持的文档页面（不仅限于 PDF）都可以使用专业的文本提取方法进行 OCR。结果是标准和 OCR 文本的混合（取决于页面的哪部分需要 OCR），可以无限制地搜索和提取。
• 所有这些都需要独立安装 Tesseract。实际上，MuPDF（仅）需要 Tesseract 的"tessdata"文件夹的位置，其中存储了其语言支持数据。此位置必须作为环境变量TESSDATA_PREFIX可用。

新的 MuPDF 功能是记录 PDF 更新，这也得到了 PyMuPDF 版本的支持。更改可能被记录、回滚或重播，允许实现对 PDF 文档完整性的全新控制级别，类似于现代数据库系统中的功能。

第三个功能（与新 MuPDF 版本无关）包括检测页面对象何时覆盖或隐藏彼此。例如，现在可以看到文本被绘图或图像覆盖。

• 修改了重要几何概念的术语和含义：矩形现在被描述为有限、有效或空，同时这些术语的定义也有所变化。具体而言，矩形现在被视为“开放”：并非所有的角和边都被认为是矩形的一部分。请参阅矩形章节了解详情。
• 新增了一个名为"no_new_id"的参数到Document.save() / Document.tobytes() 方法中。使用它来抑制更新 PDF 文档的第二项/ID，在 PDF 中表示原始文件已被更新。如果 PDF 中还没有/ID，则也不会创建新的/ID。
• 新增了用于 PDF 更新的日志记录功能。这允许记录更改、撤销或重做操作，并将日志保存以供以后使用。请参阅Document.journal_enable() 及相关方法。
• 新增了新的 Pixmap 方法 Pixmap.pdfocr_save() 和 Pixmap.pdfocr_tobytes()，生成包含 OCR 文本层的 PNG 图像的单页 PDF。
• 新增了Page.get_textpage_ocr() 方法，用于执行页面的光学字符识别，然后将结果提取并与“普通”页面内容一起存储在 TextPage 中。在后续的文本提取和文本搜索中使用或重复使用此对象，以避免多次努力。已扩展现有的文本搜索和文本提取方法以支持单独创建的 textpage — 请参阅下一项。
• 新增了一个名为textpage的参数到文本提取和文本搜索方法中。这允许重复使用之前创建的 TextPage，从而实现显著的运行时优势——这对于新的 OCR 功能尤为重要。但“普通”的文本提取也能从中受益。
• 新增了Page.get_texttrace() 方法，提供低级文本字符属性的技术方法。它以前是一个私有方法，但作者认为现在它已经足够成熟，可以正式提供。它特别包括一个“序列号”，指示绘制文本的页面外观构建操作。
• 新增了Page.get_bboxlog() 方法，提供页面对象（如文本、图像或绘图）的矩形列表。其重要性在于其顺序：索引较低的矩形覆盖或隐藏了其后的区域。
• 更改方法 Page.get_drawings() 和 Page.get_cdrawings()，现在包括一个表示页面外观构建操作创建的“序列号”。
• 修复 #1311。组合框中的字段值现在应该能够正确处理。
• 修复问题 #1290。由于新版本的几何逻辑，由于错误的矩形空白检查而导致的错误已修复。
• 修复 #1286。红色动作注释的文本对齐问题已恢复。
• 修复 #1287。在非 Windows 系统上应用某些红色动作时发生的无限循环问题已解决。
• 修复 #1284。在某些情况下应用红色动作后文本布局破坏问题已解决。

---

版本 1.18.18 / 1.18.19 的变更

• 修复问题 #1266。在重要情况下未设置Pixmap.samples的失败已在新版本 1.18.19 中进行了热修复。
• 修复问题 #1257。现在可以解除 PDF 字段的只读标志。
• 修复问题 #1252。现在正确指定了 PDF 链接注释的 zoom 值。
• 修复问题 #1244。现在在 Page.get_image__bbox() 方法中正确计算变换矩阵。
• 修复问题 #1241。在某些情况下，防止在Page.get_textbox()中返回工件字符。
• 修复问题 #1234。避免在边界情况下创建无限矩形 - Page.get_drawings()，Page.get_cdrawings()。
• 添加了测试数据和测试脚本到 PyPI 源发行版中。

---

版本 1.18.17 的变更

本版本的重点是对选定功能的主要性能改进。

• 修复问题 #1199。在Document.get_page_images()及其相关方法中使用不存在的页码不再导致段错误。
• 更改 Page.get_drawings()，现在区分“描边”、“填充”和组合路径。现在支持包含多个矩形（即“re”项）的路径。提取“剪辑”路径现在作为选项可用。
• 添加Page.get_cdrawings()，性能优化版本的Page.get_drawings()。
• 添加Pixmap.samples_mv，像素图像素区域的memoryview。不会复制，因此始终访问该区域的当前状态。
• 添加Pixmap.samples_ptr，Python 中一个指向像素图像素区域的“指针”。可以大大加快创建（速度提高 800 倍）Qt 图像的速度。

---

1.18.16 版本变更

• 修复问题 #1184。PDF 中现有的小部件字体现在被接受（即不强制更改为 Base-14 字体）。
• 修复问题 #1154。当指定clip时，文本搜索结果现在应该是正确的。
• 修复问题 #1152。
• 修复问题 #1146。
• 添加Link.flags和Link.set_flags()到 Link 类。实现增强请求 #1187。
• 添加选项，用于模拟TextWriter.fill_textbox()的输出，以预测给定文本在文本框中占据的行数。
• 添加对fitz CLI 模块的子命令gettext的文本输出支持。最重要的是，现在支持原始物理文本布局的再现。

---

1.18.15 版本变更

• 修复问题 #1088。现在应该可以正确地移除注释的填充颜色，使用Annot.update()中的fill_color=[]参数以及Annot.set_colors()中的fill=[]。
• 修复问题 #1081。Document.subset_fonts()：修复了某些字体的字符宽度错误的问题。
• 修复问题 #1078。Page.get_text()和其他与文本提取相关的方法：更改了 TextPage flags参数的默认值。现在保留所有空白和连字。
• 修复问题 #1085。旧的snake_cased别名fitz.detTextlength现在已正确定义。
• 更改Document.subset_fonts()现在将正确地前缀字体子集，符合 PDF 规范的六个大写字母标签。
• 新增新方法Widget.button_states()，返回按钮类型字段在设置为“on”或“off”时可能具有的值。
• 新增为 Font 和 TextWriter 类支持具有小型大写字母的文本。这在它们的多个方法中通过额外的布尔参数small_caps反映出来。

---

版本 1.18.14 变更

• 完成实现了新的“snake_cased”方法和属性名称，这些名称以前是“camelCased”并且在许多方面都很尴尬。文档末尾有一个名为 Deprecated Names 的部分，提供了更多背景信息和从旧名称到新名称的映射。
• 修复问题 #1053。Page.insert_image()：如给定，则在哈希计算中包括图像掩码。
• 修复问题 #1043。将Pixmap.getPNGdata添加到Pixmap.tobytes()的别名中。
• 修复计算绘制路径的包围矩形时出现的内部错误，该错误由Page.get_drawings()返回。
• 修复通过TextWriter.fill_textbox()输出文本时偶尔导致循环的内部错误。
• 新增Font.char_lengths()，返回字符串的字符宽度元组。
• 新增更多指定页面的方法Document.delete_pages()。现在可以指定序列（列表、元组或范围），并且可以使用 Python 的del语句。在后一种情况下，也接受 Python 的切片。
• 更改Document.del_toc_item()，禁用 TOC 中的单个项目：以前是移除标题文本，现在支持视图器显示整个项目为灰色。

---

版本 1.18.13 变更

• 修复问题 #1014。
• 修复计算图像边界框时的内存泄漏，Page.get_image_bbox()。
• 新增支持对 PDF 尾部进行低级访问和修改。适用于Document.xref_get_keys()，Document.xref_get_key()和Document.xref_set_key()。
• 新增为维护 PDF 元数据中的私有条目提供文档。
• 添加 处理透明图像插入的文档，Page.insert_image()。
• 添加 Page.get_image_rects()，这是 Page.get_image_bbox() 的改进版本。
• 更改 Document.delete_pages() 以支持多种指定要删除页面的方法。实现了 #1042。
• 更改 Page.insert_image() 还接受文件中现有图像的交叉引用。这允许在页面之间“复制”图像，并且支持极快的多次插入。
• 更改 Page.insert_image() 还接受整数参数 alpha。用于性能改进。
• 更改 Pixmap.set_alpha() 以支持使用其 alpha 值预乘颜色和设置特定颜色为完全透明（例如白色）。
• 更改 Document.embfile_add() 自动设置创建和修改日期时间。对应地，Document.embfile_upd() 自动维护修改日期时间（PDF 键 /ModDate），并且 Document.embfile_info() 相应地报告这些数据。此外，通过其 xref，还包括了嵌入文件的相关“集合项”，这支持开发 PDF 组合应用。

---

版本 1.18.11 / 1.18.12 中的更改

• 修复 问题 #972。改进了源分发材料的布局。
• 修复 问题 #962。稳定了 Linux 发行版检测以生成来自源代码的 PyMuPDF。
• 添加: Page.get_xobjects() 提供了 Document.get_page_xobjects() 的结果。
• 添加: Page.get_image_info() 提供了页面上所有图像的元信息。
• 添加: Tools.mupdf_display_warnings() 允许设置开启/关闭 MuPDF 生成的警告显示。默认为关闭。
• 添加: Document.ez_save() 是 Document.save() 的方便别名，具有一些不同的默认设置。
• 更改：文档页面的图像提取现在还包含图像的变换矩阵。这涉及Page.get_image_bbox()和Page.get_text()的 DICT、JSON、RAWDICT 和 RAWJSON 变体。

---

1.18.10 版本更改

• 修复问题#941。为DisplayList.get_pixmap()和DisplayList.get_textpage()添加了旧别名。
• 修复问题#929。通过Document.scrub()稳定移除 JavaScript 对象。
• 修复问题#927。在重做的TextWriter.fill_textbox()中移除了一个循环。
• 更改Document.xref_get_keys()和Document.xref_get_key()，还允许访问 PDF 尾部字典。可以通过将 xref 编号参数设置为-1来实现。
• 添加了一些用于重建由Page.get_text()选项“dict”和“rawdict”提取的文本行、跨度和字符的四边形函数。参见recover_quad()及相关函数。
• 添加Tools.unset_quad_corrections()以抑制字符四边形校正（偶尔对错误字体需要）。

---

1.18.9 版本更改

• 修复问题#888。删除了关于 PyMuPDF 许可证的歧义声明，现在明确说明为 GNU AGPL V3。
• 修复问题#895。
• 修复问题#896。自 v1.17.6 以来，PyMuPDF 抑制字体子集标记，仅在文本提取输出“dict”/“json”/“rawdict”/“rawjson”中报告基本字体名称。现在，新的全局参数可以请求旧行为，Tools.set_subset_fontnames()。
• 修复问题#885。现在，使用pathlib.Paths作为文件名也可以创建位图。
• 更改Document.subset_fonts()：文本不再被重写，因此保留所有原始属性，如隐藏或由可选内容机制控制。
• 更改了 TextWriter 输出，以接受右到左模式（阿拉伯语、希伯来语）的文本：TextWriter.fill_textbox()，TextWriter.append()。这些方法现在接受一个新的布尔参数 right_to_left，默认为 False。实现了请求 #897。
• 更改了 TextWriter.fill_textbox() 以返回未适合给定矩形的所有文本行。还将 warn 参数的默认值更改为在溢出情况下不再打印警告消息。
• 新增了一个实用函数 recover_quad()，用于计算跨度的四边形。这个函数可用于正确标记使用 Page.get_text() 的“dict”或“rawdict”选项提取的文本。

---

1.18.8 版本变更

这只是一个修复 bug 的版本。我们提前发布是因为这些功能可能被广泛使用。

• 修复了问题 #881。修复了在从文件或内存插入图像时 Page.insert_image() 中的内存泄漏。
• 修复了问题 #878。pathlib.Path 对象现在应正确处理文件路径层次结构。

---

1.18.7 版本变更

• 新增了一个实验性功能 Document.subset_fonts()，根据 PDF 中文本使用情况减小合格字体的大小。实现了请求 #855。
• 实现了请求 #870：Document.convert_to_pdf() 现在还支持 PDF 文档。
• 将 Document.write 重命名为 Document.tobytes() 以增强清晰度。但废弃的名称仍然可用一段时间。
• 实现了请求 #843：Document.tobytes() 现在支持线性化 PDF 输出。Document.save() 现在也支持向 Python 文件对象写入。此外，open 函数现在也支持 Python 文件对象。
• 修复了问题 #844。
• 修复了问题 #838。
• 修复了问题 #823。增强逻辑以更好支持 OCR 文本输出（Tesseract、ABBYY）。
• 修复了问题 #818。
• Fixed 问题#814。
• Added Document.get_page_labels() 返回 PDF 的页面标签定义列表。
• Added Document.has_annots() 和 Document.has_links() 用于检查 PDF 中是否存在这些对象类型。
• Added 专家级低级功能以简化 PDF 对象源的查询和修改：Document.xref_get_keys() 列出对象xref 的键，Document.xref_get_key() 返回键的类型和内容，以及Document.xref_set_key() 修改键的值。
• Added 参数thumbnails到Document.scrub()，以允许删除页面缩略图图像。
• Improved 文档如何为非水平文本添加有效文本标记注释的文档已更新。

我们继续将方法和属性从*“mixedCase”重命名为“snake_case”*的过程。文档通常仅提及新名称，但旧的弃用名称在一段时间内仍然可用。

---

版本 1.18.6 中的更改

• Fixed 问题#812。
• Fixed 问题#793。之前无效的文档元数据导致某些文档根本无法打开。已修复此错误。
• Fixed 问题#792。如果使用默认的clip=None，则文本搜索和文本提取将完全不进行矩形包含检查。
• Fixed 问题#785。
• Fixed 问题#780。修正了参数检查错误。
• Fixed 问题#779。修正了拼写错误。
• Added 选项以设置文本框的期望行高。实现了#804。
• Changed 文本位置检索已优化以更好地处理 Tesseract 的无字体字符。实现了#803。
• Added 选项以选择提供唯一注释 ID 的新注释、字段和链接的前缀。实现了请求#807。
• Added 获取和设置 PDF 目录项目的颜色和文本属性。实现了#779。
• 新增PDF 页面标签处理：Page.get_label() 返回页面标签，Document.get_page_numbers() 返回具有指定标签的所有页面编号，Document.set_page_labels() 添加或更新 PDF 的页面标签定义。

注意

此版本引入了Python 类型提示。目标是为所有函数和方法的每个参数和返回值提供类型信息。尽管大部分函数已经处理，但仍在进行中。

---

版本 1.18.5 的变更

除了几个修复外，此版本还专注于几个次要但重要的功能改进。其中之一是更精确地计算适合文本书写/插入的适当行高和插入点。与使用字体无关的常量不同，现在这些值来自于字体的属性。

还请注意，这是不再为 Python 版本低于 3.6 提供预生成轮子的第一个版本。PIP 也将在 2020 年底停止对这些版本的支持。

• 修复问题#771。通过使用“小字形高度”选项，可以提取完整页面文本。
• 修复问题#768。
• 修复问题#750。
• 修复问题#739。 “dict”、"rawdict"及其对应的 JSON 输出变体现在具有两个新的span键：“ascender"和"descender”。这些浮点数表示特殊的字体属性，可用于计算与默认行高不同但与字体大小相同的边界框的 span 或字符。在“Span Dictionary”章节这里中展示了一个示例算法。还改进了检测和修正某些字体中遇到的未明确定义的 ascender/descender 值。
• 新增了一个新的实验性方法Tools.set_small_glyph_heights() – 同时响应问题#739。此方法设置或取消一个全局参数，以始终使用字体大小计算边界框。如果“开启”，则文本搜索和所有文本提取都将返回高度较小的矩形、边界框和四边形。
• 修复问题#728。
• 更改“Polyline”注释的填充颜色逻辑：此参数现在仅适用于线条末端符号 – 注释本身不再能有填充颜色。还解决了问题#727。
• 修改了Page.getImageBbox()，以便在图像包含在 XObject 中时也计算其 bbox。
• 修改了Shape.insertTextbox()、Page.insertTextbox()和TextWriter.fillTextbox()方法，以在计算行高和插入点时尊重字体的“上升部分”和“下降部分”。这不再导致多行输出的行重叠。这些方法以前忽略了字体的特定信息，而是使用固定值。

---

1.18.4 版本变更

该版本添加了多项功能以支持 PDF 可选内容。其中包括具有全面*“可见性表达式”*（PDF 键/VE）的 OCMDs（可选内容成员字典）、文本插入（包括 TextWriter 类）和绘图。

• 修复了问题#727。现在，自由文本注释在fill_color=None时支持无颜色矩形。
• 修复了问题#726。现在已处理 HTML/XML Page.getText()输出的 UTF-8 编码错误。
• 修复了问题#724。不再将空值存储在 PDF /Info 元数据字典中。
• 新增了Document.set_oc()和Document.get_oc()方法，用于设置或获取现有图像和表单 XObject 的可选内容引用。这些方法与 Annot 中同名方法类似。
• 新增了Document.set_ocmd()和Document.get_ocmd()方法，用于处理 OCMDs。
• 新增了对文本插入和绘制的可选内容支持。
• 新增了Page.deleteWidget()方法，用于从页面中删除表单字段。这类似于删除注释。
• 新增了对弹出式注释的支持。这包括定义弹出式矩形并设置弹出式注释的打开或关闭状态。方法/属性Annot.set_popup()、Annot.set_open()、Annot.has_popup、Annot.is_open、Annot.popup_rect、Annot.popup_xref。

其他变更：

• PyMuPDF 中的方法和属性命名远未令人满意：我们的CamelCases、mixedCases和lower_case_with_underscores无处不在。以 Annot 为首位，我们已开始逐步清理此问题，将方法和属性转换为下划线小写形式，同时保留常量的大写形式。
  • 旧名称将继续保留以防止代码中断，但它们将不再在文档中提及。
  • 所有类的新方法和属性将按照新标准命名。

---

版本 1.18.3 的更改

作为一个重要的新功能，此版本引入了对 PDF 的 可选内容 概念的支持。

• 修复 问题 #714。
• 修复 问题 #711。
• 修复 问题 #707：如果提供了 PDF 的用户密码但没有提供或不存在所有者密码，则用户密码也将用作所有者密码。
• 修复 expand 和 deflate 参数在 Document.save() 和 Document.write() 方法中的问题。现在个别图像和字体的压缩应该最终能够正常工作。解决问题 #713。
• 添加 对 PDF 可选内容的支持。这包括几种新的 Document 方法，用于查询和设置可选内容状态，以及添加可选内容配置和组。此外，现在可以将图像、表单 XObjects 和注释绑定到可选内容规格。 解决 问题 #709。

---

版本 1.18.2 的更改

此版本对文本搜索进行了一些有趣的改进：现在返回任意数量的搜索结果，并且删除了 hit_max 参数。此外，新增的 clip 参数还允许限制搜索区域。现在搜索会检测换行时的连字符，并相应地找到连字符词。

• 修复 问题 #575：如果在文本搜索中使用 quads=False，则同一行上重叠的矩形将合并。之前，搜索字符串的部分属于不同的“标记内容”项，每个生成自己的矩形，就像它们出现在不同的行上一样。
• 添加 Document.isRepaired，如果 PDF 在打开时被修复，则为 true。
• 添加 Document.setXmlMetadata() 方法，用于更新或创建 PDF 的 XML 元数据。实现问题 #691。
• 添加 Document.getXmlMetadata() 返回 PDF 的 XML 元数据。
• 更改 创建 PDF 文档的方式：现在它们将始终在文档尾部带有 PDF 标识（/ID 字段）。实现问题 #691。
• 更改 Page.searchFor()：现在接受一个新的 clip 参数，以限制搜索到这个矩形区域内。相应地，TextPage.search() 现在尊重 TextPage.rect 属性。
• 更改了 Page.searchFor() 和 TextPage.search() 中的参数 hit_max 现在已经过时：这些方法将返回所有命中结果。
• 更改 Page.getText() 中的字符选择标准：如果其包围框完全包含，则现在将字符视为 clip 的一部分。在此之前，非空交集是足够的。
• 更改 Document.scrub() 来支持新选项 redact_images。这解决了问题 #697。

---

1.18.1 版本的变更

• 修复问题 #692。PyMuPDF 现在能够检测并从 PDF 页面中更多的循环资源依赖中恢复，并且首次将其报告在 MuPDF 的警告存储中。
• 修复问题 #686。
• 为 Shape 类添加了不透明度选项：现在可以为描边和填充颜色设置一些透明度值。这意味着所有 Page 绘制方法，方法 Page.insertText()，Page.insertTextbox()，Shape.finish()，Shape.insertText() 和 Shape.insertTextbox() 都支持两个新参数：stroke_opacity 和 fill_opacity。
• 向 Page.insertImage() 添加了新参数 mask，用于可选地提供外部图像掩码。解决了问题 #685。
• 添加 Annot.soundGet() 用于提取音频注释的声音。

---

1.18.0 版本的变更

这是第一个支持 MuPDF v1.18 的 PyMuPDF 版本。重点在于扩展 PyMuPDF 的功能——除了修复错误之外。随后的 PyMuPDF 补丁可能会解决 MuPDF 中新增的功能。

• 修复问题 #519。此上游错误偶尔会在某些页面上发生，现在似乎已经修复：在这些情况下页面布局不应再被破坏。
• 修复问题 #675。
  • 不成功的存储分配现在应该始终引发异常（规避了一个时而导致解释器崩溃的上游错误）。
  • Pixmap 的大小现在基于 size_t 而不是 int 在 C 中，应该可以正确处理非常大的像素图。
• 修复问题 #668。PDF 绘图插入中划线的规范应该现在正确反映 PDF 规范。
• 修复问题 #669。已删除 Page.insert_pdf() 中的一个主要内存泄漏源。
• 在 Page.apply_redactions() 中添加了关键字 “images”，以精细控制图像的处理方式。
• 添加了 Annot.getText() 和 Annot.getTextbox()，提供与 Page 版本相同的功能。
• 新增 在 Page.getText() / Annot.getText() 的块字典中添加了键 “number”，用于选项“dict”和“rawdict”。
• 新增 glyph_name_to_unicode() 和 unicode_to_glyph_name()。这两个函数不再依赖于特定的字体，现在也可以独立使用。数据现在基于Adobe Glyph List。
• 新增便利函数 adobe_glyph_names() 和 adobe_glyph_unicodes()，它们返回相应的可用数据。
• 新增 Page.getDrawings()，返回文档页面上绘图操作的详细信息。适用于所有文档类型。
• 提升了 Document.insert_pdf() 的性能。现在还跨多个独立插入操作抑制了多个对象的复制。这节省了时间、内存和目标文件大小。之前这种机制仅在单个方法执行中有效。还可以通过新方法的布尔参数 final=1 来禁止该功能，默认情况下是激活的。
• 对于从位图创建的 PNG 图像，分辨率（dpi）现在会根据相应的 Pixmap.xres 和 Pixmap.yres 值自动设置。

---

1.17.7 版本变更

• 修复问题 #651，通过从其开发仓库反向移植 MuPDF 更改，解决了在极端情况下造成解释器崩溃的上游错误。
• 修复问题 #645，位图的左上角坐标现在可以通过它们自己的方法 Pixmap.set_origin() 再次设置。
• 修复问题 #622，Page.insertImage() 再次接受 rect_like 参数。
• 新增多个新方法，以改进和加速目录（TOC）处理。在其他功能中，现在可以单独更改或删除 TOC 项，而无需总是替换整个 TOC。此外，现在可以在不先加载页面的情况下访问某些 PDF 页面属性。这对于 TOC 操作的性能有显著影响。
• 新增 Document.insert_pdf() 的选项，允许显示进度消息。解决了问题 #640。
• 新增 Page.getTextbox()，它可以提取矩形框中包含的文本。在许多情况下，这应该可以替代编写自己的脚本来完成这种任务。
• 新增 clip 参数到 Page.getText()，以简化和加速页面子区域的文本提取。
• 新增 TextWriter.appendv() 以垂直写入模式添加文本。解决了问题 #653

---

1.17.6 版本变更

• 修复问题 #605
• 修复问题 #600 – 现在文本应该对于裁剪框小于媒体框的页面位置正确。
• 新增文本跨度字典键 origin，包含该跨度中第一个字符的左下角坐标。
• 新增属性 Font.buffer，一个字体文件的 bytes 复制。
• 新增参数 sanitize 到 Page.cleanContents()。允许切换清理，因此只进行语法清理。

---

1.17.5 版本变更

• 修复问题 #561 – 第二次尝试：某些具有多个交替字体的 TextWriter 使用未能正确工作。
• 修复问题 #566。
• 修复问题 #568。
• 修复 – 现在从 TextWriter 对象正确获取不在 TextWriter.writeText() 中指定的不透明度。
• 新增一个新的全局属性 fitz_fontdescriptors。包含来自仓库 pymupdf-fonts 的可用字体信息。
• 新增 Font.valid_codepoints() 返回一个包含字体具有字形的 Unicode 码点数组。
• 新增选项 text_as_path 到 Page.getSVGimage()。实现了 #580。如果设置为 False，生成的 SVG 文件会更小且包含可解析的文本。

---

1.17.4 版本变更

• 修复问题 #561。现在一页上超过 10 个 Font 对象的处理应该正常工作。
• 修复问题 #562。注释的像素图不再从页面像素图派生，从而避免意外包含页面内容。
• 修复问题 #559。这是对 MuPDF 的一个临时修复，使用了下一个版本的预发布版。
• 新增实用函数 repair_mono_font() 用于修正某些等宽字体的显示字符间距。
• 新增实用方法 Document.need_appearances() 用于精细控制 PDF 表单的行为。解决了问题 #563。
• 新增 实用函数 sRGB_to_pdf() 用于将 sRGB 格式的颜色整数转换为 PDF 颜色三元组。
• 新增 实用函数 sRGB_to_rgb() 用于将 sRGB 格式的颜色整数转换为(R, G, B)颜色三元组。
• 新增 实用函数 make_table()，用于根据给定的矩形和所需的列数和行数生成表格单元。
• 新增 对存储库 pymupdf-fonts 中的可选字体的支持。

---

版本 1.17.3 中的变更

• 修复了一个未记录的问题，使用 Page.cleanContents() 时可能无法完全清除 PDF 页面。
• 修复 问题 #540。EPUB 的文本提取现在应该再次正常工作。
• 修复 问题 #548。现在文档包括了 LINK_NAMED。
• 新增 新参数以控制在 TextWriter.fillTextbox() 中文本开始位置。实现 #549。
• 修改 Page.add_redact_annot() 的文档，以解释非内置字体的使用方式。

---

版本 1.17.2 中的变更

• 修复 问题 #533。
• 新增 修改“Redact”注释外观的选项。实现 #535。

---

版本 1.17.1 中的变更

• 修复 问题 #520。
• 修复 问题 #525。现在"Ink"注释的顶点应该是正确的。
• 修复 问题 #524。现在可以查询和设置适用注释类型的旋转。

还显著改进了内联文档，以更好地支持交互式帮助。

---

版本 1.17.0 中的变更

此版本基于 MuPDF v1.17。以下是新功能和更改的亮点：

• 新增 扩展语言支持以用于注释和小部件：拉丁文、希腊文、俄文、中文、日文和韩文字符的混合现在可以在"FreeText"注释和文本小部件中使用。无需特殊安排即可使用。
• 为支持“章节”结构的文档实现了更快的页面访问。目前适用于 EPUB 文档。这带来了多个新的 Document 方法和 Document.loadPage() 的变更，以及“索引”页面访问 doc[n] 的变更：除了以前指定页面编号外，现在还可以指定元组 (章节, 页码) 来标识所需的页面。
• 已更改: 改进了对删除注释的支持：被删除区域覆盖的图像被 永久修改，重叠区域被擦除。同时，如果链接被删除区域覆盖，链接也会被移除。这现在完全符合 PDF 规范。

其他变更：

• 已更改 TextWriter.writeText() 方法，现在支持 “morph” 参数。
• 新增 方法 Rect.morph(), IRect.morph() 和 Quad.morph()，它们返回一个新的 Quad 对象。
• 已更改 Page.add_freetext_annot() 方法，现在支持通过新的 “align” 参数进行文本对齐。
• 已修复 问题 #508。改进了图像矩形计算，希望能在大多数情况下提供正确的值。
• 已修复 问题 #502。
• 已修复 问题 #500。Document.convertToPDF() 现在不应再导致内存泄漏。
• 已修复 问题 #496。现在添加或修改注释和小部件/字段时使用的坐标是 未旋转页面 的坐标。此行为现在与修改 PDF 页面的其他方法同步。
• 新增 Page.rotationMatrix 和 Page.derotationMatrix，用于支持 PDF 页面旋转后和原始版本之间的坐标转换。

可能会导致代码兼容性问题的更改：

• 私有方法 Page._getTransformation() 已被移除。请使用公共方法 Page.transformationMattrix 替代。

---

版本 1.16.18 的变更

本版本引入了几个围绕 PDF 文本输出的新功能。目的是简化此任务，同时提供扩展功能。

一个主要的成就是利用 MuPDF 的功能动态选择回退字体，以便在当前字体中找不到字符时使用。这对 Base-14 字体与 CJK 字体（中文、日文、韩文）的组合无缝运作。因此，文本可以包含来自拉丁文、希腊文、俄文、中文、日文和韩文的 任意组合的字符。

• 已修复 问题 #493。Pixmap(doc, xref) 现在应正确地反映已加载的图像对象。
• 已修复 问题 #488。小部件名称现在是可修改的。
• 新增 新类 Font，表示一个字体。
• 新增 新类 TextWriter，用作页面上要写入的文本的容器。
• 新增 Page.writeText() 方法，用于向页面写入一个或多个 TextWriter 对象。

---

版本 1.16.17 的变更

• 修复问题 #479。PyMuPDF 现在应更正确地报告图像分辨率。这适用于从图像文件提取的图像或从 PDF 文档中提取的图像，以及从图像创建的像素图。
• 添加了 Pixmap.set_dpi()，用于设置图像在 x 和 y 方向的分辨率。

---

版本 1.16.16 变更

• 修复问题 #477。
• 修复问题 #476。
• 更改了注释行结束符的颜色，并修复了 ‘Polyline’ / ‘Polygon’ 注释内部颜色的错误。

---

版本 1.16.14 变更

• 更改了文本标记注释，以接受除了四边形外的参数，使得现在可以标记两个给定点之间的 文本行。
• 添加了 Document.scrub()，用于从 PDF 中 删除可能敏感的数据。实现了 #453。
• 添加了 Annot.blendMode()，用于返回注释的 混合模式。
• 添加了 Annot.setBlendMode()，用于设置注释的混合模式。解决了问题 #416。
• 更改了 Annot.update()，以接受用于设置混合模式和不透明度的附加参数。
• 添加了高级图形功能以控制抗锯齿值，Tools.set_aa_level()。解决了 #467。
• 修复问题 #474。
• 修复问题 #466。

---

版本 1.16.13 变更

• 添加了 Document.getPageXObjectList()，返回页面的 Form XObjects 列表。
• 添加了 Page.setMediaBox()，用于更改物理 PDF 页面大小。
• 添加了 Page 方法，这些方法在此之前是内部的：Page.cleanContents()（= Page._cleanContents()）、Page.getContents()（= Page._getContents()）、Page.getTransformation()（= Page._getTransformation()）。

---

版本 1.16.12 变更

• 修复问题 #447。
• 修复问题 #461。
• 修复问题 #397。
• 修复问题 #463。
• 添加了对 PDF 表单字段的 JavaScript 支持，从而解决了 #454 问题。
• 添加了一个新的注释方法 Annot.delete_responses()，用于删除引用当前注释的 ‘Popup’ 和响应注释。主要用于数据保护目的。
• 新增了一个新的表单字段方法 Widget.reset()，将字段值重置为其默认值。
• 改变和扩展了对清除的处理：如果图像和 XObjects 包含在清除的矩形中，则会被删除。任何部分重叠的内容将只被清除背景颜色覆盖。现在可以指定一个 叠加文本 来插入到矩形区域中代替删除的原始文本。这解决了 #434。

---

版本 1.16.11 中的变化

• 新增了通过方法 Page.add_redact_annot() 和 Page.apply_redactions() 支持清除注释的功能。
• 修复了问题 #426（“1.16.10 版本中的 PolygonAnnotation”）。
• 修复了文档问题 #443 和 #444。

---

版本 1.16.10 中的变化

• 修复了问题 #421（“annot.set_rect(rect) 对文本注释无效”）
• 修复了问题 #417（“1.16.9 版本中的 page.deleteAnnot 行为奇怪，与 1.13.20 版本不符”）
• 修复了问题 #415（“Annot.setOpacity 抛出 mupdf 警告”）
• 更改了所有“添加注释 / 小部件”方法，以在 /NM PDF 键中存储唯一名称。
• 更改了 Annot.setInfo() ，现在也可以接受直接参数，而不仅仅是字典。
• 更改了 Annot.info ，现在还会显示注释的唯一标识（/NM PDF 键）（如果存在）。
• 新增了 Page.annot_names() 方法，返回所有注释名称（/NM 键）的列表。
• 新增了 Page.load_annot() 方法，根据其唯一标识（/NM 键）加载注释。
• 新增了 Document.reload_page() 方法，在完成对页面的所有待处理更新后，提供页面的新副本。

---

版本 1.16.9 中的变化

• 修复了 #412（“功能请求：允许控制 TOC 条目是否应该折叠”）
• 修复了 #411（“使用 page.firstWidget 导致 Seg Fault”）
• 修复了 #407（“Annot.setOpacity 出问题”）
• 更改了方法 Annot.setBorder()、Annot.setColors()、Link.setBorder() 和 Link.setColors() ，现在也可以接受直接参数，而不仅仅是冗长的字典。

---

版本 1.16.8 中的变化

• 增加了几种新的方法到 Document 类中，这些方法使得处理 PDF 低级结构更加容易。我也决定将它们提供为“正常”方法（而不是以下划线“_”开头的私有方法）。这些方法包括 Document.xrefObject()、Document.xrefStream()、Document.xrefStreamRaw()、Document.PDFTrailer()、Document.PDFCatalog()、Document.metadataXML()、Document.updateObject() 和 Document.updateStream()。
• 添加 Tools.mupdf_disply_errors()，设置 mupdf 错误在 sys.stderr 上的显示。
• 添加 命令行功能。这是一个重要的新功能：现在可以通过 “python -m fitz …” 调用几个实用函数。这应该能够取代许多最简单的脚本。请参阅 命令行接口。

---

版本 1.16.7 的更改

对于 TextPage 图像块和 Document.extractImage() 图像，进行了微小的更改，以更好地同步二进制图像流。

• 修复 问题 #394（“使用 TOOLS.mupdf_warnings() 时，PyMuPDF Segfaults”）。
• 修改 MuPDF 错误消息的重定向：除了将它们写入 Python 的 sys.stderr 外，现在还将它们存储在 MuPDF 警告中。
• 修改 Tools.mupdf_warnings()，现在会自动清空存储（如果没有通过参数停用）。
• 修改 Page.getImageBbox()，如果无法在页面上定位图像，则返回一个无限矩形，而不是引发异常。

---

版本 1.16.6 的更改

• 修复 问题 #390（“注释不完全删除”）。
• 修改 Page.searchFor() / Document.searchPageFor()，现在也支持 flags 参数，用于控制包含在 TextPage 中的数据。
• 修改 Document.getPageImageList()，Document.getPageFontList() 及其 Page 对应方法，支持新的 full 参数。如果为 true，则返回的项目将包含引用字体或图像的 Form XObject 的 xref。

---

版本 1.16.5 的更改

进一步优化文本提取性能。

• 修复 问题 #381 的第二部分（请参阅 v1.16.4 中的项目）。
• 添加 Page.getTextPage()，现在不再需要为文本提取创建中间显示列表。页面级别的文本提取和文本搜索现在都基于此方法，预计可以提高约 5% 的性能。

---

版本 1.16.4 的更改

• 修复 问题 #381（“TextPage.extractDICT … 升级到 1.16.3 后失败 …”）
• 添加 方法 Document.pages()，用于生成页面范围的迭代器。
• 添加 方法 Page.links()，用于生成页面链接的迭代器。
• 添加 方法 Page.annots()，用于生成页面注释的迭代器。
• 添加 方法 Page.widgets()，用于生成页面表单字段的迭代器。
• 修改 Document.is_form_pdf，现在包含小部件的数量，如果不是 PDF 或此数量为零，则为 False。

---

版本 1.16.3 的更改

与版本 1.16.2 相比，较小的变化。Page.getText()的“dict”和“rawdict”变体代码已经移植到了 C 中，极大地提高了性能。这在文本导向的文档中特别明显，现在几乎可以快两倍执行。

• Fixed 问题 #369 (“mupdf: cmsCreateTransform failed”)，通过移除 ICC 颜色空间支持来解决。
• Changed Page.getText() 已修改以接受额外的关键字“blocks”和“words”。它们将分别返回Page.getTextBlocks()和Page.getTextWords()的结果。因此，所有文本提取方法现在通过统一的 API 可用。对应地，现在有新的方法TextPage.extractBLOCKS()和TextPage.extractWords()。
• Changed Page.getText() 将默认的位指示器TEXT_INHIBIT_SPACES设为off。默认情况下不会抑制额外空格的插入。

---

版本 1.16.2 中的更改

• Changed 文本提取方法的 Page 已更改，允许详细控制提取数据量。
• Added planish_line()用于将给定线（定义为一对点）映射到 x 轴。
• Fixed 一个问题（无 Github 编号），当使用带有“dict”选项的Page.getText()时，遇到某些非 UTF-8 可编码字符时，解释器崩溃。
• Fixed 问题 #362 (“使用 getText(‘rawDICT’)导致内存泄漏”).

---

版本 1.16.1 中的更改

• Added 属性Quad.is_convex，用于检查线是否包含在四边形中，如果连接了它的两个点。
• Changed Document.insert_pdf()现在允许在复制期间独立地放弃或包含链接和注释。修复了问题 #352 (“损坏的 PDF 数据和…”)，在使用该方法处理某些问题 PDF 文件时似乎偶尔会出现。
• Fixed 修复了一个 bug，当使用*“m1/m2”语法进行矩阵除法时，导致矩阵“m1”*被替换为结果而不是生成新的矩阵。
• Fixed 问题 #354 (“Python 3.8 语法警告”)。我们现在始终使用*“==”来比较字面值（而不是 Python 关键字“is”*）。
• Fixed 问题 #353 (“mupdf 版本检查”), 不再因 MuPDF 只有补丁级别偏差而拒绝导入。

---

版本 1.16.0 中的更改

MuPDF 的这个重大新版本带来了几个不错的新特性或更改。其中一些暗示了编程 API 的变化。这是变化的概述：

• 现在完全支持 PDF 文档的加密和解密。包括设置权限、密码（用户密码和所有者密码）以及所需的加密方法。
• 针对新的加密功能，PyMuPDF 返回一个整数（即权限的位组合），不再返回字典。
• 现在原生支持重定向 MuPDF 的错误和警告。PyMuPDF 将 MuPDF 的错误消息重定向到 sys.stderr，不再缓冲它们。警告仍将被缓冲，并且不会显示。存在函数来访问和重置警告缓冲区。
• 现在仅支持 PDF 的注释。
• 注释和小部件（表单字段）现在是页面上的单独对象链（虽然小部件在技术上仍然是 PDF 注释）。这意味着，当使用 Page.firstAnnot 或 Annot.next() 时，永远不会遇到小部件。您必须使用 Page.firstWidget 和 Widget.next() 来访问表单字段。
• 作为 MuPDF 关于小部件更改的一部分，在添加或更改表单字段时，仅支持以下四种字体：Courier, Helvetica, Times-Roman 和 ZapfDingBats。

变更详情列表：

• 添加 Document.can_save_incrementally()，检查阻止使用选项 incremental=True 的 Document.save() 的条件。
• 添加了 Page.firstWidget，指向页面上第一个字段。
• 添加 Page.getImageBbox()，返回页面上显示的图像所占用的矩形。
• 添加 Annot.setName()，允许您更改（图标）名称字段。
• 添加了在 Page.getText() 中输出文本颜色的功能：“dict”，“rawdict” 和 “xml” 选项现在还显示 sRGB 格式的颜色。
• 变更 Document.permissions 现在包含一个布尔指示器的整数 – 之前是一个字典。
• 变更 Document.save()，Document.write()，现在完全支持基于密码的 PDF 文件解密和加密。
• 变更所有与注释和小部件相关的 Python 常量名称。请确保查阅常量和枚举章节，如果您的脚本涉及这两个类。这一决定源于对非 PDF 注释的支持。旧名称（以“ANNOT_”或“WIDGET_”开头）将作为弃用的同义词可用。
• 变更 对小部件的字体支持：仅支持 Cour (Courier), Helv (Helvetica, 默认), TiRo (Times-Roman) 和 ZaDb (ZapfDingBats) 添加或更改表单字段时。只有普通版本是可能的 – 不支持它们的斜体或粗体变体。然而，阅读小部件将显示其原始字体。
• 变更 警告缓冲区的名称为 Tools.mupdf_warnings()，清空此缓冲区的函数现在称为 Tools.reset_mupdf_warnings()。
• 更改了 Page.getPixmap() 和 Document.get_page_pixmap()：现在可以使用新的布尔参数 annots 来抑制页面上注释的渲染。
• 更改了 Page.add_file_annot() 和 Page.add_text_annot()，可以设置图标。
• 移除了 Annot 对象中与小部件相关的方法和属性。
• 移除了 Document 属性 openErrCode、openErrMsg，以及 Tools 的属性/方法 stderr、reset_stderr、stdout 和 reset_stdout。
• 移除了 PyMuPDF 中的 thirdparty zlib 依赖：现在 MuPDF 中提供了压缩函数。因此，PyMuPDF 的源安装程序现在可以省略这一额外的安装步骤。

MuPDF v1.15.0 未发布任何版本

---

1.14.20 / 1.14.21 版本变更

• 更改了文本标记注释，支持多个矩形/四边形。修复问题 #341（“问题：如何添加高亮，以便跨多行的字符串只覆盖一个高亮？”）和类似问题 #285。
• 修复了问题 #331（“导入 PyMuPDF 更改警告全局过滤行为”）。

---

1.14.19 版本变更

• 修复了问题 #319（“使用自定义字体时 InsertText 函数错误”）。
• 添加了新方法 Document.get_sigflags()，用于返回 PDF 签名信息。解决问题 #326（“如何检测表单 PDF 中的签名？”）。

---

1.14.17 版本变更

• 添加了 Document.fullcopyPage()，用于在 PDF 中进行完整页面复制（不仅是 Document.copyPage() 中的引用复制）。
• 更改了 Page.getPixmap() 和 Document.get_page_pixmap()，现在默认使用 alpha=False。
• 更改了文本提取方式：现在 span 字典再次包含在 bbox 键下的矩形。
• 更改了 Document.movePage() 和 Document.copyPage()，使用直接函数而不是包装 Document.select() – 类似于 v1.14.16 中的 Document.delete_page()。

---

1.14.16 版本变更

• 更改了关于 PDF /EmbeddedFiles 的 Document 方法，不再使用 MuPDF 的“portfolio”功能。MuPDF v1.15 将不再支持该功能，因此需要另一种解决方案。
• 更改了 Document.embfile_Count()，现在是一个函数（之前是一个属性）。
• 添加了新方法 Document.embfile_Names()，用于返回嵌入文件的名称列表。
• 更改 Document.delete_page() 和 Document.delete_pages() 在内部不再使用 Document.select()，而是直接使用函数执行删除。由于已经发现，Document.select() 方法对于非常复杂的 PDF 和注释使用复杂的文档（目录表）生成了无效的大纲树。

---

1.14.15 版本变更

• 修复问题 #301（“线段端点和连接点”）、#300（“如何绘制没有轮廓的形状”）和 #298（“utils.updateRect 异常”）。这些 bug 与 PyMuPDF 绘制形状相关。完全支持绘制没有任何边框的形状。线段端点样式和线段连接样式现在有所区别，并支持所有可能的 PDF 值（0、1、2），而不仅仅是布尔值。先前的参数 roundCap 已被 lineCap 和 lineJoin 取代，将在下一个版本中删除。
• 修复问题 #290（“使用 getText(‘rawDICT’) 时的内存泄漏”）。此 bug 导致在调用 Page.getText() 的 “dict”、“rawdict” 和 “json” 版本后内存没有（完全）释放。

---

1.14.14 版本变更

• 新增新的低级函数 ImageProperties()，用于确定图像的许多特征。
• 新增新的低级函数 Document.is_stream()，用于检查对象是否为流类型。
• 更改低级函数 Document._getXrefString() 和 Document._getTrailerString() 现在默认以格式化形式返回对象定义，这使得解析变得容易。

---

1.14.13 版本变更

• 更改处理二进制输入的方法：虽然一直支持字节和字节数组对象，但现在还接受 io.BytesIO 输入，并使用它们的 getvalue() 方法。这适用于文档创建、嵌入文件、FileAttachment 注释、位图创建等。修复了问题 #274（“使用 BytesIO 作为 insertImage 流时导致的 Segfault”）。
• 修复问题 #278（“插入图片（保持比例=True）是否有问题？”）。现在在保持长宽比的情况下正确显示图片。

---

1.14.12 版本变更

• 更改Page 和 Shape 的绘制方法，以支持 RGB、GRAY 和 CMYK 颜色空间。这解决了问题 #270（“是否有一种方法可以使用 CMYK 颜色来绘制形状？”）。此更改还适用于 Shape 和 Page 的文本插入方法。
• 修复问题 #269（“Document.insert_page() 中的 AttributeError”），该问题发生在使用 Document.insert_page() 进行文本插入时。

---

1.14.11 版本变更

• 变更 Page.show_pdf_page() 以始终将源矩形居中放置在目标中。此方法现在还支持任意角度的旋转。参数 reuse_xref 已被弃用：防止重复现在内部处理。
• 变更 Page.insertImage() 以支持图像的旋转显示并保持纵横比。此处仅支持 90 度的倍数旋转。
• 修复了 #265 号问题（“TypeError: insertText()接收到意外的关键字参数‘idx’”）。此问题仅在使用 Document.insert_page() 时插入文本时发生。

---

1.14.10 版本变更

• 变更 Page.show_pdf_page() 以支持源矩形的旋转。修复了 #261 号问题（“无法旋转插入的页面”）。
• 修复了 Page.insertImage() 中的一个错误，该错误阻止了以流的形式插入多个图像。

---

1.14.9 版本变更

• 添加了新的低级方法 Document._getTrailerString()，它返回 PDF 的尾部对象。这与 Document._getXrefString() 类似，但 PDF 尾部没有 / 不需要 xref 来标识它。
• 添加了用于文本插入方法的新参数。现在可以独立设置字形（文本字符）的描边和填充颜色，以及字形边框的厚度。新参数 render_mode 控制这些颜色的使用以及文本是否应该可见。
• 修复了 #258 号问题（“将图像流复制到新的 PDF 时不增加大小”）：对于嵌入 PDF 中的 JPX 图像，Document.extractImage() 现在将以原始格式返回它们。先前使用的是 MuPDF 基本库，它以 PNG 格式返回它们（导致了巨大的大小增加）。
• 修复了 #259 号问题（“将文字变形以适应矩形内部”）。澄清了 get_text_length() 的用法，并删除了长单词的额外换行。

---

1.14.8 版本变更

• 添加了 Pixmap.set_rect() 以更改矩形中的像素值。这也是设置完整 Pixmap 颜色（Pixmap.clear_with()）的替代方法。
• 修复了使用 JBIG2（单色）编码的 PDF 图像的图像提取问题。该问题出现在 Page.getText()（参数“dict”和“rawdict”）和 Document.extractImage() 方法中。
• 修复了一个关于非 AlphaPixmap（Pixmap.clear_with()）的清除不正确的问题。
• 修复了一个关于非 AlphaPixmap（Pixmap.invert_irect()）的颜色未正确反转的问题。

---

版本 1.14.7 中的变更

• 新增了 Pixmap.set_pixel() 方法，用于改变一个像素值。
• 新增了关于在 FAQ 中进行图像转换的文档。
• 新增了 get_text_length() 函数，用于确定给定字体的字符串长度。
• 新增了 Postscript 图像输出（更改了 Pixmap.save() 和 Pixmap.tobytes()）。
• 更改了 Pixmap.save() 和 Pixmap.tobytes() 以确保颜色空间、alpha 和输出格式的有效组合。
• 更改了 Pixmap.save() 方法：现在所需的格式可以从文件名推断出来。
• 更改了 FreeText 注释现在可以具有透明背景 - 请参见 Annot.update()。

---

版本 1.14.5 中的变更

• 更改了： Shape 方法现在严格使用 Page 的变换矩阵 – 而不是手动计算位置。
• 新增了 Pixmap.pixel() 方法，用于返回给定像素坐标的像素值（一个列表）。
• 新增了 Pixmap.tobytes() 方法，用于返回表示各种格式的 pixmap 的字节对象。先前，这仅适用于 PNG 输出（Pixmap.tobytes()）。
• 更改了： Pixmap.save() 方法及（新的）Pixmap.tobytes() 方法的输出现在也可能是 PSD（Adobe Photoshop Document）格式。
• 新增了 Shape.drawQuad() 方法，用于绘制 Quad。实际上，这是使用四边形的边缘进行 Shape.drawPolyline() 的简写。
• 更改了 Shape.drawOval() 方法：现在参数可以是一个矩形（rect_like）或者一个四边形（quad_like）。

---

版本 1.14.4 中的变更

• 修复了问题 #239 “注释坐标一致性”。

---

版本 1.14.3 中的变更

此补丁版本包含了次要错误修复和 CJK 字体输出支持。

• 新增了对四种 CJK 字体的支持，作为 PyMuPDF 生成的文本输出。这涉及到 Page.insertFont()、Shape.insertText()、Shape.insertTextbox() 方法及其对应的 Page 方法。新字体可在“保留”字体名称下使用，包括 “china-t”（繁体中文）、“china-s”（简体中文）、“japan”（日文）和 “korea”（韩文）。
• 新增了对内置字体 ‘Symbol’ 和 ‘Zapfdingbats’ 的完整支持。
• 更改了： 现在可以通过四字母缩写引用每个 14 种标准字体。

---

版本 1.14.1 的变更

此补丁版本包含轻微的性能改进。

• 添加 对文档文件名的支持，作为pathlib对象，使用 Python 的*str()*函数。

---

版本 1.14.0 的变更

为了支持 MuPDF v1.14.0，PyMuPDF 需要进行了大量的更改 - 其中大部分是技术性的，对开发人员的可见性不大。但也有相当多的有趣的新功能和改进功能。以下是详细信息：

• 添加 “墨迹”注释。
• 添加 “橡皮图章”注释。
• 添加 “波浪线”文本标记注释。
• 添加 新的类四边形（平面中的四边形或四边形）- 代表平面中的一般四边形形状。在文本标记注释中使用的矩形特殊子类型和文本搜索方法返回的对象。
• 添加 新选项“解密”到Document.save()和Document.write()。现在，保存受密码保护的 PDF 时可以保持加密。
• 添加 对底层 C 库 MuPDF 发出的未经请求的消息的抑制和重定向。有关详细信息，请参阅重定向错误和警告消息。
• 更改： 现在对注释的更改始终需要 Annot.update() 才能生效。
• 更改 自由文本注释以支持完整的拉丁字符集和外观选项范围。
• 更改 文本搜索，Page.searchFor()，可选择返回四边形而不是矩形对象，围绕每个搜索命中。
• 更改 纯文本输出：现在如果每行不以此字符结尾，则在每行末尾添加 n。
• 修复 问题 211（“文档中有错误”）。
• 修复 问题 213（“重写的大纲仅由基于 MuPDF 的应用程序显示”）。
• 修复 问题 214（“PDF 解密 GONE！”）。
• 修复 问题 215（“使用 pyMuPDF 添加的链接格式”）。
• 修复 问题 217（“我的 PDF 提取通过 JSON 失败”）。

在幕后，我们已经改变了几何对象的实现方式：它们现在完全存在于 Python 中，不再在 C 级别（MuPDF 中）存在“影子”双胞胎。这在该领域的处理速度提高了两倍以上。

由于同样的原因，现在大多数涉及几何参数的方法也接受相应的 Python 序列。例如，在方法*“page.show_pdf_page(rect, …)”中，参数rect*现在可以是任何rect_like序列。

我们还投入了大量精力来进一步扩展和改进常见问题解答（FAQ）章节。

---

版本 1.13.19 的变更

此版本包含一些技术/性能改进和错误修复。

• 更改内存管理：对于 Python 3 构建，Python 内存管理专门用于所有 C 级别代码（即 MuPDF 代码或 PyMuPDF 接口代码中不再使用原生 malloc()）。这导致改进的内存使用配置文件，并且还有一些运行时改进：我们已经看到文本提取和像素图创建的运行时间缩短了 > 2%（目前仅在 Windows 机器上）。
• 修复Python 2.7 中出现的错误，在使用 TextPage.extractRAWDICT() (= Page.getText(“rawdict”)）时导致解释器崩溃。
• 修复一个错误，在 Python 2.7 中创建链接目标时出现错误。
• 扩展FAQ 章节，提供更多示例。

---

版本 1.13.18 变更

• 添加方法TextPage.extractRAWDICT()，以及相应的新字符串参数“rawdict”到方法Page.getText()。它以 Python dict 形式从页面提取文本和图像，类似于 TextPage.extractDICT()，但具有 TextPage.extractXML() 的详细级别，即位置信息下到每个单个字符。

---

版本 1.13.17 变更

• 修复一个错误，此错误间歇性地导致Page.show_pdf_page()中的异常，当来自许多不同源 PDF 的页面显示时。
• 更改方法Document.extractImage()现在返回有关提取图像的更多元信息。此外，其性能已大大提高。几个演示脚本已更改以使用此方法。
• 更改方法Document._getXrefStream()现在如果对象不是流则返回 None，并且不再引发异常。
• 添加方法Document._deleteObject()，它删除由其 xref 标识的 PDF 对象。只能由经验丰富的 PDF 专家使用。
• 添加一个方法paper_rect()，它返回所提供纸张格式字符串的 Rect。示例：fitz.paper_rect(“letter”) = fitz.Rect(0.0, 0.0, 612.0, 792.0)。
• 在此文档中添加FAQ 章节。

---

版本 1.13.16 变更

• 添加对于某些注释类型正确设置透明度（不透明度）的支持。
• 添加一个工具属性（Tools.fitz_config gives “cannot resize a buffer with shared storage” error’）。

---

版本 1.13.15 变更

• 修复了 问题 #189（“无法找到内置的 CJK 字体”），所以我们现在支持内置的 CJK 字体（CJK = 中国、日本、韩国）。这应该会导致对使用这些语言的文档生成正确的像素图。这个变化对我们的二进制文件大小有影响：它现在将在 8 到 10MB 之间，取决于操作系统。
• 修复了 问题 #191（“Jupyter 笔记本内核在大约 40 页后死机”），当修改注释的内容时会出现此问题。

---

版本 1.13.14 中的变化

这个补丁版本包含了几个改进，主要是用于注释。

• 更改了 Annot.lineEnds 现在是表示行结束符号的两个整数的列表。之前是一个字符串的字典。
• 新增了 对适用注释的行结束符号的支持。PyMuPDF 现在可以生成包括行结束符号在内的这些注释。
• 新增了 Annot.setLineEnds() 用于向适用的注释类型（‘Line’、‘PolyLine’、‘Polygon’）添加行结束符号。
• 更改了 Page.insertImage() 和 Page.show_pdf_page() 的技术实现：它们现在会创建自己的内容对象，从而避免了对潜在大流的更改，避免了压缩/解压缩工作以及增量更新时的高更改量。

---

版本 1.13.13 中的变化

这个补丁版本包含了几个嵌入文件和文件附件注释的改进。

• 新增了 Document.embfile_Upd() 允许更改嵌入文件的文件内容和元数据。它取代了旧方法 Document.embfile_SetInfo()（将在将来的版本中删除）。内容会自动压缩，元数据可以是 Unicode。
• 更改了 Document.embfile_Add() 现在会自动压缩文件内容。相关元数据现在可以是 Unicode（过去必须是 ASCII）。
• 更改了 Document.embfile_Del() 现在会自动删除所有具有提供的标识名称的条目。返回码现在是被删除条目的整数计数（之前是None）。
• 更改了 嵌入文件方法，现在也接受或显示 PDF 的 Unicode 文件名作为额外参数ufilename。
• 新增了 Page.add_file_annot() 用于添加新的文件附件注释。
• 更改了 Annot.fileUpd()（文件附件注释）现在还接受 PDF 的 Unicode ufilename 参数。描述参数desc可以正确使用 Unicode。此外，所有参数都是可选的，因此可以更改元数据而不必替换文件内容。
• 更改了 Annot.fileInfo()（文件附件注释）现在还会显示 PDF 的 Unicode 文件名作为参数ufilename。
• 修复了 问题 #180（“page.getText(output=’dict’) 返回无效的 bbox”），现在也适用于垂直文本。
• 修复 问题 #185（“无法呈现 PyMuPDF 创建的注释”）。该问题的原因是 MuPDF 在创建注释时采用了极简主义方法。MuPDF 函数创建的几种注释类型没有 /AP（“外观”）对象。此修复现在确保，每次创建注释时都会同时创建外观对象。我们仍不支持线条端点样式。

---

1.13.12 版本变更

• 修复 问题 #180（“page.getText(output=’dict’) 返回无效的 bbox”）。请注意，这是对 MuPDF 错误的一种规避，某些情况下会生成零高度字符矩形。当发生这种情况时，此修复确保 bbox 高度至少为字体大小。
• 对于列表框和组合框小部件，可选择值的属性列表已重命名为 Widget.choice_values。
• 更改 在添加小部件时，自动将任何缺失的 PDF Base 14 Fonts 添加到 PDF 中。现在还可以从现有的小部件字体中选择小部件文本字体。任何指定的字段值现在都会被尊重，并导致具有预设值的字段。
• 新增 Annot.updateWidget() 允许更改现有表单字段，包括字段值。

---

1.13.11 版本变更

尽管前几个补丁子版本只包含各种修复，但此版本再次引入了重要的新功能：

• 新增 PDF 小部件注释的基本支持。现在可以添加类型为文本、复选框、列表框和组合框的 PDF 表单字段。在需要时，PDF 被转换为带有第一个添加的小部件的表单 PDF。
• 修复 问题 #176（“嵌入错误文件”）、#177（“调用 page.getText() 时段错误”）和 #179（“在加密 PDF 上使用 page.getLinks() 时分段错误”）。

---

1.13.7 版本变更

• 新增 对可重排文档（电子书、HTML 等）的可变页面大小支持：在 Document 创建（打开）时新增参数 rect 和 fontsize，以及作为单独方法 Document.layout()。
• 新增 Annot 创建多种注释类型：便签、自由文本、圆形、矩形、线条、多边形、折线和文本标记。
• 新增支持注释透明度（Annot.opacity，Annot.setOpacity()）。
• 更改 Annot.vertices：点坐标现在被分组为浮点数对（不再作为单独的浮点数）。
• 更改 注释颜色字典：两个键现在命名为 “stroke”（以前为 “common”）和 “fill”。
• 新增 Document.isDirty 如果 PDF 在本次会话中已更改，则为 True。每次 Document.save() 或 Document.write() 后重置为 False。

---

版本 1.13.6 变更

• 修复 #173：对于内存驻留文档，确保在文档关闭之前 Python 不会垃圾回收流对象。

---

版本 1.13.5 变更

• 新的低级方法 Page._setContents() 定义了一个由其 xref 指定的对象，作为 contents 对象。
• 改变并扩展了 PDF 表单字段支持：属性 widget_text 已重命名为 Annot.widget_value。现在支持所有表单字段类型的值（除了签名）。新属性 Annot.widget_choices 包含列表框和组合框的可选值。如果没有值存在，所有这些属性现在都包含 None。

---

版本 1.13.4 变更

• Document.convertToPDF() 现在支持页面范围、恢复的页面顺序和页面旋转。如果文档已经是 PDF，则会引发异常。
• 修复了一个 bug（从 v1.13.0 引入），阻止了对透明图像进行 Page.insertImage()。

---

版本 1.13.3 变更

引入了一种将 任何 MuPDF 支持的文档 转换为 PDF 的方法。如果您希望将 XPS、EPUB、CBZ 或 FB2 文件转换为 PDF 版本，这里有一个方法。

• Document.convertToPDF() 返回一个 Python 的 bytes 对象，以 PDF 格式呈现。可以像普通文件一样在 PyMuPDF 中打开，或者带有 “.pdf” 扩展名写入磁盘。

---

版本 1.13.2 变更

主要增强是 PDF 表单字段支持。表单字段是类型为 (19, ‘Widget’) 的注释。有一个新的文档方法来检查 PDF 是否为表单。Annot 类具有描述字段详细信息的新属性。

• Document.is_form_pdf 如果对象类型为 /AcroForm 并且至少存在一个表单字段，则为 true。
• Annot.widget_type、Annot.widget_text 和 Annot.widget_name 包含表单字段（即“Widget”注释）的详细信息。

---

版本 1.13.1 变更

• TextPage.extractDICT() 是提取文档页（文本和图像）内容的新方法。与其他 TextPage extract()* 方法一样，支持所有文档类型。返回的对象是嵌套列表和其他字典的字典，与旧的 TextPage.extractJSON() 的 JSON 反序列化完全相同。不同之处在于结果是直接创建的 – 不使用 JSON 模块。因为用户无需 JSON 模块来解释信息，所以使用起来应该更容易，而且性能更好，因为它包含图像的原始 二进制格式 – 无需进行 base64 解码。
• Page.getText() 相应地支持新参数值 “dict” 以调用上述方法。
• TextPage.extractJSON()（或 Page.getText(“json”)）仍然为方便起见支持，但预计其使用将减少。

---

版本 1.13.0 的变更

本版本基于 MuPDF v1.13.0. 此版本是“主要的 bug 修复版本”。

在 PyMuPDF 中，我们还进行了一些 bug 修复，同时引入了一些小的增强功能。对用户 API 仅有非常小的更改。

• Document 的构造更加灵活：新的 filetype 参数允许设置文档类型。如果指定了此参数，将忽略文件名中的任何扩展名。更全面地解决了 问题 #156。作为此过程的一部分，文档已经重新编写。
• Pixmap 构造函数的变更：
  • 色彩空间转换不再允许丢弃 alpha 通道：源和目标的 alpha 现在将始终相同。当使用 alpha = 0 时，我们曾看到异常甚至解释器崩溃。
  • 作为替代，简单的像素图复制允许您选择目标 alpha 值。
• Document.save() 再次提供完整的垃圾回收范围 0 到 4. 由于 xref 维护中的一个 bug，我们不得不临时强制 garbage > 1。最终解决了 问题 #148。
• Document.save() 现在提供通过额外的参数“美化” PDF 源码的选项。
• Page.insertImage() 现在有了额外的 stream 参数，指定一个保存图像的内存区域。
• 解决了在 Linux 系统上 PNG 图像乱码的问题（“Problem writing PNG” #133）。

---

版本 1.12.4 的变更

这是 1.12.3 版本的扩展。

• 修复了 问题 #147：方法 Document.getPageFontlist() 和 Document.getPageImagelist() 现在还显示通过“Form XObjects”嵌套的 resources 中包含的字体和图像。
• 临时修复了 问题 #148：保存到新的 PDF 文件现在将自动使用 garbage = 2，如果给定值较低。最终修复预计将在 MuPDF 的下一个版本中完成。届时我们将移除这个变通方法。
• 修正了某些方法中非法使用模版 / 图像掩模位图的预防性修复。
• 方法 Document.getPageFontlist() 现在包含列表中每个字体的编码名称。
• 方法 Document.getPageImagelist() 现在包含列表中每个图像的解码方法名称。

---

版本 1.12.3 的变更

这是 1.12.2 版本的扩展。

• 许多函数现在在结果没有其他含义时返回 None，而不是 0（例如 Document.close(), Document.save(), Document.select(), Pixmap.save() 和许多其他函数）。

---

版本 1.12.2 变更

这是 1.12.1 版本的扩展。

• 方法 Page.show_pdf_page() 现在接受新的 clip 参数。这指定了应限制显示的源页面区域。
• 为方便起见，新增了 Page.CropBox 和 Page.MediaBox。

---

版本 1.12.1 变更

这是 1.12.0 版本的扩展。

• 新方法 Page.show_pdf_page() 显示另一个 PDF 页面。这是一个矢量图像，因此在缩放时保持精确。两个涉及的文档必须是 PDF 格式。
• 新方法 Page.getSVGimage() 创建页面的 SVG 图像。与位图的光栅图像相比，这是一种矢量图像格式。返回的是一个 Unicode 文本字符串，可以保存在 .svg 文件中。
• 方法 Page.getTextBlocks() 现在接受额外的布尔参数 “images”。如果设置为 true（默认为 false），则包括图像块（仅元数据）在内的列表，从而允许检测包含渲染图像的区域。
• 进行了一些次要的错误修复。
• Page.getText() 的 “text” 结果通过使用单个空格字符连接块内所有行。MuPDF 的原始版本使用 “n”，导致输出比较不规则。
• 页面对象 Page 的新属性 Page.MediaBoxSize 和 Page.CropBoxPosition 提供了关于页面尺寸的更多信息。对于非 PDF 文件（以及大多数 PDF 文件），它们将等同于 Page.rect.bottom_right 和 Page.rect.top_left。例如，类 Shape 使用它们正确地定位其项目。

---

版本 1.12.0 变更

此版本基于并需要 MuPDF v1.12.0。新的 MuPDF 版本包含了许多变更，主要围绕文本提取。其中一些变更影响了程序员的 API。

• Outline.saveText() 和 Outline.saveXML() 被删除且没有替代。你可能并未经常使用它们。但如果你在寻找替代方案：Document.get_toc() 的输出可以轻松用于生成等效内容。
• 类 TextSheet 不再存在。
• 文本“spans”（TextPage 的层次之一）不再包含位置信息（即没有 “bbox” 键）。相反，spans 现在为其文本提供字体信息。这影响了我们的 JSON 输出变体。
• HTML 输出已经大大改进：现在它创建的是有效的文档，可以由浏览器显示，以产生与原始文档类似的视图。
• 现在有一个新的输出格式 XHTML，它以浏览器可读的格式提供文本和图像。与 HTML 输出的区别在于，不会尽力复制原始布局。
• Page.getText() 的所有输出格式现在都支持创建完整的、有效的文档，通过添加适当的头部和尾部信息进行包装。如果您有兴趣使用 HTML 输出，请确保阅读 控制 HTML 输出的质量。
• 为了支持查找文本位置，我们添加了一些特殊方法，无需像 TextPage.extractJSON() 或 TextPage.extractXML() 那样绕弯子：使用 Page.getTextBlocks() 或 Page.getTextWords() 来创建文本块或单词列表，它们附带其矩形。这应该比标准文本提取方法快得多，也避免了使用额外的包来解释它们的输出。

---

版本 1.11.2 中的更改

这是 v1.11.1 的扩展版本。

• 新的 Page.insertFont() 创建一个 PDF 的 /Font 对象并返回其对象编号。
• 新的 Document.extractFont() 提取给定对象编号的嵌入字体的内容。
• 方法 FontList(…) 中的项目不再包含 PDF 生成编号。这个值从未有过任何意义。相反，现在包括了字体文件扩展名（例如，“pfa”表示“PostScript Font for ASCII”），这是更有价值的信息。
• 除了“简单字体”（Type1）之外，现在还支持其他字体。
• 改变 Pixmap 尺寸的新选项：
  • 方法 Pixmap.shrink() 在原地按比例减小了像素图。
  • 通过设置目标宽度和高度，新的 Pixmap 复制构造函数允许进行缩放。

---

版本 1.11.1 中的更改

这是 v1.11.0 的扩展版本。

• 新类 Shape。它简化并扩展了在 PDF 页面上创建图像形状的过程。它包含多个用于创建基本形状（如线条、矩形或圆形）的方法，这些形状可以组合成更复杂的形状，并且可以赋予它们共同的属性，如线宽或颜色。组合的形状被视为一个单元，例如可以一起“变形”。该类可以累积多个复杂形状，并将它们全部放在页面的前景或背景中 - 因此还可以减少页面的 contents 对象的更新次数。
• 所有 Page 绘制方法现在都使用新的 Shape 类。
• 文本插入方法 insertText() 和 insertTextBox() 现在除了支持文本旋转外，还支持变形。它们已成为 Shape 类的一部分，因此允许文本与图形自由组合。
• 新的 Pixmap 构造函数允许创建带有附加 alpha 通道的 pixmap 副本。一个新方法还允许直接操作 alpha 值。
• 二元几何对象（矩阵、矩形和点）的代数运算现在通常也支持列表或元组作为第二操作数。您可以将数字元组 (x, y) 添加到 Point 中。在这种情况下，这些序列被称为“point_like”（或 matrix_like、rect_like）。
• 几何对象现在完全支持就地运算符。例如，p /= m 将点 p 替换为数字 1/m 的 p，或者对于 matrix_like 对象 m，则为 p * ~m。同样，如果 r 是一个矩形，则 r |= (3, 4) 是包含 fitz.Point(3, 4) 的新矩形，r &= (1, 2, 3, 4) 则是与 fitz.Rect(1, 2, 3, 4) 的交集。

---

版本 1.11.0 中的变更

此版本基于并需要 MuPDF v1.11。

虽然 MuPDF 已经声明这主要是一个修复 bug 的版本，但确实包含一个重要的新功能：支持嵌入文件，也称为组合或集合。我们已扩展了 PyMuPDF 的功能，以支持这一功能，超过了 mutool 实用程序的范围。

• Document 类现在支持嵌入文件，具有几个新方法和一个新属性：
  • embfile_Info() 返回嵌入文件列表中条目的元数据信息。这比 mutool 目前提供的更多，它显示了用于嵌入文件的所有信息（而不仅仅是条目的名称）。
  • embfile_Get() 将条目的（解压缩的）内容检索到一个 bytes 缓冲区中。
  • embfile_Add(…) 将新内容插入到 PDF 组合中。我们（与 mutool 相反）限制此操作仅适用于具有新名称的条目（不允许重复名称）。
  • embfile_Del(…) 从组合中删除条目（MuPDF 中不提供此功能）。
  • embfile_SetInfo() – 更改嵌入文件的文件名或描述。
  • embfile_Count – 包含嵌入文件的数量。
• 几个增强功能用于简化几何对象的流程。这些与新的 MuPDF 版本无关，大多数也反映在 PyMuPDF v1.10.0 中。其中包括通过名称识别矩形的新属性（例如 Rect.bottom_right）以及处理集合论问题的新方法，如 Rect.contains(x) 或 IRect.intersects(x)。特别关注支持更多“Pythonic”语言构造：if x in rect … 相当于 rect.contains(x)。
• Rect 章节现在更多地介绍了空和无限矩形的背景及其处理方式的更新。处理本身也更新为在这一领域更加一致。
• 我们已开始基本支持 PDF 内容的生成：
  • Document.insert_page() 将一个新页面添加到 PDF 中，可选包含一些文本。
  • Page.insertImage() 将新的图像放在 PDF 页面上。
  • Page.insertText() 将新的文本放在现有页面上。
• 对于 FileAttachment 注释，可以提取和更改附加文件的内容和名称。

---

版本 1.10.0 中的更改

MuPDF v1.10 影响

MuPDF 版本 1.10 对我们的绑定产生了重大影响。一些更改也影响了 API - 换句话说，你作为 PyMuPDF 用户受到了影响。

• 链接目标信息已减少。 linkDest 类的几个属性不再包含有价值的信息。事实上，这个类作为一个整体已从 MuPDF 的库中删除，我们在 PyMuPDF 中只是为了提供对现有代码的兼容性而维护它。
• 为了最小化内存要求，MuPDF v1.10 中内置了几项改进：
  • 一个新的 config.h 文件可以用来取消 C 代码中不需要的功能。使用这个功能，我们已经成功将二进制文件 _fitz.o / _fitz.pyd 的大小减少了约 50%（从 9 MB 减少到了 4.5 MB）。当使用 UPX 压缩时，大小甚至进一步减少到了非常方便的 2.3 MB。
  • pixmap 的 alpha（透明度）通道现在是可选的。让 alpha 默认为 False 可显著减小 pixmap 的大小（20% - CMYK，25% - RGB，50% - GRAY）。因此，许多 Pixmap 构造函数现在接受一个 alpha 布尔值来控制是否包含此通道。其他 pixmap 构造函数（例如文件和图像输入的构造函数）完全不包含 alpha 的 pixmap。但是，pixmap 的保存方法不再接受 savealpha 选项：当存在时，此通道将始终保存。为了最小化代码断点，我们在调用模式中保留了此参数 - 它将被忽略。
• DisplayList 和 TextPage 类的构造函数现在需要页面的媒介框（即*page.bound()*矩形）。没有办法从其他来源构造这些信息，因此在这些情况下无法避免源代码更改。但是我们假设，实际上没有多少用户会明确地使用这些底层类。因此，这种变化的影响应该是很小的。

与版本 1.9.3 相比的其他更改

• 新的 Document 方法 write() 将已打开的 PDF 写入内存（与 save() 不同，它将文件写入）。
• 注释现在可以在页面上缩放和移动。这是通过修改其矩形来完成的。
• 现在可以删除注释。 Page 包含了新方法 deleteAnnot()。
• 现在可以修改各种注释属性，例如内容、日期、标题（= 作者）、边框、颜色。
• 方法 Document.insert_pdf() 现在还会复制源页面的注释。
• 类 Pages 已被删除。由于现在可以使用页面编号作为索引访问文档（比如 doc[n] = doc.loadPage(n)），并且文档对象可以用作迭代器，因此维护此类的好处太低。请参见以下评论。
• loadPage(n) / doc[n] 现在接受任意整数来指定页面号，只要 n < pageCount。例如，doc[-500] 总是有效的，并将加载页面 (-500) % pageCount。
• 现在可以像这样将文档用作迭代器：for page in doc: …<使用“page”做某事> …。这将生成 doc 的所有页面作为 page。
• 方法 getSize() 已被属性 size 取代。与之前一样，Pixmap.size == len(Pixmap) 成立。
• 针对透明度（alpha）是可选的反应，已向 Pixmap 和 Colorspace 类添加了多个新参数和属性，以支持确定它们的特性。
• 页面 类现在包含新属性 firstAnnot 和 firstLink，用于提供到相应类链的起始点，其中 firstLink 仅是方法 loadLinks() 的助记符同义词，该方法仍然存在。类似地，新属性 rect 是方法 bound() 的同义词，该方法也仍然存在。
• Pixmap 方法 samplesRGB() 和 samplesAlpha() 已删除，因为现在可以创建不带透明度的像素图。
• Rect 现在具有属性 irect，它是方法 round() 的同义词。同样地，IRect 现在具有属性 rect，以提供具有浮点坐标值的 Rect。
• 文档具有新方法 searchPageFor() 用于搜索文本字符串。它的工作方式与相应的 Page.searchFor() 相同，额外的参数是页码。

---

版本 1.9.3 中的变更

此版本还基于 MuPDF v1.9a。与版本 1.9.2 相比的更改包括：

• 作为一个重大的增强，注释现在以类似于链接的方式支持。可以显示注释（作为像素图），并且可以访问它们的属性。
• 除了文档的 select() 方法外，现在还可以使用一些更简单的方法来操作 PDF：
  • copyPage() 在文档内复制页面。
  • movePage() 类似，但会删除原始页面。
  • delete_page() 删除页面。
  • delete_pages() 删除页面范围。
• rotation 或 setRotation() 分别访问或更改 PDF 页面的旋转。
• 以前虽然未记录，但 IRect、Rect、Point 和 Matrix 现在支持 len() 方法，可以通过索引访问它们的坐标属性，例如 IRect.x1 == IRect[2]。
• 为方便起见，文档现在支持简单的索引：doc.loadPage(n) == doc[n]。索引可能在范围 -pageCount < n < pageCount 内，因此 doc[-1] 是文档的最后一页。

---

版本 1.9.2 的变更

此版本还基于 MuPDF v1.9a。与版本 1.9.1 相比的更改如下：

• fitz.open()（无参数）创建一个新的空PDF文档，即如果之后保存，必须加上*.pdf*扩展名。
• 文档现在接受以下所有格式（Document和open是同义词）：
  • open()，
  • open(filename)（等效于open(filename, None)），
  • open(filetype, area)（等效于open(filetype, stream = area)）。

  内存区域stream的类型可以是bytes或bytearray。因此，例如，可以直接使用area = open(“file.pdf”, “rb”).read()（而不必先转换为 bytearray）。

• 新方法Document.insert_pdf()（仅限 PDF）从另一个 PDF 插入页面范围。
• Document对象现在支持*len()*函数：len(doc) == doc.pageCount。
• 新方法*Document.getPageImageList()*创建页面上使用的图像列表。
• 新方法*Document.getPageFontList()*创建页面引用的字体列表。
• 新的像素图构造函数*fitz.Pixmap(doc, xref)*基于已打开的 PDF 文档和图像的xref编号创建像素图。
• 新的像素图构造函数fitz.Pixmap(cspace, spix)创建一个像素图，作为另一个像素图spix的副本，并将颜色空间转换为cspace。这适用于所有颜色空间组合。
• 像素图构造函数fitz.Pixmap(colorspace, width, height, samples)现在还允许samples为bytes，不仅仅是bytearray。

---

版本 1.9.1 的变更

此版本的 PyMuPDF 基于 MuPDF 库源代码版本 1.9a，发布于 2016 年 4 月 21 日。

请查看 MuPDF 的网站，了解包含的变更和增强功能。

与版本 1.8.0 相比，版本 1.9.1 的更改如下：

• 对于fitz.Rect和fitz.IRect，现在都有新的方法get_area()。
• 现在可以直接从文件创建像素图，使用新构造函数fitz.Pixmap(filename)。
• 像素图构造函数*fitz.Pixmap(image)*相应地进行了扩展。
• fitz.Rect现在可以使用所有可能的点和坐标组合创建。
• 现在所有 PyMuPDF 类和方法都包含 doc 字符串，大多数是由 SWIG 自动生成的。虽然 PyMuPDF 文档肯定更详细，但这个功能应该在使用 Python-aware IDE 进行编程时非常有帮助。
• 一个新的文档方法*getPermits()*返回与当前访问文档相关的权限（打印、编辑、注释、复制），作为 Python 字典。
• 现在不可变的身份矩阵是fitz.Identity。
• 新文档方法*select(list)*从文档中删除不包含在列表中的所有页面。页面也可以复制和重新排列。
• 在我们的演示和示例集合中有各种改进和新成员。可能最显著的是：PDF_display 现在支持鼠标滚轮滚动，还有一个新的示例程序 wxTableExtract 允许图形化识别和提取文档中的表数据。
• fitz.open() 现在是 fitz.Document() 的别名。
• 新的像素图方法 tobytes() 可以返回一个按 PNG 图像格式排列的 bytearray。
• 新的像素图方法 samplesRGB() 提供一个剥离了 alpha 字节的 samples 版本（仅限 RGB 颜色空间）。
• 新的像素图方法 samplesAlpha() 仅提供 samples 区域的 alpha 字节。
• 新的迭代器 fitz.Pages(doc) 可以遍历文档的页面集合。
• 新的矩阵方法 invert()（计算矩阵的逆）、concat()（计算矩阵乘积）、pretranslate()（执行移位操作）。
• 新的 IRect 方法 intersect()（与另一个矩形的交集）、translate()（执行移位操作）。
• 新的 Rect 方法 intersect()（与另一个矩形的交集）、transform()（矩形的变换）、include_point()（扩展矩形以包含一个点）、include_rect()（扩展矩形以包含另一个矩形）。
• 记录了 Point.transform()（使用矩阵转换点）。
• Matrix、IRect、Rect 和 Point 类现在支持紧凑的、代数形式的操作。
• 现在可以使用调用模式 doc.save(doc.name, incremental=True) 进行增量保存更改。
• 可以通过文档方法 set_metadata() 删除、设置或更改 PDF 的元数据。支持增量保存。
• 可以使用文档方法 set_toc(list) 删除、设置或更改 PDF 的书签（或目录）。支持增量保存。

您对本页有何反馈？

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

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

数据 表单 对象 工具 函数

0 人点赞