Package com.simsilica.mathd

Class Quatd

java.lang.Object
com.simsilica.mathd.Quatd
All Implemented Interfaces:
Cloneable
public final class Quatd extends Object implements Cloneable
Used to efficiently represent rotations and orientations in 3-dimensional space, without risk of gimbal lock. Each instance has 4 double-precision components: 3 imaginary components (X, Y, and Z) and a real component (W).

Methods with names ending in "Local" modify the current instance. They are used to avoid creating temporary objects.

Mathematically, quaternions are an extension of complex numbers. In mathematics texts, W often appears first, but here the conventional order is (X, Y, Z, W).

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    double
    w
    The real (W) component.
    double
    x
    The first imaginary (X) component.
    double
    y
    The 2nd imaginary (Y) component.
    double
    z
    The 3rd imaginary (Z) component.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Quatd()
    Instantiates an identity quaternion: all components zeroed except w, which is set to 1.
    Quatd(double x, double y, double z, double w)
    Instantiates a quaternion with the specified components.
    Quatd(Quaternion quat)
    Instantiates based on the specified (single-precision) Quaternion.
    Quatd(Quatd quat)
    Instantiates a copy of the argument.

  • Method Summary

    Modifier and Type
    Method
    Description
    final Quatd
    clone()
    Creates a copy.
    boolean
    equals(Object o)
    Tests for exact equality with the argument, distinguishing -0 from 0.
    Quatd
    fromAngles(double xAngle, double yAngle, double zAngle)
    Builds a Quaternion from the Euler rotation angles (x,y,z) aka (pitch, yaw, roll).
    int
    hashCode()
    Returns a hash code.
    Quatd
    inverse()
    Returns the multiplicative inverse.
    boolean
    isRotationIdentity()
    Tests for an identity rotation.
    boolean
    isZero()
    Tests for a zero value.
    final double
    lengthSq()
    Returns the squared length.
    final Quatd
    mult(Quatd q)
    Takes the Hamilton product of the current instance times the argument to yield a new Quatd.
    final Quatd
    mult(Quatd q, Quatd result)
    Takes the Hamilton product of the current instance times the first argument and returns the product in the 2nd argument.
    Vec3d
    mult(Vec3d v)
    Rotates the argument vector to produce a new vector.
    Vec3d
    mult(Vec3d v, Vec3d result)
    Rotates a specified vector and return the result in another vector.
    final Quatd
    multLocal(Quatd q)
    Takes the Hamilton product of the current instance times the argument, in place.
    final Quatd
    normalizeLocal()
    Normalizes the current instance in place.
    final Quatd
    set(double x, double y, double z, double w)
    Sets all 4 components to the specified values.
    final Quatd
    set(Quaternion quat)
    Copies all 4 components of the specified (single-precision) Quaternion to the current instance.
    final Quatd
    set(Quatd q)
    Copies all 4 components from the argument.
    Quaternion
    toQuaternion()
    Creates a (single-precision) Quaternion that approximates the current instance.
    Matrix3d
    toRotationMatrix()
    Converts the quaternion to an equivalent rotation matrix.
    String
    toString()
    Returns a string representation of the quaternion, which is unaffected.

    Methods inherited from class java.lang.Object

    finalize, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • x

      public double x
      The first imaginary (X) component. Not an angle!

    • y

      public double y
      The 2nd imaginary (Y) component. Not an angle!

    • z

      public double z
      The 3rd imaginary (Z) component. Not an angle!

    • w

      public double w
      The real (W) component. Not an angle!

  • Constructor Details

    • Quatd

      public Quatd()
      Instantiates an identity quaternion: all components zeroed except w, which is set to 1.

    • Quatd

      public Quatd(double x, double y, double z, double w)
      Instantiates a quaternion with the specified components.
      Parameters:
      x - the desired X component
      y - the desired Y component
      z - the desired Z component
      w - the desired W component

    • Quatd

      public Quatd(Quatd quat)
      Instantiates a copy of the argument.
      Parameters:
      quat - the quaternion to copy (not null, unaffected)

    • Quatd

      public Quatd(Quaternion quat)
      Instantiates based on the specified (single-precision) Quaternion.
      Parameters:
      quat - the input Quaternion (not null, unaffected)

  • Method Details

    • clone

      public final Quatd clone()
      Creates a copy. The current instance is unaffected.
      Overrides:
      clone in class Object
      Returns:
      a new instance, equivalent to this one

    • toQuaternion

      public Quaternion toQuaternion()
      Creates a (single-precision) Quaternion that approximates the current instance.
      Returns:
      a new Quaternion

    • hashCode

      public int hashCode()
      Returns a hash code. If two quaternions have identical values, they will have the same hash code. The current instance is unaffected.
      Overrides:
      hashCode in class Object
      Returns:
      a 32-bit value for use in hashing

    • equals

      public boolean equals(Object o)
      Tests for exact equality with the argument, distinguishing -0 from 0. If o is null, false is returned. Either way, the current instance is unaffected.
      Overrides:
      equals in class Object
      Parameters:
      o - the object to compare (may be null, unaffected)
      Returns:
      true if this and o have identical values, otherwise false

    • isRotationIdentity

      public boolean isRotationIdentity()
      Tests for an identity rotation. The quaternion is unaffected.
      Returns:
      true if W is non-zero and not NaN and X, Y, and Z are all 0 or -0, otherwise false

    • isZero

      public boolean isZero()
      Tests for a zero value. The quaternion is unaffected.
      Returns:
      true if all components are 0 or -0, otherwise false

    • set

      public final Quatd set(double x, double y, double z, double w)
      Sets all 4 components to the specified values.
      Parameters:
      x - the desired X component
      y - the desired Y component
      z - the desired Z component
      w - the desired W component
      Returns:
      the (modified) current instance (for chaining)

    • set

      public final Quatd set(Quatd q)
      Copies all 4 components from the argument.
      Parameters:
      q - the quaternion to copy (not null, unaffected)
      Returns:
      the (modified) current instance (for chaining)

    • set

      public final Quatd set(Quaternion quat)
      Copies all 4 components of the specified (single-precision) Quaternion to the current instance.
      Parameters:
      quat - the input Quaternion (not null, unaffected)
      Returns:
      the (modified) current instance (for chaining)

    • mult

      public final Quatd mult(Quatd q)
      Takes the Hamilton product of the current instance times the argument to yield a new Quatd. The current instance is unaffected.

      It is safe for q and this to be the same object.

      This method is used to combine rotations. Note that the Hamilton product is noncommutative, so generally q * p != p * q.

      Parameters:
      q - the right factor (not null, unaffected)
      Returns:
      this * q (a new instance)

    • mult

      public final Quatd mult(Quatd q, Quatd result)
      Takes the Hamilton product of the current instance times the first argument and returns the product in the 2nd argument. The current instance is unaffected, unless it's result.

      This method is used to combine rotations. Note that the Hamilton product is noncommutative, so generally q * p != p * q.

      It is safe for any or all of q, result, and this to be the same object.

      Parameters:
      q - the right factor (not null, unaffected unless it's result)
      result - storage for the product, or null for a new Quatd
      Returns:
      this * q (either result or a new Quatd)

    • multLocal

      public final Quatd multLocal(Quatd q)
      Takes the Hamilton product of the current instance times the argument, in place.

      This method is used to combine rotations. Note that the Hamilton product is noncommutative, so generally q * p != p * q.

      It IS safe for q and this to be the same object.

      Parameters:
      q - the right factor (not null, unaffected unless it's this)
      Returns:
      the (modified) current instance (for chaining)

    • mult

      public Vec3d mult(Vec3d v)
      Rotates the argument vector to produce a new vector. The quaternion is unaffected.
      Parameters:
      v - the input vector (not null, unaffected)
      Returns:
      a new instance

    • mult

      public Vec3d mult(Vec3d v, Vec3d result)
      Rotates a specified vector and return the result in another vector. The quaternion is unaffected.

      It IS safe for v and result to be the same object.

      Parameters:
      v - the vector to rotate (not null, unaffected unless it's result)
      result - storage for the result (not null)
      Returns:
      the (rotated) vector result

    • lengthSq

      public final double lengthSq()
      Returns the squared length.
      Returns:
      the squared length (≥0)

    • normalizeLocal

      public final Quatd normalizeLocal()
      Normalizes the current instance in place.
      Returns:
      the (modified) current instance (for chaining)

    • toRotationMatrix

      public Matrix3d toRotationMatrix()
      Converts the quaternion to an equivalent rotation matrix. The quaternion is unaffected.

      Note: the result is created from a normalized version of the current instance.

      Returns:
      a new 3x3 rotation matrix

    • inverse

      public Quatd inverse()
      Returns the multiplicative inverse. For a quaternion with norm=0, null is returned. Either way, the current instance is unaffected.
      Returns:
      a new instance, or null if not invertible

    • fromAngles

      public Quatd fromAngles(double xAngle, double yAngle, double zAngle)
      Builds a Quaternion from the Euler rotation angles (x,y,z) aka (pitch, yaw, roll). They are applied in order: (y, z, x) aka (yaw, roll, pitch).
      Parameters:
      xAngle - the desired rotation about the +X axis (in radians)
      yAngle - the desired rotation about the +Y axis (in radians)
      zAngle - the desired rotation about the +Z axis (in radians)
      Returns:
      the (modified) current instance (for chaining)
      See Also:

    • toString

      public String toString()
      Returns a string representation of the quaternion, which is unaffected. For example, the identity quaternion is represented by: 
       Quatd[0.0, 0.0, 0.0, 1.0]
      Overrides:
      toString in class Object
      Returns:
      the string representation (not null, not empty)