PyMuPDF 1.24.4 中文文档（九）（1）

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

像素图

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

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

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

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

注意

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

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

类 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）– 是否包含透明通道。
  

注意

1. 下列方程式 必须为真：(colorspace.n + alpha) * width * height == len(samples)。
   
2. 从版本 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。

注意

1. 这种方法相当于对矩形中的每个像素执行 Pixmap.set_pixel()，但是如果涉及到许多像素，这显然速度更快。
   
2. 可以使用此方法类似于 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)) 

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

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

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

PyMuPDF 1.24.4 中文文档（九）（2）https://developer.aliyun.com/article/1559625