Transform3D

代表 3D 变换的 3×4 矩阵。

描述

The Transform3D built-in Variant type is a 3×4 matrix representing a transformation in 3D space. It contains a Basis, which on its own can represent rotation, scale, and shear. Additionally, combined with its own origin, the transform can also represent a translation.

For a general introduction, see the Matrices and transforms tutorial.

Note: Godot uses a right-handed coordinate system, which is a common standard. For directions, the convention for built-in types like Camera3D is for -Z to point forward (+X is right, +Y is up, and +Z is back). Other objects may use different direction conventions. For more information, see the 3D asset direction conventions tutorial.

备注

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

教程

• 数学文档索引

• 矩阵与变换

• 使用 3D 变换

• 矩阵变换演示

• 3D 平台跳跃演示

• 2.5D 游戏演示

属性

构造函数

方法

运算符

常量

IDENTITY = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0) 🔗

不含平移、旋转、缩放为 1 的变换。basis 等于 Basis.IDENTITY。

与 AABB、Transform3D 等其他 Variant 相乘时，不会进行任何变换。

FLIP_X = Transform3D(-1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0) 🔗

应用了垂直于 YZ 平面镜像操作的 Transform3D。其 basis 相当于 Basis.FLIP_X。

FLIP_Y = Transform3D(1, 0, 0, 0, -1, 0, 0, 0, 1, 0, 0, 0) 🔗

应用了垂直于 XZ 平面镜像操作的 Transform3D。其 basis 相当于 Basis.FLIP_Y。

FLIP_Z = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, -1, 0, 0, 0) 🔗

应用了垂直于 XY 平面镜像操作的 Transform3D。其 basis 相当于 Basis.FLIP_Z。

属性说明

Basis basis = Basis(1, 0, 0, 0, 1, 0, 0, 0, 1) 🔗

该变换的 Basis。它由 3 个轴（Basis.x、Basis.y 和 Basis.z）组成。它们共同代表变换的旋转、缩放和错切。

Vector3 origin = Vector3(0, 0, 0) 🔗

该变换的平移偏移量。在 3D 空间中，这可以被看作是位置。

构造函数说明

Transform3D Transform3D() 🔗

构造与 IDENTITY 相同的 Transform3D。

Transform3D Transform3D(from: Transform3D)

构造给定 Transform3D 的副本 Transform3D。

Transform3D Transform3D(basis: Basis, origin: Vector3)

根据 Basis 和 Vector3 构造 Transform3D。

Transform3D Transform3D(from: Projection)

根据 Projection 构造 Transform3D。因为 Transform3D 是 3×4 的矩阵，而 Projection 是 4×4 的矩阵，所以这个操作会削去投影矩阵的最后一行（新的变换中不包含 from.x.w、from.y.w、from.z.w、from.w.w）。

Transform3D Transform3D(x_axis: Vector3, y_axis: Vector3, z_axis: Vector3, origin: Vector3)

根据四个 Vector3 值（也叫矩阵列）构造 Transform3D。

前三个参数是 basis 的三个轴（Basis.x、Basis.y、Basis.z）。

方法说明

Transform3D affine_inverse() const 🔗

返回该变换的逆版本。与 inverse 不同，则该方法几乎适用于任何 basis，包括非均匀的，但速度较慢。另见 Basis.inverse。

注意：为了使该方法正确返回，该变换的 basis 需要具有一个不完全是 0 的行列式（参见 Basis.determinant）。

Transform3D interpolate_with(xform: Transform3D, weight: float) const 🔗

返回将该变换和 xform 按照给定的权重 weight 进行线性插值结果。

weight 应该在 0.0 到 1.0（闭区间）的范围内。允许使用超出这个范围的值，表示进行外插。

Transform3D inverse() const 🔗

返回该变换的逆版本。另见 Basis.inverse。

注意：为了使该方法正确返回，该变换的 basis 需要是正交归一化的（请参阅 Basis.orthonormalized）。这意味着，该基应该只代表旋转。如果没有，请改用 affine_inverse。

bool is_equal_approx(xform: Transform3D) const 🔗

如果通过在每个分量上运行 @GlobalScope.is_equal_approx，该变换和 xform 近似相等，则返回 true。

bool is_finite() const 🔗

如果该变换是有限的，则返回 true，判断方法是在每个分量上调用 @GlobalScope.is_finite。

Transform3D looking_at(target: Vector3, up: Vector3 = Vector3(0, 1, 0), use_model_front: bool = false) const 🔗

返回该变换的旋转副本，以便向前轴（-Z）指向 target 的位置。

