primitives.geometry

geometry

几何基础模块 (geometry)

此模块提供了用于处理几何图形和坐标系统的基础类，包括点、向量、矩形等几何对象的表示和操作。

主要功能

• 坐标系统：提供二维、三维、四维坐标的表示
• 点操作：支持整数和浮点数坐标点的各种运算
• 矩形操作：提供矩形的创建、变换、相交检测等功能
• 向量运算：支持向量的加减乘除、距离计算、单位化等操作
• 类型安全：使用泛型和类型守卫确保类型安全

核心类

• Vector2D - 二维向量，支持泛型
• Vector3D - 三维向量，适用于颜色和空间坐标
• Vector4D - 四维向量，适用于 RGBA 等场景
• Point - 整数坐标点，适用于像素定位
• PointF - 浮点数坐标点，适用于精确计算
• Rect - 矩形类，提供丰富的几何操作

使用示例

# 坐标点操作
p1 = Point(100, 200, name="起始点")
p2 = PointF(150.5, 250.8)
distance = p1.distance_to(p2)

# 矩形操作
rect = Rect(10, 20, 100, 50, name="按钮区域")
center = rect.center
enlarged = rect.inflate(5, 5)

# 向量运算
v1 = Vector2D(10, 20)
v2 = Vector2D(5, 8)
result = v1 + v2

注意事项

• 所有坐标系统遵循屏幕坐标系，原点在左上角
• 矩形操作使用半开区间规则：[x1, x2) x [y1, y2)
• 点和向量的运算会根据输入类型自动选择返回类型

类：

名称	描述
Vector2D	Vector2D
Vector3D	Vector3D
Vector4D	Vector4D
PointF	PointF
Point	Point
Rect	Rect

函数：

名称	描述
unify_point	将点或元组统一转换为 Point 对象。
unify_pointf	将点或元组统一转换为 PointF 对象。
unify_any_point	将点或元组统一转换为 Point 或 PointF 对象。
unify_rect	将矩形或元组 (x, y, w, h) 统一转换为 Rect 对象。

属性：

名称	类型	描述
RectTuple		矩形。(x, y, w, h)
PointTuple		点。(x, y)
PointFTuple		浮点数点。(x, y)
Size		尺寸。相当于 Vector2D[int]
SizeTuple		尺寸。(width, height)
SizeLike		尺寸类型，可以是 Size 对象或尺寸元组。
Number		数字类型，可以是整数或浮点数。
AnyPoint		任意 Point 对象，包括 Point 与 PointF。
AnyPointTuple		任意 Point 元组，包括 tuple[int, int] 与 tuple[float, float]。
AnyPointLike		任意类似于 Point 的对象，包括 Point、PointF、tuple[int, int]、tuple[float, float]。
RectLike		任意类似于 Rect 的对象，包括 Rect、tuple[int, int, int, int]。

RectTuple module-attribute

RectTuple = tuple[int, int, int, int]

矩形。(x, y, w, h)

PointTuple module-attribute

PointTuple = tuple[int, int]

点。(x, y)

PointFTuple module-attribute

PointFTuple = tuple[float, float]

浮点数点。(x, y)

Size module-attribute

Size = Vector2D[int]

尺寸。相当于 Vector2D[int]

SizeTuple module-attribute

SizeTuple = tuple[int, int]

尺寸。(width, height)

SizeLike module-attribute

SizeLike = Union[Size, SizeTuple]

尺寸类型，可以是 Size 对象或尺寸元组。

Number module-attribute

Number = TypeVar('Number', int, float)

数字类型，可以是整数或浮点数。

AnyPoint module-attribute

AnyPoint = Union[Point, PointF]

任意 Point 对象，包括 Point 与 PointF。

AnyPointTuple module-attribute

AnyPointTuple = Union[PointTuple, PointFTuple]

任意 Point 元组，包括 tuple[int, int] 与 tuple[float, float]。

AnyPointLike module-attribute

