PyMuPDF-1-24-4-中文文档-九-

PyMuPDF 1.24.4 中文文档（九）

原文：https://pymupdf.readthedocs.io/en/latest/

像素图

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

像素图（“像素映射”）是 MuPDF 渲染能力的核心对象。它们代表平面矩形像素集。每个像素由几个字节（“组件”）描述其颜色，另外还有一个可选的透明度字节描述其透明度。

在 PyMuPDF 中，存在几种创建像素图的方法。除了第一种外，所有其他方法都作为重载的构造函数提供。可以创建像素图…

来自文档页面（方法Page.get_pixmap()）
空的，基于 Colorspace 和 IRect 的信息
来自文件
来自内存中的图像
来自纯像素的内存区域
来自 PDF 文档中的图像
作为另一个像素图的副本

注意

支持多种图像格式作为上述第 3 和第 4 点的输入。请参阅“支持的输入图像格式”部分（#imagefiles）。

请查看 FAQ 部分，了解一些像素图的使用情况。

方法 / 属性	简短描述
`Pixmap.clear_with()`	清除像素图的部分内容
`Pixmap.color_count()`	确定使用的颜色数量
`Pixmap.color_topusage()`	确定最常用颜色的份额
`Pixmap.copy()`	复制另一个像素图的部分内容
`Pixmap.gamma_with()`	对像素应用伽马因子
`Pixmap.invert_irect()`	反转给定区域的像素
`Pixmap.pdfocr_save()`	将像素图保存为 OCRed 的单页 PDF
`Pixmap.pdfocr_tobytes()`	将像素图保存为 OCRed 的单页 PDF
`Pixmap.pil_save()`	使用 pillow 保存为图像
`Pixmap.pil_tobytes()`	使用 pillow 将其写入`bytes`对象
`Pixmap.pixel()`	返回像素值
`Pixmap.save()`	以多种格式保存像素图
`Pixmap.set_alpha()`	设置透明度值
`Pixmap.set_dpi()`	设置图像分辨率
`Pixmap.set_origin()`	设置像素图的 x、y 值
`Pixmap.set_pixel()`	设置像素的颜色和透明度
`Pixmap.set_rect()`	设置矩形内所有像素的颜色和透明度
`Pixmap.shrink()`	缩小大小并保持比例
`Pixmap.tint_with()`	对图像进行着色。
`Pixmap.tobytes()`	以多种格式返回内存区域。
`Pixmap.warp()`	返回从四边形内部生成的图像。
`Pixmap.alpha`	透明度指示器。
`Pixmap.colorspace`	图像的颜色空间，参见颜色空间。
`Pixmap.digest`	图像的 MD5 哈希码。
`Pixmap.height`	图像高度。
`Pixmap.interpolate`	插值方法指示器。
`Pixmap.is_monochrome`	检查是否仅包含黑白颜色。
`Pixmap.is_unicolor`	检查是否仅出现一种颜色。
`Pixmap.irect`	图像矩形 (`IRect`)。
`Pixmap.n`	每像素字节。
`Pixmap.samples_mv`	像素区域的 `memoryview`。
`Pixmap.samples_ptr`	指向像素区域的 Python 指针。
`Pixmap.samples`	像素区域的 `bytes` 副本。
`Pixmap.size`	图像的总长度。
`Pixmap.stride`	一行图像的大小。
`Pixmap.width`	图像宽度。
`Pixmap.x`	左上角的 X 坐标。
`Pixmap.xres`	X 方向的分辨率。
`Pixmap.y`	左上角的 Y 坐标。
`Pixmap.yres`	Y 方向的分辨率。

类 API

class Pixmap

__init__(self, colorspace, irect, alpha)

新的空白图像： 创建一个大小和原点由矩形指定的空白图像。因此，irect.top_left 指定了图像的左上角，其宽度和高度分别为 irect.width 和 irect.height。请注意，图像区域未初始化，可能包含垃圾数据 – 使用例如 clear_with() 或 set_rect() 确保。

参数：

颜色空间 (颜色空间) – 颜色空间。
irect（类似 irect 的 irect） – 图像的位置和尺寸。
alpha（布尔值） – 指定是否包括透明度字节。默认为 False。

__init__(self, colorspace, source)

复制并设置颜色空间： 复制源图像并转换颜色空间。可以使用任何颜色空间组合，但源颜色空间不能为 None。

参数：

colorspace (Colorspace) – 所需的目标颜色空间。这也可能是 None。在这种情况下，将创建一个“蒙版”像素图：其Pixmap.samples将仅包含源的 alpha 字节。
source (Pixmap) – 源像素图。

__init__(self, source, mask)

v1.18.18 新功能

复制并添加图像掩码： 复制source像素图，添加一个带有来自掩码像素图的透明度数据的 alpha 通道。

参数：

source (Pixmap) – 不带 alpha 通道的像素图。
mask (Pixmap) – 掩码像素图。必须是灰度像素图。

__init__(self, source, width, height[, clip])

复制并缩放： 复制source像素图，缩放到新的宽度和高度值 – 图像将相应地拉伸或缩小。支持部分复制。源颜色空间可以是None。

参数：

source (Pixmap) – 源像素图。
width (float) – 目标宽度。
height (float) – 所需的目标高度。
clip (irect_like) – 将生成的像素图限制为缩放像素图的这个区域。

注意

如果宽度或高度不是整数（即value.is_integer() != True），那么生成的像素图将具有 alpha 通道。

__init__(self, source, alpha=1)

复制并添加或删除 alpha： 复制source并添加或删除其 alpha 通道。如果alpha等于source.alpha，则是相同的副本。如果添加了 alpha 通道，则其值将设置为 255。

参数：

source (Pixmap) – 源像素图。
alpha (bool) – 目标是否带有 alpha 通道，默认且如果源颜色空间为None则为必须项。

注意

典型用法包括将颜色和透明度字节分离到单独的像素图中。某些应用程序需要此功能，例如wxPython的wx.Bitmap.FromBufferAndAlpha()：

>>> # 'pix' is an RGBA pixmap
>>> pixcolors = pymupdf.Pixmap(pix, 0)    # extract the RGB part (drop alpha)
>>> pixalpha = pymupdf.Pixmap(None, pix)  # extract the alpha part
>>> bm = wx.Bitmap.FromBufferAndAlpha(pix.width, pix.height, pixcolors.samples, pixalpha.samples)

__init__(self, filename)

从文件中创建： 从filename创建一个像素图。所有属性均从输入中推断。生成像素图的原点为(0, 0)。

参数：

filename (str) – 图像文件的路径。

__init__(self, stream)

从内存中创建： 从内存区域创建一个像素图。所有属性均从输入中推断。生成像素图的原点为(0, 0)。

参数：

stream (bytes,bytearray,BytesIO) –

包含完整有效图像的数据。例如可以通过stream = bytearray(open('image.file', 'rb').read())创建。仅支持Python 3 中的bytes类型，因为在 Python 2 中bytes == str，该方法将把流解释为文件名。

在版本 1.14.13 中更改： 现在也支持io.BytesIO。

__init__(self, colorspace, width, height, samples, alpha)

从纯像素创建： 从samples创建一个像素图。每个像素必须由colorspace和alpha参数控制的字节数表示。生成像素图的原点为(0, 0)。当某些其他程序提供原始图像数据时，此方法非常有用 - 请参见 FAQ。

参数：

colorspace (Colorspace) – 图像的颜色空间。
width (int) – 图像宽度
height (int) – 图像高度
samples (bytes,bytearray,BytesIO) –

包含图像所有像素的区域。如果指定，必须包括 alpha 值。

从版本 1.14.13 开始更改：（1）现在也可以使用io.BytesIO。（2）数据现在已被复制到像素图中，因此可以安全删除或变得不可用。
alpha（bool）– 是否包含透明通道。

注意

下列方程式 必须为真：(colorspace.n + alpha) * width * height == len(samples)。
从版本 1.14.13 开始，样本数据被复制到像素图中。

__init__(self, doc, xref)

从 PDF 图像中： 从以其xref标识的 PDF 文档doc中提取的图像创建一个像素图。所有像素图属性都由图像设置。请查看extract-img1.py和extract-img2.py，了解如何使用这些工具来恢复 PDF 的所有图像。

参数：

doc（Document）– 打开的PDF文档。
xref（int）– 图像对象的xref。例如，您可以使用Document.get_page_images()列出特定页面上使用的所有图像，并显示每个图像的xref编号。

clear_with([value[, irect]])

初始化样本区域。

参数：

value（int）– 如果指定，值从 0 到 255 有效。每个像素的每个颜色字节将设置为此值，如果存在 alpha 通道，则 alpha 将设置为 255（不透明）。如果省略，则所有字节（包括任何 alpha 通道）都将清除为0x00。
irect（irect_like）– 要清除的区域。如果还指定了value，则可以省略以清除整个像素图。如果颜色空间为CS_GRAY，则将采用平均值(red + green + blue)/3。像素图将在原地更改。

tint_with(black, white)

通过用sRGB 整数值替换黑色和/或白色来着色像素图。仅支持颜色空间CS_GRAY和CS_RGB，其他颜色空间将被忽略并显示警告。

如果颜色空间是CS_GRAY，则将采用平均值(red + green + blue)/3。像素图将在原地更改。

参数：

黑色（int）– 用此值替换黑色。指定 0x000000 不会做任何更改。
白色（int）– 用此值替换白色。指定 0xFFFFFF 不会做任何更改。

示例：

tint_with(0x000000, 0xFFFFFF) 不起作用。

tint_with(0x00FF00, 0xFFFFFF) 将黑色改为绿色，保留白色不变。

tint_with(0xFF0000, 0x0000FF) 将黑色改为红色，白色改为蓝色。

gamma_with(gamma)

将伽马因子应用于像素图，即使图像变亮或变暗。颜色空间为None的像素图将被忽略并显示警告。

参数：

gamma（float）– gamma = 1.0 不起作用，gamma < 1.0 变亮，gamma > 1.0 变暗。

shrink(n)

将像素图的宽度和高度都除以 2:sup:n来缩小像素图。

参数：

n (整数) – 确定新像素图（样本）的大小。例如，值为 2 将宽度和高度除以 4，因此结果是原始大小的 1/16。小于 1 的值会被忽略并显示警告。

注意

使用这些方法可以保持比例减小像素图的大小。像素图会被“就地”修改。如果想要保留原始图像并且有更多细粒度的选择，可以使用上面的相应复制构造函数。

pixel(x, y)

自版本 1.14.5 新增: 返回位于位置 (x, y)（列，行）的像素的值。

参数：

x (整数) – 像素的列数。必须在range(pix.width)内。
y (整数) – 像素的行数，必须在range(pix.height)内。

返回类型:

列表

返回值：

一个颜色值列表，可能还包括 alpha 值。其长度和内容取决于像素图的颜色空间和 alpha 的存在。对于 RGBA 像素图，结果可能是 [r, g, b, a]。所有项都是range(256)内的整数。

set_pixel(x, y, color)

自版本 1.14.7 新增: 操纵位于位置 (x, y)（列，行）的像素。

参数：

x (整数) – 像素的列数。必须在range(pix.width)内。
y (整数) – 像素的行数。必须在range(pix.height)内。
color (序列) – 作为整数序列给出的期望像素值，范围在range(256)内。序列的长度必须等于 Pixmap.n，其中包括任何 alpha 字节。

