术语表#
- coordinate#
这是理解本文档所需的数学/几何基本通用术语。更详细的讨论请参阅此节：坐标（Coordinates）。
- matrix_like#
一个包含 6 个数字的 Python 序列。
- rect_like#
一个包含 4 个数字的 Python 序列。
- irect_like#
一个包含 4 个整数的 Python 序列。
- point_like#
一个包含 2 个数字的 Python 序列。
- quad_like#
一个包含 4 个点（
point_like）项的 Python 序列。
- inheritable#
PDF 中的许多值可以在父子关系中由下层对象继承。例如，页面的媒体框（物理大小）可以在页面树（
pagetree）中的某个节点中只指定一次或在某些节点中指定，然后该值将作为所有未指定自己值的子级（kids）的值。
- MediaBox#
一个包含 4 个浮点数的 PDF 数组，指定页面的物理大小 – （可继承（
inheritable），强制）。此矩形应包含所有其他 PDF（可选）页面矩形，这些矩形可以额外指定：CropBox、TrimBox、ArtBox 和 BleedBox。详情请查阅 Adobe PDF 参考（Adobe PDF References）。MediaBox 是唯一一个在 MuPDF 和 PDF 坐标系之间没有区别的矩形：Page.mediabox将始终显示与页面对象定义中的/MediaBox键相同的坐标。对于所有其他矩形，MuPDF 会转换 y 坐标，使其顶部边界成为参考点。这有时可能会令人困惑 – 例如，您可能会遇到以下情况：页面定义包含以下相同的值：
/MediaBox [ 36 45 607.5 765 ]，/CropBox [ 36 45 607.5 765 ]。PyMuPDF 相应地显示
page.mediabox = Rect(36.0, 45.0, 607.5, 765.0)。但是：
page.cropbox = Rect(36.0, 0.0, 607.5, 720.0)，因为两个 y 坐标都被转换了（从它们都减去了 45）。
- CropBox#
一个包含 4 个浮点数的 PDF 数组，指定页面的可见区域 – （可继承（
inheritable），可选）。它是 TrimBox、ArtBox 和 BleedBox 的默认值。如果不存在，则默认为 MediaBox。与Page.rect不同，此值不受页面旋转的影响。此外，与页面矩形不同，裁剪框的左上角可能不一定是 (0, 0)。
- catalog#
一个核心的 PDF 字典（
dictionary）——也称为“根”——包含文档范围的参数以及指向许多其他信息的指针。Document.pdf_catalog()返回其交叉引用（xref）。
- trailer#
更准确地说，PDF 尾部包含字典（
dictionary）格式的信息。它通常位于文件的末尾。在此字典中，您可以找到目录和元数据的交叉引用、交叉引用（xref）号的数量等。以下是 PDF 规范的定义：“PDF 文件的尾部使读取该文件的应用程序能够快速找到交叉引用表和某些特殊对象。应用程序应从文件的末尾开始读取 PDF 文件。”
要在 PyMuPDF 中访问尾部，请使用常用的方法
Document.xref_object()、Document.xref_get_key()和Document.xref_get_keys()，并使用-1代替正交叉引用号。
- contents#
内容流是一个 PDF 对象（
object），它附加了一个流（stream），其数据由描述要在页面上绘制的图形元素的指令序列组成，请参阅 Adobe PDF 参考（Adobe PDF References）第 19 页的“流对象”。有关这些流中使用的微语言的概述，请参阅 Adobe PDF 参考（Adobe PDF References）第 643 页的“运算符摘要”章节。PDF 页面（page）可以有零个或多个内容对象。如果为零，则页面为空（但仍可能显示注释）。如果页面有多个内容对象，则它们将按顺序解释，就像它们的指令存在于一个对象中一样（即就像在一个连接的字符串中）。应注意，还有更多使用相同语法的流对象类型：例如与注释和 Form XObjects 相关联的外观字典。PyMuPDF 提供了许多处理 PDF 页面内容的方法：
Page.read_contents()– 读取并连接所有页面内容到一个bytes对象中。Page.clean_contents()– MuPDF 函数的包装器，该函数读取、连接并清理所有页面内容语法。在此之后，将只存在一个/Contents对象。此外，页面资源（resources）也将与之同步，使其恰好包含页面实际引用的图像、字体和其他对象。Page.get_contents()– 返回页面内容对象（contents）的交叉引用（xref）号列表。可能为空。使用Document.xref_stream()和其中一个交叉引用号来读取相应的内容部分。Page.set_contents()– 将页面的/Contents键设置为提供的交叉引用（xref）号。
- resources#
一个字典（
dictionary），包含 PDF 页面（page）或其他某些对象（Form XObjects）所需的任何资源（如图像或字体）的引用（必需，可继承，Adobe PDF References p. 81）。此字典作为子字典出现在对象定义中的 /Resources 键下。作为一种可继承的对象类型，对于所有页面或页面的某些子集，可能存在“父”资源。
- dictionary#
一种 PDF 对象（
object）类型，与 Python 中同名的概念有些相似：“字典对象是一个关联表，包含成对的对象，称为字典的条目。每个条目的第一个元素是键，第二个元素是值。键必须是一个名称（...）。值可以是任何类型的对象，包括另一个字典。值为 null（...）的字典条目等同于不存在的条目。”（Adobe PDF References p. 18）。字典是 PDF 中最重要的对象（
object）类型。以下是一个示例（描述一个页面（page））<< /Contents 40 0 R % value: an indirect object /Type/Page % value: a name object /MediaBox[0 0 595.32 841.92] % value: an array object /Rotate 0 % value: a number object /Parent 12 0 R % value: an indirect object /Resources<< % value: a dictionary object /ExtGState<</R7 26 0 R>> /Font<< /R8 27 0 R/R10 21 0 R/R12 24 0 R/R14 15 0 R /R17 4 0 R/R20 30 0 R/R23 7 0 R /R27 20 0 R >> /ProcSet[/PDF/Text] % value: array of two name objects >> /Annots[55 0 R] % value: array, one entry (indirect object) >>
Contents、Type、MediaBox 等是键，40 0 R、Page、[0 0 595.32 841.92] 等是相应值。字符串 “<<” 和 “>>” 用于包围对象定义。
此示例还展示了嵌套字典值的语法：Resources 的值是一个对象，该对象本身又是一个字典，其键如 ExtGState（值为 <</R7 26 0 R>>，这是另一个字典）等。
- page#
PDF 页面是一个字典（
dictionary）对象，定义了 PDF 中的一页，请参阅 Adobe PDF References p. 71。
- pagetree#
通过称为页面树的结构来访问文档的页面，该结构定义了文档中页面的顺序。树结构允许仅使用有限内存的 PDF 消费者应用程序快速打开包含数千页的文档。该树包含两种类型的节点：中间节点，称为页面树节点；叶子节点，称为页面对象。（Adobe PDF References p. 75）。
虽然可以将所有页面引用都列在一个数组中，但包含许多页面的 PDF 通常使用平衡树结构（“页面树”）创建，以便更快地访问任何单个页面。相对于总页面数，这可以将按页码访问页面的平均时间从线性顺序降低到对数顺序。
为了快速访问页面，MuPDF 可以在内存中使用自己的数组——独立于文档文件中可能或可能不存在的内容。该数组按页码索引，因此比通过完全平衡的页面树访问要快得多。
- object#
与 Python 类似，PDF 支持对象的概念，对象可以分为八种基本类型：布尔值（“true”或“false”）、整数和实数、字符串（始终用括号括起来——或者“()”，或者“<>”表示十六进制）、名称（必须始终以“/”开头，例如
/Contents）、数组（用方括号“[]”括起来）、字典（用尖括号“<<>>”括起来）、流（用关键字“stream”/“endstream”括起来）和 null 对象（“null”）（Adobe PDF References p. 13）。对象可以通过分配标签来标识。此标签然后称为间接对象。PyMuPDF 支持通过其交叉引用号使用Document.xref_object()检索间接对象的定义。
- stream#
一种 PDF 字典（
dictionary）对象（object）类型，其后跟随一个字节序列，类似于 Python 的 bytes。“但是，PDF 应用程序可以增量读取流，而字符串必须一次性读取整个内容。此外，流可以具有无限长度，而字符串受实现限制。因此，包含潜在大量数据的对象（例如图像和页面描述）表示为流。”“流由一个字典（dictionary）后跟零个或多个字节组成，这些字节用关键字 stream 和 endstream 括起来”nnn 0 obj << dictionary definition >> stream (zero or more bytes) endstream endobj
请参阅 Adobe PDF References p. 19。PyMuPDF 支持通过
Document.xref_stream()检索流内容。使用Document.is_stream()判断对象是否为流类型。
- unitvector#
一个数学概念，表示范数（“长度”）为 1 的向量——通常指欧几里得范数。在 PyMuPDF 中，此术语仅限于点（Point）对象，请参阅
Point.unit。
- xref#
交叉引用号的缩写：这是 PDF 中对象的唯一整数标识符。每个 PDF 中都存在一个交叉引用表（其物理上可能由几个独立的段组成），用于存储每个对象的相对位置以便快速查找。交叉引用表比现有对象的数量长一项：第零项是保留的，不得以任何方式使用。许多 PyMuPDF 类都有一个 xref（
xref）属性（对于非 PDF 文件，该属性为零），可以通过Document.xref_length()- 1 获取 PDF 中对象的总数。
- fontsize#
字体大小此度量单位以磅为单位，其中 1 英寸 = 72 磅。
- resolution#
图像和像素图（Pixmap）对象可能包含以“每英寸点数”（dpi）表示的分辨率信息（水平和垂直方向）。当 MuPDF 从文件或 PDF 对象读取图像时，它将解析此信息并将其放入
Pixmap.xres和Pixmap.yres中。如果在输入中找不到有意义的信息（例如非正值或超过 4800 的值），它将使用“合理”的默认值。通常的默认值为 96，但在某些情况下（例如对于 JPX 图像）也可能是 72。
- OCPD#
可选内容属性字典 - PDF 目录（
catalog）的子字典（dictionary）。存储可选内容信息的中心位置，由键/OCProperties标识。此字典有两个必需条目和一个可选条目：（1）/OCGs，必需，列出所有可选内容组的数组，（2）/D，必需，默认可选内容配置字典（OCCD），（3）/Configs，可选，替代 OCCD 的数组。
- OCCD#
可选内容配置字典 - PDF OCPD（
OCPD）中的 PDF 字典（dictionary）。它存储 OCG 的开/关状态设置以及它们如何呈现给 PDF 查看器程序。选择配置是快速实现临时批量可见性状态更改的方法。打开 PDF 后，OCPD（OCPD）的/D配置始终被激活。查看器应该提供一种在/D或包含在/Configs数组中的可选配置之间切换的方式。
- OCG#
可选内容组 – 一个字典（
dictionary）对象，用于控制其他 PDF 对象（如图像或注释）的可见性。无论它们在哪一页定义，具有相同 OCG 的对象都可以通过将它们的 OCG 设置为 ON 或 OFF 同时显示或隐藏。这可以通过许多 PDF 查看器（Adobe Acrobat）提供的用户界面或通过编程实现。
- OCMD#
可选内容成员字典 – 一个字典（
dictionary）对象，可以像 OCG（OCG）一样使用：它具有可见性状态。OCMD 的可见性是计算得出的：它是一个逻辑表达式，使用一个或多个 OCG 的状态产生布尔值。表达式的结果解释为 ON（真）或 OFF（假）。
- ligature#
在更高级的字体中，一些常见的字符组合由其自身的特殊字形表示。典型示例包括“fi”、“fl”、“ffi”和“ffl”。这些复合词称为连字（ligatures）。在 PyMuPDF 文本提取中，可以选择返回相应的 Unicode 不变，或将连字拆分成其组成部分：“fi”==>“f”+“i”等。