AnyPointLike = Union[AnyPoint, AnyPointTuple]

任意类似于 Point 的对象，包括 Point、PointF、tuple[int, int]、tuple[float, float]。

RectLike module-attribute

RectLike = Union[Rect, RectTuple]

任意类似于 Rect 的对象，包括 Rect、tuple[int, int, int, int]。

Vector2D

Bases: Generic[T]

Vector2D

表示一个二维向量。此类支持泛型，可用于表示不同类型的坐标（如整数、浮点数等）。

例

# 创建二维坐标
v = Vector2D(10, 20, name="位置")
print(v.x, v.y)  # 10, 20

# 使用索引访问
print(v[0], v[1])  # 10, 20

# 坐标计算
v2 = Vector2D(5, 8)
print(f"坐标距离: {math.sqrt((v.x - v2.x)**2 + (v.y - v2.y)**2):.2f}")

# 支持命名坐标
center = Vector2D(640, 360, name="屏幕中心")
print(center)  # Point<"屏幕中心" at (640, 360)>

方法：

名称	描述
as_tuple	Return coordinates as a tuple of ints: (x, y).

属性：

名称	类型	描述
name	str | None	坐标的名称。

name instance-attribute

name: str | None = name

坐标的名称。

as_tuple

as_tuple() -> tuple[T, T]

Return coordinates as a tuple of ints: (x, y).

Vector3D

Bases: Generic[T]

Vector3D

表示一个三维向量。

例

# 创建三维坐标
v3 = Vector3D(100, 200, 50, name="3D点")
print(v3.x, v3.y, v3.z)  # 100, 200, 50

# 使用索引访问
print(v3[0], v3[1], v3[2])  # 100, 200, 50

# 解构
x, y, z = v3.xyz  # (100, 200, 50)
x, y = v3.xy    # (100, 200)

# 颜色值应用
rgb = Vector3D(255, 128, 64, name="颜色")
print(f"RGB: {rgb.rgb if hasattr(v3, 'rgb') else '未定义'}")

方法：

名称	描述
as_tuple	Return coordinates as a tuple of ints: (x, y, z).

属性：

名称	类型	描述
name	str | None	坐标的名称。
xyz	tuple[T, T, T]	三元组 (x, y, z)。OpenCV 格式的坐标。
xy	tuple[T, T]	二元组 (x, y)。OpenCV 格式的坐标。

name instance-attribute

name: str | None = name

坐标的名称。

xyz property

xyz: tuple[T, T, T]

三元组 (x, y, z)。OpenCV 格式的坐标。

xy property

xy: tuple[T, T]

二元组 (x, y)。OpenCV 格式的坐标。

as_tuple

as_tuple() -> tuple[T, T, T]

Return coordinates as a tuple of ints: (x, y, z).

Vector4D

Bases: Generic[T]

Vector4D

此类用于表示四维坐标或向量，通常用于颜色空间（如RGBA）等场景。

例

# 创建四维坐标
v4 = Vector4D(100, 200, 150, 255, name="颜色值")
print(f"RGBA: {v4.x}, {v4.y}, {v4.z}, {v4.w}")  # 100, 200, 150, 255

# 使用索引访问
print(v4[0], v4[1], v4[2], v4[3])  # 100, 200, 150, 255

# 在颜色空间中使用
color = Vector4D(255, 0, 0, 128, name="半透明红色")
print(f"颜色: {color}")

# 四维向量运算
v4_2 = Vector4D(50, 50, 50, 100)
# 注意：Vector4D 未定义运算，但可用于数据存储

方法：

名称	描述
as_tuple	Return coordinates as a tuple of ints: (x, y, z, w).

属性：

名称	类型	描述
name	str | None	坐标的名称。

name instance-attribute

name: str | None = name

坐标的名称。

as_tuple

as_tuple() -> tuple[T, T, T, T]

Return coordinates as a tuple of ints: (x, y, z, w).

PointF