set_rect(irect, color)

自版本 1.14.8 新增: 将矩形的像素设置为一个值。

参数：

irect (irect_like) – 要用值填充的矩形。实际区域是该参数与 Pixmap.irect 的交集。对于空交集（或无效参数），不会发生任何更改。
color (序列) – 期望的值，作为range(256)内的整数序列给出。序列的长度必须等于 Pixmap.n，其中包括任何 alpha 字节。

返回类型:

布尔值

返回值：

如果矩形无效或与 Pixmap.irect 的交集为空，则为 False，否则为 True。

注意

这种方法相当于对矩形中的每个像素执行 Pixmap.set_pixel()，但是如果涉及到许多像素，这显然速度更快。
可以使用此方法类似于 Pixmap.clear_with() 来初始化具有特定颜色的像素图，例如: pix.set_rect(pix.irect, (255, 255, 0))（RGB 示例，将整个像素图着色为黄色）。

set_origin(x, y)

新增于 v1.17.7

设置像素图左上角点的 x 和 y 值。

参数：

x (整数) – x 坐标
y (整数) – y 坐标

set_dpi(xres, yres)

新增于 v1.16.17
v1.18.0 中更改: 将这些值保存为 PNG 图像时，现在会存储这些值。

设置 x 和 y 方向的分辨率（dpi）。

参数：

xres (整数) – x 方向的分辨率。
yres (整数) – y 方向的分辨率。

set_alpha(alphavalues, premultiply=1, opaque=None)

v 1.18.13 中更改

更改 alpha 值。像素图必须具有 alpha 通道。

参数：

alphavalues (bytes,bytearray,BytesIO) – 新的 alpha 值。如果提供，其长度必须至少为 width * height。如果省略 (None)，则所有 alpha 值都设置为 255（不透明）。从版本 1.14.13 开始更改: 现在还接受 io.BytesIO。
premultiply (bool) – v1.18.13 新增: 是否使用 alpha 值预乘颜色分量。
opaque (list,tuple) – 忽略 alpha 值，并将此颜色设置为完全透明。长度为 Pixmap.n 的 range(256) 整数序列。默认为 None。例如，RGB 的典型选择可能是 opaque=(255, 255, 255)（白色）。

invert_irect([irect])

反转 IRect irect 区域中所有像素的颜色。如果颜色空间为 None，则不会产生任何效果。

参数：

irect (irect_like) – 要反转的区域。省略以反转所有内容。

copy(source, irect)

复制源像素图的 irect 部分到此像素图的相应区域。这两个像素图可能具有不同的尺寸，并且每个都可以具有 CS_GRAY 或 CS_RGB 颜色空间，但它们当前必须具有相同的 alpha 属性 [2]。复制机制会自动调整源和目标之间的差异，方法如下：

如果从 CS_GRAY 复制到 CS_RGB，源灰阶值将放入每个 RGB 组件字节中。如果反过来，则目标的灰阶值将取为 (r + g + b) / 3。

首先计算 irect 和目标像素图矩形的“交集”。这考虑了矩形坐标以及当前属性值 Pixmap.x 和 Pixmap.y（您可以通过 Pixmap.set_origin() 自由修改以达到此目的）。然后复制此交集的相应数据。如果交集为空，则什么也不会发生。

参数：

source (Pixmap) – 源像素图。
irect (irect_like) – 要复制的区域。

注意

示例：假设您有两个像素图 pix1 和 pix2，您想将 pix2 的右下角四分之一复制到 pix1，使其从 pix1 的左上角点开始。请使用以下代码片段：

>>> # safeguard: set top-left of pix1 and pix2 to (0, 0)
>>> pix1.set_origin(0, 0)
>>> pix2.set_origin(0, 0)
>>> # compute top-left coordinates of pix2 region to copy
>>> x1 = int(pix2.width / 2)
>>> y1 = int(pix2.height / 2)
>>> # shift top-left of pix2 such, that the to-be-copied
>>> # area starts at (0, 0):
>>> pix2.set_origin(-x1, -y1)
>>> # now copy ...
>>> pix1.copy(pix2, (0, 0, x1, y1))

_images/img-pixmapcopy.jpg

save(filename, output=None, jpg_quality=95)

v1.22.0 中更改：直接支持 JPEG 图像。可以通过参数 “jpg_quality” 控制图像质量。

将像素图保存为图像文件。根据选择的输出，仅支持一些或所有颜色空间，并且可以选择不同的文件扩展名。请参见下表。

参数：

filename (str,Path,file) – 要保存到的文件。可以提供为字符串，作为 pathlib.Path 或作为 Python 文件对象。在后两种情况下，文件名取自相应的对象。文件名的扩展名确定图像格式，可以通过输出参数覆盖。
output (str) – 所需的图像格式。默认为文件名的扩展名。如果此值和文件扩展名都不受支持，则会引发异常。可能的值请参阅支持的输出图像格式。
jpg_quality (int) – 所需的图像质量，默认为 95。仅适用于 JPEG 图像，否则忽略。此参数在质量和文件大小之间进行权衡。值为 98 接近无损。更高的值不应导致更好的质量。

引发：

ValueError – 不支持的图像格式。

tobytes(output='png', jpg_quality=95)

从版本 1.14.5 新增：将像素图作为指定格式的 bytes 内存对象返回 – 类似于 save()。
自 v1.22.0 版本更改：添加 直接的 JPEG 支持。可以通过新参数“jpg_quality”影响图像质量。

参数：

output (str) – 所需的图像格式。默认为“png”。可能的值请参阅支持的输出图像格式。
jpg_quality (int) – 所需的图像质量，默认为 95。仅适用于 JPEG 图像，否则忽略。此参数在质量和文件大小之间进行权衡。值为 98 接近无损。更高的值不应导致更好的质量。
output – 请求的图像格式。默认为“png”。其他可能的值请参阅支持的输出图像格式。

引发：

ValueError – 不支持的图像格式。

返回类型：

字节

pdfocr_save(filename, compress=True, language='eng', tessdata=None)

自 v1.19.0 新增
自 v1.22.5 版本更改：支持 Tesseract 的 tessdata 的新参数。

使用 Tesseract 执行文本识别，并将图像保存为带有 OCR 文本层的 1 页 PDF。

参数：

filename (str,fp) – 要保存的文件标识。可以是字符串，也可以是以“wb”打开的文件指针（包括 io.BytesIO() 对象）。
compress (bool) – 是否压缩生成的 PDF，默认为 True。
language (str) – 图像中出现的语言。必须以 Tesseract 格式指定。默认为“eng”表示英语。对于多种语言，请使用以“+”分隔的 Tesseract 语言代码，如“eng+spa”表示英语和西班牙语。
tessdata (str) – Tesseract 语言支持的文件夹名称。如果省略，则必须存在此信息作为环境变量 TESSDATA_PREFIX。

注意

如果未安装 Tesseract 或者环境变量“TESSDATA_PREFIX”未设置为 tessdata 文件夹名称且未作为参数提供，则会失败。

pdfocr_tobytes(compress=True, language='eng', tessdata=None)

自 v1.19.0 新增
自 v1.22.5 版本更改：支持 Tesseract 的 tessdata 的新参数。

使用 Tesseract 执行文本识别，并将图像转换为带有 OCR 文本层的单页 PDF。内部调用 Pixmap.pdfocr_save()。

内存中的单页 PDF 文件。可以像这样打开 doc=pymupdf.open("pdf", pix.pdfocr_tobytes())，并可以在其上执行文本提取 page=doc[0]。

注意

另一个可能的用途是插入到某些 PDF 中。以下代码片段读取文件夹中的图像，并将其存储为包含 OCR 文本层的新 PDF 的页面：

doc = pymupdf.open()
for imgfile in os.listdir(folder):
   pix = pymupdf.Pixmap(imgfile)
   imgpdf = pymupdf.open("pdf", pix.pdfocr_tobytes())
   doc.insert_pdf(imgpdf)
   pix = None
   imgpdf.close()
doc.save("ocr-images.pdf")

pil_save(*args, unmultiply=False, **kwargs)

新功能在 v1.17.3 中引入。

使用 Pillow 将像素图写入图像文件。用此方法输出 MuPDF 不支持的内容。示例包括：

格式 JPX、J2K、WebP 等。
存储 EXIF 信息。
如果未提供 dpi 信息，则将自动使用像素图存储的 xres、yres 值。

简单示例：pix.pil_save("some.webp", optimize=True, dpi=(150, 150))。

参数：

unmultiply (bool) – 如果像素图的颜色空间为 RGB 且带有透明度，则 alpha 值可能已经或未经过乘入颜色分量 ref/green/blue（称为“预乘 alpha”）。若要强制取消预乘，将此参数设置为 True。有关背景信息，请参阅例如此处的“预乘 alpha” 页面。

有关其他参数的详细信息，请参阅 Pillow 文档。

自 v1.22.0 起，PyMuPDF 直接支持 JPEG 输出。基于性能原因和避免不必要的外部依赖，我们建议不再使用此方法进行 JPEG 输出。

抛出异常：

ImportError – 如果未安装 Pillow。

pil_tobytes(*args, unmultiply=False, **kwargs)

新功能在 v1.17.3 中引入。

使用 Pillow 返回指定格式的图像作为字节对象。例如 stream = pix.pil_tobytes(format="WEBP", optimize=True, dpi=(150, 150))。同样请参阅上文。有关其他参数的详细信息，请参阅 Pillow 文档。

抛出异常：

ImportError – 如果未安装 Pillow。

返回类型：

字节

warp(quad, width, height)

新功能在 v1.19.3 中引入。

返回通过“扭曲”四边形以使四边形角点成为新像素图角点的新像素图。目标像素图的 IRect 将是 (0, 0, width, height)。

参数：

quad (quad_like) – 一个凸四边形，其坐标位于 Pixmap.irect 内（包括边界点）。
width (int) – 期望的结果宽度。
height (int) – 期望的结果高度。

新的像素图，在四边形角点以顺时针方向映射到像素图的角点：quad.ul -> irect.tl，quad.ur -> irect.tr，等等。

返回类型：

Pixmap

_images/img-warp.png

color_count(colors=False, clip=None)

新功能在 v1.19.2 中引入。
在 v1.19.3 中更改。

确定像素图的唯一颜色及其计数。

参数：

colors (bool) – (在 v1.19.3 中更改) 如果为 True，返回颜色像素及其使用计数的字典，否则仅返回唯一颜色的数量。
clip（rect_like） – Pixmap.irect 内的一个矩形。如果提供，则仅考虑这些像素。这允许直接检查给定像素图的子矩形，而无需构建子像素图。

返回类型：

字典或整型

要么颜色数量，要么带有 pixel: count 项目的字典。像素键是长度为 Pixmap.n 的 bytes 对象。

注意

要恢复像素的元组，使用 tuple(colors.keys()[i]) 获取第 i 项。

响应时间取决于像素图的样本大小，对于非常大的像素图可能超过一秒钟。
在适用的情况下，具有不同 alpha 值的像素将被视为不同颜色。

color_topusage(clip=None)

新功能，版本号为 v1.19.3

返回最常用的颜色及其相对频率。

参数：

clip（rect_like） – Pixmap.irect 内的一个矩形。如果提供，则仅考虑这些像素。这允许直接检查给定像素图的子矩形，而无需构建子像素图。

