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

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 * 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

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)。这种支持是双重的：

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

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

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

注意

• 并非所有图像文件类型都在所有操作系统平台上都受支持（或至少常见）。例如，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）。此支持具有双重性：

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

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

支持的输出图像格式

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

注

• 并非所有图像文件类型在所有操作系统平台上都受支持（或至少是常见的）。例如，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 版本。

点

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

Point 表示平面上的一个点，由其 x 和 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