Bases: _BasePoint[float]

PointF

表示浮点数坐标点。

例

# 创建浮点数坐标点
p1 = PointF(10.5, 20.7, name="精确位置")
p2 = PointF(5.2, 8.9)

# 距离计算
distance = p1.distance_to(p2)  # 计算到另一点的距离
print(f"距离: {distance:.2f}")

# 向量运算
result = p1 + p2  # 坐标相加
scaled = p1 * 2   # 坐标缩放

# 单位向量
unit = p1.normalized()  # 转换为单位向量

# 坐标偏移
moved = p1.offset(5.0, 10.0)  # 偏移坐标

方法：

名称	描述
as_tuple	Return coordinates as a tuple of ints: (x, y).
distance_to	计算到另一个点的距离。
__eq__	比较两个点是否相等。
__lt__	小于比较，按 (x, y) 的字典序进行比较。
__le__	小于等于比较，按 (x, y) 的字典序比较。
__gt__	大于比较，按 (x, y) 的字典序比较。
__ge__	大于等于比较，按 (x, y) 的字典序比较。
normalized	返回一个新的、方向相同但长度为 1 的 PointF 对象（单位向量）。
offset	偏移坐标。
__add__	与另一个点或元组相加。
__sub__	与另一个点或元组相减。
__mul__	与标量相乘（缩放）。
__truediv__	与标量相除（缩放）。总是返回一个 PointF 对象。

属性：

名称	类型	描述
name	str | None	坐标的名称。
xy	NumberTuple2D	二元组 (x, y)。
length	float	将点视为从原点出发的向量，其长度（模）。

name instance-attribute

name: str | None = name

坐标的名称。

xy property

xy: NumberTuple2D

二元组 (x, y)。

返回：

类型	描述
NumberTuple2D	包含 x 和 y 坐标的元组。

length property

length: float

将点视为从原点出发的向量，其长度（模）。

返回：

类型	描述
float	向量长度。

as_tuple

as_tuple() -> tuple[T, T]

Return coordinates as a tuple of ints: (x, y).

distance_to

distance_to(other: AnyPoint | AnyPointTuple) -> float

计算到另一个点的距离。

参数：

名称	类型	描述	默认
other	AnyPoint | AnyPointTuple	另一个点或元组。	必需

返回：

类型	描述
float	距离。

__eq__

__eq__(value: object) -> bool

比较两个点是否相等。

参数：

名称	类型	描述	默认
value	object	另一个点。	必需

返回：

类型	描述
bool	如果坐标相等则返回 True，否则返回 False。

__lt__

__lt__(other: AnyPoint | AnyPointTuple) -> bool

小于比较，按 (x, y) 的字典序进行比较。 支持 Point / PointF 或长度为2的元组/列表。

__le__

__le__(other: AnyPoint | AnyPointTuple) -> bool

小于等于比较，按 (x, y) 的字典序比较。

__gt__

__gt__(other: AnyPoint | AnyPointTuple) -> bool

大于比较，按 (x, y) 的字典序比较。

__ge__

__ge__(other: AnyPoint | AnyPointTuple) -> bool

大于等于比较，按 (x, y) 的字典序比较。

normalized

normalized() -> PointF

返回一个新的、方向相同但长度为 1 的 PointF 对象（单位向量）。

返回：

类型	描述
PointF	单位向量。

offset

offset(dx: int | float, dy: int | float) -> AnyPoint

偏移坐标。

如果 self, dx, dy 均为整数，返回 Point。否则返回 PointF。

参数：

名称	类型	描述	默认
dx	int | float	x方向偏移量。	必需
dy	int | float	y方向偏移量。	必需

返回：

类型	描述
AnyPoint	偏移后的新 Point 或 PointF 对象。

__add__

__add__(other: Point | PointTuple) -> Point

__add__(other: PointF | PointFTuple) -> PointF

__add__(other: AnyPoint | AnyPointTuple) -> PointF