返回类型：

元组

一个元组 (ratio, pixel)，其中 0 < ratio <= 1，pixel 是颜色的像素值。使用这个来判断图像是否“几乎”单色：响应 (0.95, b"x00x00x00") 表示所有像素中有 95% 是黑色。查看示例如何使用像素图：检查文本可见性。

alpha

指示像素图是否包含透明信息。

类型：

布尔型

digest

像素图的 MD5 哈希码（16 字节）。这是用于唯一标识的技术值。

类型：

字节

colorspace

像素图的颜色空间。如果图像被视为所谓的“图像掩码”或“模板掩码”（目前仅适用于提取的 PDF 文档图像），此值可能为 None。

类型：

颜色空间

stride

包含 Pixmap.samples 中图像数据的一行长度。这主要用于计算目的。以下表达式是真实的：

len(samples) == height * stride
width * n == stride

类型：

整型

is_monochrome

新功能，版本号为 v1.19.2

如果灰度像素图只有黑色和白色，则为 True。

类型：

布尔型

is_unicolor

新功能，版本号为 v1.19.2

如果所有像素相同（任何颜色空间），则为 True。在适用的情况下，具有不同 alpha 值的像素将被视为不同颜色。

类型：

布尔型

irect

包含像素图的 IRect。

类型：

IRect

samples

所有像素的颜色（如果Pixmap.alpha为 true，则还包括透明度值）。这是一个大小为 width * height * n 字节的区域。每 n 字节定义一个像素。每个后续的 n 字节按扫描线顺序给出另一个像素。后续扫描线相继排列，没有填充。例如，对于 RGBA 颜色空间，这意味着 samples 是一个像 …, R, G, B, A, … 的字节序列，四个字节值 R, G, B, A 定义一个像素。

此区域可以传递给其他图形库（如 PIL - Python Imaging Library）进行额外处理，例如将像素图保存为其他图像格式。

注意

底层数据通常是一个大的内存区域，每次访问时会为此属性创建一个 bytes 复制 … 例如，一个 RGB 渲染的字母页具有接近 1.4 MB 的样本大小。因此，请考虑为其分配一个新变量或使用 memoryview 版本 Pixmap.samples_mv（自 v1.18.17 新增）。
仅在重新访问此属性后才能获得底层数据的任何更改。这与使用 memoryview 版本不同。

类型：

bytes

samples_mv

自 v1.18.17 新增

类似于 Pixmap.samples，但以 Python memoryview 格式呈现。它是指向像素图中内存的指针，而不是从中复制出来的。因此，其创建速度与像素图大小无关，对像素的任何更改都将立即生效。

bytearray(pix.samples_mv) 或 bytes(pixmap.samples_mv) 的复制与 pix.samples 等效，并可用于替代其位置。

我们还有 len(pix.samples) == len(pix.samples_mv)。

看看这个来自 2 MB JPEG 的例子：memoryview 快一万倍：

In [3]: %timeit len(pix.samples_mv)
367 ns ± 1.75 ns per loop (mean ± std. dev. of 7 runs, 1000000 loops each)
In [4]: %timeit len(pix.samples)
3.52 ms ± 57.5 µs per loop (mean ± std. dev. of 7 runs, 100 loops each)

类型：

memoryview

samples_ptr

自 v1.18.17 新增

Python 指向像素区域的指针。这是一种特殊的整数格式，支持应用程序（如 PyQt）可以直接访问样本区域，从而极大地加速图像构建过程。例如：

img = QtGui.QImage(pix.samples, pix.width, pix.height, format) # (1)
img = QtGui.QImage(pix.samples_ptr, pix.width, pix.height, format) # (2)

上述两者都导致相同的 Qt 图像，但 (2) 可能快几百倍，因为它避免了像素区域的额外复制。

类型：

int

size

包含 len(pixmap)。通常会等于 len(pix.samples) 加上某些平台特定的值，用于定义对象的其他属性。

类型：

int

width

区域的宽度，以像素为单位。

类型：

int

height

区域的高度，以像素为单位。

类型：

int

左上角 X 坐标，以像素为单位。不能直接更改 —— 使用 Pixmap.set_origin()。

类型：

int

左上角 Y 坐标，以像素为单位。不能直接更改 —— 使用 Pixmap.set_origin()。

类型：

int

每像素组件数。此数字取决于颜色空间和 alpha 值。如果颜色空间不是 None（模板掩码），那么 Pixmap.n - Pixmap.alpha == pixmap.colorspace.n 为真。如果颜色空间为 None，则 n == alpha == 1。

类型：

int

xres

水平分辨率，单位为 dpi（每英寸点数）。请参阅 resolution。不能直接更改 —— 使用 Pixmap.set_dpi()。

类型：

int

yres

垂直分辨率，单位为 dpi（每英寸点数）。请参阅 resolution。不能直接更改 —— 使用 Pixmap.set_dpi()。

类型：

int

interpolate

一个仅用于信息的布尔标志，如果使用“线性插值”绘制图像，则设置为 True。如果使用“最近邻采样”，则设置为 False。

类型：

布尔值

支持的输入图像格式

以下文件类型支持作为输入构建像素图：BMP, JPEG, GIF, TIFF, JXR, JPX, PNG, PAM 和所有 Portable Anymap 家族的文件 (PBM, PGM, PNM, PPM)。这种支持是双重的：

使用 Pixmap(filename) 或 Pixmap(byterray) 直接创建一个像素图。然后，该像素图的属性将由图像确定。
使用 pymupdf.open(…) 打开此类文件。结果将显示为包含单个页面的文档。创建此页面的像素图可在此上下文中提供所有可用的选项：应用矩阵、选择颜色空间和 alpha、将像素图限制在剪辑区域内等。

SVG 图像 仅通过上述方法 2 支持，而不是直接作为像素图。但请记住：这个结果是一个 光栅图像，这在像素图中总是如此 [1]。 ## 支持的输出图像格式

支持多种图像输出格式。您可以选择将图像直接写入文件（Pixmap.save()），或生成一个字节对象（Pixmap.tobytes()）。这两种方法都接受一个字符串，用于标识所需的格式（下面的格式列）。请注意，并非所有像素图颜色空间、透明度支持（alpha）和图像格式的组合都可能。

格式	颜色空间	alpha	扩展名	描述
jpg, jpeg	灰度, RGB, CMYK	否	.jpg, .jpeg	Joint Photographic Experts Group
pam	灰度, RGB, CMYK	是	.pam	Portable Arbitrary Map
pbm	灰度, RGB	否	.pbm	Portable Bitmap
pgm	灰度, RGB	否	.pgm	Portable Graymap
png	灰度, RGB	是	.png	Portable Network Graphics
pnm	灰度, RGB	否	.pnm	Portable Anymap
ppm	灰度, RGB	否	.ppm	Portable Pixmap
ps	灰度, RGB, CMYK	否	.ps	Adobe PostScript 图像
psd	灰度, RGB, CMYK	是	.psd	Adobe Photoshop 文档

注意

并非所有图像文件类型都在所有操作系统平台上都受支持（或至少常见）。例如，PAM 和 Portable Anymap 格式在 Windows 上可能很少甚至未知。
特别是在 CMYK 颜色空间方面，您始终可以使用 rgb_pix = pymupdf.Pixmap(pymupdf.csRGB, cmyk_pix) 将 CMYK 像素图转换为 RGB 像素图，然后以所需格式保存。
可见，MuPDF 的图像支持范围在输入和输出方面是不同的。在双向支持的图像中，PNG 和 JPEG 可能是最流行的。
我们还建议将 “ppm” 格式作为 tkinter 的 PhotoImage 方法的输入，如 tkimg = tkinter.PhotoImage(data=pix.tobytes(“ppm”))（也请参阅教程）。这是非常快速的（比 PNG 快 60 倍）。

脚注

您对本页面有任何反馈吗？

此软件按“原样”提供，不附带任何明示或暗示的担保。此软件在许可下分发，除非在该许可条款明确授权下，否则不得复制、修改或分发。请参阅artifex.com上的许可信息或联系美国加利福尼亚州旧金山 Mesa Street 39 号 108A 室 Artifex Software Inc. 获取更多信息。

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

Discord logo ## 支持的输入图像格式

以下文件类型支持作为输入以构建像素图：BMP, JPEG, GIF, TIFF, JXR, JPX, PNG, PAM 和所有便携式任意映射系列（PBM, PGM, PNM, PPM）。此支持具有双重性：

直接使用Pixmap(filename)或Pixmap(byterray)创建像素图。然后，像素图将具有由图像确定的属性。
用 pymupdf.open(...) 打开此类文件。结果将显示为包含单个页面的文档。在此上下文中创建此页面的像素图提供了所有可用的选项：应用矩阵、选择颜色空间和透明度、将像素图限制为剪辑区域等。

SVG 图像只能通过上述第二种方法支持，而不能直接作为像素图。但请记住：这样做的结果是一幅光栅图像，这在像素图中总是如此 [1]。

支持的输出图像格式

支持多种图像输出格式。您可以选择直接将图像写入文件（Pixmap.save()），或生成一个字节对象（Pixmap.tobytes()）。这两种方法均接受一个字符串，用于标识所需格式（下面的格式列）。请注意，并非所有像素图颜色空间、透明度支持（alpha）和图像格式的组合都可能。

格式	颜色空间	alpha	扩展名	描述
jpg, jpeg	灰度, RGB, CMYK	否	.jpg, .jpeg	联合摄影专家小组
pam	灰度, RGB, CMYK	是	.pam	便携式任意映射
pbm	灰度, RGB	否	.pbm	便携式位图
pgm	灰度, RGB	否	.pgm	便携式灰度图
png	灰度, RGB	是	.png	便携式网络图形
pnm	灰度, RGB	否	.pnm	便携式任意映射
ppm	灰度, RGB	否	.ppm	便携式像素图
ps	灰度, RGB, CMYK	否	.ps	Adobe PostScript 图像
psd	灰度, RGB, CMYK	是	.psd	Adobe Photoshop 文档

注

并非所有图像文件类型在所有操作系统平台上都受支持（或至少是常见的）。例如，PAM 和便携式任意映射格式在 Windows 上很少见，甚至是未知的。
特别是关于 CMYK 色彩空间，您始终可以使用 rgb_pix = pymupdf.Pixmap(pymupdf.csRGB, cmyk_pix) 将 CMYK 像素图转换为 RGB 像素图，然后以所需格式保存。
正如所见，MuPDF 的图像支持范围对输入和输出是不同的。在双向支持中，PNG 和 JPEG 可能是最流行的格式。
我们还建议将“ppm”格式作为输入传递给 tkinter 的PhotoImage方法，像这样：tkimg = tkinter.PhotoImage(data=pix.tobytes("ppm"))（也请参阅教程）。这种方式非常快（比 PNG 快60 倍）。

脚注

对本页面有任何反馈吗？

本软件按原样提供，不提供任何明示或暗示的担保。本软件在许可下分发，未经明确授权不得复制、修改或分发。请参阅artifex.com上的许可信息或联系美国旧金山 CA 94129 Mesa 街 39 号 108A 套房的 Artifex Software Inc.以获取更多信息。

本文档覆盖所有 1.24.4 版本。

Discord 标志

点

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

