Transform3D

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

描述

Transform3D 即 3D 变换，是一种内置的 Variant 类型，这种 3×4 矩阵代表的是 3D 空间中的变换。变换中包含了一个 Basis，表示的是旋转、缩放、倾斜。另外变换自身还提供了 origin，这样就能够表示平移。

通用的介绍见教程《矩阵和变换》。

注意：Godot 使用右手坐标系，这是一种普遍标准。方向方面，Camera3D 等内置类型的约定是 -Z 指向前方（+X 为右、+Y 为上、+Z 为后）。其他对象可能使用不同的方向约定。更多信息见教程《3D 资产方向约定》。

备注

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

教程

属性

Basis	basis	`Basis(1, 0, 0, 0, 1, 0, 0, 0, 1)`
Vector3	origin	`Vector3(0, 0, 0)`

构造函数

Transform3D	Transform3D()
Transform3D	Transform3D(from: Transform3D)
Transform3D	Transform3D(basis: Basis, origin: Vector3)
Transform3D	Transform3D(from: Projection)
Transform3D	Transform3D(x_axis: Vector3, y_axis: Vector3, z_axis: Vector3, origin: Vector3)

方法

Transform3D	affine_inverse() const
Transform3D	interpolate_with(xform: Transform3D, weight: float) const
Transform3D	inverse() const
bool	is_equal_approx(xform: Transform3D) const
bool	is_finite() const
Transform3D	looking_at(target: Vector3, up: Vector3 = Vector3(0, 1, 0), use_model_front: bool = false) const
Transform3D	orthonormalized() const
Transform3D	rotated(axis: Vector3, angle: float) const
Transform3D	rotated_local(axis: Vector3, angle: float) const
Transform3D	scaled(scale: Vector3) const
Transform3D	scaled_local(scale: Vector3) const
Transform3D	translated(offset: Vector3) const
Transform3D	translated_local(offset: Vector3) const

运算符

bool	operator !=(right: Transform3D)
AABB	operator *(right: AABB)
PackedVector3Array	operator *(right: PackedVector3Array)
Plane	operator *(right: Plane)
Transform3D	operator *(right: Transform3D)
Vector3	operator *(right: Vector3)
Transform3D	operator *(right: float)
Transform3D	operator *(right: int)
Transform3D	operator /(right: float)
Transform3D	operator /(right: int)
bool	operator ==(right: Transform3D)

常量

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

单位 Transform3D。这是一个没有平移和旋转的变换，缩放为 Vector3.ONE。basis 等于 Basis.IDENTITY。这意味着：

Basis.x 指向右侧（Vector3.RIGHT）；
Basis.y 指向上方（Vector3.UP）；
Basis.z 指向后方（Vector3.BACK）。

var transform = Transform3D.IDENTITY
var basis = transform.basis
print("| X | Y | Z | 原点")
print("| %.f | %.f | %.f | %.f" % [basis.x.x, basis.y.x, basis.z.x, transform.origin.x])
print("| %.f | %.f | %.f | %.f" % [basis.x.y, basis.y.y, basis.z.y, transform.origin.y])
print("| %.f | %.f | %.f | %.f" % [basis.x.z, basis.y.z, basis.z.z, transform.origin.z])
# 输出：
# | X | Y | Z | 原点
# | 1 | 0 | 0 | 0
# | 0 | 1 | 0 | 0
# | 0 | 0 | 1 | 0

如果使用该常量变换（相乘）Vector3、AABB、Plane、PackedVector3Array 或其他 Transform3D，则不会发生变换。

注意：在 GDScript 中，该常量与不带任何参数创建 Transform3D 相同。使用该常量可以让你的代码更清晰，并与 C# 保持一致。

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。

注意：在 C# 中构造的 Transform3D 的 origin 和 basis 的所有分量都为 Vector3.ZERO。

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.0 的行列式（见 Basis.determinant()）。

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

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

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

Transform3D inverse() const 🔗

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

注意：为了使该方法正确返回，该变换的基需要是正交归一化的（见 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.0），这也意味着它只能代表旋转。另见 Basis.orthonormalized()。

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

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

axis 必须为归一化的向量（见 Vector3.normalized()）。如果 angle 为正数，则基会围绕轴进行逆时针旋转。

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

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

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

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

axis 必须为归一化的向量，使用变换的局部坐标系。例如，要围绕局部 X 轴旋转请使用 Vector3.RIGHT。

这个方法的结果和让 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()，这样更可靠。