__add__(other: AnyPoint | AnyPointTuple) -> AnyPoint

与另一个点或元组相加。

如果任一操作数为浮点数，则结果提升为 PointF。

参数：

名称	类型	描述	默认
other	AnyPoint | AnyPointTuple	另一个 Point/PointF 对象或元组。	必需

返回：

类型	描述
AnyPoint	相加后的新 Point 或 PointF 对象。

__sub__

__sub__(other: Point | PointTuple) -> Point

__sub__(other: PointF | PointFTuple) -> PointF

__sub__(other: AnyPoint | AnyPointTuple) -> PointF

__sub__(other: AnyPoint | AnyPointTuple) -> AnyPoint

与另一个点或元组相减。

如果任一操作数为浮点数，则结果提升为 PointF。

参数：

名称	类型	描述	默认
other	AnyPoint | AnyPointTuple	另一个 Point/PointF 对象或元组。	必需

返回：

类型	描述
AnyPoint	相减后的新 Point 或 PointF 对象。

__mul__

__mul__(scalar: int) -> Point

__mul__(scalar: float) -> PointF

__mul__(scalar: int | float) -> AnyPoint

与标量相乘（缩放）。

参数：

名称	类型	描述	默认
scalar	int | float	用于缩放的标量。	必需

返回：

类型	描述
AnyPoint	缩放后的新 Point 或 PointF 对象。

__truediv__

__truediv__(scalar: int | float) -> PointF

与标量相除（缩放）。总是返回一个 PointF 对象。

参数：

名称	类型	描述	默认
scalar	int | float	用于缩放的标量。	必需

返回：

类型	描述
PointF	缩放后的新 PointF 对象。

Point

Bases: _BasePoint[int]

Point

表示整数坐标点。

例

# 创建整数坐标点
pixel = Point(1920, 1080, name="屏幕分辨率")
button = Point(100, 200, name="按钮位置")

# 像素定位操作
center = Point(640, 360)
offset = center.offset(10, -5)  # 向右移动10像素，向下移动5像素

# 点与点的运算
distance = center.distance_to(button)
relative_pos = button - center  # 相对位置

# 检查点是否相等
if center == Point(640, 360):
    print("找到了中心点")

# 与浮点数运算时会自动转换为PointF
precise = center + (5.5, 3.2)  # 结果为PointF类型

方法：

名称	描述
as_tuple	Return coordinates as a tuple of ints: (x, y).
distance_to	计算到另一个点的距离。
__eq__	比较两个点是否相等。
__lt__	小于比较，按 (x, y) 的字典序进行比较。
__le__	小于等于比较，按 (x, y) 的字典序比较。
__gt__	大于比较，按 (x, y) 的字典序比较。
__ge__	大于等于比较，按 (x, y) 的字典序比较。
normalized	返回一个新的、方向相同但长度为 1 的 PointF 对象（单位向量）。
offset	偏移坐标。
__add__	与另一个点或元组相加。
__sub__	与另一个点或元组相减。
__mul__	与标量相乘（缩放）。
__truediv__	与标量相除（缩放）。总是返回一个 PointF 对象。

属性：

名称	类型	描述
name	str | None	坐标的名称。
xy	NumberTuple2D	二元组 (x, y)。
length	float	将点视为从原点出发的向量，其长度（模）。

name instance-attribute

name: str | None = name

坐标的名称。

xy property

xy: NumberTuple2D

二元组 (x, y)。

返回：

类型	描述
NumberTuple2D	包含 x 和 y 坐标的元组。

length property

length: float

将点视为从原点出发的向量，其长度（模）。

返回：

类型	描述
float	向量长度。

as_tuple

as_tuple() -> tuple[T, T]

Return coordinates as a tuple of ints: (x, y).

distance_to

distance_to(other: AnyPoint | AnyPointTuple) -> float

计算到另一个点的距离。

参数：

名称	类型	描述	默认
other	AnyPoint | AnyPointTuple	另一个点或元组。	必需

