Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

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()，这样更可靠。