Point 表示平面上的一个点，由其 x 和 y 坐标定义。

属性 / 方法	描述
`Point.distance_to()`	计算到点或矩形的距离
`Point.norm()`	欧几里得范数
`Point.transform()`	用矩阵变换点
`Point.abs_unit`	与单位相同，但坐标为正
`Point.unit`	点坐标除以 abs(point)
`Point.x`	X 坐标
`Point.y`	Y 坐标

类 API

class Point

__init__(self)

__init__(self, x, y)

__init__(self, point)

__init__(self, sequence)

重载的构造函数。

没有参数时，将创建 Point(0, 0)。

指定另一个点后，将创建一个新副本，“sequence”是一个包含 2 个数字的 Python 序列（详见在 PyMuPDF 中使用 Python 序列作为参数）。

参数：

x（浮点数） – 点的 x 坐标
y（浮点数） – 点的 y 坐标

distance_to(x[, unit])

计算到 x 的距离，其中 x 可能是 point_like 或 rect_like。距离以像素（默认）、英寸、厘米或毫米为单位给出。

参数：

x（point_like,rect_like） – 要计算距离的对象。
单位（字符串） – 要测量的单位。其中之一为“px”、“in”、“cm”、“mm”。

返回类型：

浮点数

到 x 的距离。如果这是 rect_like，则距离

是连接到矩形边之一的最短线段的长度
被计算为其有限版本
如果包含该点则为零

norm()

1.16.0 版本中新增

返回点的欧几里得范数（长度）作为向量。等同于函数 abs() 的结果。

transform(m)

将矩阵应用于点并用结果替换它。

参数：

m（类似矩阵） – 要应用的矩阵。

返回类型：

点

unit

将每个坐标除以 norm(point) 的结果，点到(0,0)的距离。这是一个长度为 1 的指向与点相同方向的向量。它的 x 和 y 值等于该向量与 x 轴的夹角的余弦和正弦值。

_images/img-point-unit.jpg

类型：

点

abs_unit

与上述 unit 相同，但用其绝对值替换坐标。

类型：

点

x 坐标

类型：

浮点数

y 坐标

类型：

浮点数

注意

此类遵循 Python 序列协议，因此也可以通过索引访问组件。还请参阅在 PyMuPDF 中使用 Python 序列作为参数。
矩形可以使用算术运算符 – 见章节几何对象的运算代数。

对这个页面有任何反馈吗？

本软件按原样提供，不提供任何明示或暗示的保证。本软件根据许可证分发，未经许可不得复制、修改或分发。请参阅artifex.com上的许可信息或联系美国旧金山 94129 号 39 Mesa Street, Suite 108A 的 Artifex Software Inc.获取更多信息。

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

Discord logo

四边形

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

表示平面中的四边形数学形状（也称为“四边形”或“四边形”），定义为四个 Point 对象 ul, ur, ll, lr 的序列（便于称为左上、右上、左下、右下）。

四边形可以作为文本搜索方法（Page.search_for()）的结果，它们用于定义文本标记注释（例如 Page.add_squiggly_annot() 等），以及多个绘制方法（如 Page.draw_quad() / Shape.draw_quad()， Page.draw_oval() / Shape.draw_quad()）。

注意

如果矩形的角点通过旋转、缩放或平移 Matrix 进行变换，则生成的四边形是矩形（全等于矩形），即其所有角再次形成 90 度角。属性 Quad.is_rectangular 检查四边形是否可以被看作是这样一个操作的结果。
并非所有矩阵均满足此条件：例如，剪切矩阵生成平行四边形，而不可逆矩阵则生成“退化”四边形，如三角形或线段。
属性 Quad.rect 获取包围矩形。反之亦然，现在矩形具有属性 Rect.quad 和 IRect.quad 分别获得它们的四边形版本。

方法 / 属性	简要描述
`Quad.transform()`	使用矩阵进行变换
`Quad.morph()`	使用点和矩阵进行变形
`Quad.ul`	左上角点
`Quad.ur`	右上角点
`Quad.ll`	左下角点
`Quad.lr`	右下角点
`Quad.is_convex`	如果四边形是凸集则为 true
`Quad.is_empty`	如果四边形是空集则为 true
`Quad.is_rectangular`	如果四边形与矩形全等则为 true
`Quad.rect`	最小包含的 Rect
`Quad.width`	最长的宽度数值
`Quad.height`	最长的高度数值

类 API

class Quad

__init__(self)

__init__(self, ul, ur, ll, lr)

__init__(self, quad)

__init__(self, sequence)

过载的构造函数：“ul”，“ur”，“ll”，“lr”表示point_like对象（四个角点），“sequence”是包含四个point_like对象的 Python 序列。

如果指定了“quad”，则构造函数会创建其的新副本。

没有参数时，创建包含 4 个Point(0, 0)的四边形。

transform(matrix)

通过使用矩阵转换四边形的每个角来修改它。

参数：

矩阵 (matrix_like) – 矩阵。

morph(fixpoint, matrix)

（从版本 1.17.0 开始） 使用矩阵样式和点样式将四边形“变形”。

参数：

fixpoint (point_like) – 点。
矩阵 (matrix_like) – 矩阵。

创建一个新的四边形（如果这是无限四边形，则不执行操作）。

rect

包含四边形的最小矩形，由以下图片中的蓝色区域表示。

_images/img-quads.jpg

类型：

矩形

ul

左上角点。

类型：

点

ur

右上角点。

类型：

点

ll

左下角点。

类型：

点

lr

右下角点。

类型：

点

is_convex

版本 1.16.1 中的新功能

检查四边形的任意两个点，其连接线上的所有点是否也属于四边形。

类型：

布尔值

is_empty

如果封闭区域为零，则为真，这意味着四个角中至少有三个点在同一条线上。如果为假，则四边形可能仍然退化或根本不像四边形（三角形，平行四边形，梯形，...）。

类型：

布尔值

is_rectangular

如果所有角落的角度都为 90 度，则为真。这意味着四边形是凸的且非空的。

类型：

布尔值

width

顶部和底部边的最大长度。

类型：

浮点数

height

左右边的最大长度。

类型：

浮点数

备注

此类符合序列协议，因此组件也可以通过它们的索引处理。还参阅在 PyMuPDF 中使用 Python 序列作为参数。

代数和包含性检查

从 v1.19.6 开始，四边形可以像其他几何对象一样用于代数表达式 – 已取消了相应的限制。特别是现在可以进行所有以下包含检查的组合：

{Point | IRect | Rect | Quad} 在 {IRect | Rect | Quad}

请注意以下有趣的细节：

对于矩形，仅其左上角点属于矩形。自 v1.19.0 起，矩形被定义为“开放的”，因此其底部和右边缘不属于矩形 – 包括相应的角点。但对于四边形，不存在“开放性”的概念，因此我们有以下有些令人惊讶的推论：

>>> rect.br in rect
False
>>> # but:
>>> rect.br in rect.quad
True

对这页有任何反馈？

此软件按原样提供，不附带任何明示或暗示的保证。此软件受许可证约束，未经许可不得复制、修改或分发。请参阅artifex.com获取许可信息，或联系美国旧金山 94129，Mesa 街 39 号 108A 套房的 Artifex Software Inc. 了解更多信息。

此文档涵盖了截止到 1.24.4 版本的所有内容。

Discord logo

备注

此类符合序列协议，因此组件也可以通过它们的索引处理。还请参阅在 PyMuPDF 中将 Python 序列用作参数。

代数和包含检查

从 v1.19.6 开始，四边形可以像其他几何对象一样用于代数表达式——相应的限制已经解除。特别地，所有以下组合的包含检查现在都是可能的：

{点 | 矩形 | 矩形 | 四边形} 在 {矩形 | 矩形 | 四边形} 中

请注意以下有趣的细节：

对于矩形，只有它的左上角点属于它。自 v1.19.0 起，矩形被定义为“开放的”，因此其底部和右边缘不属于它——包括相应的角落。但对于四边形来说，不存在“开放性”这样的概念，因此我们有以下有些令人惊讶的推论：

>>> rect.br in rect
False
>>> # but:
>>> rect.br in rect.quad
True

你对本页面有任何反馈吗？

此文档涵盖了截止到 1.24.4 版本的所有内容。

Discord logo

矩形

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

矩形由四个浮点数 x0、y0、x1、y1 定义。它们被视为两个对角点的坐标。前两个数被视为“左上”角 P[(x0,y0)]，后两个数 P[(x1,y1)]被视为“右下”角。然而，这两个属性不一定与它们直觉上的含义相符——请继续阅读。

以下注释也适用于 IRect 对象：

在（Py-）MuPDF （和 PDF）的意义上，矩形始终具有与 x-或 y 轴平行的边界。一般的正交四边形不是矩形——与数学定义相反。
构造点可以（几乎！——见下文）位于平面的任何地方——它们甚至不需要不同，例如，“左上角”不需要是几何上的“西北角”。
单位为点，其中 72 点为 1 英寸。
对于给定的四个数，几何上“相同”的矩形可以以四种不同的方式定义：
1. 矩形 P[(x0,y0)], P[(x1,y1)]
2. 矩形 P[(x1,y1)], P[(x0,y0)]
3. 矩形 P[(x0,y1)], P[(x1,y0)]
4. 矩形 P[(x1,y0)], P[(x0,y1)]

（自 v1.19.0 更改）因此有些分类：

如果x0 <= x1且y0 <= y1（即右下角点位于左上角点的“东南”方向），则矩形被称为有效，否则为无效。在 MuPDF 的坐标系统中，y 轴是从上到下方向的。在早期版本中，无效的矩形被称为无限的。
如果x0 >= x1或y0 >= y1，则矩形被称为空。这意味着无效的矩形也总是空的。如果x0 > x1（或者y0 > y1），则width（或height）被设置为零。在早期版本中，只有当宽度或高度之一为零时，矩形才为空。
矩形坐标不能超出从FZ_MIN_INF_RECT = -2147483648到FZ_MAX_INF_RECT = 2147483520的数字范围。选择这两个值是因为它们是经过 C 浮点转换来回转换的最小/最大 32 位整数。在早期版本中，坐标值没有限制。
存在确切的一个“无限”矩形，由x0 = y0 = FZ_MIN_INF_RECT和x1 = y1 = FZ_MAX_INF_RECT定义。它包含每一个其他矩形。主要用于技术目的，例如当函数调用应忽略一个形式上要求的矩形参数时。此矩形不为空。
矩形是（半）开放的：右边和底边（包括相应的角）不被视为矩形的一部分。这意味着只有左上角(x0, y0)可能属于矩形，其余三个角不会。一个空矩形根本不包含任何角。

这里是更改的概览。

注意版本 < 1.19.0 版本 1.19.*

空 x0 = x1 或 y0 = y1 x0 >= x1 或 y0 >= y1 – 包括无效矩形

有效不适用 x0 <= x1 且 y0 <= y1

无限所有 x0 > x1 或 y1 > y0 的矩形 确切地一个无限矩形 / irect！

坐标值所有数字 FZ_MIN_INF_RECT <= number <= FZ_MAX_INF_RECT

边界和角落是矩形的一部分右下角和边缘 在外部

新增了定义无限和标准空矩形和四边形的顶级函数，请参见 INFINITE_RECT() 和相关函数。

