设备
不同的格式处理程序（pdf、xps 等）将页面解释为“设备”。设备是可以对页面执行的所有操作的基础：渲染、文本提取和搜索。设备类型由所选的构造方法确定。
类 API
class Device
__init__(self, object, clip)
用于像素映射或显示列表设备的构造函数。
参数：
- 对象（位图或显示列表）- 可以是Pixmap或DisplayList之一。
- 剪裁（IRect）- 用于Pixmap设备的可选 IRect，限制页面渲染到特定区域。如果需要完整页面，请指定None。对于显示列表设备，必须省略此参数。
__init__(self, textpage, flags=0)
用于文本页设备的构造函数。
参数：
- 文本页（TextPage）- TextPage对象
- 标志（int）- 控制文本如何解析为文本页的方式。当前可以将 3 个选项编码到此参数中，请参见文本提取标志。要设置这些选项，请使用类似*flags=0 | TEXT_PRESERVE_LIGATURES | …*的方式。
您对本页面有任何反馈吗？
此软件按原样提供，没有任何明示或暗示的保证。此软件在许可下分发，除非在该许可条款明确授权下，否则不得复制、修改或分发此软件。请参阅artifex.com获取许可信息或联系美国加利福尼亚州旧金山 Mesa Street 39 号 108A 套房的 Artifex Software Inc.获取更多信息。
此文档覆盖所有版本，直到 1.24.4。
共同工作：DisplayList 和 TextPage
这里有一些关于如何一起使用这些类的说明。
在某些情况下，当您回到这里解释的详细级别时，可能可以实现性能改进。
创建一个 DisplayList
一个 DisplayList 代表一个解释的文档页面。方法用于创建像素图、提取文本和文本搜索都是在幕后使用页面的显示列表来执行它们的任务。如果一个页面必须被多次渲染（例如因为变化的缩放级别），或者如果同时执行文本搜索和文本提取，可以节省开销，只需创建显示列表一次，然后用于所有其他任务。
>>> dl = page.get_displaylist() # create the display list
您还可以在“堆栈”上（列表中）为多个页面创建显示列表，可以在文档打开时、空闲时，或者在第一次访问页面时（例如在 GUI 脚本中）存储它。
注意，对于接下来的所有内容，只需要显示列表 – 相应的 Page 对象可能已被删除。
生成 Pixmap
以下代码从一个 DisplayList 创建一个 Pixmap。参数与 Page.get_pixmap() 相同。
>>> pix = dl.get_pixmap() # create the page's pixmap
这个语句的执行时间可能比 Page.get_pixmap() 短多达 50%。
执行文本搜索
使用上面的显示列表，我们也可以搜索文本。
为此，我们需要创建一个 TextPage。
>>> tp = dl.get_textpage() # display list from above >>> rlist = tp.search("needle") # look up "needle" locations >>> for r in rlist: # work with the found locations, e.g. pix.invert_irect(r.irect) # invert colors in the rectangles
提取文本
使用同一个 TextPage 对象，我们现在可以立即使用任何或所有 5 种文本提取方法。
注意
在上述，我们创建了我们的文本页面而没有参数。这导致默认参数为 3（保留连字和空白），IAW 图像将不会被提取 – 见下文。
>>> txt = tp.extractText() # plain text format >>> json = tp.extractJSON() # json format >>> html = tp.extractHTML() # HTML format >>> xml = tp.extractXML() # XML format >>> xml = tp.extractXHTML() # XHTML format
进一步的性能改进
Pixmap
如同在 Page 章节中解释的那样：
如果您不需要透明度，请在创建像素图时设置 alpha = 0。这将节省 25% 的内存（如果是 RGB，最常见的情况），并可能节省 5% 的执行时间（取决于 GUI 软件）。
TextPage
如果您不需要提取页面文本旁边的图像，可以设置以下选项：
>>> flags = pymupdf.TEXT_PRESERVE_LIGATURES | pymupdf.TEXT_PRESERVE_WHITESPACE >>> tp = dl.get_textpage(flags)
这将为 HTML、XHTML 和 JSON 文本提取节省约 25% 的总体执行时间，并极大地减少存储量（内存和磁盘空间）如果文档是面向图形的。
如果您确实需要图像，请使用标志值 7：
>>> flags = pymupdf.TEXT_PRESERVE_LIGATURES | pymupdf.TEXT_PRESERVE_WHITESPACE | pymupdf.TEXT_PRESERVE_IMAGES
对此页面有任何反馈吗？
本软件按原样提供，不附带任何明示或暗示的担保。此软件受许可证分发，除非在该许可证的条款明确授权下，否则不得复制、修改或分发此软件。有关更多信息，请参阅 artifex.com 的许可信息或联系 Artifex Software Inc., 39 Mesa Street, Suite 108A, San Francisco CA 94129, United States。
此文档涵盖了所有版本直至 1.24.4。
创建一个 DisplayList
DisplayList 表示一个解释的文档页面。幕后的方法，用于创建位图、提取文本和文本搜索的页面显示列表来执行它们的任务。如果一个页面必须渲染多次（例如，由于缩放级别的更改），或者如果同时进行文本搜索和文本提取，那么如果仅创建一次显示列表然后用于所有其他任务，则可以节省开销。
>>> dl = page.get_displaylist() # create the display list
你也可以为许多页面“在堆栈中”创建显示列表（列表中），可能是在文档打开时，空闲时，或者当第一次访问页面时存储它（例如，在 GUI 脚本中）。
注意，对于接下来的一切，只需要显示列表——相应的 Page 对象可能已被删除。
生成 Pixmap
以下从 DisplayList 创建一个 Pixmap。参数与 Page.get_pixmap() 相同。
>>> pix = dl.get_pixmap() # create the page's pixmap
该语句的执行时间可能比 Page.get_pixmap() 的执行时间短长达 50%。
执行文本搜索
使用上述显示列表，我们还可以搜索文本。
为此，我们需要创建一个 TextPage。
>>> tp = dl.get_textpage() # display list from above >>> rlist = tp.search("needle") # look up "needle" locations >>> for r in rlist: # work with the found locations, e.g. pix.invert_irect(r.irect) # invert colors in the rectangles
提取文本
使用上述相同的 TextPage 对象，我们现在可以立即使用任意或所有的 5 个文本提取方法。
注意
如上所述，我们创建了我们的文本页而不带参数。这将导致默认参数为 3（保留连字和空格），IAW 图像不会被提取——请参阅下文。
>>> txt = tp.extractText() # plain text format >>> json = tp.extractJSON() # json format >>> html = tp.extractHTML() # HTML format >>> xml = tp.extractXML() # XML format >>> xml = tp.extractXHTML() # XHTML format
进一步的性能改进
Pixmap
如 Page 章节所述：
如果不需要透明度，请在创建位图时将 alpha = 0 设置为。这将节省 25% 的内存（如果是 RGB，则是最常见的情况），并可能节省 5% 的执行时间（取决于 GUI 软件）。
TextPage
如果您不需要在页面文本旁边提取图像，可以设置以下选项：
>>> flags = pymupdf.TEXT_PRESERVE_LIGATURES | pymupdf.TEXT_PRESERVE_WHITESPACE >>> tp = dl.get_textpage(flags)
这将为 HTML、XHTML 和 JSON 文本提取节省大约 25% 的总执行时间，并且如果文档是面向图形的，则会大大减少存储量（内存和磁盘空间）。
如果您确实需要图像，请为标志使用值 7：
>>> flags = pymupdf.TEXT_PRESERVE_LIGATURES | pymupdf.TEXT_PRESERVE_WHITESPACE | pymupdf.TEXT_PRESERVE_IMAGES
你对这页有任何反馈吗？
此软件按原样提供，不提供任何明示或暗示的担保。此软件根据许可分发，除非在许可条款明确授权，否则不得复制、修改或分发。有关更多信息，请参阅artifex.com，或联系 Artifex Software Inc.，39 Mesa Street，Suite 108A，San Francisco CA 94129，美国。
本文档涵盖了所有版本直至 1.24.4。
Pixmap
如 Page 章节所述：
如果创建像素图时不需要透明度，请将alpha = 0。这将节省 25%的内存（如果是 RGB，这是最常见的情况），并可能节省 5%的执行时间（取决于 GUI 软件）。
TextPage
如果不需要在页面文本旁边提取图像，可以设置以下选项：
>>> flags = pymupdf.TEXT_PRESERVE_LIGATURES | pymupdf.TEXT_PRESERVE_WHITESPACE >>> tp = dl.get_textpage(flags)
这将为 HTML、XHTML 和 JSON 文本提取节省大约 25%的总执行时间，并大幅减少存储量（内存和磁盘空间），如果文档是图形导向的话。
然而，如果需要图像，请使用 7 作为标志的值：
>>> flags = pymupdf.TEXT_PRESERVE_LIGATURES | pymupdf.TEXT_PRESERVE_WHITESPACE | pymupdf.TEXT_PRESERVE_IMAGES
你对这页有任何反馈吗？
此软件按原样提供，不提供任何明示或暗示的担保。此软件根据许可分发，除非在许可条款明确授权，否则不得复制、修改或分发。有关更多信息，请参阅artifex.com，或联系 Artifex Software Inc.，39 Mesa Street，Suite 108A，San Francisco CA 94129，美国。
本文档涵盖了所有版本直至 1.24.4。
术语表
coordinate
这是理解本文档的一个基本数学/几何术语。请参阅本节以获取更详细的讨论：坐标。
matrix_like
一个包含 6 个数字的 Python 序列。
rect_like
一个包含 4 个数字的 Python 序列。
irect_like
一个包含 4 个整数的 Python 序列。
point_like
一个包含 2 个数字的 Python 序列。
quad_like
一个包含 4 个point_like项的 Python 序列。
inheritable
PDF 中的许多值可以通过父子关系进一步向下继承到对象中。例如，页面的 mediabox（物理大小）可能只在pagetree的某些节点中指定一次，然后将作为所有未指定自己值的kids的值。
MediaBox
一个包含 4 个浮点数的 PDF 数组，指定了页面的物理大小 - (可继承，必填）。此矩形应包含所有其他 PDF 页面矩形，可选 - 页边框、裁剪框、艺术框和出血框。请参阅 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 数组，指定页面的可见区域 - （可继承，可选）。它是 TrimBox、ArtBox 和 BleedBox 的默认值。如果不存在，则默认为 MediaBox。此值不受页面旋转的影响 - 与Page.rect相反。另外，与页面矩形不同，裁剪框的左上角可能是*(0, 0)*，也可能不是。
catalog
一个中心 PDF 字典 - 也称为“根” - 包含文档范围的参数和指向许多其他信息的指针。其xref由Document.pdf_catalog()返回。
trailer
更准确地说，PDF 尾部 以 字典 格式包含信息。通常位于文件的末尾。在此字典中，您将找到诸如目录和元数据的 xrefs、xref 数量等内容。以下是 PDF 规范的定义：
“PDF 文件的尾部信息允许读取文件的应用程序快速找到交叉引用表和某些特殊对象。应用程序应该从文件的末尾开始读取 PDF 文件。”
要访问 PyMuPDF 中的尾部，请使用通常的方法 Document.xref_object()、Document.xref_get_key() 和 Document.xref_get_keys()，使用 -1 而不是正数 xref 编号。
contents
内容流 是带有附加 stream 的 PDF 对象，其数据包含一系列描述要在页面上绘制的图形元素的指令，详见 Adobe PDF 参考手册第 19 页上的“Stream Objects”。有关这些流中使用的迷你语言的概述，请参阅 Adobe PDF 参考手册第 643 页上的“操作符总结”章节。PDF 页面 可以没有到多个内容对象。如果没有内容对象，则页面为空（但仍可能显示注释）。如果有多个内容对象，则将按顺序解释它们，就好像它们的指令存在于一个这样的对象中（即像连接字符串一样）。应注意，还有更多使用相同语法的流对象类型，例如与注释相关联的外观字典和表单 XObjects。
PyMuPDF 提供了多种处理 PDF 页面内容的方法：
Page.read_contents()– 读取并连接所有页面内容为一个bytes对象。Page.clean_contents()– 一个 MuPDF 函数的包装，用于读取、连接和语法清理所有页面内容。之后，只会存在一个/Contents对象。此外，页面的资源也将与之同步，确保它只包含页面实际引用的那些图像、字体和其他对象。Page.get_contents()– 返回页面内容对象的xref编号列表。可能为空。使用Document.xref_stream()和其中一个 xref 来读取相应的内容部分。Page.set_contents()– 将页面的/Contents键设置为提供的xref编号。
resources
一个包含对 PDF page（必需的，可继承的，Adobe PDF References 第 81 页）和某些其他对象（Form XObjects）所需资源（如图像或字体）的引用的dictionary，此字典作为对象定义的子字典出现，在键*/Resources*下。作为可继承对象类型，所有页面或某些页面子集可能存在“父”资源。
dictionary
PDF object类型，与同名的 Python 概念有些类似：“字典对象是一个关联表，包含对象对，称为字典的条目。每个条目的第一个元素是键，第二个元素是值。键必须是名称（…）。值可以是任何类型的对象，包括另一个字典。其值为 null（…）的字典条目相当于不存在的条目。”（Adobe PDF References 第 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（其值为*<>*，即另一个字典）等键的字典。
page
PDF 页面是一个dictionary对象，用于定义 PDF 中的一个页面，请参见 Adobe PDF References 第 71 页。
pagetree
文档的页面通过称为页面树的结构访问，该结构定义了文档中页面的顺序。树结构允许 PDF 消费应用程序仅使用有限内存快速打开包含数千页的文档。树包含两种类型的节点：中间节点称为页面树节点，叶节点称为页面对象。（Adobe PDF References 第 75 页）。
尽管可以在一个数组中列出所有页面引用，但是具有许多页面的 PDF 通常使用“平衡树”结构（“页面树”）创建，以便更快地访问任何单个页面。相对于页面总数，这可以将平均页面访问时间从线性降低到对数级别。
为了快速访问页面，MuPDF 可以使用内存中的自己的数组 – 与文档文件中可能有或没有的内容无关。该数组通过页面号索引，因此比甚至通过完全平衡的页面树访问还要快得多。
object
与 Python 类似，PDF 支持 对象（object）的概念，它可以分为八种基本类型：布尔值（“true”或“false”）、整数和实数、字符串（始终用括号括起来 – 要么“()”，要么“<>”表示十六进制）、名称（必须始终以“/”开头，例如 /Contents）、数组（用方括号“[]”括起来）、字典（用双尖括号“<<>>”括起来）、流（由关键字“stream” / “endstream”括起来）、以及空对象（“null”）（Adobe PDF References p. 13）。对象可以通过分配标签来进行标识。然后称为间接对象。PyMuPDF 支持通过它们的交叉引用号检索间接对象的定义，通过 Document.xref_object()。
stream
一个 PDF 的字典 对象类型，其后跟着一系列字节，类似于 Python 的 bytes。“然而，PDF 应用程序可以逐步读取流，而字符串必须一次性读取。此外，流可以是无限长度的，而字符串则受实现限制。因此，具有大量数据的对象（例如图像和页面描述）被表示为流。” “一个流由一个字典后跟关键字 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属性（对于非 PDF 文件为零），可以通过 Document.xref_length() - 1 来找出 PDF 中对象的总数。
fontsize
当提及字体大小时，这个度量单位是以点（points）为单位，其中 1 英寸 = 72 点。
resolution
图像和像素图对象可能包含分辨率信息，以每个方向（水平和垂直）的“每英寸点数”，dpi 为单位提供。 当 MuPDF 从文件或 PDF 对象中读取图像时，它将解析此信息并将其分别放入Pixmap.xres、Pixmap.yres中。 如果在输入中找不到有意义的信息（如非正值或值超过 4800），则将使用“合理”的默认值。 通常的默认值是 96，但在某些情况下也可能是 72（例如对于 JPX 图像）。
OCPD
可选内容属性字典 - PDF catalog的子dictionary。 存储可选内容信息的中心位置，由键/OCProperties标识。 此字典具有两个必填项和一个可选项：（1）/OCGs，必填，列出所有可选内容组的数组，（2）/D，必填，默认可选内容配置字典（OCCD），（3）/Configs，可选，备用 OCCD 的数组。
OCCD
可选内容配置字典 - PDF catalog的子dictionary。 它存储了 OCG 的 ON / OFF 状态的设置以及它们如何呈现给 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”，等等。
你对这个页面有什么反馈吗？
此软件按原样提供，不提供任何明示或暗示的保证。此软件根据许可证分发，未经许可不得复制、修改或分发。请参考 artifex.com 上的许可信息，或联系美国旧金山 94129 号 Mesa 街 39 号 108A 套房的 Artifex Software Inc. 获取更多信息。
此文档涵盖所有版本，直至 1.24.4。
PyMuPDF 1.24.4 中文文档（十二）（2）https://developer.aliyun.com/article/1559502
