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

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

确保 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，则对象的父项已丢失，并且对其属性或方法的任何引用都将引发异常，通知此“孤立”的状态。

一个示例会话：

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

这显示了级联效应：

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

注意

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

方法设计Page.show_pdf_page()

目的和能力

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

• 相比Page.insert_image()，此显示是基于矢量的，因此在缩放级别上保持准确。
  
• 就像Page.insert_image()一样，显示的大小根据给定的矩形调整。
  

当前支持以下显示变体：

• 布尔参数"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. /BBox等于源页面的/Mediabox
3. 
   
4. /Matrix等于单位矩阵。
5. 
   
6. /资源 等同于源页面。这涉及“深拷贝”层次嵌套的其他对象（包括字体、图像等）。这里涉及的复杂性由 MuPDF 的嫁接[1]技术函数来处理。
7. 
   
8. 这是一个流对象类型，其流是源页面contents对象的组合数据的精确副本。
9. 
   

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

1. 然后创建第二个Form XObject，目标页面用于调用显示。此对象具有以下属性：
2. /BBox等于源页面的/CropBox（或"clip"）。
3. 
   
4. /Matrix表示将/BBox映射到目标矩形。
5. 
   
6. /XObject通过固定名称fullpage引用前一个 Form XObject。
7. 
   
8. 此对象的流正好包含一个固定语句：/fullpage Do。
9. 
   
10. 如果方法的"oc"参数已给出，则将其值分配给此 Form XObject 作为/OC。
11. 
    
12. 现在修改了目标页面的resources和contents对象如下。
13. 在/资源的/XObject字典中添加一个条目，名称为fzFrm（n 选取得使该条目在页面上唯一）。
14. 
    
15. 根据"overlay"，在页面的/Contents数组之前或之后添加一个新对象，其中包含语句q /fzFrm 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. /BBox等于源页面的/Mediabox。
3. 
   
4. /Matrix等于单位矩阵。
5. 
   
6. /Resources等于源页面的资源。这涉及到层次嵌套的其他对象（包括字体、图像等）的“深复制”。这里涉及的复杂性由 MuPDF 的嫁接技术函数[1]覆盖。
7. 
   
8. 这是一个流对象类型，其流是源页面contents对象的组合数据的精确副本。
9. 
   

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

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

>>> 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) 是相同的。参见以下代码片段：

>>> 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 为单位），除以页数。
  
• 描述文件类型的备注。
  

注意

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

使用的工具

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

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

复制/连接/合并

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

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

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

PyMuPDF

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

PDFrw

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

PikePDF

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

PyPDF2

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

观察

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

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

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

观察

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

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

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

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

PyMuPDF

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

pdftopng.exe -r 150 file.pdf ./ 
• 1

PDF2JPG

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

观察

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

对此页面有任何反馈吗？

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

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

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

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

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

注

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

使用的工具

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

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

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