返回：

类型	描述
float	距离。

__eq__

__eq__(value: object) -> bool

比较两个点是否相等。

参数：

名称	类型	描述	默认
value	object	另一个点。	必需

返回：

类型	描述
bool	如果坐标相等则返回 True，否则返回 False。

__lt__

__lt__(other: AnyPoint | AnyPointTuple) -> bool

小于比较，按 (x, y) 的字典序进行比较。 支持 Point / PointF 或长度为2的元组/列表。

__le__

__le__(other: AnyPoint | AnyPointTuple) -> bool

小于等于比较，按 (x, y) 的字典序比较。

__gt__

__gt__(other: AnyPoint | AnyPointTuple) -> bool

大于比较，按 (x, y) 的字典序比较。

__ge__

__ge__(other: AnyPoint | AnyPointTuple) -> bool

大于等于比较，按 (x, y) 的字典序比较。

normalized

normalized() -> PointF

返回一个新的、方向相同但长度为 1 的 PointF 对象（单位向量）。

返回：

类型	描述
PointF	单位向量。

offset

offset(dx: int | float, dy: int | float) -> AnyPoint

偏移坐标。

如果 self, dx, dy 均为整数，返回 Point。否则返回 PointF。

参数：

名称	类型	描述	默认
dx	int | float	x方向偏移量。	必需
dy	int | float	y方向偏移量。	必需

返回：

类型	描述
AnyPoint	偏移后的新 Point 或 PointF 对象。

__add__

__add__(other: Point | PointTuple) -> Point

__add__(other: PointF | PointFTuple) -> PointF

__add__(other: AnyPoint | AnyPointTuple) -> PointF

__add__(other: AnyPoint | AnyPointTuple) -> AnyPoint

与另一个点或元组相加。

如果任一操作数为浮点数，则结果提升为 PointF。

参数：

名称	类型	描述	默认
other	AnyPoint | AnyPointTuple	另一个 Point/PointF 对象或元组。	必需

返回：

类型	描述
AnyPoint	相加后的新 Point 或 PointF 对象。

__sub__

__sub__(other: Point | PointTuple) -> Point

__sub__(other: PointF | PointFTuple) -> PointF

__sub__(other: AnyPoint | AnyPointTuple) -> PointF

__sub__(other: AnyPoint | AnyPointTuple) -> AnyPoint

与另一个点或元组相减。

如果任一操作数为浮点数，则结果提升为 PointF。

参数：

名称	类型	描述	默认
other	AnyPoint | AnyPointTuple	另一个 Point/PointF 对象或元组。	必需

返回：

类型	描述
AnyPoint	相减后的新 Point 或 PointF 对象。

__mul__

__mul__(scalar: int) -> Point

__mul__(scalar: float) -> PointF

__mul__(scalar: int | float) -> AnyPoint

与标量相乘（缩放）。

参数：

名称	类型	描述	默认
scalar	int | float	用于缩放的标量。	必需

返回：

类型	描述
AnyPoint	缩放后的新 Point 或 PointF 对象。

__truediv__

__truediv__(scalar: int | float) -> PointF

与标量相除（缩放）。总是返回一个 PointF 对象。

参数：

名称	类型	描述	默认
scalar	int | float	用于缩放的标量。	必需

返回：

类型	描述
PointF	缩放后的新 PointF 对象。

Rect

Rect

表示一个矩形区域，支持多种坐标格式和几何操作。

例

# 创建矩形
rect = Rect(10, 20, 100, 50, name="按钮区域")
rect2 = Rect(xywh=(10, 20, 100, 50))

# 从两点创建矩形
rect3 = Rect.from_xyxy(10, 20, 110, 70)

# 获取矩形属性
print(rect.center)     # 中心点
print(rect.size)       # (100, 50)
print(rect.top_left)   # 左上角点，其他三个角落同理

