Rect#

Rect 表示由四个浮点数 x0, y0, x1, y1 定义的矩形。它们被视为对角相对的两个点（P(x0,y0) 和 P(x1,y1)）的坐标。前两个数字被视为“左上角”点 P(x0,y0)，P(x1,y1) 被视为“右下角”点。然而，这两个属性不一定与其直观含义一致——请继续阅读。

以下说明也适用于 IRect 对象

  • (Py-) MuPDF（和 PDF）中的矩形总是具有与 x 轴或 y 轴平行的边框。一个一般的正交四边形不是矩形——这与数学定义不同。

  • 构成点可以（几乎！——见下文）在平面上的任意位置——它们甚至不必不同，并且例如“左上角”不一定是几何意义上的“西北角”点。

  • 单位是点，其中 72 点等于 1 英寸。

  • 对于任何给定的四元组数字，几何意义上“相同”的矩形可以用四种不同的方式定义

    1. Rect(P(x0,y0), P(x1,y1))

    2. Rect(P(x1,y1), P(x0,y0))

    3. Rect(P(x0,y1), P(x1,y0))

    4. Rect(P(x1,y0), P(x0,y1))

(v1.19.0 中更改) 因此进行了一些分类

  • 如果 x0 <= x1 且 y0 <= y1（即右下角点位于左上角点的“东南”方向），则称矩形为 valid（有效），否则为 invalid（无效）。在上述四种备选方式中，只有第一种是有效的。请注意，在 MuPDF 的坐标系中，y 轴方向是自上而下的。在早期版本中，无效矩形曾被称为 infinite（无限）。

  • 如果 x0 >= x1 或 y0 >= y1，则称矩形为 empty（空）。这意味着 无效矩形也总是空的。 并且如果 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) 可以属于矩形——其他三个角点永远不属于。空矩形完全不包含任何角点。

    _images/img-rect-contains.png

  • 以下是更改概述。

    概念

    版本 < 1.19.0

    版本 1.19.*

    empty（空）

    x0 = x1 或 y0 = y1

    x0 >= x1 或 y0 >= y1 – 包括无效矩形

    valid（有效）

    不适用

    x0 <= x1 且 y0 <= y1

    infinite（无限）

    所有满足 x0 > x1 或 y1 > y0 的矩形

    恰好一个无限矩形 / 整数矩形 (irect)！

    坐标值

    所有数字

    FZ_MIN_INF_RECT <= number <= FZ_MAX_INF_RECT

    边界、角点

    是矩形的一部分

    右侧和底部角点和边缘在外部

  • 有新的顶级函数定义无限矩形和标准空矩形以及四边形，详见 INFINITE_RECT() 及相关函数。

方法 / 属性

简短描述

Rect.contains()

检查是否包含 point_likes 和 rect_likes

Rect.get_area()

计算矩形面积

Rect.include_point()

扩大矩形使其也包含一个点

Rect.include_rect()

扩大矩形使其也包含另一个矩形

Rect.intersect()

与另一个矩形的公共部分

Rect.intersects()

检查是否存在非空的交集

Rect.morph()

使用一个点和一个矩阵进行变换

Rect.torect()

将此矩形变换到另一个矩形的矩阵

Rect.norm()

欧几里得范数

Rect.normalize()

使矩形有效

Rect.round()

创建包含此矩形的最小 IRect

Rect.transform()

使用矩阵变换矩形

Rect.bottom_left

左下角点，同义词 bl

Rect.bottom_right

右下角点，同义词 br

Rect.height

矩形高度

Rect.irect

等于 method round() 的结果

Rect.is_empty

矩形是否为空

Rect.is_valid

矩形是否有效

Rect.is_infinite

矩形是否无限

Rect.top_left

左上角点，同义词 tl

Rect.top_right

右上角点，同义词 tr

Rect.quad

由矩形角点构成的 Quad

Rect.width

矩形宽度

Rect.x0

左侧角点的 x 坐标

Rect.x1

右侧角点的 x 坐标

Rect.y0

顶部角点的 y 坐标

Rect.y1

底部角点的 y 坐标

类 API

类 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 (matrix_like) – 用于变换的矩阵。

返回类型：

Rect

返回：

