Package eu.svjatoslav.sixth.e3d.math

Class Transform

java.lang.Object
eu.svjatoslav.sixth.e3d.math.Transform
All Implemented Interfaces:
Cloneable
public class Transform extends Object implements Cloneable
Represents a transformation in 3D space combining translation and rotation.

Transformations are applied in order: rotation first, then translation.

Performance optimization: The rotation matrix is cached and only recomputed when the rotation quaternion changes. This avoids allocating a new Matrix3x3 on every transform() call and avoids redundant quaternion-to-matrix conversions for vertices sharing the same transform.

Mutability convention:

  • Imperative verbs (set, setTranslation, transform) mutate this transform or the input point
  • with-prefixed methods (withTransformed) return a new instance without modifying the original

Thread safety: The transform phase is single-threaded (synchronized in ShapeCollection.transformShapes()), so no synchronization is needed for the cached matrix. The matrix is computed once per Transform per frame and reused for all vertices.

See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    Transform()
    Creates a transform with no translation or rotation (identity transform).
    Transform(Point3D translation)
    Creates a transform with the specified translation and no rotation.
    Transform(Point3D translation, Quaternion rotation)
    Creates a transform with the specified translation and rotation.

  • Method Summary

    Modifier and Type
    Method
    Description
    Transform
    clone()
    Creates a copy of this transform with cloned translation and rotation.
    static Transform
    fromAngles(double x, double y, double z, double yaw, double pitch, double roll)
    Creates a transform with translation and full Euler rotation.
    static Transform
    fromAngles(Point3D translation, double yaw, double pitch)
    Creates a transform with the specified translation and rotation from Euler angles.
    Quaternion
    getRotation()
    Returns the rotation component of this transform.
    Point3D
    getTranslation()
    Returns the translation component of this transform.
    Transform
    invalidateCache()
    Invalidates the cached rotation matrix.
    Transform
    set(double x, double y, double z, double yaw, double pitch, double roll)
    Sets both translation and rotation from Euler angles.
    Transform
    setTranslation(Point3D translation)
    Sets the translation for this transform by copying the values from the given point.
    void
    transform(Point3D point)
    Applies this transform to a point: rotation followed by translation.
    Point3D
    withTransformed(Point3D point)
    Returns a new point with this transform applied.

    Methods inherited from class java.lang.Object

    equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • Transform

      public Transform()
      Creates a transform with no translation or rotation (identity transform).

    • Transform

      public Transform(Point3D translation)
      Creates a transform with the specified translation and no rotation.
      Parameters:
      translation - the translation

    • Transform

      public Transform(Point3D translation, Quaternion rotation)
      Creates a transform with the specified translation and rotation.
      Parameters:
      translation - the translation
      rotation - the rotation (will be cloned)

  • Method Details

    • fromAngles

      public static Transform fromAngles(Point3D translation, double yaw, double pitch)
      Creates a transform with the specified translation and rotation from Euler angles.
      Parameters:
      translation - the translation
      yaw - the angle around the Y axis (horizontal heading) in radians
      pitch - the angle around the X axis (vertical tilt) in radians
      Returns:
      a new transform with the specified translation and rotation

    • fromAngles

      public static Transform fromAngles(double x, double y, double z, double yaw, double pitch, double roll)
      Creates a transform with translation and full Euler rotation.

      Rotation order: yaw (Y) → pitch (X) → roll (Z). This is the standard Y-X-Z Euler order commonly used for object placement in 3D scenes.

      Parameters:
      x - translation X coordinate
      y - translation Y coordinate
      z - translation Z coordinate
      yaw - rotation around Y axis (horizontal heading) in radians
      pitch - rotation around X axis (vertical tilt) in radians
      roll - rotation around Z axis (bank/tilt) in radians
      Returns:
      a new transform with the specified translation and rotation

    • clone

      public Transform clone()
      Creates a copy of this transform with cloned translation and rotation.
      Overrides:
      clone in class Object
      Returns:
      a new transform with the same translation and rotation values

    • getRotation

      public Quaternion getRotation()
      Returns the rotation component of this transform.

      Warning: If you modify the returned quaternion directly, you must call invalidateCache() afterwards to ensure the cached rotation matrix is recomputed on the next call to transform(Point3D).

      Returns:
      the rotation quaternion (mutable reference)

    • invalidateCache

      public Transform invalidateCache()
      Invalidates the cached rotation matrix.

      Call this method after directly modifying the rotation quaternion (obtained via getRotation()) to ensure the matrix is recomputed on the next call to transform(Point3D).

      This method is automatically called by set(double, double, double, double, double, double).

      Returns:
      this transform (for chaining)

    • getTranslation

      public Point3D getTranslation()
      Returns the translation component of this transform.
      Returns:
      the translation point (mutable reference)

    • transform

      public void transform(Point3D point)
      Applies this transform to a point: rotation followed by translation.

      Uses a cached rotation matrix to avoid allocation and redundant computation. The matrix is computed once (lazily) and reused for all subsequent calls until invalidateCache() is called.

      Parameters:
      point - the point to transform (modified in place)
      See Also:

    • withTransformed

      public Point3D withTransformed(Point3D point)
      Returns a new point with this transform applied. The original point is not modified.
      Parameters:
      point - the point to transform
      Returns:
      a new Point3D with the transform applied
      See Also:

    • setTranslation

      public Transform setTranslation(Point3D translation)
      Sets the translation for this transform by copying the values from the given point.
      Parameters:
      translation - the translation values to copy
      Returns:
      this transform (for chaining)

    • set

      public Transform set(double x, double y, double z, double yaw, double pitch, double roll)
      Sets both translation and rotation from Euler angles.

      Rotation order: yaw (Y) → pitch (X) → roll (Z). This is the standard Y-X-Z Euler order commonly used for object placement in 3D scenes.

      This method invalidates the cached rotation matrix.

      Parameters:
      x - translation X coordinate
      y - translation Y coordinate
      z - translation Z coordinate
      yaw - rotation around Y axis (horizontal heading) in radians
      pitch - rotation around X axis (vertical tilt) in radians
      roll - rotation around Z axis (bank/tilt) in radians
      Returns:
      this transform for chaining