:github_url: hide .. DO NOT EDIT THIS FILE!!! .. Generated automatically from Godot engine sources. .. Generator: https://github.com/godotengine/godot/tree/4.2/doc/tools/make_rst.py. .. XML source: https://github.com/godotengine/godot/tree/4.2/doc/classes/Transform3D.xml. .. _class_Transform3D: Transform3D =========== A 3×4 matrix representing a 3D transformation. .. rst-class:: classref-introduction-group Description ----------- The **Transform3D** built-in :ref:`Variant` type is a 3×4 matrix representing a transformation in 3D space. It contains a :ref:`Basis`, which on its own can represent rotation, scale, and shear. Additionally, combined with its own :ref:`origin`, the transform can also represent a translation. For a general introduction, see the :doc:`Matrices and transforms <../tutorials/math/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 :ref:`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 `Importing 3D Scenes <../tutorials/assets_pipeline/importing_scenes.html#d-asset-direction-conventions>`__ tutorial. .. note:: There are notable differences when using this API with C#. See :ref:`doc_c_sharp_differences` for more information. .. rst-class:: classref-introduction-group Tutorials --------- - :doc:`Math documentation index <../tutorials/math/index>` - :doc:`Matrices and transforms <../tutorials/math/matrices_and_transforms>` - :doc:`Using 3D transforms <../tutorials/3d/using_transforms>` - `Matrix Transform Demo `__ - `3D Platformer Demo `__ - `2.5D Demo `__ .. rst-class:: classref-reftable-group Properties ---------- .. table:: :widths: auto +-------------------------------+--------------------------------------------------+--------------------------------------+ | :ref:`Basis` | :ref:`basis` | ``Basis(1, 0, 0, 0, 1, 0, 0, 0, 1)`` | +-------------------------------+--------------------------------------------------+--------------------------------------+ | :ref:`Vector3` | :ref:`origin` | ``Vector3(0, 0, 0)`` | +-------------------------------+--------------------------------------------------+--------------------------------------+ .. rst-class:: classref-reftable-group Constructors ------------ .. table:: :widths: auto +---------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Transform3D` | :ref:`Transform3D` **(** **)** | +---------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Transform3D` | :ref:`Transform3D` **(** :ref:`Transform3D` from **)** | +---------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Transform3D` | :ref:`Transform3D` **(** :ref:`Basis` basis, :ref:`Vector3` origin **)** | +---------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Transform3D` | :ref:`Transform3D` **(** :ref:`Projection` from **)** | +---------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Transform3D` | :ref:`Transform3D` **(** :ref:`Vector3` x_axis, :ref:`Vector3` y_axis, :ref:`Vector3` z_axis, :ref:`Vector3` origin **)** | +---------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-reftable-group Methods ------- .. table:: :widths: auto +---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Transform3D` | :ref:`affine_inverse` **(** **)** |const| | +---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Transform3D` | :ref:`interpolate_with` **(** :ref:`Transform3D` xform, :ref:`float` weight **)** |const| | +---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Transform3D` | :ref:`inverse` **(** **)** |const| | +---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`is_equal_approx` **(** :ref:`Transform3D` xform **)** |const| | +---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`is_finite` **(** **)** |const| | +---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Transform3D` | :ref:`looking_at` **(** :ref:`Vector3` target, :ref:`Vector3` up=Vector3(0, 1, 0), :ref:`bool` use_model_front=false **)** |const| | +---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Transform3D` | :ref:`orthonormalized` **(** **)** |const| | +---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Transform3D` | :ref:`rotated` **(** :ref:`Vector3` axis, :ref:`float` angle **)** |const| | +---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Transform3D` | :ref:`rotated_local` **(** :ref:`Vector3` axis, :ref:`float` angle **)** |const| | +---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Transform3D` | :ref:`scaled` **(** :ref:`Vector3` scale **)** |const| | +---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Transform3D` | :ref:`scaled_local` **(** :ref:`Vector3` scale **)** |const| | +---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Transform3D` | :ref:`translated` **(** :ref:`Vector3` offset **)** |const| | +---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Transform3D` | :ref:`translated_local` **(** :ref:`Vector3` offset **)** |const| | +---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-reftable-group Operators --------- .. table:: :widths: auto +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`operator !=` **(** :ref:`Transform3D` right **)** | +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`AABB` | :ref:`operator *` **(** :ref:`AABB` right **)** | +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`PackedVector3Array` | :ref:`operator *` **(** :ref:`PackedVector3Array` right **)** | +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Plane` | :ref:`operator *` **(** :ref:`Plane` right **)** | +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Transform3D` | :ref:`operator *` **(** :ref:`Transform3D` right **)** | +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Vector3` | :ref:`operator *` **(** :ref:`Vector3` right **)** | +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Transform3D` | :ref:`operator *` **(** :ref:`float` right **)** | +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Transform3D` | :ref:`operator *` **(** :ref:`int` right **)** | +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`operator ==` **(** :ref:`Transform3D` right **)** | +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group Constants --------- .. _class_Transform3D_constant_IDENTITY: .. rst-class:: classref-constant **IDENTITY** = ``Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0)`` A transform with no translation, no rotation, and its scale being ``1``. Its :ref:`basis` is equal to :ref:`Basis.IDENTITY`. When multiplied by another :ref:`Variant` such as :ref:`AABB` or another **Transform3D**, no transformation occurs. .. _class_Transform3D_constant_FLIP_X: .. rst-class:: classref-constant **FLIP_X** = ``Transform3D(-1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0)`` **Transform3D** with mirroring applied perpendicular to the YZ plane. Its :ref:`basis` is equal to :ref:`Basis.FLIP_X`. .. _class_Transform3D_constant_FLIP_Y: .. rst-class:: classref-constant **FLIP_Y** = ``Transform3D(1, 0, 0, 0, -1, 0, 0, 0, 1, 0, 0, 0)`` **Transform3D** with mirroring applied perpendicular to the XZ plane. Its :ref:`basis` is equal to :ref:`Basis.FLIP_Y`. .. _class_Transform3D_constant_FLIP_Z: .. rst-class:: classref-constant **FLIP_Z** = ``Transform3D(1, 0, 0, 0, 1, 0, 0, 0, -1, 0, 0, 0)`` **Transform3D** with mirroring applied perpendicular to the XY plane. Its :ref:`basis` is equal to :ref:`Basis.FLIP_Z`. .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_Transform3D_property_basis: .. rst-class:: classref-property :ref:`Basis` **basis** = ``Basis(1, 0, 0, 0, 1, 0, 0, 0, 1)`` The :ref:`Basis` of this transform. It is composed by 3 axes (:ref:`Basis.x`, :ref:`Basis.y`, and :ref:`Basis.z`). Together, these represent the transform's rotation, scale, and shear. .. rst-class:: classref-item-separator ---- .. _class_Transform3D_property_origin: .. rst-class:: classref-property :ref:`Vector3` **origin** = ``Vector3(0, 0, 0)`` The translation offset of this transform. In 3D space, this can be seen as the position. .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group Constructor Descriptions ------------------------ .. _class_Transform3D_constructor_Transform3D: .. rst-class:: classref-constructor :ref:`Transform3D` **Transform3D** **(** **)** Constructs a **Transform3D** identical to the :ref:`IDENTITY`. .. rst-class:: classref-item-separator ---- .. rst-class:: classref-constructor :ref:`Transform3D` **Transform3D** **(** :ref:`Transform3D` from **)** Constructs a **Transform3D** as a copy of the given **Transform3D**. .. rst-class:: classref-item-separator ---- .. rst-class:: classref-constructor :ref:`Transform3D` **Transform3D** **(** :ref:`Basis` basis, :ref:`Vector3` origin **)** Constructs a **Transform3D** from a :ref:`Basis` and :ref:`Vector3`. .. rst-class:: classref-item-separator ---- .. rst-class:: classref-constructor :ref:`Transform3D` **Transform3D** **(** :ref:`Projection` from **)** Constructs a **Transform3D** from a :ref:`Projection`. Because **Transform3D** is a 3×4 matrix and :ref:`Projection` is a 4×4 matrix, this operation trims the last row of the projection matrix (``from.x.w``, ``from.y.w``, ``from.z.w``, and ``from.w.w`` are not included in the new transform). .. rst-class:: classref-item-separator ---- .. rst-class:: classref-constructor :ref:`Transform3D` **Transform3D** **(** :ref:`Vector3` x_axis, :ref:`Vector3` y_axis, :ref:`Vector3` z_axis, :ref:`Vector3` origin **)** Constructs a **Transform3D** from four :ref:`Vector3` values (also called matrix columns). The first three arguments are the :ref:`basis`'s axes (:ref:`Basis.x`, :ref:`Basis.y`, and :ref:`Basis.z`). .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group Method Descriptions ------------------- .. _class_Transform3D_method_affine_inverse: .. rst-class:: classref-method :ref:`Transform3D` **affine_inverse** **(** **)** |const| Returns the inverted version of this transform. Unlike :ref:`inverse`, this method works with almost any :ref:`basis`, including non-uniform ones, but is slower. See also :ref:`Basis.inverse`. \ **Note:** For this method to return correctly, the transform's :ref:`basis` needs to have a determinant that is not exactly ``0`` (see :ref:`Basis.determinant`). .. rst-class:: classref-item-separator ---- .. _class_Transform3D_method_interpolate_with: .. rst-class:: classref-method :ref:`Transform3D` **interpolate_with** **(** :ref:`Transform3D` xform, :ref:`float` weight **)** |const| Returns the result of the linear interpolation between this transform and ``xform`` by the given ``weight``. The ``weight`` should be between ``0.0`` and ``1.0`` (inclusive). Values outside this range are allowed and can be used to perform *extrapolation* instead. .. rst-class:: classref-item-separator ---- .. _class_Transform3D_method_inverse: .. rst-class:: classref-method :ref:`Transform3D` **inverse** **(** **)** |const| Returns the inverted version of this transform. See also :ref:`Basis.inverse`. \ **Note:** For this method to return correctly, the transform's :ref:`basis` needs to be *orthonormal* (see :ref:`Basis.orthonormalized`). That means, the basis should only represent a rotation. If it does not, use :ref:`affine_inverse` instead. .. rst-class:: classref-item-separator ---- .. _class_Transform3D_method_is_equal_approx: .. rst-class:: classref-method :ref:`bool` **is_equal_approx** **(** :ref:`Transform3D` xform **)** |const| Returns ``true`` if this transform and ``xform`` are approximately equal, by running :ref:`@GlobalScope.is_equal_approx` on each component. .. rst-class:: classref-item-separator ---- .. _class_Transform3D_method_is_finite: .. rst-class:: classref-method :ref:`bool` **is_finite** **(** **)** |const| Returns ``true`` if this transform is finite, by calling :ref:`@GlobalScope.is_finite` on each component. .. rst-class:: classref-item-separator ---- .. _class_Transform3D_method_looking_at: .. rst-class:: classref-method :ref:`Transform3D` **looking_at** **(** :ref:`Vector3` target, :ref:`Vector3` up=Vector3(0, 1, 0), :ref:`bool` use_model_front=false **)** |const| Returns a copy of this transform rotated so that the forward axis (-Z) points towards the ``target`` position. The up axis (+Y) points as close to the ``up`` vector as possible while staying perpendicular to the forward axis. The resulting transform is orthonormalized. The existing rotation, scale, and skew information from the original transform is discarded. The ``target`` and ``up`` vectors cannot be zero, cannot be parallel to each other, and are defined in global/parent space. If ``use_model_front`` is ``true``, the +Z axis (asset front) is treated as forward (implies +X is left) and points toward the ``target`` position. By default, the -Z axis (camera forward) is treated as forward (implies +X is right). .. rst-class:: classref-item-separator ---- .. _class_Transform3D_method_orthonormalized: .. rst-class:: classref-method :ref:`Transform3D` **orthonormalized** **(** **)** |const| Returns a copy of this transform with its :ref:`basis` orthonormalized. An orthonormal basis is both *orthogonal* (the axes are perpendicular to each other) and *normalized* (the axes have a length of ``1``), which also means it can only represent rotation. See also :ref:`Basis.orthonormalized`. .. rst-class:: classref-item-separator ---- .. _class_Transform3D_method_rotated: .. rst-class:: classref-method :ref:`Transform3D` **rotated** **(** :ref:`Vector3` axis, :ref:`float` angle **)** |const| Returns a copy of this transform rotated around the given ``axis`` by the given ``angle`` (in radians). The ``axis`` must be a normalized vector. This method is an optimized version of multiplying the given transform ``X`` with a corresponding rotation transform ``R`` from the left, i.e., ``R * X``. This can be seen as transforming with respect to the global/parent frame. .. rst-class:: classref-item-separator ---- .. _class_Transform3D_method_rotated_local: .. rst-class:: classref-method :ref:`Transform3D` **rotated_local** **(** :ref:`Vector3` axis, :ref:`float` angle **)** |const| Returns a copy of this transform rotated around the given ``axis`` by the given ``angle`` (in radians). The ``axis`` must be a normalized vector. This method is an optimized version of multiplying the given transform ``X`` with a corresponding rotation transform ``R`` from the right, i.e., ``X * R``. This can be seen as transforming with respect to the local frame. .. rst-class:: classref-item-separator ---- .. _class_Transform3D_method_scaled: .. rst-class:: classref-method :ref:`Transform3D` **scaled** **(** :ref:`Vector3` scale **)** |const| Returns a copy of this transform scaled by the given ``scale`` factor. This method is an optimized version of multiplying the given transform ``X`` with a corresponding scaling transform ``S`` from the left, i.e., ``S * X``. This can be seen as transforming with respect to the global/parent frame. .. rst-class:: classref-item-separator ---- .. _class_Transform3D_method_scaled_local: .. rst-class:: classref-method :ref:`Transform3D` **scaled_local** **(** :ref:`Vector3` scale **)** |const| Returns a copy of this transform scaled by the given ``scale`` factor. This method is an optimized version of multiplying the given transform ``X`` with a corresponding scaling transform ``S`` from the right, i.e., ``X * S``. This can be seen as transforming with respect to the local frame. .. rst-class:: classref-item-separator ---- .. _class_Transform3D_method_translated: .. rst-class:: classref-method :ref:`Transform3D` **translated** **(** :ref:`Vector3` offset **)** |const| Returns a copy of this transform translated by the given ``offset``. This method is an optimized version of multiplying the given transform ``X`` with a corresponding translation transform ``T`` from the left, i.e., ``T * X``. This can be seen as transforming with respect to the global/parent frame. .. rst-class:: classref-item-separator ---- .. _class_Transform3D_method_translated_local: .. rst-class:: classref-method :ref:`Transform3D` **translated_local** **(** :ref:`Vector3` offset **)** |const| Returns a copy of this transform translated by the given ``offset``. This method is an optimized version of multiplying the given transform ``X`` with a corresponding translation transform ``T`` from the right, i.e., ``X * T``. This can be seen as transforming with respect to the local frame. .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group Operator Descriptions --------------------- .. _class_Transform3D_operator_neq_Transform3D: .. rst-class:: classref-operator :ref:`bool` **operator !=** **(** :ref:`Transform3D` right **)** Returns ``true`` if the components of both transforms are not equal. \ **Note:** Due to floating-point precision errors, consider using :ref:`is_equal_approx` instead, which is more reliable. .. rst-class:: classref-item-separator ---- .. _class_Transform3D_operator_mul_AABB: .. rst-class:: classref-operator :ref:`AABB` **operator *** **(** :ref:`AABB` right **)** Transforms (multiplies) the :ref:`AABB` by this transformation matrix. .. rst-class:: classref-item-separator ---- .. _class_Transform3D_operator_mul_PackedVector3Array: .. rst-class:: classref-operator :ref:`PackedVector3Array` **operator *** **(** :ref:`PackedVector3Array` right **)** Transforms (multiplies) every :ref:`Vector3` element of the given :ref:`PackedVector3Array` by this transformation matrix. On larger arrays, this operation is much faster than transforming each :ref:`Vector3` individually. .. rst-class:: classref-item-separator ---- .. _class_Transform3D_operator_mul_Plane: .. rst-class:: classref-operator :ref:`Plane` **operator *** **(** :ref:`Plane` right **)** Transforms (multiplies) the :ref:`Plane` by this transformation matrix. .. rst-class:: classref-item-separator ---- .. _class_Transform3D_operator_mul_Transform3D: .. rst-class:: classref-operator :ref:`Transform3D` **operator *** **(** :ref:`Transform3D` right **)** Transforms (multiplies) this transform by the ``right`` transform. This is the operation performed between parent and child :ref:`Node3D`\ s. \ **Note:** If you need to only modify one attribute of this transform, consider using one of the following methods, instead: - For translation, see :ref:`translated` or :ref:`translated_local`. - For rotation, see :ref:`rotated` or :ref:`rotated_local`. - For scale, see :ref:`scaled` or :ref:`scaled_local`. .. rst-class:: classref-item-separator ---- .. _class_Transform3D_operator_mul_Vector3: .. rst-class:: classref-operator :ref:`Vector3` **operator *** **(** :ref:`Vector3` right **)** Transforms (multiplies) the :ref:`Vector3` by this transformation matrix. .. rst-class:: classref-item-separator ---- .. _class_Transform3D_operator_mul_float: .. rst-class:: classref-operator :ref:`Transform3D` **operator *** **(** :ref:`float` right **)** Multiplies all components of the **Transform3D** by the given :ref:`float`, including the :ref:`origin`. This affects the transform's scale uniformly, scaling the :ref:`basis`. .. rst-class:: classref-item-separator ---- .. _class_Transform3D_operator_mul_int: .. rst-class:: classref-operator :ref:`Transform3D` **operator *** **(** :ref:`int` right **)** Multiplies all components of the **Transform3D** by the given :ref:`int`, including the :ref:`origin`. This affects the transform's scale uniformly, scaling the :ref:`basis`. .. rst-class:: classref-item-separator ---- .. _class_Transform3D_operator_eq_Transform3D: .. rst-class:: classref-operator :ref:`bool` **operator ==** **(** :ref:`Transform3D` right **)** Returns ``true`` if the components of both transforms are exactly equal. \ **Note:** Due to floating-point precision errors, consider using :ref:`is_equal_approx` instead, which is more reliable. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` .. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` .. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` .. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` .. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)`