# 矩形操作
moved = rect.move(10, 10)      # 原地移动
copied = rect.moved(5, 15)     # 移动后的新矩形
enlarged = rect.inflate(5, 5)  # 原地扩大

# 几何计算
if rect.contains_point(Point(50, 40)):
    print("点在矩形内")

if rect.intersects_with(other_rect):
    print("两个矩形相交")

union = rect.union_of(other_rect)      # 并集
intersection = rect.intersection_of(other_rect)  # 交集

方法：

名称	描述
__init__	从给定的坐标信息创建矩形。
from_xyxy	从 (x1, y1, x2, y2) 创建矩形。
copy	返回一个与当前对象完全相同的新 Rect 对象。
move	原地移动矩形。
moved	返回一个移动后的新 Rect 对象。
inflate	原地缩放矩形（中心点不变）。
inflated	返回一个缩放后的新 Rect 对象。
normalize	原地修正矩形，确保 width 和 height 为正数。
normalized	返回一个修正后的新 Rect 对象，确保 width 和 height 为正数。
contains_point	检查一个点是否在此矩形内部。
contains_rect	检查此矩形是否完全包含另一个矩形。
intersects_with	检查此矩形是否与另一个矩形相交。
union_of	返回一个能同时包含两个矩形的新 Rect 对象（并集）。
intersection_of	返回两个矩形相交区域的新 Rect 对象（交集）。
is_empty	如果矩形的 width 或 height 小于等于零，则返回 True。
__contains__	判断点或矩形是否被此矩形包含。

属性：

名称	类型	描述
x1		矩形左上角的 X 坐标。
y1		矩形左上角的 Y 坐标。
w		矩形的宽度。
h		矩形的高度。
name	str | None	矩形的名称。
x2	int	矩形右下角的 X 坐标。
y2	int	矩形右下角的 Y 坐标。
xywh	RectTuple	四元组 (x1, y1, w, h)。OpenCV 格式的坐标。
xyxy	RectTuple	四元组 (x1, y1, x2, y2)。
top_left	Point	矩形的左上角点。
bottom_right	Point	矩形的右下角点。
left_bottom	Point	矩形的左下角点。
right_top	Point	矩形的右上角点。
center	Point	矩形的中心点。
center_x	int	中心点的 x 坐标。
center_y	int	中心点的 y 坐标。
middle_top	Point	矩形顶部边的中点。
middle_bottom	Point	矩形底部边的中点。
middle_left	Point	矩形左侧边的中点。
middle_right	Point	矩形右侧边的中点。
size	tuple[int, int]	一个 (width, height) 元组。

x1 instance-attribute

x1 = int(x)

矩形左上角的 X 坐标。

y1 instance-attribute

y1 = int(y)

矩形左上角的 Y 坐标。

w instance-attribute

w = int(w)

矩形的宽度。

h instance-attribute

h = int(h)

矩形的高度。

name instance-attribute

name: str | None = name

矩形的名称。

x2 property writable

x2: int

矩形右下角的 X 坐标。

y2 property writable

y2: int

矩形右下角的 Y 坐标。

xywh property

xywh: RectTuple

四元组 (x1, y1, w, h)。OpenCV 格式的坐标。

xyxy property

xyxy: RectTuple

四元组 (x1, y1, x2, y2)。

top_left property

top_left: Point

矩形的左上角点。

bottom_right property

bottom_right: Point

矩形的右下角点。

left_bottom property

left_bottom: Point

矩形的左下角点。

right_top property

right_top: Point

矩形的右上角点。

center property

center: Point

矩形的中心点。

返回：

类型	描述
Point	中心点 Point 对象。

center_x property

center_x: int

中心点的 x 坐标。

返回：

类型	描述
int	中心点的 x 坐标。

center_y property

center_y: int

中心点的 y 坐标。

返回：

类型	描述
int	中心点的 y 坐标。

middle_top property

middle_top: Point

矩形顶部边的中点。

返回：

类型	描述
Point	顶部边的中点。

