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

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

四边形

原文：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 分别获得它们的四边形版本。
  

类 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

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

类型：

矩形

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 版本的所有内容。

备注

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

代数和包含检查

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

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

请注意以下有趣的细节：

对于矩形，只有它的左上角点属于它。自 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 版本的所有内容。

矩形

原文：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)可能属于矩形，其余三个角不会。一个空矩形根本不包含任何角。

• 这里是更改的概览。

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

类 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) 

1. 如果矩形是空的，则结果也是空的。
   
2. 可能的悖论：即使矩形不为空，结果可能为空！在这种情况下，显然结果中不包含矩形。这是因为 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。

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