PyMuPDF 1.24.4 中文文档（九）（1）https://developer.aliyun.com/article/1559624
参数：
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 * stridewidth * 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
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（每英寸点数）。请参阅 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。
## 支持的输入图像格式
以下文件类型支持作为输入以构建像素图：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 版本。
点
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 轴的夹角的余弦和正弦值。
类型：
点
abs_unit
与上述 unit 相同，但用其绝对值替换坐标。
类型：
点
x
x 坐标
类型：
浮点数
y
y 坐标
类型：
浮点数
注意
- 此类遵循 Python 序列协议，因此也可以通过索引访问组件。还请参阅 在 PyMuPDF 中使用 Python 序列作为参数。
- 矩形可以使用算术运算符 – 见章节几何对象的运算代数。
对这个页面有任何反馈吗？
本软件按原样提供，不提供任何明示或暗示的保证。本软件根据许可证分发，未经许可不得复制、修改或分发。请参阅artifex.com上的许可信息或联系美国旧金山 94129 号 39 Mesa Street, Suite 108A 的 Artifex Software Inc.获取更多信息。
此文档覆盖了所有版本直到 1.24.4。
PyMuPDF 1.24.4 中文文档（九）（3）https://developer.aliyun.com/article/1559626