middle_bottom property

middle_bottom: Point

矩形底部边的中点。

返回：

类型	描述
Point	底部边的中点。

middle_left property

middle_left: Point

矩形左侧边的中点。

返回：

类型	描述
Point	左侧边的中点。

middle_right property

middle_right: Point

矩形右侧边的中点。

返回：

类型	描述
Point	右侧边的中点。

size property writable

size: tuple[int, int]

一个 (width, height) 元组。

返回：

类型	描述
tuple[int, int]	包含宽度和高度的元组。

__init__

__init__(x: int | None = None, y: int | None = None, w: int | None = None, h: int | None = None, *, xywh: RectTuple | None = None, name: str | None = None)

从给定的坐标信息创建矩形。

参数 x, y, w, h 和 xywh 必须至少指定一组。

参数：

名称	类型	描述	默认
x	int | None	矩形左上角的 X 坐标。	None
y	int | None	矩形左上角的 Y 坐标。	None
w	int | None	矩形的宽度。	None
h	int | None	矩形的高度。	None
xywh	RectTuple | None	四元组 (x, y, w, h)。	None
name	str | None	矩形的名称。	None

引发：

类型	描述
ValueError	提供的坐标参数不完整时抛出。

from_xyxy classmethod

from_xyxy(x1: int, y1: int, x2: int, y2: int) -> Rect

从 (x1, y1, x2, y2) 创建矩形。

返回：

类型	描述
Rect	创建结果。

copy

copy() -> Rect

返回一个与当前对象完全相同的新 Rect 对象。

返回：

类型	描述
Rect	当前 Rect 对象的一个副本。

move

move(dx: int, dy: int) -> Rect

原地移动矩形。

参数：

名称	类型	描述	默认
dx	int	x 方向的移动距离。	必需
dy	int	y 方向的移动距离。	必需

返回：

类型	描述
Rect	移动后的矩形本身。

moved

moved(dx: int, dy: int) -> Rect

返回一个移动后的新 Rect 对象。

参数：

名称	类型	描述	默认
dx	int	x 方向的移动距离。	必需
dy	int	y 方向的移动距离。	必需

返回：

类型	描述
Rect	移动后的新 Rect 对象。

inflate

inflate(dx: int, dy: int) -> Rect

原地缩放矩形（中心点不变）。

矩形的宽度增加 2 * dx，高度增加 2 * dy。 负值会缩小矩形。

参数：

名称	类型	描述	默认
dx	int	宽度方向的膨胀量（每边）。	必需
dy	int	高度方向的膨胀量（每边）。	必需

返回：

类型	描述
Rect	缩放后的矩形本身。

inflated

inflated(dx: int, dy: int) -> Rect

返回一个缩放后的新 Rect 对象。

参数：

名称	类型	描述	默认
dx	int	宽度方向的膨胀量（每边）。 param dy: 高度方向的膨胀量（每边）。	必需

返回：

类型	描述
Rect	缩放后的新 Rect 对象。

normalize

normalize() -> Rect

原地修正矩形，确保 width 和 height 为正数。

如果宽度或高度为负，则交换坐标以使其为正。

返回：

类型	描述
Rect	修正后的矩形本身。

normalized

normalized() -> Rect

返回一个修正后的新 Rect 对象，确保 width 和 height 为正数。

返回：

类型	描述
Rect	修正后的新 Rect 对象。

contains_point

contains_point(point: AnyPoint | PointTuple | PointFTuple) -> bool

检查一个点是否在此矩形内部。

.. note:: 对于边界值，左边界与上边界包含，而右边界与下边界不包含。

例如 `Rect(0, 0, 10, 10)` 包含 `Point(0, 0)`，但不包含 `Point(10, 10)`。

参数：

名称	类型	描述	默认
point	AnyPoint | PointTuple | PointFTuple	要检查的点。	必需

返回：

类型	描述
bool	如果点在矩形内，则返回 True。