注意	版本 < 1.19.0	版本 1.19.*
空	x0 = x1 或 y0 = y1	x0 >= x1 或 y0 >= y1 – 包括无效矩形
有效	不适用	x0 <= x1 且 y0 <= y1
无限	所有 x0 > x1 或 y1 > y0 的矩形	确切地一个无限矩形 / irect！
坐标值	所有数字	`FZ_MIN_INF_RECT <= number <= FZ_MAX_INF_RECT`
边界和角落	是矩形的一部分	右下角和边缘在外部

方法 / 属性	简短描述
`Rect.contains()`	检查点和矩形包含关系
`Rect.get_area()`	计算矩形面积
`Rect.include_point()`	扩展矩形以包含一个点
`Rect.include_rect()`	扩展矩形以包含另一个矩形
`Rect.intersect()`	与另一个矩形的公共部分
`Rect.intersects()`	检查非空交集
`Rect.morph()`	使用点和矩阵进行变换
`Rect.torect()`	将矩阵转换为另一个矩形
`Rect.norm()`	欧几里得范数
`Rect.normalize()`	使矩形有效
`Rect.round()`	创建包含矩形的最小 IRect
`Rect.transform()`	使用矩阵变换矩形
`Rect.bottom_left`	左下角点，同义词 bl
`Rect.bottom_right`	右下角点，同义词 br
`Rect.height`	矩形高度
`Rect.irect`	等同于方法 round() 的结果
`Rect.is_empty`	矩形是否为空
`Rect.is_valid`	矩形是否有效
`Rect.is_infinite`	矩形是否无限大
`Rect.top_left`	左上角点，同义词 tl
`Rect.top_right`	右上角点，同义词 tr
`Rect.quad`	由矩形角落制成的 Quad
`Rect.width`	矩形宽度
`Rect.x0`	左上角的 x 坐标
`Rect.x1`	右上角的 x 坐标
`Rect.y0`	左上角的 y 坐标
`Rect.y1`	底部的 y 坐标

类 API

class Rect

__init__(self)

__init__(self, x0, y0, x1, y1)

__init__(self, top_left, bottom_right)

__init__(self, top_left, x1, y1)

__init__(self, x0, y0, bottom_right)

__init__(self, rect)

__init__(self, sequence)

重载的构造函数：top_left，bottom_right表示point_like对象，“sequence”是一个包含 4 个数字的 Python 序列类型（见在 PyMuPDF 中使用 Python 序列作为参数），“rect”表示另一个rect_like，而其他参数表示坐标。

如果指定了“rect”，则构造函数将创建它的新副本。

没有参数时，创建空矩形Rect(0.0, 0.0, 0.0, 0.0)。

round()

创建包含 IRect 的最小矩形。这不同于简单地将矩形的边缘四舍五入：左上角向上和向左舍入，而右下角向下和向右舍入。

>>> pymupdf.Rect(0.5, -0.01, 123.88, 455.123456).round()
IRect(0, -1, 124, 456)

如果矩形是空的，则结果也是空的。
可能的悖论：即使矩形不为空，结果可能为空！在这种情况下，显然结果中不包含矩形。这是因为 MuPDF 的算法允许有一个小的容差（1e-3）。例如：

>>> r = pymupdf.Rect(100, 100, 200, 100.001)
>>> r.is_empty  # rect is NOT empty
False
>>> r.round()  # but its irect IS empty!
pymupdf.IRect(100, 100, 200, 100)
>>> r.round().is_empty
True

返回类型：

IRect

transform(m)

用矩阵变换矩形并替换原始矩形。如果矩形为空或无限，则这是一个无操作。

参数：

m（矩阵）- 转换的矩阵。

返回类型：

矩形

包含变换后原始矩形的最小矩形。

intersect(r)

计算当前矩形和r的交集（公共矩形区域，同时包含在两者中的最大矩形）并替换当前矩形。如果其中一个矩形为空，则结果也为空。如果r是无限的，则这是一个无操作。如果矩形（在数学上）是不相交的集合，则结果无效。如果结果有效但为空，则矩形在一个角落或一边的（部分）接触。

参数：

r（矩形）- 第二个矩形

include_rect(r)

计算当前矩形和r的最小包含矩形，并替换当前矩形。如果其中一个矩形是无限的，则结果也是无限的。如果其中一个为空，则另一个将被视为结果。

参数：

r（矩形）- 第二个矩形

include_point(p)

计算当前矩形和点p的最小包含矩形，并替换当前矩形。无限矩形保持不变。要创建包含一系列点的矩形，请从（空的）pymupdf.Rect(p1, p1)开始，然后逐步包含其余点。

参数：

p（点）- 要包含的点。

get_area([unit])

计算矩形的面积，并且没有参数时，等于abs(rect)。就像空矩形一样，无限矩形的面积也是零。因此，pymupdf.Rect(p1, p2) 和 pymupdf.Rect(p2, p1) 至少有一个具有零面积。

参数：

unit（str）– 指定所需单位：px（像素，默认）、in（英寸）、cm（厘米）或mm（毫米）的平方。

返回类型：

浮动

contains(x)

检查x是否包含在矩形中。它可以是IRect、Rect、Point或数字。如果x是空矩形，则始终为真。如果矩形为空，则对所有非空矩形和所有点始终为False。x in rect 和 rect.contains(x) 是等价的。

参数：

x（rect_like 或 point_like。）– 要检查的对象。

返回类型：

布尔

intersects(r)

检查矩形和rect_like “r”是否包含公共非空 Rect。如果其中一个是无限的或为空，将始终为False。

参数：

r（rect_like）– 要检查的矩形。

返回类型：

布尔

torect(rect)

新版中的版本 1.19.3

计算将此矩形转换为给定矩形的矩阵。

参数：

rect（rect_like）– 目标矩形。必须不为空或无限。

返回类型：

Matrix

一个矩阵mat，使得self * mat = rect。例如，可用于在页面坐标和像素图坐标之间进行转换。请查看此处的示例用法 How to Use Pixmaps: Checking Text Visibility。

morph(fixpoint, matrix)

新版中的版本 1.17.0

在使用固定点fixpoint应用矩阵到矩形后，返回一个新的四边形。

参数：

fixpoint（point_like）– 固定点。
matrix（matrix_like）– 矩阵。

新的 Quad。这是同名 quad 方法的包装器。如果是无限的，将返回无限 quad。

norm()

新版中的版本 1.16.0

返回作为四个数字向量处理的矩形的欧几里得范数。

normalize()

替换矩形为其有效版本。通过对矩形角进行洗牌来完成此操作。完成此方法后，右下角确实位于左上角的东南方（但可能仍为空）。

irect

等于方法round()的结果。

top_left

tl

等于 Point(x0, y0)。

类型：

Point

top_right

tr

等于 Point(x1, y0)。

类型：

Point

bottom_left

bl

等于 Point(x0, y1)。

类型：

Point

bottom_right

br

等于 Point(x1, y1)。

类型：

Point

quad

四边形 Quad(rect.tl, rect.tr, rect.bl, rect.br)。

类型：

Quad

width

矩形的宽度。等于 max(x1 - x0, 0)。

返回类型：

浮动

height

矩形的高度。等于 max(y1 - y0, 0)。

返回类型：

浮动

x0

左侧角的 X 坐标。

类型：

浮动

y0

顶部角的 Y 坐标。

类型：

浮动

x1

右侧角的 X 坐标。

类型：

浮动

y1

底部角的 Y 坐标。

类型：

浮动

is_infinite

True如果这是无限矩形。

类型：

布尔值

is_empty

True如果矩形为空。

类型：

布尔值

is_valid

True如果矩形有效。

类型：

布尔值

注意

此类符合 Python 序列协议，因此也可以通过索引访问组件。还请参阅在 PyMuPDF 中使用 Python 序列作为参数。
矩形可以与算术运算符一起使用 — 请参阅几何对象运算代数章节。

您对此页面有任何反馈吗？

本软件按原样提供，没有任何明示或暗示的保证。本软件在许可下分发，未经许可明确授权，不得复制、修改或分发。请参阅artifex.com的许可信息或联系美国旧金山 CA 94129 Mesa 街 39 号 108A 套房的 Artifex Software Inc.获取更多信息。

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

Discord logo

形状

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

此类仅适用于 PDF。

此类允许在 PDF 页面上创建互连的图形元素。其方法的含义和名称与对应的 Page 方法相同。

实际上，每个 Page 绘制方法只是一个便利的包装器，包括（1）一个形状绘制方法，（2）Shape.finish()方法，和（3）Shape.commit()方法。对于页面文本插入，只调用了Shape.commit()方法。如果为页面执行了许多绘制和文本操作，则应始终考虑使用 Shape 对象。

可以连续执行几种绘制方法，每一种方法都将为一个绘制做出贡献。完成绘制后，必须调用Shape.finish()方法来应用颜色、虚线、宽度、变形和其他属性。

此类的绘制方法（以及Shape.insert_textbox()）记录它们覆盖的区域在一个矩形内（Shape.rect）。例如，此属性可用于设置Page.cropbox_position。

粗体（Text insertions）Shape.insert_text()和Shape.insert_textbox()隐式执行“完成”，因此只需要Shape.commit()生效。因此，两者都包括控制属性如颜色等的参数。

方法/属性	描述
`Shape.commit()`	更新页面内容
`Shape.draw_bezier()`	绘制三次贝塞尔曲线
`Shape.draw_circle()`	绘制围绕点的圆
`Shape.draw_curve()`	绘制使用一个辅助点的三次贝塞尔曲线
`Shape.draw_line()`	绘制直线
`Shape.draw_oval()`	绘制椭圆
`Shape.draw_polyline()`	连接一系列点
`Shape.draw_quad()`	绘制四边形
`Shape.draw_rect()`	绘制矩形
`Shape.draw_sector()`	绘制圆形扇区或饼图
`Shape.draw_squiggle()`	绘制波浪线
`Shape.draw_zigzag()`	绘制之字形线条
`Shape.finish()`	完成一组绘图命令
`Shape.insert_text()`	插入文本行
`Shape.insert_textbox()`	将文本适配到矩形中
`Shape.doc`	存储页面文档
`Shape.draw_cont`	上次`Shape.finish()`之后的绘图命令
`Shape.height`	存储页面高度
`Shape.lastPoint`	存储当前点
`Shape.page`	存储所属页面
`Shape.rect`	包围图形的矩形
`Shape.text_cont`	累积文本插入
`Shape.totalcont`	累积字符串，存储在`contents`中
`Shape.width`	存储页面宽度

类 API

class Shape

__init__(self, page)

创建一个新的图形。在导入 PyMuPDF 时，pymupdf.Page对象被赋予构造Shape对象的便利方法new_shape()。在实例化期间，将检查我们是否有 PDF 页面。否则会引发异常。

参数：

page (页面) – PDF 文档的现有页面。

draw_line(p1, p2)

从point_like对象p1到p2绘制线条。

参数：

p1 (类似点) – 起始点
p2 (类似点) – 终点

返回类型：

点

终点，p2。

draw_squiggle(p1, p2, breadth=2)

从point_like对象p1到p2绘制波浪线。始终会绘制整数个完整波浪周期，其中一个周期的长度为4 * breadth。根据需要调整breath参数以满足此条件。绘制的线条在离开p1时总是向“左”转向，并且总是从“右”连接到p2。