向上的轴（+Y）在保持与向前的轴垂直的前提下，尽可能接近 up 向量。最终的变换是标准正交变换。变换中原有的旋转、缩放、偏斜信息会被丢弃。target 和 up 向量不能为零，不能互相平行，使用全局/父级空间。

如果 use_model_front 为 true，则会将 +Z 轴（资产正面）作为向前的轴（此时 +X 为左），指向 target 的位置。默认情况下会将 -Z 轴（相机前方）作为向前的轴（此时 +X 为右）。

Transform3D orthonormalized() const 🔗

返回该变换的副本，其 basis 已正交归一化。正交归一化的基既是正交的（轴彼此垂直）又是归一化的（轴长度为 1），这也意味着它只能代表旋转。另见 Basis.orthonormalized。

Transform3D rotated(axis: Vector3, angle: float) const 🔗

返回该变换围绕给定 axis 旋转给定 angle（单位为弧度）的副本。

axis 必须为归一化的向量。

这个方法的结果和让 X 变换与相应的旋转变换 R 从左侧相乘一致，即 R * X，但进行了优化。

可以视作在全局/父级坐标系中的变换。

Transform3D rotated_local(axis: Vector3, angle: float) const 🔗

返回该变换围绕给定 axis 旋转给定 angle（单位为弧度）的副本。

axis 必须为归一化的向量。

这个方法的结果和让 X 变换与相应的旋转变换 R 从右侧相乘一致，即 R * X，但进行了优化。

可以视作在局部坐标系中的变换。

Transform3D scaled(scale: Vector3) const 🔗

返回该变换按给定的 scale 系数缩放的副本。

这个方法的结果和让 X 变换与相应的缩放变换 S 从左侧相乘一致，即 S * X，但进行了优化。

可以视作在全局/父级坐标系中的变换。

Transform3D scaled_local(scale: Vector3) const 🔗

返回该变换按给定的 scale 系数缩放的副本。

这个方法的结果和让 X 变换与相应的缩放变换 S 从右侧相乘一致，即 X * S，但进行了优化。

可以视作在局部坐标系中的变换。

Transform3D translated(offset: Vector3) const 🔗

返回该变换平移了给定 offset 的副本。

这个方法的结果和让 X 变换与相应的平移变换 T 从左侧相乘一致，即 T * X，但进行了优化。

可以视作在全局/父级坐标系中的变换。

Transform3D translated_local(offset: Vector3) const 🔗

返回该变化平移了给定 offset 的副本。

这个方法的结果和让 X 变换与相应的平移变换 T 从右侧相乘一致，即 X * T，但进行了优化。

可以视作在局部坐标系中的变换。

运算符说明

bool operator !=(right: Transform3D) 🔗

如果两个变换的分量不相等，则返回 true。

注意：由于浮点精度误差，请考虑改用 is_equal_approx，这样更可靠。

AABB operator *(right: AABB) 🔗

使用该变换矩阵对 AABB 进行变换（相乘）。

PackedVector3Array operator *(right: PackedVector3Array) 🔗

由该变换矩阵变换（乘以）给定 PackedVector3Array 的每个 Vector3 元素。

在较大的数组上，该操作比单独变换每个 Vector3 要快得多。

Plane operator *(right: Plane) 🔗

使用该变换矩阵对 Plane 进行变换（相乘）。

Transform3D operator *(right: Transform3D) 🔗

由 right 变换来变换（乘以）该变换。

这是父级和子级 Node3D 之间执行的操作。

注意：如果你只需要修改该变换的一个属性，请考虑改用以下方法之一：

• 对于平移，请参阅 translated 或 translated_local。

• 对于旋转，请参阅 rotated 或 rotated_local。

• 对于缩放，请参阅 scaled 或 scaled_local。

Vector3 operator *(right: Vector3) 🔗

使用该变换矩阵对 Vector3 进行变换（相乘）。

Transform3D operator *(right: float) 🔗

将 Transform3D 包括 origin 在内的所有分量乘以给定的 float。会均匀地影响该变换的缩放，对 basis 进行缩放。

Transform3D operator *(right: int) 🔗

将 Transform3D 包括 origin 在内的所有分量乘以给定的 int。会均匀地影响该变换的缩放，对 basis 进行缩放。

Transform3D operator /(right: float) 🔗

将 Transform3D 包括 origin 在内的所有分量除以给定的 float。会均匀地影响该变换的缩放，对 basis 进行缩放。

Transform3D operator /(right: int) 🔗

将 Transform3D 包括 origin 在内的所有分量除以给定的 int。会均匀地影响该变换的缩放，对 basis 进行缩放。

bool operator ==(right: Transform3D) 🔗

如果两个变换的分量完全相等，则返回 true。

注意：由于浮点精度误差，请考虑改用 is_equal_approx，这样更可靠。