contains_rect

contains_rect(other_rect: Rect) -> bool

检查此矩形是否完全包含另一个矩形。

参数：

名称	类型	描述	默认
other_rect	Rect	要检查的另一个矩形。	必需

返回：

类型	描述
bool	是否完全包含。

intersects_with

intersects_with(other_rect: Rect) -> bool

检查此矩形是否与另一个矩形相交。

.. note:: 若两个矩形只有边界重叠，不算做相交。

参数：

名称	类型	描述	默认
other_rect	Rect	要检查的另一个矩形。	必需

返回：

类型	描述
bool	如果两个矩形相交，则返回 True。

union_of

union_of(other_rect: Rect) -> Rect

返回一个能同时包含两个矩形的新 Rect 对象（并集）。

参数：

名称	类型	描述	默认
other_rect	Rect	要合并的另一个矩形。	必需

返回：

类型	描述
Rect	包含两个矩形的最小矩形。

intersection_of

intersection_of(other_rect: Rect) -> Rect | None

返回两个矩形相交区域的新 Rect 对象（交集）。

如果不相交，则返回 None。

参数：

名称	类型	描述	默认
other_rect	Rect	要计算交集的另一个矩形。	必需

返回：

类型	描述
Rect | None	相交区域的矩形，或 None。

is_empty

is_empty() -> bool

如果矩形的 width 或 height 小于等于零，则返回 True。

返回：

类型	描述
bool	如果矩形为空，则返回 True。

__contains__

__contains__(obj: Point | PointTuple | PointF | PointFTuple) -> bool

__contains__(obj: Rect) -> bool

__contains__(obj: AnyPoint | PointTuple | PointFTuple | Rect) -> bool

判断点或矩形是否被此矩形包含。

• 如果传入的是点或点元组，等价于 Rect.contains_point。
• 如果传入的是 Rect，则判断整个矩形是否被包含（完全包含）。

参数：

名称	类型	描述	默认
obj	AnyPoint | PointTuple | PointFTuple | Rect	要检查的点或矩形。	必需

返回：

类型	描述
bool	如果被包含则返回 True。

unify_point

unify_point(point: PointLike) -> Point

将点或元组统一转换为 Point 对象。

参数：

名称	类型	描述	默认
point	PointLike	要转换的点或元组。	必需

返回：

类型	描述
Point	转换后的 Point 对象。

引发：

类型	描述
TypeError	如果输入类型不正确则抛出。 .. note:: 若输入数据为 float，会被强制转换为 int。

unify_pointf

unify_pointf(point: PointLike) -> PointF

将点或元组统一转换为 PointF 对象。

参数：

名称	类型	描述	默认
point	PointLike	要转换的点或元组。	必需

返回：

类型	描述
PointF	转换后的 PointF 对象。

引发：

类型	描述
TypeError	如果输入类型不正确则抛出。

unify_any_point

unify_any_point(point: AnyPointLike) -> Point | PointF

将点或元组统一转换为 Point 或 PointF 对象。

如果输入已是 Point 或 PointF 对象，直接返回。 如果输入是元组，根据其数值类型决定返回类型： - 若所有坐标为整数，返回 Point - 若有任何坐标为浮点数，返回 PointF

参数：

名称	类型	描述	默认
point	AnyPointLike	要转换的点或元组。	必需

返回：

类型	描述
Point | PointF	转换后的 Point 或 PointF 对象。

引发：

类型	描述
TypeError	如果输入类型不正确则抛出。

unify_rect

unify_rect(rect: RectLike) -> Rect

将矩形或元组 (x, y, w, h) 统一转换为 Rect 对象。

参数：

名称	类型	描述	默认
rect	RectLike	要转换的矩形或元组。	必需

返回：

类型	描述
Rect	转换后的 Rect 对象。

引发：

类型	描述
TypeError	如果输入类型不正确则抛出。 .. note:: 若输入数据为 float，会被强制转换为 int。