参数：

p1 (类似点) – 起始点
p2 (类似点) – 终点
breadth (浮点数) – 每个波浪的振幅。条件2 * breadth < abs(p2 - p1)必须为真，以适配至少一个波浪。参见以下图片，显示由一个完整周期连接的两个点。

返回类型：

点

终点，p2。

_images/img-breadth.png

这是一个三条相连的线的示例，形成一个封闭的、填充的三角形。小箭头表示描边方向。

>>> import pymupdf
>>> doc=pymupdf.open()
>>> page=doc.new_page()
>>> r = pymupdf.Rect(100, 100, 300, 200)
>>> shape=page.new_shape()
>>> shape.draw_squiggle(r.tl, r.tr)
>>> shape.draw_squiggle(r.tr, r.br)
>>> shape.draw_squiggle(r.br, r.tl)
>>> shape.finish(color=(0, 0, 1), fill=(1, 1, 0))
>>> shape.commit()
>>> doc.save("x.pdf")

_images/img-squiggly.png

注意

绘制的波浪线不是三角函数（正弦/余弦）。如果需要，请查看draw.py。

draw_zigzag(p1, p2, breadth=2)

从point_like对象p1到p2绘制一条锯齿线。否则，与Shape.draw_squiggle()完全相同。

参数：

p1（point_like） – 起点
p2（point_like） – 终点
breadth（float） – 运动的幅度。条件2 * breadth < abs(p2 - p1)必须为真，以至少适合一个周期。

返回类型：

点

终点，p2。

draw_polyline(points)

在序列points中的点之间绘制多个连接线。通过将最后一个项目设置为第一个项目，可以用于创建任意多边形。

参数：

points（sequence） – 一系列point_like对象。其长度必须至少为 2（在这种情况下等效于draw_line()）。

返回类型：

点

points[-1] – 参数序列中的最后一个点。

draw_bezier(p1, p2, p3, p4)

从p1到p4绘制标准的立方贝塞尔曲线，使用p2和p3作为控制点。

所有参数都是point_like s。

返回类型：

点

终点，p4。

注意

点不需要不同 – 尝试一些相等的情况！

示例：

_images/img-drawBezier.png

draw_oval(tetra)

在给定的四边形（四边形）内绘制一个“椭圆”。如果是正方形，则绘制正规圆，一般矩形将导致椭圆。如果使用四边形，则可以得到大量的形状。

绘图从底部左 -> 左上角线的中点开始并结束，以逆时针方向进行。

参数：

tetra（rect_like,quad_like） –

rect_like或quad_like。

版本 1.14.5 中的更改： 现在还支持四边形。

返回类型：

点

线段rect.bl -> rect.tl或quad.ll -> quad.ul的中间点。这里仅仅看几个例子，或者在 PyMuPDF-Utilities 仓库的quad-show?.py脚本中查看。

_images/img-drawquad.jpg

draw_circle(center, radius)

给定其中心和半径，绘制一个圆。绘图从点center - (radius, 0)开始并结束，以逆时针方向进行。此点是包围正方形左侧边中点。

这是一个快捷方式，用于draw_sector(center, start, 360, fullSector=False)。要以顺时针方向绘制相同的圆，请使用-360作为角度。

参数：

center（point_like） – 圆的中心。
radius（float） – 圆的半径。必须为正。

返回类型：

点

Point(center.x - radius, center.y)。

_images/img-drawcircle.jpg

draw_curve(p1, p2, p3)

draw_bezier() 的特例：从 p1 到 p3 绘制三次贝塞尔曲线。在线段 p1 -> p2 和 p3 -> p2 上生成一个控制点。因此，两个控制点都位于线段 p1 -> p3 的同一侧。这保证了曲线的曲率不会改变其符号。如果到达 p2 的线段成 90 度角，则生成的曲线是一个四分之一椭圆（或同样长度的四分之一圆）。

所有参数都是point_like。

返回类型：

点

端点 p3。以下是一个填充的四分之一椭圆段。黄色区域的方向为顺时针：

_images/img-drawCurve.png

draw_sector(center, point, angle, fullSector=True)

绘制一个圆形扇区，可选地将弧连接到圆的中心（就像一个饼图片段）。

参数：

center（point_like） – 圆的中心。
point（point_like） – 饼图弧段的两个端点之一。另一个端点由 angle 计算得出。
angle（float） – 扇形的角度（以度为单位）。用于计算弧的另一个端点。根据其符号，弧可能逆时针绘制（正）或顺时针绘制。
fullSector（bool） – 是否从弧的两端绘制连接线到圆心。如果指定了填充颜色，则整个“饼图”会被着色，否则只有扇区被着色。

返回类型：

点

弧的另一个端点。可以用作创建逻辑连接的饼图的后续调用的起点。示例：

_images/img-drawSector1.png _images/img-drawSector2.png

draw_rect(rect, *, radius=None)

自 v1.22.0 更改：添加参数 radius。

绘制一个矩形。绘制从左上角开始并以逆时针方向结束的图形。

参数：

rect（rect_like） – 矩形在页面上的位置。
radius（multiple） – 绘制圆角矩形的圆角。如果不是 None，则指定圆角的曲率半径，作为矩形边长的百分比。必须是一个或两个浮点数 0 < radius <= 0.5，其中 0.5 对应于相应边长的 50%。如果是一个浮点数，则曲率的半径计算为 radius * min(width, height)，绘制角的周长作为四分之一圆。如果给出一个元组 (rx, ry)，则曲率是关于水平和垂直方向不对称的。radius=(0.5, 0.5) 绘制一个椭圆。

返回类型：

点

矩形的左上角。

draw_quad(quad)

绘制一个四边形。绘制从左上角（Quad.ul）开始并以逆时针方向结束的图形。这是使用参数 (ul, ll, lr, ur, ul) 调用 Shape.draw_polyline() 的快捷方式。

参数：

quad (quad_like) – 在页面上放置四边形的位置。

返回类型：

Point

Quad.ul。

finish(width=1, color=(0,), fill=None, lineCap=0, lineJoin=0, dashes=None, closePath=True, even_odd=False, morph=(fixpoint, matrix), stroke_opacity=1, fill_opacity=1, oc=0)

通过将 Common Parameters 应用于所有draw()方法来完成一组绘制draw()方法。

Shape.insert_text()和Shape.insert_textbox()对此没有影响。

该方法还支持使用 Point fixpoint和 Matrix matrix对复合图形进行变形。

参数：

morph (sequence) – 在某个任意的 Point fixpoint周围对文本或复合图形进行变形，方法是将 Matrix matrix应用于它。这意味着fixpoint是此操作的固定点：它不会改变其位置。默认值为无变形（None）。矩阵的前 4 个组件可以包含任何值，但matrix.e == matrix.f == 0必须为真。这意味着可以进行任意组合的缩放、倾斜、旋转、翻转等操作，但不能进行平移。
stroke_opacity (float) – (new in v1.18.1) 设置笔触颜色的透明度。值小于 0 或大于 1 将被忽略。默认值为 1（不透明）。
fill_opacity (float) – (new in v1.18.1) 设置填充颜色的透明度。默认值为 1（不透明）。
even_odd (bool) – 请求使用“even-odd 规则”进行填充操作。默认值为False，因此使用“nonzero winding number 规则”。这些规则是在区域重叠时应用填充颜色的备选方法。只有在相当复杂的形状中，才会使用这些规则产生不同的行为。有关详细解释，请参阅 Adobe PDF References，第 137 页及以后。以下是一个示例，演示了差异。
oc (int) – (new in v1.18.4) xref的数字，表示可以有条件地显示此绘图的OCG或OCMD。

_images/img-even-odd.png

注

对于形状中的每个像素，将发生以下情况：

规则 “even-odd” 计算像素包含的区域数。如果此计数为奇数，则像素被视为内部形状；如果为偶数，则像素被视为外部形状。
默认规则 “nonzero winding” 还会查看包含像素的每个区域的“方向”：如果区域逆时针绘制，则加 1；如果顺时针，则减 1。如果结果为零，则像素被视为外部，具有非零计数的像素被视为内部形状。

在上图的四个形状中，上两个形状分别显示了以标准方式绘制的三个圆（逆时针，查看箭头）。下面的两个形状包含一个（左上角）按顺时针方向绘制的圆。可以看出，面积方向对右侧列（奇偶规则）无关紧要。

insert_text(point, text, fontsize=11, fontname='helv', fontfile=None, set_simple=False, encoding=TEXT_ENCODING_LATIN, color=None, lineheight=None, fill=None, render_mode=0, border_width=1, rotate=0, morph=None, stroke_opacity=1, fill_opacity=1, oc=0)

插入文本行从 point 处开始。

参数：

point (point_like) –

text 的左下角第一个字符的像素位置。了解它如何与 rotate 参数结合使用很重要。请参考下图。小红点表示 point 在四种可能情况下的位置。
text (str/sequence) – 要插入的文本。可以指定为字符串类型或序列类型。对于包含换行符 n 的序列或字符串，将插入多行。不会处理行太宽的问题，但插入的行数将受页面上的“垂直”空间限制（根据 rotate 参数所建立的阅读方向）。任何文本的剩余部分将被丢弃 – 但是返回代码包含插入行的数量。
lineheight (float) – 一个因子，用于覆盖从字体属性计算的行高。如果不是 None，将使用 fontsize * lineheight 的行高。
stroke_opacity (float) – (v1.18.1 新增) 设置描边颜色（字符的边框线）的透明度。只有 0 <= value <= 1 的值会被考虑。默认为 1（不透明）。
fill_opacity (float) – (v1.18.1 新增) 设置填充颜色的透明度。默认为 1（不透明）。使用此值来控制文本颜色的透明度。描边透明度仅影响字符的边框线。
rotate (int) – 决定是否旋转文本。可接受的值为 90 度的倍数。默认为 0（无旋转），意味着从左到右的水平文本行。180 表示从右到左倒置显示文本。90 表示逆时针旋转，文本向上运行。270（或-90）表示顺时针旋转，文本向下运行。在任何情况下，point 指定第一个字符矩形的左下角坐标。如果存在多行，则始终按照此参数建立的阅读方向进行排列。因此，在 rotate = 180 的情况下，第二行位于第一行上方，依此类推。
oc (int) – (v1.18.4 新增) 表示一个 Xref 的编号，用于使此文本在特定条件下显示。

返回类型：

int

插入的行数。

其他参数的描述请参见 Common Parameters。

insert_textbox(rect, buffer, fontsize=11, fontname='helv', fontfile=None, set_simple=False, encoding=TEXT_ENCODING_LATIN, color=None, fill=None, render_mode=0, border_width=1, expandtabs=8, align=TEXT_ALIGN_LEFT, rotate=0, lineheight=None, morph=None, stroke_opacity=1, fill_opacity=1, oc=0)

仅适用于 PDF：将文本插入指定的矩形区域。文本将被分割成行和单词，然后填充到可用空间中，从四个矩形角之一开始，这取决于 rotate。将尊重换行符和多个空格。

参数：

rect (rect_like) – 要使用的区域。必须是有限且非空的。
buffer（str/sequence）– 要插入的文本。必须指定为字符串或字符串序列。即使在序列条目中也会尊重换行。
align（int）– 对齐每一行文本。默认为 0（左对齐）。居中、右对齐和两端对齐是其他支持的选项，请参阅文本对齐。请注意，参数值 TEXT_ALIGN_JUSTIFY 的效果仅可通过“简单”（单字节）字体（包括 PDF 基本 14 字体）实现。
lineheight（float）–