包含变换后原矩形的最小矩形。

intersect(r)#

计算当前矩形与 r 的交集（共同的矩形区域，包含在两者中的最大矩形），并替换当前矩形。如果任一矩形为空，结果也为空。如果 r 是无限矩形，此操作无效。如果矩形是（数学上）不相交的集合，则结果为无效矩形。如果结果有效但为空，则矩形在角点或（部分）边上相互接触。

参数：

r (rect_like) – 第二个矩形

include_rect(r)#

计算包含当前矩形和 r 的最小矩形，并替换当前矩形。如果任一矩形是无限矩形，结果也为无限矩形。如果 r 为空，则当前矩形保持不变。否则，如果当前矩形为空，则被 r 替换。

参数：

r (rect_like) – 第二个矩形

include_point(p)#

计算包含当前矩形和 point_like p 的最小矩形，并替换当前矩形。无限矩形保持不变。要创建一个包含点序列的矩形，可以从 EMPTY_RECT() 开始，然后依次包含序列中的成员。

参数：

p (point_like) – 要包含的点。

get_area([unit])#

计算矩形面积，不带参数时等于 abs(rect)。与空矩形一样，无限矩形的面积也为零。因此，pymupdf.Rect(p1, p2) 和 pymupdf.Rect(p2, p1) 中至少有一个面积为零。

参数：

unit (str) – 指定所需单位：px（像素，默认）、in（英寸）、cm（厘米）或 mm（毫米）的相应平方。

返回类型：

float

contains(x)#

检查 x 是否包含在矩形中。x 可以是 IRect, Rect, Point 或数字。如果 x 是空矩形，则此操作始终为真。如果矩形为空，则对于所有非空矩形和所有点，此操作始终为 False。 x in rect 和 rect.contains(x) 等效。

参数：

x (rect_like 或 point_like。) – 要检查的对象。

返回类型：

bool

intersects(r)#

检查当前矩形和 rect_like “r”是否包含共同的非空 Rect。如果任一矩形为无限或为空，此操作始终为 False。

参数：

r (rect_like) – 要检查的矩形。

返回类型：

bool

torect(rect)#

  • 1.19.3 版本新增

计算将此矩形变换为给定矩形的矩阵。

参数：

rect (rect_like) – 目标矩形。不能为空或无限矩形。

返回类型：

Matrix

返回：

一个矩阵 mat，使得 self * mat = rect。例如，可用于在页面坐标和像素图坐标之间进行变换。请参阅此处的示例用法：如何使用像素图：检查文本可见性。

morph(fixpoint, matrix)#

  • 1.17.0 版本新增

使用固定点 fixpoint 将矩阵应用于矩形后，返回一个新的 Quad。

参数：

  • fixpoint (point_like) – 固定点。

  • matrix (matrix_like) – 矩阵。

返回：

一个新的 Quad。这是同名 quad 方法的封装。如果是无限矩形，则返回无限四边形。

norm()#

  • 1.16.0 版本新增

将矩形视为四个数字的向量，返回其欧几里得范数。

normalize()#

将矩形替换为其有效版本。这是通过重新排列矩形角点实现的。此方法完成后，右下角点确实会位于左上角点（one refers to point）的东南方向（但仍可能为空）。

irect#

等于 method 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)。

返回类型：

float

height#

矩形的高度。等于 max(y1 - y0, 0)。

返回类型：

float

x0#

左侧角点的 X 坐标。

类型：

float

y0#

顶部角点的 Y 坐标。

类型：

float

x1#

右侧角点的 x 坐标

类型：

float

y1#

底部角点的 y 坐标。

类型：

float

is_infinite#

如果这是无限矩形，则为 True。

类型：

bool

is_empty#

如果矩形为空，则为 True。

类型：

bool

is_valid#

如果矩形有效，则为 True。

类型：

bool

注意

本软件按原样提供，不附带任何明示或暗示的保证。本软件根据许可协议分发，未经该许可协议明确授权，不得复制、修改或分发。有关许可信息，请访问 artifex.com 或联系 Artifex Software Inc., 39 Mesa Street, Suite 108A, San Francisco CA 94129, United States 以获取更多信息。

本文档涵盖至 1.26.0 版的所有内容。