Class Transform

java.lang.Object
eu.svjatoslav.aukio.e3d.math.Transform
All Implemented Interfaces:
Cloneable
public class Transform extends Object implements Cloneable
Represents a transformation in 3D space combining uniform scale, rotation, and translation (a similarity transform).

Transformations are applied in order: scale first (about the local origin), then rotation, 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, preserving the scale.
    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.
    double
    getScale()
    Returns the uniform scale applied before rotation (about the local origin).
    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
    setScale(double scale)
    Sets the uniform scale, applied before rotation about the local origin.
    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: uniform scale (about the local origin), then rotation, then translation.
    Point3D
    withTransformed(Point3D point)
    Returns a new point with this transform applied.

    Methods inherited from class 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, preserving the scale.
      Overrides:
      clone in class Object
      Returns:
      a new transform with the same translation, rotation and scale values

    • getScale

      public double getScale()
      Returns the uniform scale applied before rotation (about the local origin). Default is 1.0 (no scaling).
      Returns:
      the scale factor

    • setScale

      public Transform setScale(double scale)
      Sets the uniform scale, applied before rotation about the local origin.

      Values other than 1.0 resize the geometry in its local space. Negative values additionally mirror the geometry, which flips face winding and therefore inverts backface culling. Zero is rejected because it would collapse all geometry onto the translation point.

      Like the rest of this class, the new value is picked up by a TransformStack only on the next push (push-time snapshot contract).

      Parameters:
      scale - the scale factor (must be finite and non-zero)
      Returns:
      this transform (for chaining)

    • 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: uniform scale (about the local origin), then rotation, then 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.

      With the default scale of 1.0 the multiply is skipped, so existing rigid-motion usage produces bit-identical results.

      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