一个因子，用于覆盖从字体属性计算出的行高。如果不是 None，则将使用行高 fontsize * lineheight。

arg int expandtabs:

使用 string.expandtabs() 方法逐行控制制表符 \t 的处理。
stroke_opacity（float）– （在 v1.18.1 中新增）设置描边颜色的透明度。负值和大于 1 的值将被忽略。默认为 1（不透明）。
fill_opacity（float）– （在 v1.18.1 中新增）设置填充颜色的透明度。默认为 1（不透明）。使用此值控制文本颜色的透明度。描边不透明度仅影响字符的边框线。
rotate（int）– 请求文本在矩形中旋转。该值必须是 90 度的倍数。默认为 0（不旋转）。实际上，处理四个值 0、90、180 和 270（= -90），每个值导致文本从不同的矩形角开始。左下角是 90，右下角是 180，-90 / 270 是右上角。请参阅示例，了解文本如何填充到矩形中。此参数优先于变形。请参阅第二个示例，其中文本首先向左旋转了 90 度，然后整个矩形围绕其左下角顺时针旋转。
oc（int）– （在 v1.18.4 中新增）xref编号，用于使此文本有条件地显示为 OCG 或 OCMD。

返回类型：

浮点

如果为正数或零：执行成功。返回的值是像素中未使用的矩形线空间。这可以安全地忽略 – 或用于优化矩形，定位后续项目等。

如果为负数：不执行。返回的值是存储文本行的空间不足。扩大矩形，减小 fontsize，减少文本数量等。

_images/img-rotate.png _images/img-rot%2Bmorph.png

有关其他参数的描述，请参阅常见参数。

commit(overlay=True)

更新页面的 contents，其中包含累积的绘图，然后是任何文本插入。如果文本重叠绘图，则将在绘图的顶部写入。

警告

不要忘记执行此方法：

如果形状未提交，它将被忽略，并且页面不会更改！

方法将重置属性Shape.rect，lastPoint，draw_cont，text_cont和totalcont。之后，形状对象可以在同一页中重新使用。

参数：

overlay（bool）– 确定是否将内容放置在前景（默认）或背景中。仅当页面已经具有非空contents对象时才相关。

———- 属性 ———-

doc

仅供参考：页面的文档。

类型：

文档

page

仅供参考：拥有的页面。

类型：

页面

height

页面的高度副本

类型：

浮点

width

页面的宽度副本。

类型：

浮点数

draw_cont

自上次完成以来的draw 方法累积的命令缓冲区。每个完成方法将其命令附加到Shape.totalcont。

类型：

str

text_cont

累积的文本缓冲区。所有文本插入都在这里进行。此缓冲区将附加到totalcont Shape.commit()，因此文本永远不会被同一形状中的绘图覆盖。

类型：

str

rect

围绕绘图的矩形。此属性可供您使用，并且可以随时更改。在创建或提交形状时，其值设置为None。每个draw方法以及Shape.insert_textbox()将更新此属性（即根据需要扩展矩形）。然而，morphing操作（Shape.finish()，Shape.insert_textbox()）将被忽略。

此属性的典型用法是在稍后或外部使用时将Page.cropbox_position设置为此值。如果您未手动操作属性，则应反映一个包含到目前为止所有绘图的矩形。

如果您使用了 morphing 并且需要包含 morphed 对象的矩形，请使用以下代码：

>>> # assuming ...
>>> morph = (point, matrix)
>>> # ... recalculate the shape rectangle like so:
>>> shape.rect = (shape.rect - pymupdf.Rect(point, point)) * ~matrix + pymupdf.Rect(point, point)

类型：

矩形

totalcont

用于 draws 和 text insertions 的总累积命令缓冲区。这将被Shape.commit()使用。

类型：

str

lastPoint

仅供参考：绘图路径的当前点。在Shape创建后以及每次finish()和commit()之后为None。

类型：

点

用法

通过shape = page.new_shape()构造绘图对象。之后，可以跟随所需数量的 draw、finish 和 text insertions 方法。在提交绘图之前必须完成每个绘制序列。整体编码模式如下：

>>> shape = page.new_shape()
>>> shape.draw1(...)
>>> shape.draw2(...)
>>> ...
>>> shape.finish(width=..., color=..., fill=..., morph=...)
>>> shape.draw3(...)
>>> shape.draw4(...)
>>> ...
>>> shape.finish(width=..., color=..., fill=..., morph=...)
>>> ...
>>> shape.insert_text*
>>> ...
>>> shape.commit()
>>> ....

注意

每个 finish() 将前面的绘制组合成一个逻辑形状，使其具有共同的颜色、线宽、变形等。如果指定了 closePath，它还将连接最后一个绘制的结束点与第一个绘制的起始点。
要成功创建复合图形，请让每个绘制方法使用前一个绘制的结束点作为其起始点。在上述伪代码中，draw2 因此应使用 draw1 的返回的 Point 作为其起始点。如果未能如此做，将自动开始一个新路径，并且 finish() 可能不会按预期工作（但它也不会报错）。
文本插入可以出现在提交之前的任何位置（它们既不接触 Shape.draw_cont 也不接触 Shape.lastPoint）。它们将直接附加到 Shape.totalcont，而绘制则将由 Shape.finish 附加。
每个 commit 将所有文本插入和形状放置在页面的前景或背景中，从而提供了一种控制图形层的方法。
只有 commit 将更新 页面的内容，其他方法基本上是字符串操作。

示例

创建不同颜色的饼图完整圆形：

shape = page.new_shape()  # start a new shape
cols = (...)  # a sequence of RGB color triples
pieces = len(cols)  # number of pieces to draw
beta = 360. / pieces  # angle of each piece of pie
center = pymupdf.Point(...)  # center of the pie
p0 = pymupdf.Point(...)  # starting point
for i in range(pieces):
    p0 = shape.draw_sector(center, p0, beta,
                          fullSector=True) # draw piece
    # now fill it but do not connect ends of the arc
    shape.finish(fill=cols[i], closePath=False)
shape.commit()  # update the page

下面是 5 种颜色的示例：

_images/img-cake.png

创建常规的 n 边形（填充黄色，红色边框）。我们仅使用 draw_sector() 计算周长上的点，并在绘制多边形之前清空绘制命令缓冲区：

shape = page.new_shape() # start a new shape
beta = -360.0 / n  # our angle, drawn clockwise
center = pymupdf.Point(...)  # center of circle
p0 = pymupdf.Point(...)  # start here (1st edge)
points = [p0]  # store polygon edges
for i in range(n):  # calculate the edges
    p0 = shape.draw_sector(center, p0, beta)
    points.append(p0)
shape.draw_cont = ""  # do not draw the circle sectors
shape.draw_polyline(points)  # draw the polygon
shape.finish(color=(1,0,0), fill=(1,1,0), closePath=False)
shape.commit()

下面是 n = 7 的多边形：

_images/img-7edges.png ## 常用参数

fontname (str)

通常有三种选项：

使用标准的 PDF 基本 14 字体之一。在这种情况下，如果省略此参数，则必须不指定 fontfile，且将使用 “Helvetica”。

选择页面已经在使用的字体。然后指定其带斜杠“/”的引用名称，如下例所示。

指定系统中存在的字体文件。在这种情况下，选择一个任意的新名称用于此参数（不带“/”前缀）。

如果插入的文本应重用页面的某个字体，请使用其在 Page.get_fonts() 中出现的引用名称，如下所示：

假设字体列表中有项目 [1024, 0, ‘Type1’, ‘NimbusMonL-Bold’, ‘R366’]，则指定 fontname = “/R366”，fontfile = None 使用字体 NimbusMonL-Bold。

fontfile (str)

您计算机上现有的字体文件路径。如果指定了 fontfile，请确保使用上述列表中不存在的 fontname。此新字体将在 doc.save() 时嵌入 PDF。类似于新图像，每个字体文件只会被嵌入一次。使用二进制字体内容的 MD5 码表来确保这一点。

set_simple (bool)

从文件安装的字体默认安装为Type0字体。如果要仅使用 1 字节字符，请将此设置为 true。此设置无法恢复。后续更改将被忽略。

fontsize（浮点数）

文本的字体大小，请参见：fontsize。

dashes（字符串）

导致线条绘制为虚线。一般格式为"[n m] p"，其中（最多）3 个浮点数表示像素长度。n 是虚线长度，m（可选）是随后的间隔长度，p（“相位” - 必须的，即使为 0！）指定虚线开始之前应跳过多少像素。如果省略 m，则默认为 n。

使用"[] 0"或None或""绘制连续线条（无虚线）。示例：

指定 "[3 4] 0" 意味着 3 像素虚线和 4 像素间隔交替出现。

"[3 3] 0" 和 "[3] 0" 做同样的事情。

有关如何实现复杂虚线效果的详细信息，请参见 Adobe PDF 参考手册，第 217 页。

color / fill（列表、元组）

描边和填充颜色可以指定为浮点数列表或元组，范围从 0 到 1。这些序列必须具有长度为 1（GRAY）、3（RGB）或 4（CMYK）。对于 GRAY 颜色空间，可以接受单个浮点数，而不是笨重的(float,)或[float]。接受（默认）或使用None来不使用该参数。

为了简化颜色规范，pymupdf.utils 中的 getColor() 方法可以通过名称获取预定义的 RGB 颜色三元组。它接受颜色名称的字符串，并返回相应的三元组。该方法知道超过 540 个颜色名称 - 请参阅颜色数据库部分。

请注意，当与填充颜色一起使用时，术语color通常意味着“描边”颜色。

如果将颜色参数默认为 None，则不会生成相应的颜色选择命令。如果fill和color都是 None，则绘图将不包含颜色规范。但仍将“描边”，这会导致 PDF 默认颜色“黑色”被 Adobe Acrobat 和所有其他查看器使用。

width（浮点数）

形状中元素的描边（“边框”）宽度（如果适用）。默认值为 1。width、color 和 fill 有以下关系/依赖：

如果 fill=None，则形状元素始终会带有边框，即使 color=None（此时取黑色）或 width=0（此时取 1）也是如此。

形状没有边框只能在指定了填充颜色（当然可以是白色）的情况下实现。要实现这一点，请指定width=0。在这种情况下，color 参数将被忽略。

stroke_opacity / fill_opacity（浮点数）

两个值都是在范围[0, 1]内的浮点数。负值或大于 1 的值将被忽略（在大多数情况下）。两者设置透明度，使得值 0.5 对应于 50％的透明度，0 表示不可见，1 表示不透明。例如，对于矩形，边框透明度适用于其边框，而填充透明度适用于其内部。

对于文本插入（Shape.insert_text()和Shape.insert_textbox()），使用fill_opacity控制文本的透明度。乍一看，这似乎令人惊讶，但是当你继续查看render_mode时，它就变得明显了：fill_opacity适用于黄色，stroke_opacity适用于蓝色。

border_width（浮点数）

设置文本插入的边框宽度。在 v1.14.9 中新增。仅在使用大于零的值的渲染模式参数时相关。

render_mode（整数）

