Package eu.svjatoslav.sixth.e3d.math

Class Quaternion

java.lang.Object
eu.svjatoslav.sixth.e3d.math.Quaternion
public class Quaternion extends Object
A unit quaternion representing a 3D rotation.

Quaternions provide a compact representation of rotations that avoids gimbal lock and enables smooth interpolation (slerp).

Usage example:


 // Create a rotation from yaw and pitch angles
 Quaternion rotation = Quaternion.fromAngles(0.5, -0.3);

 // Apply rotation to a point
 Point3D point = new Point3D(1, 0, 0);
 rotation.rotate(point);

 // Combine rotations
 Quaternion combined = rotation.multiply(otherRotation);
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    double
    w
    The scalar (real) component of the quaternion.
    double
    x
    The i component (x-axis rotation factor).
    double
    y
    The j component (y-axis rotation factor).
    double
    z
    The k component (z-axis rotation factor).

  • Constructor Summary

    Constructors
    Constructor
    Description
    Quaternion()
    Creates an identity quaternion representing no rotation.
    Quaternion(double w, double x, double y, double z)
    Creates a quaternion with the specified components.

  • Method Summary

    Modifier and Type
    Method
    Description
    Quaternion
    clone()
    Creates a copy of this quaternion.
    static Quaternion
    fromAngles(double angleXZ, double angleYZ)
    Creates a quaternion from XZ (yaw) and YZ (pitch) Euler angles.
    static Quaternion
    fromAngles(double yaw, double pitch, double roll)
    Creates a quaternion from full Euler angles (yaw, pitch, roll).
    static Quaternion
    fromAxisAngle(Point3D axis, double angle)
    Creates a quaternion from an axis-angle representation.
    static Quaternion
    identity()
    Returns the identity quaternion representing no rotation.
    Quaternion
    invert()
    Returns the inverse (conjugate) of this unit quaternion.
    Quaternion
    multiply(Quaternion other)
    Multiplies this quaternion by another (Hamilton product).
    Quaternion
    normalize()
    Normalizes this quaternion to unit length.
    void
    set(Quaternion other)
    Copies the values from another quaternion into this one.
    double[]
    toAngles()
    Extracts Euler angles (yaw, pitch, roll) from this quaternion.
    Matrix3x3
    toMatrix()
    Converts this quaternion to a 3x3 rotation matrix.
    Matrix3x3
    toMatrix3x3()
    Converts this quaternion to a 3x3 rotation matrix.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • w

      public double w
      The scalar (real) component of the quaternion.

    • x

      public double x
      The i component (x-axis rotation factor).

    • y

      public double y
      The j component (y-axis rotation factor).

    • z

      public double z
      The k component (z-axis rotation factor).

  • Constructor Details

    • Quaternion

      public Quaternion()
      Creates an identity quaternion representing no rotation. Equivalent to Quaternion(1, 0, 0, 0).

    • Quaternion

      public Quaternion(double w, double x, double y, double z)
      Creates a quaternion with the specified components.
      Parameters:
      w - the scalar component
      x - the i component
      y - the j component
      z - the k component

  • Method Details

    • clone

      public Quaternion clone()
      Creates a copy of this quaternion.
      Overrides:
      clone in class Object
      Returns:
      a new quaternion with the same component values

    • set

      public void set(Quaternion other)
      Copies the values from another quaternion into this one.
      Parameters:
      other - the quaternion to copy from

    • identity

      public static Quaternion identity()
      Returns the identity quaternion representing no rotation.
      Returns:
      the identity quaternion (1, 0, 0, 0)

    • fromAxisAngle

      public static Quaternion fromAxisAngle(Point3D axis, double angle)
      Creates a quaternion from an axis-angle representation.
      Parameters:
      axis - the rotation axis (must be normalized)
      angle - the rotation angle in radians
      Returns:
      a quaternion representing the rotation

    • fromAngles

      public static Quaternion fromAngles(double angleXZ, double angleYZ)
      Creates a quaternion from XZ (yaw) and YZ (pitch) Euler angles.

      The rotation is composed as yaw (around Y axis) followed by pitch (around X axis). No roll rotation is applied.

      For full 3-axis rotation, use fromAngles(double, double, double).

      Parameters:
      angleXZ - the angle around the XZ axis (yaw) in radians
      angleYZ - the angle around the YZ axis (pitch) in radians
      Returns:
      a quaternion representing the combined rotation

    • fromAngles

      public static Quaternion fromAngles(double yaw, double pitch, double roll)
      Creates a quaternion from full Euler angles (yaw, pitch, roll).

      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:
      yaw - rotation around Y axis (horizontal heading) in radians
      pitch - rotation around X axis (vertical tilt) in radians; positive values tilt upward
      roll - rotation around Z axis (bank/tilt) in radians; positive values rotate clockwise when looking along +Z
      Returns:
      a quaternion representing the combined rotation

    • multiply

      public Quaternion multiply(Quaternion other)
      Multiplies this quaternion by another (Hamilton product).
      Parameters:
      other - the quaternion to multiply by
      Returns:
      a new quaternion representing the combined rotation

    • normalize

      public Quaternion normalize()
      Normalizes this quaternion to unit length.
      Returns:
      this quaternion (for chaining)

    • invert

      public Quaternion invert()
      Returns the inverse (conjugate) of this unit quaternion.

      For a unit quaternion, the inverse equals the conjugate: (w, -x, -y, -z). This represents the opposite rotation.

      Returns:
      a new quaternion representing the inverse rotation

    • toMatrix3x3

      public Matrix3x3 toMatrix3x3()
      Converts this quaternion to a 3x3 rotation matrix.
      Returns:
      a new matrix representing this rotation

    • toMatrix

      public Matrix3x3 toMatrix()
      Converts this quaternion to a 3x3 rotation matrix. Alias for toMatrix3x3() for API convenience.
      Returns:
      a new matrix representing this rotation

    • toAngles

      public double[] toAngles()
      Extracts Euler angles (yaw, pitch, roll) from this quaternion.

      This is the inverse of fromAngles(double, double, double). Returns angles in the Y-X-Z Euler order used by this engine.

      Returns:
      array of {yaw, pitch, roll} in radians