Pixmap#
Pixmap（“像素图”）是 MuPDF 渲染能力的核心对象。它们表示平面的矩形像素集合。每个像素由定义其颜色的若干字节（“分量”）以及一个可选的定义其透明度的 alpha 字节描述。
在 PyMuPDF 中，有几种创建 pixmap 的方法。除了第一种方法外，所有方法都可以作为重载构造函数使用。可以从以下内容创建 pixmap：
从文档页面（方法
Page.get_pixmap()）空 pixmap，基于 Colorspace 和 IRect 信息
从文件
从内存中的图像
从普通像素的内存区域
从 PDF 文档中的图像
作为另一个 pixmap 的副本
注意
上述第 3 和第 4 点支持多种图像格式作为输入。请参阅 支持的输入图像格式 部分。
请查阅 常见问题解答 部分，了解一些 pixmap 的实际用法。
方法 / 属性 |
简要描述 |
|---|---|
清除 pixmap 的部分区域 |
|
确定使用的颜色 |
|
确定最常用颜色的占比 |
|
复制另一个 pixmap 的部分区域 |
|
对 pixmap 应用伽马因子 |
|
反转给定区域的像素 |
|
将 pixmap 保存为 OCR 文本层的单页 PDF |
|
将 pixmap 保存为 OCR 文本层的单页 PDF |
|
创建一个 Pillow Image |
|
保存为 Pillow Image |
|
将 Pillow Image 写入 |
|
返回像素的值 |
|
将 pixmap 保存为多种格式 |
|
设置 alpha 值 |
|
设置图像分辨率 |
|
设置 pixmap 的 x,y 值 |
|
设置像素的颜色和 alpha 值 |
|
设置矩形区域内所有像素的颜色和 alpha 值 |
|
在保持比例的情况下减小尺寸 |
|
对 pixmap 进行着色 |
|
以多种格式返回内存区域 |
|
返回由内部 quad 创建的 pixmap |
|
透明度指示器 |
|
pixmap 的 Colorspace |
|
pixmap 的 MD5 哈希码 |
|
pixmap 高度 |
|
插值方法指示器 |
|
检查是否只有黑白两色 |
|
检查是否只有一种颜色 |
|
pixmap 的 IRect |
|
每像素字节数 |
|
像素区域的 |
|
指向像素区域的 Python 指针 |
|
像素区域的 |
|
pixmap 的总长度 |
|
图像一行的大小 |
|
pixmap 宽度 |
|
左上角的 X 坐标 |
|
X 方向的分辨率 |
|
左上角的 Y 坐标 |
|
Y 方向的分辨率 |
类 API
- class Pixmap#
- __init__(self, colorspace, irect, alpha=False)#
新建空 pixmap：创建一个由矩形指定大小和原点的空 pixmap。因此，irect.top_left 表示 pixmap 的左上角，其宽度和高度分别为 irect.width 和 irect.height。请注意，图像区域未初始化，将包含垃圾数据——请使用例如
clear_with()或set_rect()来确保。- 参数:
colorspace (Colorspace) – 颜色空间。
irect (irect_like) – pixmap 的位置和尺寸。
alpha (bool) – 指定是否应包含透明度字节。默认为
False。
- __init__(self, colorspace, source)#
复制并设置颜色空间：复制 source pixmap 并转换颜色空间。任何颜色空间组合都是可能的，但源颜色空间不能是
None。- 参数:
colorspace (Colorspace) – 所需的目标颜色空间。这也可以是
None。在这种情况下，将创建一个“遮罩” pixmap：其Pixmap.samples将仅由源的 alpha 字节组成。source (Pixmap.) – 源 pixmap。
- __init__(self, source, mask)#
v1.18.18 新增
复制并添加图像遮罩：复制 source pixmap，并从遮罩 pixmap 添加一个包含透明度数据的 alpha 通道。
- __init__(self, source, width, height[, clip])#
复制并缩放：复制 source pixmap，缩放新的宽度和高度值——图像将相应地拉伸或收缩。支持部分复制。源颜色空间可以是
None。- 参数:
source (Pixmap.) – 源 pixmap。
width (float) – 所需的目标宽度。
height (float) – 所需的目标高度。
clip (irect_like) – 将结果 pixmap 限制在缩放后 pixmap 的此区域内。
注意
如果 width 或 height 不表示整数（即
value.is_integer() != True），则结果 pixmap 将包含一个 alpha 通道。
- __init__(self, source, alpha=1)#
复制并添加或删除 alpha 通道：复制 source 并添加或删除其 alpha 通道。如果 alpha 等于 source.alpha，则为完全相同的副本。如果添加 alpha 通道，其值将设置为 255。
- 参数:
source (Pixmap.) – 源 pixmap。
alpha (bool) – 目标是否将具有 alpha 通道，如果源颜色空间为
None，则为默认值且强制要求。
注意
典型用途包括将颜色和透明度字节分离到单独的 pixmap 中。一些应用程序需要这样做，例如 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 创建 pixmap。所有属性都从输入推断。结果 pixmap 的原点是 (0, 0)。
- 参数:
filename (str) – 图像文件的路径。
- __init__(self, stream)#
从内存创建：从内存区域创建 pixmap。所有属性都从输入推断。结果 pixmap 的原点是 (0, 0)。
- 参数:
stream (bytes,bytearray,BytesIO) –
包含完整、有效图像的数据。例如可以通过 stream = bytearray(open(‘image.file’, ‘rb’).read()) 创建。bytes 类型仅在 Python 3 中支持，因为在 Python 2 中 bytes == str，该方法会将 stream 解释为文件名。
v1.14.13 版本修改：现在也支持 io.BytesIO。
- __init__(self, colorspace, width, height, samples, alpha)#
从普通像素创建：从 samples 创建 pixmap。每个像素必须由 colorspace 和 alpha 参数控制的字节数表示。结果 pixmap 的原点是 (0, 0)。当由其他程序提供原始图像数据时，此方法很有用 – 请参阅 常见问题解答。
- 参数:
colorspace (Colorspace) – 图像的颜色空间。
width (int) – 图像宽度
height (int) – 图像高度
samples (bytes,bytearray,BytesIO) –
包含图像所有像素的区域。如果指定，必须包含 alpha 值。
v1.14.13 版本修改： (1) 现在也可以使用 io.BytesIO。(2) 数据现在复制到 pixmap 中，因此可以安全地删除或变得不可用。
alpha (bool) – 是否包含透明度通道。
注意
以下等式必须为真：(colorspace.n + alpha) * width * height == len(samples)。
从 v1.14.13 版本开始，样本数据会复制到 pixmap 中。
- __init__(self, doc, xref)#
从 PDF 图像创建：从 doc PDF 中包含的、由
xref标识的图像创建 pixmap。所有 pixmap 属性均由图像设置。请查看 extract-img1.py 和 extract-img2.py，了解如何使用此方法恢复 PDF 中的所有图像。- 参数:
doc (Document) – 一个已打开的 PDF 文档。
xref (int) – 图像对象的
xref。例如，您可以使用Document.get_page_images()列出特定页面上使用的图像，该方法也会显示每张图像的xref编号。
- clear_with([value[, irect]])#
初始化 samples 区域。
- 参数:
value (int) – 如果指定，0 到 255 的值有效。每个像素的每个颜色字节将被设置为此值，如果存在 alpha，则 alpha 将设置为 255（不透明）。如果省略，则所有字节（包括任何 alpha）都将被清零为 0x00。
irect (irect_like) – 要清除的区域。省略则清除整个 pixmap。只有在也指定了 value 时才能指定此参数。
- tint_with(black, white)#
通过用给定的 sRGB 整数颜色值替换黑色和/或白色来对 pixmap 进行着色。仅支持
CS_GRAY和CS_RGB颜色空间，其他颜色空间将被忽略并发出警告。如果颜色空间是
CS_GRAY，将取平均值 (红色 + 绿色 + 蓝色)/3。pixmap 将被原地修改。- 参数:
black (int) – 用此值替换黑色。指定 0x000000 不进行任何更改。
white (int) – 用此值替换白色。指定 0xFFFFFF 不进行任何更改。
示例
tint_with(0x000000, 0xFFFFFF)是一个无操作。tint_with(0x00FF00, 0xFFFFFF)将黑色更改为绿色，白色保持不变。tint_with(0xFF0000, 0x0000FF)将黑色更改为红色，将白色更改为蓝色。
- gamma_with(gamma)#
对 pixmap 应用伽马因子，即使其变亮或变暗。颜色空间为
None的 pixmap 将被忽略并发出警告。- 参数:
gamma (float) – gamma = 1.0 不执行任何操作，gamma < 1.0 使图像变亮，gamma > 1.0 使图像变暗。
- shrink(n)#
通过将其宽度和高度都除以 2 的
n次方来缩小 pixmap。- 参数:
n (int) – 确定新的 pixmap (samples) 大小。例如，值为 2 会将宽度和高度都除以 4，因此结果大小为原始大小的 1/16。小于 1 的值将被忽略并发出警告。
注意
使用此方法可以在保持比例的情况下减小 pixmap 的大小。pixmap 将“原地”修改。如果您想保留原始 pixmap 并有更精细的选择，请使用相应的复制构造函数。
- pixel(x, y)#
v1.14.5 版本新增：返回位置 (x, y)（列，行）处的像素值。
- 参数:
x (int) – 像素的列号。必须在
range(pix.width)范围内。y (int) – 像素的行号。必须在
range(pix.height)范围内。
- 返回类型:
list
- 返回:
一个包含颜色值以及可能的 alpha 值的列表。其长度和内容取决于 pixmap 的颜色空间以及是否存在 alpha 通道。对于 RGBA pixmap，结果例如是 [r, g, b, a]。所有项目都是
range(256)范围内的整数。
- set_pixel(x, y, color)#
v1.14.7 版本新增：修改位置 (x, y)（列，行）处的像素。
- 参数:
x (int) – 像素的列号。必须在
range(pix.width)范围内。y (int) – 像素的行号。必须在
range(pix.height)范围内。color (sequence) – 所需的像素值，以
range(256)范围内的整数序列形式给出。序列长度必须等于Pixmap.n，其中包括任何 alpha 字节。
- set_rect(irect, color)#
v1.14.8 版本新增：将矩形区域的像素设置为指定值。
- 参数:
irect (irect_like) – 要填充指定值的矩形区域。实际区域是此参数与
Pixmap.irect的交集。如果交集为空（或参数无效），则不会发生任何更改。color (sequence) – 所需的值，以
range(256)范围内的整数序列形式给出。序列长度必须等于Pixmap.n，其中包括任何 alpha 字节。
- 返回类型:
bool
- 返回:
如果矩形无效或与
Pixmap.irect没有交集，则为False，否则为True。
注意
此方法等同于对矩形中的每个像素执行
Pixmap.set_pixel()，但在涉及大量像素时显然快得多。此方法可以类似地使用
Pixmap.clear_with()来用某种颜色初始化 pixmap，例如：pix.set_rect(pix.irect, (255, 255, 0))（RGB 示例，将整个 pixmap 染成黄色）。
- set_origin(x, y)#
v1.17.7 新增
设置 pixmap 左上角的 x 和 y 值。
- 参数:
x (int) – x 坐标
y (int) – y 坐标
- set_dpi(xres, yres)#
v1.16.17 新增
v1.18.0 版本修改：保存为 PNG 图像时，现在会存储这些值。
设置 x 和 y 方向的分辨率 (dpi)。
- 参数:
xres (int) – x 方向的分辨率。
yres (int) – y 方向的分辨率。
- set_alpha(alphavalues, premultiply=1, opaque=None)#
v1.18.13 版本修改
更改 alpha 值。pixmap 必须包含 alpha 通道。
- 参数:
alphavalues (bytes,bytearray,BytesIO) – 新的 alpha 值。如果提供，其长度必须至少为 width * height。如果省略 (
None)，则所有 alpha 值都设置为 255（无透明度）。v1.14.13 版本修改：现在也接受 io.BytesIO。premultiply (bool) – v1.18.13 新增：是否将颜色分量与 alpha 值进行预乘。
opaque (list,tuple) – 忽略 alpha 值，并将此颜色设置为完全透明。一个包含
range(256)范围内整数的序列，长度为Pixmap.n。默认为None。例如，RGB 的典型选择是opaque=(255, 255, 255)（白色）。
- invert_irect([irect])#
反转 IRect irect 中所有像素的颜色。如果颜色空间为
None，则无效。- 参数:
irect (irect_like) – 要反转的区域。省略则反转所有内容。
- copy(source, irect)#
将 source pixmap 的 irect 部分复制到当前 pixmap 的相应区域。这两个 pixmap 可以有不同的尺寸，并且都可以是
CS_GRAY或CS_RGB颜色空间，但它们目前必须具有相同的 alpha 属性 [2]。复制机制会自动调整源和目标之间的差异，如下所示：如果从
CS_GRAY复制到CS_RGB，源的灰度值将放入三个 rgb 分量字节中的每一个。反之，将取 (r + g + b) / 3 作为目标的灰度值。首先计算 irect 和目标 pixmap 的矩形之间的“交集”。这考虑了矩形坐标和当前的属性值
Pixmap.x和Pixmap.y（您可以通过Pixmap.set_origin()为此目的自由修改）。然后复制此交集的相应数据。如果交集为空，则什么也不会发生。- 参数:
source (Pixmap) – 源 pixmap。
irect (irect_like) – 要复制的区域。
注意
示例：假设您有两个 pixmap，
pix1和pix2，并且您想将pix2的右下角四分之一复制到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))
- save(filename, output=None, jpg_quality=95)#
v1.22.0 版本修改：新增了对 JPEG 图像的直接支持。图像质量可以通过参数“jpg_quality”控制。
将 pixmap 保存为图像文件。根据选择的输出格式，仅支持部分或全部颜色空间，并且可以选择不同的文件扩展名。请参阅下表。
- 参数:
filename (str,Path,file) – 要保存到的文件。可以以字符串、
pathlib.Path或 Python 文件对象的形式提供。后两种情况下，文件名取自相应的对象。文件名的扩展名决定了图像格式，这可以通过 output 参数覆盖。output (str) – 所需的图像格式。默认为文件名的扩展名。如果此值和文件扩展名都不受支持，则会引发异常。有关可能的值，请参阅 支持的输出图像格式。
jpg_quality (int) – 所需的图像质量，默认为 95。仅适用于 JPEG 图像，否则忽略。此参数权衡质量与文件大小。值为 98 接近无损。更高的值不应带来更好的质量。
- 引发:
ValueError – 对于不支持的图像格式。
- tobytes(output='png', jpg_quality=95)#
v1.14.5 版本新增：以指定格式返回 pixmap 的 bytes 内存对象 – 类似于
save()。v1.22.0 版本修改：新增了直接 JPEG 支持。图像质量可以通过新参数“jpg_quality”影响。
- pdfocr_save(filename, compress=True, language='eng', tessdata=None)#
v1.19.0 新增
v1.22.5 版本修改：支持 Tesseract 的 tessdata 的新参数。
使用 Tesseract 执行文本识别，并将图像保存为带 OCR 文本层的单页 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_image()#
从 pixmap 创建 Pillow Image。必须安装 PIL / Pillow。
- 引发:
ImportError – 如果未安装 Pillow。
- 返回:
一个
PIL.Image对象
- pil_save(*args, unmultiply=False, **kwargs)#
使用 Pillow 将 pixmap 写入图像文件。对于 MuPDF 不支持的输出格式，请使用此方法。示例包括：
JPX, J2K, WebP 等格式。
存储 EXIF 信息。
如果您未提供 dpi 信息，将自动使用存储在 pixmap 中的 xres、yres 值。
一个简单示例：
pix.pil_save("some.webp", optimize=True, dpi=(150, 150))。- 参数:
unmultiply (bool) – 如果 pixmap 的颜色空间是带透明度的 RGB，alpha 值可能已乘入颜色分量红/绿/蓝（称为“预乘”）。要强制撤销预乘，请将此参数设置为
True。要了解一些背景知识，例如请在此页面上查找 “预乘 alpha”。
有关其他参数的详细信息，请参阅 Pillow 文档。
自 v1.22.0 版本起，PyMuPDF 直接支持 JPEG 输出。我们建议不再使用此方法进行 JPEG 输出 – 出于性能原因并避免不必要的外部依赖。
- 引发:
ImportError – 如果未安装 Pillow。
- pil_tobytes(*args, unmultiply=False, **kwargs)#
v1.17.3 新增
使用 Pillow 以指定格式将图像返回为 bytes 对象。例如
stream = pix.pil_tobytes(format="WEBP", optimize=True, dpi=(150, 150))。另请参阅上文。有关其他参数的详细信息，请参阅 Pillow 文档。- 引发:
ImportError – 如果未安装 Pillow。
- 返回类型:
bytes
- warp(quad, width, height)#
v1.19.3 新增
通过“扭曲” quad 返回一个新的 pixmap，使 quad 的角成为新 pixmap 的角。目标 pixmap 的 IRect 将是
(0, 0, width, height)。- 参数:
quad (quad_like) – 一个坐标位于
Pixmap.irect内部（包括边界点）的凸 quad。width (int) – 所需的结果宽度。
height (int) – 所需的结果高度。
- 返回:
一个新的 pixmap，其中 quad 的角按顺时针方向映射到 pixmap 的角：
quad.ul -> irect.tl,quad.ur -> irect.tr等。- 返回类型:
-
- color_count(colors=False, clip=None)#
v1.19.2 新增
v1.19.3 修改
确定 pixmap 的唯一颜色及其计数。
- 参数:
colors (bool) – (v1.19.3 版本修改) 如果为
True，则返回颜色像素及其使用计数的字典；否则仅返回唯一颜色的数量。clip (rect_like) –
Pixmap.irect内部的矩形。如果提供，则仅考虑这些像素。这允许直接检查给定 pixmap 的子矩形，而不是构建子 pixmap。
- 返回类型:
dict 或 int
- 返回:
要么是颜色的数量，要么是一个字典，其项为
像素: 计数。像素键是长度为Pixmap.n的bytes对象。注意
要恢复像素的 tuple，对于第 i 项，请使用
tuple(colors.keys()[i])。响应时间取决于 pixmap 的 samples 大小，对于非常大的 pixmap，可能超过一秒。
在适用情况下，具有不同 alpha 值的像素将被视为不同的颜色。
- color_topusage(clip=None)#
v1.19.3 新增
返回最常用的颜色及其相对频率。
- 参数:
clip (rect_like) –
Pixmap.irect内部的矩形。如果提供，则仅考虑这些像素。这允许直接检查给定 pixmap 的子矩形，而不是构建子 pixmap。- 返回类型:
tuple
- 返回:
一个 tuple
(ratio, pixel)，其中0 < ratio <= 1，pixel 是颜色的像素值。使用此方法可以判断图像是否“几乎”单色：响应(0.95, b"x00x00x00")表示所有像素中有 95% 是黑色。请参阅此处的一个示例 如何使用 Pixmap：检查文本可见性。
- alpha#
指示 pixmap 是否包含透明度信息。
- 类型:
bool
- digest#
pixmap 的 MD5 哈希码（16 字节）。这是用于唯一标识的技术值。
- 类型:
bytes
- colorspace#
pixmap 的颜色空间。如果图像被视为所谓的图像遮罩或模板遮罩（目前仅适用于提取的 PDF 文档图像），则此值可能为
None。- 类型:
- stride#
包含
Pixmap.samples中一行图像数据的长度。这主要用于计算。以下表达式为真：len(samples) == height * stridewidth * n == stride
- 类型:
int
- is_monochrome#
v1.19.2 新增
对于仅包含黑白两色的灰度 pixmap，其值为
True。- 类型:
bool
- is_unicolor#
v1.19.2 新增
如果所有像素都相同（任何颜色空间），则为
True。在适用情况下，具有不同 alpha 值的像素将被视为不同的颜色。- 类型:
bool
- samples#
所有像素的颜色值和（如果
Pixmap.alpha为真）透明度值。它是一个包含width * height * n字节的区域。每 n 个字节定义一个像素。连续的 n 个字节按扫描线顺序产生一个又一个像素。随后的扫描线之间没有填充。例如，对于 RGBA 颜色空间，这意味着 samples 是一个字节序列，如 …, R, G, B, A, …，并且四个字节值 R、G、B、A 定义一个像素。此区域可以传递给其他图形库，例如 PIL (Python Imaging Library)，以进行额外的处理，例如将 pixmap 保存为其他图像格式。
注意
底层数据通常是大型内存区域，每次访问此属性时都会从中创建
bytes副本... 例如，RGB 渲染的信纸页面 samples 大小将近 1.4 MB。因此，请考虑将其分配给新变量或使用memoryview版本Pixmap.samples_mv(v1.18.17 新增)。对底层数据的任何更改只有在再次访问此属性后才可用。这与使用 memoryview 版本不同。
- 类型:
bytes
- samples_mv#
v1.18.17 新增
类似于
Pixmap.samples，但采用 Pythonmemoryview格式。它直接指向 pixmap 中的内存，而不是副本。因此其创建速度与 pixmap 大小无关，并且对像素的任何更改将立即生效。诸如
bytearray(pix.samples_mv)或bytes(pixmap.samples_mv)之类的副本等同于pix.samples，并可替代使用。我们也知道
len(pix.samples) == len(pix.samples_mv)。看看这个 2MB 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)
Pixmap 销毁后，任何使用 memoryview 的尝试都将因 ValueError 而失败。
- 类型:
memoryview
- samples_ptr#
v1.18.17 新增
指向像素区域的 Python 指针。这是一种特殊的整数格式，支持的应用程序（例如 PyQt）可以使用它直接访问 samples 区域，从而极快地构建图像。例如：
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) 可以快数百倍，因为它避免了对像素区域的额外复制。
警告：Pixmap 销毁后，Python 指针将失效，尝试使用它可能会导致 Python 解释器崩溃。
- 类型:
int
- size#
包含 len(pixmap)。这通常等于 len(pix.samples) 加上一些平台特定的值，用于定义对象的其他属性。
- 类型:
int
- width#
- w#
区域的宽度（像素）。
- 类型:
int
- height#
- h#
区域的高度（像素）。
- 类型:
int
- x#
左上角的 X 坐标（像素）。无法直接更改 – 请使用
Pixmap.set_origin()。- 类型:
int
- y#
左上角的 Y 坐标（像素）。无法直接更改 – 请使用
Pixmap.set_origin()。- 类型:
int
- n#
每像素的分量数。此数字取决于颜色空间和 alpha。如果颜色空间不是
None（模板遮罩），则 Pixmap.n - Pixmap.alpha == pixmap.colorspace.n 为真。如果颜色空间为None，则 n == alpha == 1。- 类型:
int
- xres#
水平分辨率，单位 dpi (dots per inch)。另请参阅
resolution。无法直接更改 – 请使用Pixmap.set_dpi()。- 类型:
int
- yres#
垂直分辨率，单位 dpi (dots per inch)。另请参阅
resolution。无法直接更改 – 请使用Pixmap.set_dpi()。- 类型:
int
- interpolate#
一个仅供参考的布尔标志，如果图像将使用“线性插值”绘制，则设置为
True。如果为False，则将使用“最近邻采样”。- 类型:
bool
支持的输入图像格式#
以下文件类型支持作为构建 pixmap 的输入：BMP、JPEG、GIF、TIFF、JXR、JPX、PNG、PAM 以及所有 Portable Anymap 系列（PBM、PGM、PNM、PPM）。此支持分为两方面：
直接使用 Pixmap(filename) 或 Pixmap(byterray) 创建 pixmap。然后 pixmap 将具有由图像确定的属性。
使用 pymupdf.open(…) 打开此类文件。结果将显示为一个包含单页的文档。从此页面创建 pixmap 可以获得此上下文中的所有可用选项：应用矩阵、选择颜色空间和 alpha、将 pixmap 限制在剪裁区域等。
SVG 图像仅通过上述方法 2 支持，不能直接作为 pixmap。但请记住：结果是一个栅格图像，就像 pixmap 一样 [1]。
支持的输出图像格式#
支持多种图像输出格式。您可以选择将图像直接写入文件 (Pixmap.save())，或生成 bytes 对象 (Pixmap.tobytes())。这两种方法都接受一个字符串来标识所需的格式（下表中的格式列）。请注意，并非所有 pixmap 颜色空间、透明度支持 (alpha) 和图像格式的组合都是可能的。
格式 |
颜色空间 |
alpha |
扩展名 |
描述 |
|---|---|---|---|---|
jpg, jpeg |
gray, rgb, cmyk |
否 |
.jpg, .jpeg |
联合图像专家组 |
pam |
gray, rgb, cmyk |
是 |
.pam |
可移植任意位图 |
pbm |
gray, rgb |
否 |
.pbm |
可移植位图 |
pgm |
gray, rgb |
否 |
.pgm |
可移植灰度图 |
png |
gray, rgb |
是 |
.png |
可移植网络图形 |
pnm |
gray, rgb |
否 |
.pnm |
可移植任意图格式 |
ppm |
gray, rgb |
否 |
.ppm |
可移植像素图 |
ps |
gray, rgb, cmyk |
否 |
.ps |
Adobe PostScript 图像 |
psd |
gray, rgb, cmyk |
是 |
.psd |
Adobe Photoshop 文档 |
注意
并非所有图像文件类型都在所有操作系统平台中受支持（或至少常见）。例如，PAM 和 Portable Anymap 格式在 Windows 上很少见或甚至不为人知。
特别是涉及 CMYK 颜色空间时，您始终可以使用 rgb_pix = pymupdf.Pixmap(pymupdf.csRGB, cmyk_pix) 将 CMYK pixmap 转换为 RGB pixmap，然后以所需格式保存。
可以看出，MuPDF 的图像支持范围在输入和输出方面是不同的。在双向支持的格式中，PNG 和 JPEG 可能是最受欢迎的。
我们还建议使用“ppm”格式作为 tkinter 的 PhotoImage 方法的输入，如下所示：tkimg = tkinter.PhotoImage(data=pix.tobytes(“ppm”))（另请参阅教程）。这非常快（比 PNG 快60 倍）。
脚注