术语#
Glossary
- matrix_like#
一个包含 6 个数字的 Python 序列。
- rect_like#
一个包含 4 个数字的 Python 序列。
- irect_like#
一个包含 4 个整数的 Python 序列。
- point_like#
一个包含 2 个数字的 Python 序列。
- quad_like#
一个包含 4 个
point_like项目的 Python 序列。
- MediaBox#
一个包含 4 个浮动数字的 PDF 数组，指定页面的物理大小 – (
inheritable, 强制性)。此矩形应包含所有其他 PDF 页面矩形，这些矩形可以另外指定：CropBox、TrimBox、ArtBox 和 BleedBox。详细信息请参考 Adobe PDF 参考。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相反。此外，除了页面矩形外，cropbox 的左上角坐标可能是 (0, 0) 也可能不是。
- catalog#
一个中心 PDF
dictionary– 也称为“根字典” – 包含文档范围的参数和指向许多其他信息的指针。它的xref由Document.pdf_catalog()返回。
- trailer#
更精确地说，PDF trailer 包含以
dictionary格式的信息。它通常位于文件的末尾。在此字典中，您将找到诸如目录和元数据的 xref、xref 数量等信息。以下是 PDF 规范中的定义：“PDF 文件的 trailer 使得读取文件的应用程序能够快速找到交叉引用表和某些特殊对象。应用程序应从 PDF 文件的末尾开始读取。”
要在 PyMuPDF 中访问 trailer，请使用常用方法
Document.xref_object()、Document.xref_get_key()和Document.xref_get_keys()，并使用-1代替正数 xref 编号。
- contents#
内容流 是一个 PDF
object，其附加了一个stream，该流的数据由描述要绘制在页面上的图形元素的指令序列组成，详见 Adobe PDF 参考 中的 “Stream Objects” 第 19 页。有关这些流中使用的迷你语言的概述，请参见 Adobe PDF 参考 中的 “Operator Summary” 第 643 页。一个 PDFpage可以有零到多个 contents 对象。如果没有，它为空页面（但仍然可能显示注释）。如果有多个，它们将按顺序解释，就像它们的指令出现在一个对象中一样（即像一个串联的字符串）。需要注意的是，还有其他使用相同语法的流对象类型：例如与注释关联的外观字典和表单 XObjects。PyMuPDF 提供了多个方法来处理 PDF 页面内容：
Page.read_contents()– 读取并将所有页面内容合并为一个bytes对象。Page.clean_contents()– 一个 MuPDF 函数的包装器，读取、合并并清理所有页面内容的语法。之后，只会存在一个/Contents对象。此外，页面resources将与其同步，确保它包含页面实际引用的所有图像、字体和其他对象。Page.get_contents()– 返回页面contents对象的xref编号列表。可能为空。使用Document.xref_stream()和这些 xrefs 中的一个来读取相应的内容部分。Page.set_contents()– 将页面的/Contents键设置为提供的xref编号。
- resources#
一个
dictionary，包含 PDFpage（强制性，继承性，参考 Adobe PDF 参考 第 81 页）及某些其他对象（如表单 XObjects）所需的所有资源的引用（如图像或字体）。此字典作为对象定义中的子字典出现，位于 Resources 键下。作为一个继承对象类型，可能存在所有页面或某些页面子集的“父级”资源。
- dictionary#
一个 PDF
object类型，类似于 Python 中的同名概念：“字典对象是一个包含对象对的关联表，称为字典条目。每个条目的第一个元素是键，第二个元素是值。键必须是一个名称（…）。值可以是任何类型的对象，包括另一个字典。一个字典条目的值为 null（…）时，相当于该条目不存在。”（参考 Adobe PDF 参考 第 18 页）。字典是 PDF 中最重要的
object类型。以下是一个示例（描述一个page）：<< /Contents 40 0 R % 值：间接对象 /Type/Page % 值：名称对象 /MediaBox[0 0 595.32 841.92] % 值：数组对象 /Rotate 0 % 值：数字对象 /Parent 12 0 R % 值：间接对象 /Resources<< % 值：字典对象
/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] % 值：包含两个名称对象的数组 >>
/Annots[55 0 R] % 值：数组，一个条目（间接对象） >>
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 参考 第 71 页。
- pagetree#
文档的页面通过称为页面树的结构进行访问，该结构定义了文档中页面的顺序。树结构允许 PDF 消费应用程序在内存有限的情况下快速打开包含成千上万页面的文档。该树包含两种类型的节点：中间节点，称为页面树节点；叶节点，称为页面对象。 （参考 Adobe PDF 参考 第 75 页）。
虽然可以通过一个数组列出所有页面引用，但包含大量页面的 PDF 通常采用 平衡树 结构（“页面树”），以便更快地访问任何单一页面。相对于总页面数，这可以将平均页面访问时间从线性减少到某个对数级别。
为了实现快速页面访问，MuPDF 可以使用其自己内存中的数组 – 独立于文档文件中可能存在或不存在的内容。该数组按页面编号索引，因此比通过完美平衡的页面树访问要快得多。
- object#
与 Python 类似，PDF 支持 对象 的概念，PDF 中有八种基本类型：布尔值（“true” 或 “false”）、整数和实数、字符串（ 始终 用括号括起来 – 可以是“()”，或用“<>”表示十六进制）、名称（必须以“/”开头，例如
/Contents）、数组（用方括号“[]”括起来）、字典（用双尖括号“<<>>”括起来）、流（由“stream”和“endstream”关键词括起来）和 null 对象（“null”）（参考 Adobe PDF 参考 第 13 页）。对象可以通过分配标签来标识。该标签称为 间接 对象。PyMuPDF 支持通过交叉引用号（xref number）通过Document.xref_object()获取间接对象的定义。
- stream#
一个 PDF
dictionaryobject类型，后跟一系列字节，类似于 Python 中的 bytes。 “然而，PDF 应用程序可以增量地读取流，而字符串必须完全读取。此外，流的长度是无限的，而字符串受实现限制。因此，具有大量数据的对象（如图像和页面描述）通常表示为流。” “一个流由一个dictionary和零个或多个字节组成，这些字节位于 stream 和 endstream 关键字之间”：nnn 0 obj << 字典定义 >> stream (零个或多个字节) endstream endobj
参见 Adobe PDF 参考 第 19 页。PyMuPDF 支持通过
Document.xref_stream()获取流内容。使用Document.is_stream()判断对象是否为流类型。
- unitvector#
一个数学概念，表示一个范数（“长度”）为 1 的向量 – 通常隐含的是欧几里得范数。在 PyMuPDF 中，这个术语限制为 Point 对象，详见
Point.unit。
- xref#
交叉引用编号的缩写：这是 PDF 中对象的唯一标识符。每个 PDF 中都有一个交叉引用表（可能由多个独立段组成），存储每个对象的位置，以便快速查找。交叉引用表比实际对象数多一个条目：项零是保留的，不能以任何方式使用。许多 PyMuPDF 类有一个 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
dictionary，位于 PDFOCPD中。它存储 OCG 的开/关状态及其如何在 PDF 查看器程序中呈现。选择一个配置是快速实现临时大规模可见性状态变化的方式。打开 PDF 后，始终会激活OCPD的/D配置。查看器应提供在/D或/Configs数组中切换备用配置的方式。
- OCG#
可选内容组 – 一个
dictionary对象，用于控制其他 PDF 对象（如图像或注释）的可见性。不管它们定义在哪一页，具有相同 OCG 的对象可以通过设置它们的 OCG 为 ON 或 OFF 来同时显示或隐藏。这可以通过许多 PDF 查看器（如 Adobe Acrobat）提供的用户界面，或者通过编程方式实现。
- OCMD#
可选内容成员字典 – 一个
dictionary对象，可以像OCG一样使用：它有一个可见性状态。OCMD 的可见性是 计算得出的：它是一个逻辑表达式，使用一个或多个 OCG 的状态来生成布尔值。表达式的结果被解释为 ON（true）或 OFF（false）。
- ligature#
一些常见的字符组合在更高级的字体中由它们自己的特殊字形表示。典型的例子有 “fi”、”fl”、”ffi” 和 “ffl”。这些组合被称为 连字。在 PyMuPDF 的文本提取中，可以选择返回相应的 Unicode 不变，或将连字拆分为它们的组成部分：“fi” ==> “f” + “i”等。