1.14.9 版本中新增： range(8) 中的整数，控制文本外观（Shape.insert_text()和Shape.insert_textbox()）。参见 Adobe PDF 参考手册第 246 页。在 v1.14.9 中新增。这些方法现在也区分填充和描边颜色。

对于默认值为 0，只使用文本填充颜色来绘制文本。为了向后兼容，也可以使用color参数。

对于渲染模式 1，只绘制每个字形（即文本字符）的边框，边框的厚度由border_width参数设置。选用color参数中的颜色，fill参数将被忽略。

对于渲染模式 2，字形填充并描边，同时使用颜色参数和指定的边框宽度。您可以使用此值来模拟粗体文本，而无需使用另一种字体：选择相同值的fill和color以及适当的border_width值。

对于渲染模式 3，字形既不描边也不填充：文本变得不可见。

以下示例使用 border_width=0.3，字体大小为 15。描边颜色为蓝色，填充颜色为一些黄色。

overlay（布尔值）

使项目出现在前景（默认）或背景中。

morph（序列）

导致“形态变化”形状或页面方法插入的文本（如 insert_textbox() / insert_text()）的“形态变化”。如果不是 None，必须是一个 (fixpoint, matrix) 对，其中 fixpoint 是一个 Point，matrix 是一个 Matrix。矩阵可以是除了平移以外的任何内容，即 matrix.e == matrix.f == 0 必须为真。点用作矩阵操作的固定点。例如，如果 matrix 是旋转或缩放，则 fixpoint 是其中心。类似地，如果 matrix 是左右或上下翻转，则镜像轴将是通过 fixpoint 的垂直或水平线等。

注意

若干方法包含检查即将插入项目是否实际适合页面的代码（如 Shape.insert_text() 或 Shape.draw_rect()）。但形态操作的结果则无此保证：这完全取决于程序员的责任。

lineCap (已弃用：“roundCap”) (int)

控制线段的外观。默认值 0 使每条线段正好以给定坐标处的尖角结束。值为 1 添加一个半圆到末端，其中心是端点，直径为线宽。值为 2 添加一个半正方形，边长为线宽，中心为线段的末端。

自版本 1.14.15 更改

lineJoin (int)

自版本 1.14.15 新增: 控制线连接外观的方式。可以是尖角（0）、圆形连接（1）或截断边缘（2，“butt”）。

closePath (bool)

导致绘图的终点自动与起点连接（通过直线）。

对本页有任何反馈意见吗？

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

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

Discord logo

用法

绘图对象由 shape = page.new_shape() 构造。此后，可以按需使用许多绘制、完成和文本插入方法。每个绘制序列必须在提交绘图之前完成。整体编码模式如下：

>>> shape = page.new_shape()
>>> shape.draw1(...)
>>> shape.draw2(...)
>>> ...
>>> shape.finish(width=..., color=..., fill=..., morph=...)
>>> shape.draw3(...)
>>> shape.draw4(...)
>>> ...
>>> shape.finish(width=..., color=..., fill=..., morph=...)
>>> ...
>>> shape.insert_text*
>>> ...
>>> shape.commit()
>>> ....

注意

每个 finish() 将前面的绘制组合成一个逻辑形状，赋予其共同的颜色、线宽、形态操作等。如果指定了 closePath，它还会连接最后一个绘制的终点与第一个绘制的起点。
为了成功创建复合图形，让每个绘制方法使用前一个绘制方法的终点作为其起点。在上述伪代码中，draw2应该使用draw1返回的 Point 作为其起点。如果未这样做，将会自动启动一个新路径，并且finish()可能不会按预期工作（但它也不会抱怨）。
文本插入可以出现在提交之前的任何地方（它们不会触及Shape.draw_cont或者Shape.lastPoint）。它们直接附加到Shape.totalcont，而绘制将通过Shape.finish附加。
每次commit都会获取所有文本插入和形状，并将它们放置在页面的前景或背景上 - 因此提供了控制图形层的一种方式。
只有 commit 将更新 页面的内容，其他方法基本上是字符串操作。

示例

创建一个由不同颜色的扇形组成的完整圆：

shape = page.new_shape()  # start a new shape
cols = (...)  # a sequence of RGB color triples
pieces = len(cols)  # number of pieces to draw
beta = 360. / pieces  # angle of each piece of pie
center = pymupdf.Point(...)  # center of the pie
p0 = pymupdf.Point(...)  # starting point
for i in range(pieces):
    p0 = shape.draw_sector(center, p0, beta,
                          fullSector=True) # draw piece
    # now fill it but do not connect ends of the arc
    shape.finish(fill=cols[i], closePath=False)
shape.commit()  # update the page

这是一个 5 种颜色的示例：

_images/img-cake.png

创建一个常规的 n 边形（填充黄色，红色边框）。我们只使用draw_sector()来计算周长上的点，并在绘制多边形之前清空绘图命令缓冲区：

shape = page.new_shape() # start a new shape
beta = -360.0 / n  # our angle, drawn clockwise
center = pymupdf.Point(...)  # center of circle
p0 = pymupdf.Point(...)  # start here (1st edge)
points = [p0]  # store polygon edges
for i in range(n):  # calculate the edges
    p0 = shape.draw_sector(center, p0, beta)
    points.append(p0)
shape.draw_cont = ""  # do not draw the circle sectors
shape.draw_polyline(points)  # draw the polygon
shape.finish(color=(1,0,0), fill=(1,1,0), closePath=False)
shape.commit()

这是 n = 7 的多边形示例：

_images/img-7edges.png ## 常见参数

fontname（str）

通常有三种选项：

使用标准的 PDF Base 14 字体之一。在这种情况下，如果未指定此参数，fontfile 不能被指定，并且使用“Helvetica”。

选择页面中已经使用的字体。然后指定其以斜杠“/”为前缀的参考名称，如下例所示。

指定系统上存在的字体文件。在这种情况下，选择一个任意的但是新的参数名（不带“/”前缀）。

如果插入的文本应该重复使用页面的某个字体，请使用出现在Page.get_fonts()中的其参考名称，如下所示：

假设字体列表中有项[1024, 0, ‘Type1’, ‘NimbusMonL-Bold’, ‘R366’]，则指定fontname = “/R366”， fontfile = None来使用字体NimbusMonL-Bold。

fontfile（str）

您计算机上存在的字体文件路径。如果指定了fontfile，请确保使用上述列表中不存在的fontname。这个新字体将在doc.save()时嵌入 PDF 中。与新图像类似，字体文件只会被嵌入一次。使用二进制字体内容的 MD5 代码表来确保这一点。

set_simple（bool）

从文件安装的字体默认为Type0字体。如果只想使用 1 字节字符，请将此设置为 true。此设置无法恢复。后续更改将被忽略。

fontsize（float）

文本的字体大小，参见：fontsize。

dashes（str）

导致绘制的线条为虚线。一般格式为"[n m] p"，其中最多有 3 个浮点数表示像素长度。n是虚线的长度，m（可选）是随后的间隔长度，p（“相位” - 必需，即使为 0！）指定在虚线开始之前应跳过多少像素。如果省略m，则默认为n。

使用"[] 0"或None或""绘制连续线条（无虚线）。示例：

指定"[3 4] 0"意味着 3 个像素长的虚线和 4 个像素长的间隔交替出现。

"[] 0"和"[3] 0"做同样的事情。

有关如何实现复杂的虚线效果的详细信息，请参阅 Adobe PDF 参考手册，第 217 页。

color / fill (list, tuple)

可以将描边和填充颜色指定为浮点数的元组或列表，范围从 0 到 1。这些序列必须具有长度为 1（灰度）、3（RGB）或 4（CMYK）。对于灰度色彩空间，也可以接受单个浮点数而不是笨重的(float,)或[float]。接受（默认）或使用None来不使用该参数。

为了简化颜色的指定，可以使用pymupdf.utils中的getColor()方法通过名称获取预定义的 RGB 颜色三元组。它接受一个颜色名称的字符串，并返回相应的三元组。该方法知道超过 540 个颜色名称 - 见章节颜色数据库。

请注意，术语color通常在与填充颜色一起使用时指“描边”颜色。

如果将颜色参数设为None，则不会生成相应的颜色选择命令。如果fill和color都是None，则绘图不包含颜色规范。但仍会进行“描边”，这将导致 Adobe Acrobat 和所有其他查看器使用 PDF 的默认颜色“黑色”。

width (float)

元素形状中的描边（“边框”）宽度（如果适用）。默认值为 1。宽度、颜色和填充的关系/依赖如下：

如果fill=None，则形状元素始终将带有边框 - 即使color=None（此时将使用黑色）或width=0（此时将使用 1）。

仅通过指定填充颜色（当然可以是白色）才能实现没有边框的形状。为此，请指定width=0。在这种情况下，将忽略color参数。

stroke_opacity / fill_opacity (floats)

两个值都是范围在[0, 1]的浮点数。负值或大于 1 的值将被忽略（在大多数情况下）。两者设置透明度，使得数值 0.5 对应 50%的透明度，0 表示不可见，1 表示不透明。例如，对于矩形，描边透明度适用于其边框，填充透明度适用于其内部。

对于文本插入（Shape.insert_text()和Shape.insert_textbox())，使用fill_opacity来设置文本的透明度。乍一看这似乎令人惊讶，但当您进一步查看render_mode时，这变得显而易见：fill_opacity适用于黄色，stroke_opacity适用于蓝色。

border_width（浮点数）

设置文本插入的边框宽度。在 v1.14.9 中新增。仅当使用渲染模式参数值大于零时相关。

渲染模式（整数）

版本 1.14.9 中的新功能：range(8)中的整数控制文本外观（Shape.insert_text()和Shape.insert_textbox()）。参见 Adobe PDF References 第 246 页。在 v1.14.9 中新增功能。这些方法现在还区分填充和描边颜色。

对于默认的 0，只使用文本填充颜色来绘制文本。为了向后兼容，也可以使用color参数。

对于渲染模式 1，只绘制每个字形（即文本字符）的边框，其厚度由border_width参数设置。选定的color参数的颜色用于此操作，fill参数被忽略。

对于渲染模式 2，字形被填充并描边，使用颜色参数和指定的边框宽度。您可以使用此值模拟粗体文本而无需使用其他字体：选择相同的值作为fill和color，并为border_width选择适当的值。

对于渲染模式 3，字形既不描边也不填充：文本变得不可见。

以下示例使用 border_width=0.3，以及字体大小为 15。描边颜色为蓝色，填充颜色为某种黄色。

叠加（布尔值）

导致项目出现在前景（默认）或背景中。

变形（序列）

导致了形状的“变形”，这些形状是由draw()方法创建的，或者是由页面方法insert_textbox()* / insert_text()插入的文本。如果不是None，它必须是一对(fixpoint, matrix)，其中fixpoint是点，matrix是矩阵。矩阵可以是除了平移以外的任何东西，即matrix.e == matrix.f == 0必须为真。该点被用作矩阵操作的固定点。例如，如果matrix是旋转或缩放，则fixpoint是其中心。同样地，如果matrix是左右或上下翻转，则镜像轴将分别通过fixpoint形成垂直或水平线等。

注意

几种方法包含检查，用于确定要插入的项目是否实际适合页面（例如 Shape.insert_text() 或 Shape.draw_rect()）。然而，对于变形操作的结果，没有这样的保证：这完全由程序员负责。