Package com.jme3.math

Class Quaternion

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

Mathematically, quaternions are an extension of complex numbers. In mathematics texts, W often appears first, but in JME it always comes last.

See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Quaternion
    DIRECTION_Z
    Another shared instance of the identity quaternion (0, 0, 0, 1).
    static final Quaternion
    IDENTITY
    Shared instance of the identity quaternion (0, 0, 0, 1).
    protected float
    w
    The real (W) component.
    protected float
    x
    The first imaginary (X) component.
    protected float
    y
    The 2nd imaginary (Y) component.
    protected float
    z
    The 3rd imaginary (Z) component.
    static final Quaternion
    ZERO
    Shared instance of the zero quaternion (0, 0, 0, 0).

  • Constructor Summary

    Constructors
    Constructor
    Description
    Quaternion()
    Instantiates an identity quaternion: all components zeroed except w, which is set to 1.
    Quaternion(float x, float y, float z, float w)
    Instantiates a quaternion with the specified components.
    Quaternion(Quaternion q)
    Instantiates a copy of the argument.

  • Method Summary

    Modifier and Type
    Method
    Description
    Quaternion
    addLocal(Quaternion q)
    Adds the argument and returns the (modified) current instance.
    Quaternion
    clone()
    Creates a copy.
    boolean
    equals(Object o)
    Tests for exact equality with the argument, distinguishing -0 from 0.
    Quaternion
    fromAngleNormalAxis(float angle, Vector3f axis)
    Sets the quaternion from the specified rotation angle and normalized axis of rotation.
    Quaternion
    fromAngles(float xAngle, float yAngle, float zAngle)
    Sets the quaternion from the specified Tait-Bryan angles, applying the rotations in x-z-y extrinsic order or y-z'-x" intrinsic order.
    Quaternion
    fromAxes(Vector3f xAxis, Vector3f yAxis, Vector3f zAxis)
    Sets the quaternion from the specified orthonormal basis.
    Quaternion
    fromRotationMatrix(float m00, float m01, float m02, float m10, float m11, float m12, float m20, float m21, float m22)
    Sets the quaternion from a rotation matrix with the specified elements.
    Quaternion
    fromRotationMatrix(Matrix3f matrix)
    Sets the quaternion from the specified rotation matrix.
    float
    getW()
    Returns the W (real) component.
    float
    getX()
    Returns the X component.
    float
    getY()
    Returns the Y component.
    float
    getZ()
    Returns the Z component.
    int
    hashCode()
    Returns a hash code.
    Quaternion
    inverse()
    Returns the multiplicative inverse.
    static boolean
    isValidQuaternion(Quaternion quaternion)
    Tests whether the argument is a valid quaternion, returning false if it's null or if any component is NaN or infinite.
    void
    loadIdentity()
    Sets all components to zero except w, which is set to 1.
    Quaternion
    mult(Quaternion q)
    Multiplies by the argument and returns the product as a new instance.
    Quaternion
    mult(Quaternion q, Quaternion storeResult)
    Multiplies by the specified quaternion and returns the product in a 3rd quaternion.
    Quaternion
    multLocal(float scalar)
    Multiplies by the scalar argument and returns the (modified) current instance.
    Quaternion
    multLocal(float qx, float qy, float qz, float qw)
    Multiplies by a quaternion with the specified components and returns the (modified) current instance.
    Quaternion
    multLocal(Quaternion q)
    Multiplies by the argument and returns the (modified) current instance.
    float
    norm()
    Returns the norm, defined as the dot product of the quaternion with itself.
    Quaternion
    normalizeLocal()
    Scales the quaternion to have norm=1 and returns the (modified) current instance.
    Quaternion
    set(float x, float y, float z, float w)
    Sets all 4 components to specified values.
    Quaternion
    set(Quaternion q)
    Copies all 4 components from the argument.
    Matrix3f
    toRotationMatrix()
    Converts to an equivalent rotation matrix.
    Matrix3f
    toRotationMatrix(Matrix3f result)
    Converts to an equivalent rotation matrix.
    Matrix4f
    toRotationMatrix(Matrix4f result)
    Sets the rotation component of the specified transform matrix.
    String
    toString()
    Returns a string representation of the quaternion, which is unaffected.
    Matrix4f
    toTransformMatrix(Matrix4f store)
    Sets the rotation component of the specified transform matrix.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • IDENTITY

      public static final Quaternion IDENTITY
      Shared instance of the identity quaternion (0, 0, 0, 1). Do not modify!

      This is the usual representation for a null rotation.

    • DIRECTION_Z

      public static final Quaternion DIRECTION_Z
      Another shared instance of the identity quaternion (0, 0, 0, 1). Do not modify!

    • ZERO

      public static final Quaternion ZERO
      Shared instance of the zero quaternion (0, 0, 0, 0). Do not modify!

      The zero quaternion doesn't represent any valid rotation.

    • x

      protected float x
      The first imaginary (X) component. Not an angle!

    • y

      protected float y
      The 2nd imaginary (Y) component. Not an angle!

    • z

      protected float z
      The 3rd imaginary (Z) component. Not an angle!

    • w

      protected float w
      The real (W) component. Not an angle!

  • Constructor Details

    • Quaternion

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

    • Quaternion

      public Quaternion(float x, float y, float z, float 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

    • Quaternion

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

  • Method Details

    • getX

      public float getX()
      Returns the X component. The quaternion is unaffected.
      Returns:
      the value of the x component

    • getY

      public float getY()
      Returns the Y component. The quaternion is unaffected.
      Returns:
      the value of the y component

    • getZ

      public float getZ()
      Returns the Z component. The quaternion is unaffected.
      Returns:
      the value of the z component

    • getW

      public float getW()
      Returns the W (real) component. The quaternion is unaffected.
      Returns:
      the value of the w component

    • set

      public Quaternion set(float x, float y, float z, float w)
      Sets all 4 components to 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 Quaternion set(Quaternion q)
      Copies all 4 components from the argument.
      Parameters:
      q - the quaternion to copy (not null, unaffected)
      Returns:
      the (modified) current instance (for chaining)

    • loadIdentity

      public void loadIdentity()
      Sets all components to zero except w, which is set to 1.

    • fromAngles

      public Quaternion fromAngles(float xAngle, float yAngle, float zAngle)
      Sets the quaternion from the specified Tait-Bryan angles, applying the rotations in x-z-y extrinsic order or y-z'-x" intrinsic order.
      Parameters:
      xAngle - the X angle (in radians)
      yAngle - the Y angle (in radians)
      zAngle - the Z angle (in radians)
      Returns:
      the (modified) current instance (for chaining)
      See Also:

    • fromRotationMatrix

      public Quaternion fromRotationMatrix(Matrix3f matrix)
      Sets the quaternion from the specified rotation matrix.

      Does not verify that the argument is a valid rotation matrix. Positive scaling is compensated for, but not reflection or shear.

      Parameters:
      matrix - the input matrix (not null, unaffected)
      Returns:
      the (modified) current instance (for chaining)

    • fromRotationMatrix

      public Quaternion fromRotationMatrix(float m00, float m01, float m02, float m10, float m11, float m12, float m20, float m21, float m22)
      Sets the quaternion from a rotation matrix with the specified elements.

      Does not verify that the arguments form a valid rotation matrix. Positive scaling is compensated for, but not reflection or shear.

      Parameters:
      m00 - the matrix element in row 0, column 0
      m01 - the matrix element in row 0, column 1
      m02 - the matrix element in row 0, column 2
      m10 - the matrix element in row 1, column 0
      m11 - the matrix element in row 1, column 1
      m12 - the matrix element in row 1, column 2
      m20 - the matrix element in row 2, column 0
      m21 - the matrix element in row 2, column 1
      m22 - the matrix element in row 2, column 2
      Returns:
      the (modified) current instance (for chaining)

    • toRotationMatrix

      public Matrix3f toRotationMatrix()
      Converts to an equivalent rotation matrix. The current instance is unaffected.

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

      Returns:
      a new 3x3 rotation matrix

    • toRotationMatrix

      public Matrix3f toRotationMatrix(Matrix3f result)
      Converts to an equivalent rotation matrix. The current instance is unaffected.

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

      Parameters:
      result - storage for the result (not null)
      Returns:
      result, configured as a 3x3 rotation matrix

    • toTransformMatrix

      public Matrix4f toTransformMatrix(Matrix4f store)
      Sets the rotation component of the specified transform matrix. The current instance is unaffected.

      Note: preserves the translation component of store but not its scaling component.

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

      Parameters:
      store - storage for the result (not null)
      Returns:
      store, with 9 of its 16 elements modified

    • toRotationMatrix

      public Matrix4f toRotationMatrix(Matrix4f result)
      Sets the rotation component of the specified transform matrix. The current instance is unaffected.

      Note: preserves the translation and scaling components of result unless result includes reflection.

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

      Parameters:
      result - storage for the result (not null)
      Returns:
      result, with 9 of its 16 elements modified

    • fromAngleNormalAxis

      public Quaternion fromAngleNormalAxis(float angle, Vector3f axis)
      Sets the quaternion from the specified rotation angle and normalized axis of rotation.
      Parameters:
      angle - the desired rotation angle (in radians)
      axis - the desired axis of rotation (not null, length=1, unaffected)
      Returns:
      the (modified) current instance (for chaining)

    • addLocal

      public Quaternion addLocal(Quaternion q)
      Adds the argument and returns the (modified) current instance.

      Seldom used. To combine rotations, use multLocal(com.jme3.math.Quaternion) or mult(com.jme3.math.Quaternion, com.jme3.math.Quaternion) instead of this method.

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

    • mult

      public Quaternion mult(Quaternion q)
      Multiplies by the argument and returns the product as a new instance. The current instance is unaffected.

      This method is used to combine rotations. Note that quaternion multiplication is noncommutative, so generally q * p != p * q.

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

    • mult

      public Quaternion mult(Quaternion q, Quaternion storeResult)
      Multiplies by the specified quaternion and returns the product in a 3rd quaternion. The current instance is unaffected, unless it's storeResult.

      This method is used to combine rotations. Note that quaternion multiplication is noncommutative, so generally q * p != p * q.

      It is safe for q and storeResult to be the same object. However, if this and storeResult are the same object, the result is undefined.

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

    • fromAxes

      public Quaternion fromAxes(Vector3f xAxis, Vector3f yAxis, Vector3f zAxis)
      Sets the quaternion from the specified orthonormal basis.

      The 3 basis vectors describe the axes of a rotated coordinate system. They are assumed to be normalized, mutually orthogonal, and in right-hand order. No error checking is performed; the caller must ensure that the specified vectors represent a right-handed coordinate system.

      Parameters:
      xAxis - the X axis of the desired coordinate system (not null, length=1, unaffected)
      yAxis - the Y axis of the desired coordinate system (not null, length=1, unaffected)
      zAxis - the Z axis of the desired coordinate system (not null, length=1, unaffected)
      Returns:
      the (modified) current instance (for chaining)

    • multLocal

      public Quaternion multLocal(Quaternion q)
      Multiplies by the argument and returns the (modified) current instance.

      This method is used to combine rotations. Note that quaternion multiplication is noncommutative, so generally q * p != p * q.

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

    • multLocal

      public Quaternion multLocal(float qx, float qy, float qz, float qw)
      Multiplies by a quaternion with the specified components and returns the (modified) current instance.

      This method is used to combine rotations. Note that quaternion multiplication is noncommutative, so generally q * p != p * q.

      Parameters:
      qx - the X component of the right factor
      qy - the Y component of the right factor
      qz - the Z component of the right factor
      qw - the W component of the right factor
      Returns:
      the (modified) current instance (for chaining)

    • multLocal

      public Quaternion multLocal(float scalar)
      Multiplies by the scalar argument and returns the (modified) current instance.
      Parameters:
      scalar - the scaling factor
      Returns:
      the (modified) current instance (for chaining)

    • norm

      public float norm()
      Returns the norm, defined as the dot product of the quaternion with itself. The current instance is unaffected.
      Returns:
      the sum of the squared components (not negative)

    • normalizeLocal

      public Quaternion normalizeLocal()
      Scales the quaternion to have norm=1 and returns the (modified) current instance. For a quaternion with norm=0, the result is undefined.
      Returns:
      the (modified) current instance (for chaining)

    • inverse

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

    • toString

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

    • 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

    • 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
      See Also:

    • clone

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

    • isValidQuaternion

      public static boolean isValidQuaternion(Quaternion quaternion)
      Tests whether the argument is a valid quaternion, returning false if it's null or if any component is NaN or infinite.
      Parameters:
      quaternion - the quaternion to test (unaffected)
      Returns:
      true if non-null and finite, otherwise false