Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

AABB

3D 轴对齐边界框。

描述

AABB 内置 Variant 类型表示 3D 空间中的轴对齐边界框。它由其 positionsize 定义,皆为 Vector3 类型。它经常被用于快速重叠测试(参见 intersects)。虽然 AABB 本身是轴对齐的,但它可以与 Transform3D 组合来表示旋转或倾斜的边界框。

它使用浮点坐标。AABB 的 2D 等效体是 Rect2。没有使用整数坐标的 AABB 版本。

注意:不支持负的 size。对于负大小,大多数 AABB 方法都无法正常工作。使用 abs 获取具有非负大小的等效 AABB

注意:在布尔上下文中,如果 positionsize 均为零(等于 Vector3.ZERO),则 AABB 的计算结果为 false。否则,它的计算结果始终为 true

备注

通过 C# 使用这个 API 时有显著的不同。详见 C# API 与 GDScript 的差异

教程

属性

Vector3

end

Vector3(0, 0, 0)

Vector3

position

Vector3(0, 0, 0)

Vector3

size

Vector3(0, 0, 0)

构造函数

AABB

AABB ( )

AABB

AABB ( AABB from )

AABB

AABB ( Vector3 position, Vector3 size )

方法

AABB

abs ( ) const

bool

encloses ( AABB with ) const

AABB

expand ( Vector3 to_point ) const

Vector3

get_center ( ) const

Vector3

get_endpoint ( int idx ) const

Vector3

get_longest_axis ( ) const

int

get_longest_axis_index ( ) const

float

get_longest_axis_size ( ) const

Vector3

get_shortest_axis ( ) const

int

get_shortest_axis_index ( ) const

float

get_shortest_axis_size ( ) const

Vector3

get_support ( Vector3 dir ) const

float

get_volume ( ) const

AABB

grow ( float by ) const

bool

has_point ( Vector3 point ) const

bool

has_surface ( ) const

bool

has_volume ( ) const

AABB

intersection ( AABB with ) const

bool

intersects ( AABB with ) const

bool

intersects_plane ( Plane plane ) const

Variant

intersects_ray ( Vector3 from, Vector3 dir ) const

Variant

intersects_segment ( Vector3 from, Vector3 to ) const

bool

is_equal_approx ( AABB aabb ) const

bool

is_finite ( ) const

AABB

merge ( AABB with ) const

操作符

bool

operator != ( AABB right )

AABB

operator * ( Transform3D right )

bool

operator == ( AABB right )


属性说明

Vector3 end = Vector3(0, 0, 0)

终点。通常是边界框的前方右上角,等价于 position + size。设置该点会影响 size


Vector3 position = Vector3(0, 0, 0)

原点。通常是边界框的背面左下角。


Vector3 size = Vector3(0, 0, 0)

边界框的宽度、高度、深度,相对于 position。设置该值会影响终点 end

注意:建议将宽度、高度、深度设置为非负数,因为 Godot 中的大多数方法假设 position 为背面的左下角、end 为正面的右上角。要获取等价且大小非负的边界框,请使用 abs


构造函数说明

AABB AABB ( )

构造 AABB,并将 positionsize 设置为 Vector3.ZERO


AABB AABB ( AABB from )

构造给定 AABB 的副本。


AABB AABB ( Vector3 position, Vector3 size )

使用指定的 positionsize 构造 AABB


方法说明

AABB abs ( ) const

返回一个与该边界框等效的 AABB,其宽度、高度和深度被修改为非负值。

var box = AABB(Vector3(5, 0, 5), Vector3(-20, -10, -5))
var absolute = box.abs()
print(absolute.position) # 打印 (-15, -10, 0)
print(absolute.size)     # 打印 (20, 10, 5)

注意:size 为负时,建议使用该方法,因为 Godot 中的大多数其他方法都假设 size 的分量大于 0


bool encloses ( AABB with ) const

如果该边界框完全包围 with 框,则返回 true。两个框的边都包括在内。

var a = AABB(Vector3(0, 0, 0), Vector3(4, 4, 4))
var b = AABB(Vector3(1, 1, 1), Vector3(3, 3, 3))
var c = AABB(Vector3(2, 2, 2), Vector3(8, 8, 8))

print(a.encloses(a)) # 打印 true
print(a.encloses(b)) # 打印 true
print(a.encloses(c)) # 打印 false

AABB expand ( Vector3 to_point ) const

返回该边界框的副本,如有必要,该边界框被扩展为将边与给定的 to_point 对齐。

var box = AABB(Vector3(0, 0, 0), Vector3(5, 2, 5))

box = box.expand(Vector3(10, 0, 0))
print(box.position) # 打印 (0, 0, 0)
print(box.size)     # 打印 (10, 2, 5)

box = box.expand(Vector3(-5, 0, 5))
print(box.position) # 打印 (-5, 0, 0)
print(box.size)     # 打印 (15, 2, 5)

Vector3 get_center ( ) const

返回该边界框的中心点。这与 position + (size / 2.0) 相同。


Vector3 get_endpoint ( int idx ) const

返回组成该边界框的 8 个顶点之一的位置。当 idx0 时,这与 position 相同;idx7 时,与 end 相同。


Vector3 get_longest_axis ( ) const

返回该边界框的 size 的最长归一化轴,作为 Vector3Vector3.RIGHTVector3.UPVector3.BACK)。

var box = AABB(Vector3(0, 0, 0), Vector3(2, 4, 8))

