Package com.ardor3d.math

Class Quaternion

java.lang.Object
com.ardor3d.math.Quaternion
All Implemented Interfaces:
Poolable, ReadOnlyQuaternion, Savable, Externalizable, Serializable, Cloneable
public class Quaternion extends Object implements Cloneable, Savable, Externalizable, ReadOnlyQuaternion, Poolable
Quaternion represents a 4 value math object used in Ardor3D to describe rotations. It has the advantage of being able to avoid lock by adding a 4th dimension to rotation. Note: some algorithms in this class were ported from Eberly, Wolfram, Game Gems and others to Java.
See Also:

  • Field Details

    • ALLOWED_DEVIANCE

      public static final double ALLOWED_DEVIANCE
      Used with equals method to determine if two Quaternions are close enough to be considered equal.
      See Also:

    • IDENTITY

      public static final ReadOnlyQuaternion IDENTITY
      x=0, y=0, z=0, w=1

    • _x

      protected double _x

    • _y

      protected double _y

    • _z

      protected double _z

    • _w

      protected double _w

  • Constructor Details

    • Quaternion

      public Quaternion()
      Constructs a new quaternion set to (0, 0, 0, 1).

    • Quaternion

      public Quaternion(ReadOnlyQuaternion source)
      Constructs a new quaternion set to the (x, y, z, w) values of the given source quaternion.
      Parameters:
      source - the source quaternion

    • Quaternion

      public Quaternion(double x, double y, double z, double w)
      Constructs a new quaternion set to (x, y, z, w).
      Parameters:
      x - the x value
      y - the y value
      z - the z value
      w - the w value

  • Method Details

    • getX

      public double getX()
      Specified by:
      getX in interface ReadOnlyQuaternion

    • getY

      public double getY()
      Specified by:
      getY in interface ReadOnlyQuaternion

    • getZ

      public double getZ()
      Specified by:
      getZ in interface ReadOnlyQuaternion

    • getW

      public double getW()
      Specified by:
      getW in interface ReadOnlyQuaternion

    • getXf

      public float getXf()
      Specified by:
      getXf in interface ReadOnlyQuaternion

    • getYf

      public float getYf()
      Specified by:
      getYf in interface ReadOnlyQuaternion

    • getZf

      public float getZf()
      Specified by:
      getZf in interface ReadOnlyQuaternion

    • getWf

      public float getWf()
      Specified by:
      getWf in interface ReadOnlyQuaternion

    • toArray

      public double[] toArray(double[] store)
      Stores the double values of this quaternion in the given double array as (x,y,z,w).
      Specified by:
      toArray in interface ReadOnlyQuaternion
      Parameters:
      store - The array in which to store the values of this quaternion. If null, a new double[4] array is created.
      Returns:
      the double array
      Throws:
      ArrayIndexOutOfBoundsException - if store is not null and is not at least length 4

    • setX

      public void setX(double x)
      Sets the x component of this quaternion to the given double value.
      Parameters:
      x - the x value to set

    • setY

      public void setY(double y)
      Sets the y component of this quaternion to the given double value.
      Parameters:
      y - the y value to set

    • setZ

      public void setZ(double z)
      Sets the z component of this quaternion to the given double value.
      Parameters:
      z - the z value to set

    • setW

      public void setW(double w)
      Sets the w component of this quaternion to the given double value.
      Parameters:
      w - the w value to set

    • set

      public Quaternion set(double x, double y, double z, double w)
      Sets the value of this quaternion to (x, y, z, w)
      Parameters:
      x - the x value
      y - the y value
      z - the z value
      w - the w value
      Returns:
      this quaternion for chaining

    • set

      public Quaternion set(ReadOnlyQuaternion source)
      Sets the value of this quaternion to the (x, y, z, w) values of the provided source quaternion.
      Parameters:
      source - the source quaternion
      Returns:
      this quaternion for chaining
      Throws:
      NullPointerException - if source is null.

    • fromEulerAngles

      public Quaternion fromEulerAngles(double[] angles)
      Updates this quaternion from the given Euler rotation angles, applied in the given order: heading, attitude, bank.
      Parameters:
      angles - the Euler angles of rotation (in radians) stored as heading, attitude, and bank.
      Returns:
      this quaternion for chaining
      Throws:
      ArrayIndexOutOfBoundsException - if angles is less than length 3
      NullPointerException - if angles is null.

    • fromEulerAngles

      public Quaternion fromEulerAngles(double heading, double attitude, double bank)
      Updates this quaternion from the given Euler rotation angles, applied in the given order: heading, attitude, bank.
      Parameters:
      heading - the Euler heading angle in radians. (rotation about the y axis)
      attitude - the Euler attitude angle in radians. (rotation about the z axis)
      bank - the Euler bank angle in radians. (rotation about the x axis)
      Returns:
      this quaternion for chaining
      See Also:

    • toEulerAngles

      public double[] toEulerAngles(double[] store)
      Converts this quaternion to Euler rotation angles in radians (heading, attitude, bank).
      Specified by:
      toEulerAngles in interface ReadOnlyQuaternion
      Parameters:
      store - the double[] array to store the computed angles in. If null, a new double[] will be created
      Returns:
      the double[] array, filled with heading, attitude and bank in that order..
      Throws:
      ArrayIndexOutOfBoundsException - if non-null store is not at least length 3
      See Also:

    • fromRotationMatrix

      public Quaternion fromRotationMatrix(ReadOnlyMatrix3 matrix)
      Sets the value of this quaternion to the rotation described by the given matrix.
      Parameters:
      matrix - the matrix
      Returns:
      this quaternion for chaining
      Throws:
      NullPointerException - if matrix is null.

    • fromRotationMatrix

      public Quaternion fromRotationMatrix(double m00, double m01, double m02, double m10, double m11, double m12, double m20, double m21, double m22)
      Sets the value of this quaternion to the rotation described by the given matrix values.
      Parameters:
      m00 - m00
      m01 - m01
      m02 - m02
      m10 - m10
      m11 - m11
      m12 - m12
      m20 - m20
      m21 - m21
      m22 - m22
      Returns:
      this quaternion for chaining

    • toRotationMatrix

      public Matrix3 toRotationMatrix(Matrix3 store)
      Specified by:
      toRotationMatrix in interface ReadOnlyQuaternion
      Parameters:
      store - the matrix to store our result in. If null, a new matrix is created.
      Returns:
      the rotation matrix representation of this quaternion (normalized) if store is not null and is read only.

    • toRotationMatrix

      public Matrix4 toRotationMatrix(Matrix4 store)
      Specified by:
      toRotationMatrix in interface ReadOnlyQuaternion
      Parameters:
      store - the matrix to store our result in. If null, a new matrix is created.
      Returns:
      the rotation matrix representation of this quaternion (normalized)

    • getRotationColumn

      public Vector3 getRotationColumn(int index, Vector3 store)
      Specified by:
      getRotationColumn in interface ReadOnlyQuaternion
      Parameters:
      index - the 3x3 rotation matrix column to retrieve from this quaternion (normalized). Must be between 0 and 2.
      store - the vector object to store the result in. if null, a new one is created.
      Returns:
      the column specified by the index.

    • fromAngleAxis

      public Quaternion fromAngleAxis(double angle, ReadOnlyVector3 axis)
      Sets the values of this quaternion to the values represented by a given angle and axis of rotation. Note that this method creates an object, so use fromAngleNormalAxis if your axis is already normalized. If axis == 0,0,0 the quaternion is set to identity.
      Parameters:
      angle - the angle to rotate (in radians).
      axis - the axis of rotation.
      Returns:
      this quaternion for chaining
      Throws:
      NullPointerException - if axis is null

    • fromAngleNormalAxis

      public Quaternion fromAngleNormalAxis(double angle, ReadOnlyVector3 axis)
      Sets the values of this quaternion to the values represented by a given angle and unit length axis of rotation. If axis == 0,0,0 the quaternion is set to identity.
      Parameters:
      angle - the angle to rotate (in radians).
      axis - the axis of rotation (already normalized - unit length).
      Returns:
      this quaternion for chaining
      Throws:
      NullPointerException - if axis is null

    • toAngleAxis

      public double toAngleAxis(Vector3 axisStore)
      Returns the rotation angle represented by this quaternion. If a non-null vector is provided, the axis of rotation is stored in that vector as well.
      Specified by:
      toAngleAxis in interface ReadOnlyQuaternion
      Parameters:
      axisStore - the object we'll store the computed axis in. If null, no computations are done to determine axis.
      Returns:
      the angle of rotation in radians.

    • fromVectorToVector

      public Quaternion fromVectorToVector(ReadOnlyVector3 from, ReadOnlyVector3 to)
      Sets this quaternion to that which will rotate vector "from" into vector "to". from and to do not have to be the same length.
      Parameters:
      from - the source vector to rotate
      to - the destination vector into which to rotate the source vector
      Returns:
      this quaternion for chaining

    • normalize

      public Quaternion normalize(Quaternion store)
      Specified by:
      normalize in interface ReadOnlyQuaternion
      Parameters:
      store - the Quaternion to store the result in. if null, a new one is created.
      Returns:
      a new quaternion that represents a unit length version of this Quaternion.

    • normalizeLocal

      public Quaternion normalizeLocal()
      Returns:
      this quaternion, modified to be unit length, for chaining.

    • invert

      public Quaternion invert(Quaternion store)
      Calculates the multiplicative inverse Q-1 of this quaternion Q such that QQ-1 = [0,0,0,1] (the identity quaternion). Note that for unit quaternions, a quaternion's inverse is equal to its (far easier to calculate) conjugate.
      Parameters:
      store - the Quaternion to store the result in. If null, a new one is created.
      Returns:
      the multiplicative inverse of this quaternion.
      See Also:

    • invertLocal

      public Quaternion invertLocal()
      Locally sets this quaternion Q to its multiplicative inverse Q-1 such that QQ-1 = [0,0,0,1] (the identity quaternion). Note that for unit quaternions, a quaternion's inverse is equal to its (far easier to calculate) conjugate.
      Returns:
      this Quaternion for chaining.
      See Also:

    • conjugate

      public Quaternion conjugate(Quaternion store)
      Creates a new quaternion that is the conjugate [-x, -y, -z, w] of this quaternion.
      Specified by:
      conjugate in interface ReadOnlyQuaternion
      Parameters:
      store - the Quaternion to store the result in. If null, a new one is created.
      Returns:
      the conjugate to this quaternion.

    • conjugateLocal

      public Quaternion conjugateLocal()
      Internally sets this quaternion to its conjugate [-x, -y, -z, w].
      Returns:
      this Quaternion for chaining.

    • add

      public Quaternion add(ReadOnlyQuaternion quat, Quaternion store)
      Adds this quaternion to another and places the result in the given store.
      Specified by:
      add in interface ReadOnlyQuaternion
      Parameters:
      quat - the quaternion
      store - the Quaternion to store the result in. if null, a new one is created.
      Returns:
      a quaternion representing the fields of this quaternion added to those of the given quaternion.

    • addLocal

      public Quaternion addLocal(ReadOnlyQuaternion quat)
      Internally increments the fields of this quaternion with the field values of the given quaternion.
      Parameters:
      quat - the quaternion
      Returns:
      this quaternion for chaining

    • subtract

      public Quaternion subtract(ReadOnlyQuaternion quat, Quaternion store)
      Specified by:
      subtract in interface ReadOnlyQuaternion
      Parameters:
      quat - the quaternion
      store - the Quaternion to store the result in. if null, a new one is created.
      Returns:
      a quaternion representing the fields of this quaternion subtracted from those of the given quaternion.

    • subtractLocal

      public Quaternion subtractLocal(ReadOnlyQuaternion quat)
      Internally decrements the fields of this quaternion by the field values of the given quaternion.
      Parameters:
      quat - the quaternion
      Returns:
      this quaternion for chaining.

    • multiply

      public Quaternion multiply(double scalar, Quaternion store)
      Multiplies each value of this quaternion by the given scalar value.
      Specified by:
      multiply in interface ReadOnlyQuaternion
      Parameters:
      scalar - the quaternion to multiply this quaternion by.
      store - the Quaternion to store the result in. if null, a new one is created.
      Returns:
      the resulting quaternion.

    • multiplyLocal

      public Quaternion multiplyLocal(double scalar)
      Multiplies each value of this quaternion by the given scalar value. The result is stored in this quaternion.
      Parameters:
      scalar - the quaternion to multiply this quaternion by.
      Returns:
      this quaternion for chaining.

    • multiply

      public Quaternion multiply(ReadOnlyQuaternion quat, Quaternion store)
      Multiplies this quaternion by the supplied quaternion. The result is stored in the given store quaternion or a new quaternion if store is null. It IS safe for quat and store to be the same object.
      Specified by:
      multiply in interface ReadOnlyQuaternion
      Parameters:
      quat - the quaternion to multiply this quaternion by.
      store - the quaternion to store the result in.
      Returns:
      the new quaternion. if the given store is read only.

    • multiplyLocal

      public Quaternion multiplyLocal(ReadOnlyQuaternion quat)
      Multiplies this quaternion by the supplied quaternion. The result is stored locally.
      Parameters:
      quat - The Quaternion to multiply this one by.
      Returns:
      this quaternion for chaining
      Throws:
      NullPointerException - if quat is null.

    • multiplyLocal

      public Quaternion multiplyLocal(ReadOnlyMatrix3 matrix)
      Multiplies this quaternion by the supplied matrix. The result is stored locally.
      Parameters:
      matrix - the matrix to apply to this quaternion.
      Returns:
      this quaternion for chaining
      Throws:
      NullPointerException - if matrix is null.

    • multiplyLocal

      public Quaternion multiplyLocal(double qx, double qy, double qz, double qw)
      Multiplies this quaternion by the supplied quaternion values. The result is stored locally.
      Parameters:
      qx - the quaternion x value
      qy - the quaternion y value
      qz - the quaternion z value
      qw - the quaternion w value
      Returns:
      this quaternion for chaining

    • applyRotation

      public Quaternion applyRotation(double angle, double x, double y, double z)
      Multiply this quaternion by a rotational quaternion made from the given angle and axis. The axis must be a normalized vector.
      Parameters:
      angle - in radians
      x - x coord of rotation axis
      y - y coord of rotation axis
      z - z coord of rotation axis
      Returns:
      this quaternion for chaining.

    • applyRotationX

      public Quaternion applyRotationX(double angle)
      Apply rotation around X
      Parameters:
      angle - in radians
      Returns:
      this quaternion for chaining.

    • applyRotationY

      public Quaternion applyRotationY(double angle)
      Apply rotation around Y
      Parameters:
      angle - in radians
      Returns:
      this quaternion for chaining.

    • applyRotationZ

      public Quaternion applyRotationZ(double angle)
      Apply rotation around Z
      Parameters:
      angle - in radians
      Returns:
      this quaternion for chaining.

    • apply

      public Vector3 apply(ReadOnlyVector3 vec, Vector3 store)
      Rotates the given vector by this quaternion. If supplied, the result is stored into the supplied "store" vector.
      Specified by:
      apply in interface ReadOnlyQuaternion
      Parameters:
      vec - the vector to multiply this quaternion by.
      store - the vector to store the result in. If store is null, a new vector is created. Note that it IS safe for vec and store to be the same object.
      Returns:
      the store vector, or a new vector if store is null.
      Throws:
      NullPointerException - if vec is null if the given store is read only.

    • fromAxes

      public Quaternion fromAxes(ReadOnlyVector3 xAxis, ReadOnlyVector3 yAxis, ReadOnlyVector3 zAxis)
      Updates this quaternion to represent a rotation formed by the given three axes. These axes are assumed to be orthogonal and no error checking is applied. It is the user's job to insure that the three axes being provided indeed represent a proper right handed coordinate system.
      Parameters:
      xAxis - vector representing the x-axis of the coordinate system.
      yAxis - vector representing the y-axis of the coordinate system.
      zAxis - vector representing the z-axis of the coordinate system.
      Returns:
      this quaternion for chaining

    • toAxes

      public Vector3[] toAxes(Vector3[] axes)
      Converts this quaternion to a rotation matrix and then extracts rotation axes.
      Specified by:
      toAxes in interface ReadOnlyQuaternion
      Parameters:
      axes - the array of vectors to be filled.
      Returns:
      the axes
      Throws:
      ArrayIndexOutOfBoundsException - if the given axes array is smaller than 3 elements.

    • slerp

      public Quaternion slerp(ReadOnlyQuaternion endQuat, double changeAmnt, Quaternion store)
      Does a spherical linear interpolation between this quaternion and the given end quaternion by the given change amount.
      Specified by:
      slerp in interface ReadOnlyQuaternion
      Parameters:
      endQuat - the end quaternion
      changeAmnt - the change amount
      store - the quaternion to store the result in for return. If null, a new quaternion object is created and returned.
      Returns:
      a new quaternion containing the result.

    • slerpLocal

      public Quaternion slerpLocal(ReadOnlyQuaternion endQuat, double changeAmnt)
      Does a spherical linear interpolation between this quaternion and the given end quaternion by the given change amount. Stores the results locally in this quaternion.
      Parameters:
      endQuat - the end quaternion
      changeAmnt - the change amount
      Returns:
      this quaternion for chaining.

    • slerp

      public static Quaternion slerp(ReadOnlyQuaternion startQuat, ReadOnlyQuaternion endQuat, double changeAmnt, Quaternion store)
      Does a spherical linear interpolation between the given start and end quaternions by the given change amount. Returns the result as a new quaternion.
      Parameters:
      startQuat - the start quaternion
      endQuat - the end quaternion
      changeAmnt - the change amount
      store - the quaternion to store the result in for return. If null, a new quaternion object is created and returned.
      Returns:
      the new quaternion

    • slerpLocal

      public Quaternion slerpLocal(ReadOnlyQuaternion startQuat, ReadOnlyQuaternion endQuat, double changeAmnt, Quaternion workQuat)
      Does a spherical linear interpolation between the given start and end quaternions by the given change amount. Stores the result locally.
      Parameters:
      startQuat - the start quaternion
      endQuat - the end quaternion
      changeAmnt - the change amount
      workQuat - a Quaternion to use as scratchpad during calculation
      Returns:
      this quaternion for chaining.
      Throws:
      NullPointerException - if startQuat, endQuat or workQuat are null.

    • slerpLocal

      public Quaternion slerpLocal(ReadOnlyQuaternion startQuat, ReadOnlyQuaternion endQuat, double changeAmnt)
      Does a spherical linear interpolation between the given start and end quaternions by the given change amount. Stores the result locally.
      Parameters:
      startQuat - the start quaternion
      endQuat - the end quaternion
      changeAmnt - the change amount
      Returns:
      this quaternion for chaining.
      Throws:
      NullPointerException - if startQuat or endQuat are null.

    • lookAt

      public Quaternion lookAt(ReadOnlyVector3 direction, ReadOnlyVector3 up)
      Modifies this quaternion to equal the rotation required to point the z-axis at 'direction' and the y-axis to 'up'.
      Parameters:
      direction - where to 'look' at
      up - a vector indicating the local up direction.
      Returns:
      this quaternion for chaining.

    • magnitudeSquared

      public double magnitudeSquared()
      Specified by:
      magnitudeSquared in interface ReadOnlyQuaternion
      Returns:
      the squared magnitude of this quaternion.

    • magnitude

      public double magnitude()
      Specified by:
      magnitude in interface ReadOnlyQuaternion
      Returns:
      the magnitude of this quaternion. basically sqrt(magnitude())

    • dot

      public double dot(double x, double y, double z, double w)
      Specified by:
      dot in interface ReadOnlyQuaternion
      Parameters:
      x - the abscissa
      y - the ordinate
      z - the applicate
      w - the w value
      Returns:
      the dot product of this quaternion with the given x,y,z and w values.

    • dot

      public double dot(ReadOnlyQuaternion quat)
      Specified by:
      dot in interface ReadOnlyQuaternion
      Parameters:
      quat - the quaternion
      Returns:
      the dot product of this quaternion with the given quaternion.

    • setIdentity

      public Quaternion setIdentity()
      Sets the value of this quaternion to (0, 0, 0, 1). Equivalent to calling set(0, 0, 0, 1)
      Returns:
      this quaternion for chaining

    • isIdentity

      public boolean isIdentity()
      Specified by:
      isIdentity in interface ReadOnlyQuaternion
      Returns:
      true if this quaternion is (0, 0, 0, 1)

    • isValid

      public static boolean isValid(ReadOnlyQuaternion quat)
      Check a quaternion... if it is null or its doubles are NaN or infinite, return false. Else return true.
      Parameters:
      quat - the quaternion to check
      Returns:
      true or false as stated above.

    • toString

      public String toString()
      Overrides:
      toString in class Object
      Returns:
      the string representation of this quaternion.

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object
      Returns:
      returns a unique code for this quaternion object based on its values. If two quaternions are numerically equal, they will return the same hash code value.

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object
      Parameters:
      o - the object to compare for equality
      Returns:
      true if this quaternion and the provided quaternion have roughly the same x, y, z and w values.

    • strictEquals

      public boolean strictEquals(Object o)
      Specified by:
      strictEquals in interface ReadOnlyQuaternion
      Parameters:
      o - the object to compare for equality
      Returns:
      true if this quaternion and the provided quaternion have the exact same double values.

    • clone

      public Quaternion clone()
      Specified by:
      clone in interface ReadOnlyQuaternion
      Overrides:
      clone in class Object

    • getClassTag

      public Class<? extends Quaternion> getClassTag()
      Specified by:
      getClassTag in interface Savable

    • write

      public void write(OutputCapsule capsule) throws IOException
      Specified by:
      write in interface Savable
      Throws:
      IOException

    • read

      public void read(InputCapsule capsule) throws IOException
      Specified by:
      read in interface Savable
      Throws:
      IOException

    • readExternal

      public void readExternal(ObjectInput in) throws IOException, ClassNotFoundException
      Used with serialization. Not to be called manually.
      Specified by:
      readExternal in interface Externalizable
      Parameters:
      in - ObjectInput
      Throws:
      IOException - if something wrong occurs while reading
      ClassNotFoundException - if a class is not found

    • writeExternal

      public void writeExternal(ObjectOutput out) throws IOException
      Used with serialization. Not to be called manually.
      Specified by:
      writeExternal in interface Externalizable
      Parameters:
      out - ObjectOutput
      Throws:
      IOException - if something wrong occurs while writing

    • fetchTempInstance

      public static final Quaternion fetchTempInstance()
      Returns:
      An instance of Quaternion that is intended for temporary use in calculations and so forth. Multiple calls to the method should return instances of this class that are not currently in use.

    • releaseTempInstance

      public static final void releaseTempInstance(Quaternion mat)
      Releases a Quaternion back to be used by a future call to fetchTempInstance. TAKE CARE: this Quaternion object should no longer have other classes referencing it or "Bad Things" will happen.
      Parameters:
      mat - the Quaternion to release.