print(box.get_longest_axis())       # 打印 (0, 0, 1)
print(box.get_longest_axis_index()) # 打印 2
print(box.get_longest_axis_size())  # 打印 8

另见 get_longest_axis_indexget_longest_axis_size


int get_longest_axis_index ( ) const

返回该边界框的 size 的最长轴的索引(请参阅 Vector3.AXIS_XVector3.AXIS_Y、和 Vector3.AXIS_Z)。

有关示例,请参阅 get_longest_axis


float get_longest_axis_size ( ) const

返回该边界框的 size 的最长尺度。

有关示例,请参阅 get_longest_axis


Vector3 get_shortest_axis ( ) const

返回该边界框的 size 的最短归一化轴,作为 Vector3Vector3.RIGHTVector3.UP、或 Vector3.BACK)。

var box = AABB(Vector3(0, 0, 0), Vector3(2, 4, 8))

print(box.get_shortest_axis())       # 打印 (1, 0, 0)
print(box.get_shortest_axis_index()) # 打印 0
print(box.get_shortest_axis_size())  # 打印 2

另见 get_shortest_axis_indexget_shortest_axis_size


int get_shortest_axis_index ( ) const

返回该边界框的 size 的最短轴的索引(请参阅 Vector3.AXIS_XVector3.AXIS_Y、和 Vector3.AXIS_Z)。

有关示例,请参阅 get_shortest_axis


float get_shortest_axis_size ( ) const

返回该边界框的 size 的最短尺度。

有关示例,请参阅 get_shortest_axis


Vector3 get_support ( Vector3 dir ) const

返回给定方向上最远的边界框的顶点位置。该点在碰撞检测算法中通常被称为支撑点。


float get_volume ( ) const

返回该边界框的体积。这相当于 size.x * size.y * size.z。另请参阅 has_volume


AABB grow ( float by ) const

返回该边界框的副本,该边界框在所有边上扩展给定量 by。负数会缩小该框。

var a = AABB(Vector3(4, 4, 4), Vector3(8, 8, 8)).grow(4)
print(a.position) # 打印 (0, 0, 0)
print(a.size)     # 打印 (16, 16, 16)

var b = AABB(Vector3(0, 0, 0), Vector3(8, 4, 2)).grow(2)
print(b.position) # 打印 (-2, -2, -2)
print(b.size)     # 打印 (12, 8, 6)

bool has_point ( Vector3 point ) const

如果该边界框包含给定的 point,则返回 true。依照惯例,包括正好位于右侧、顶部和前侧的点。

注意:对于具有 sizeAABB,该方法并不可靠。请首先使用 abs 获取一个有效的边界框。


bool has_surface ( ) const

如果该边界框具有表面或长度,即 size 的至少一个分量大于 0,则返回 true。否则,返回 false


bool has_volume ( ) const

如果该边界框的宽度、高度和深度均为正值,则返回 true。另见 get_volume


AABB intersection ( AABB with ) const

返回该边界框与 with 之间的交集。如果框不相交,则返回空的 AABB。如果框在边相交,则返回没有体积的平 AABB(请参阅 has_surfacehas_volume)。

var box1 = AABB(Vector3(0, 0, 0), Vector3(5, 2, 8))
var box2 = AABB(Vector3(2, 0, 2), Vector3(8, 4, 4))

var intersection = box1.intersection(box2)
print(intersection.position) # 打印 (2, 0, 2)
print(intersection.size)     # 打印 (3, 2, 4)

注意:如果你只需要知道两个边界框是否相交,请改用 intersects


bool intersects ( AABB with ) const

如果该边界框与框 with 重叠,则返回 true。两个框的边总是被排除。


bool intersects_plane ( Plane plane ) const

如果该边界框位于给定 plane 的两侧,则返回 true


Variant intersects_ray ( Vector3 from, Vector3 dir ) const

返回该边界框与给定射线相交的第一个点,作为 Vector3。如果没有交集存在,则返回 null

射线从 from 开始,面向 dir 并向无穷远延伸。


Variant intersects_segment ( Vector3 from, Vector3 to ) const

返回该边界框与给定线段相交的第一个点,作为 Vector3。如果没有交集存在,则返回 null

该线段从 from 开始,到 to 结束。


bool is_equal_approx ( AABB aabb ) const

如果该边界框和 aabb 近似相等,则返回 true,判断方法是通过在 positionsize 上调用 Vector3.is_equal_approx


bool is_finite ( ) const

如果该边界框的值是有限的,则返回 true,判断方法是通过在 positionsize 上调用 Vector3.is_finite


AABB merge ( AABB with ) const

返回边界包围该边界框和 withAABB。另见 encloses


操作符说明

bool operator != ( AABB right )

如果两个边界框的 position 不相等或 size 不相等,则返回 true

注意:由于浮点数精度误差,请考虑改用 is_equal_approx,会更可靠。


AABB operator * ( Transform3D right )

假设该变换的基是正交的(即旋转/反射可以,缩放/倾斜则不行),将 AABB 逆向变换(乘以)给定的 Transform3D 变换矩阵。

aabb * transform 相当于 transform.inverse() * aabb。见 Transform3D.inverse

对于通过仿射变换的逆进行的变换(例如,缩放),可以使用 transform.affine_inverse() * aabb 代替。见 Transform3D.affine_inverse


bool operator == ( AABB right )

如果两个边界框的 position 完全相等且 size 完全相等,则返回 true

注意:由于浮点数精度误差,请考虑改用 is_equal_approx,会更可靠。