Class Quaternion

java.lang.Object
com.jogamp.opengl.math.Quaternion

public class Quaternion extends Object
Quaternion implementation supporting Gimbal-Lock free rotations.

All matrix operation provided are in column-major order, as specified in the OpenGL fixed function pipeline, i.e. compatibility profile. See FloatUtil.

See Matrix-FAQ

See euclideanspace.com-Quaternion

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final float
    Quaternion Epsilon, used with equals method to determine if two Quaternions are close enough to be considered equal.
  • Constructor Summary

    Constructors
    Constructor
    Description
     
    Quaternion(float x, float y, float z, float w)
     
     
  • Method Summary

    Modifier and Type
    Method
    Description
    Add a quaternion
    Conjugates this quaternion [-x, -y, -z, w].
    float[]
    copyMatrixColumn(int index, float[] result, int resultOffset)
     
    final float
    dot(float x, float y, float z, float w)
    Returns the dot product of this quaternion with the given x,y,z and w components.
    final float
    Returns the dot product of this quaternion with the given quaternion
    boolean
     
    final float
     
    final float
     
    final float
     
    final float
     
    final int
     
    Invert the quaternion If rotational, will produce a the inverse rotation
    final boolean
    Returns true if this quaternion has identity.
    final boolean
    isRotationMatrix3f(float[] m)
    Check if the the 3x3 matrix (param) is in fact an affine rotational matrix
    final float
    Return the magnitude of this quaternion, i.e.
    final float
    See magnitude() for special handling of epsilon, which is not applied here.
    Multiply this quaternion by the param quaternion
    Normalize a quaternion required if to be used as a rotational quaternion.
    rotateByAngleNormalAxis(float angle, float axisX, float axisY, float axisZ)
    Rotate this quaternion by the given angle and axis.
    rotateByAngleX(float angle)
    Rotate this quaternion around X axis with the given angle in radians
    rotateByAngleY(float angle)
    Rotate this quaternion around Y axis with the given angle in radians
    rotateByAngleZ(float angle)
    Rotate this quaternion around Z axis with the given angle in radians
    rotateByEuler(float[] angradXYZ)
    Rotates this quaternion from the given Euler rotation array angradXYZ in radians.
    rotateByEuler(float bankX, float headingY, float attitudeZ)
    Rotates this quaternion from the given Euler rotation angles in radians.
    final float[]
    rotateVector(float[] vecOut, int vecOutOffset, float[] vecIn, int vecInOffset)
    Rotate the given vector by this quaternion
    scale(float n)
    Scale this quaternion by a constant
    set(float x, float y, float z, float w)
    Set all values of this quaternion using the given components.
    Set all values of this quaternion using the given src.
    setFromAngleAxis(float angle, float[] vector, float[] tmpV3f)
    Initialize this quaternion with given non-normalized axis vector and rotation angle
    setFromAngleNormalAxis(float angle, float[] vector)
    Initialize this quaternion with given normalized axis vector and rotation angle
    setFromAxes(float[] xAxis, float[] yAxis, float[] zAxis)
    Initializes this quaternion to represent a rotation formed by the given three orthogonal axes.
    setFromEuler(float[] angradXYZ)
    Initializes this quaternion from the given Euler rotation array angradXYZ in radians.
    setFromEuler(float bankX, float headingY, float attitudeZ)
    Initializes this quaternion from the given Euler rotation angles in radians.
    setFromMatrix(float[] m, int m_off)
    Initializes this quaternion from a 4x4 column rotation matrix
    setFromMatrix(float m00, float m01, float m02, float m10, float m11, float m12, float m20, float m21, float m22)
    Compute the quaternion from a 3x3 column rotation matrix
    setFromNormalVectors(float[] v1, float[] v2, float[] tmpPivotVec)
    Initialize this quaternion from two normalized vectors
    setFromVectors(float[] v1, float[] v2, float[] tmpPivotVec, float[] tmpNormalVec)
    Initialize this quaternion from two vectors
    Set this quaternion to identity (x=0,y=0,z=0,w=1)
    setLookAt(float[] directionIn, float[] upIn, float[] xAxisOut, float[] yAxisOut, float[] zAxisOut)
    Set this quaternion to equal the rotation required to point the z-axis at direction and the y-axis to up.
    setSlerp(Quaternion a, Quaternion b, float changeAmnt)
    Set this quaternion to a spherical linear interpolation between the given start and end quaternions by the given change amount.
    final void
    setW(float w)
     
    final void
    setX(float x)
     
    final void
    setY(float y)
     
    final void
    setZ(float z)
     
    Subtract a quaternion
    final float
    toAngleAxis(float[] axis)
    Transform the rotational quaternion to axis based rotation angles
    void
    toAxes(float[] xAxis, float[] yAxis, float[] zAxis, float[] tmpMat4)
    Extracts this quaternion's orthogonal rotation axes.
    float[]
    toEuler(float[] result)
    Transform this quaternion to Euler rotation angles in radians (pitchX, yawY and rollZ).
    final float[]
    toMatrix(float[] matrix, int mat_offset)
    Transform this quaternion to a normalized 4x4 column matrix representing the rotation.
     

    Methods inherited from class java.lang.Object

    getClass, notify, notifyAll, wait, wait, wait
  • Field Details

    • ALLOWED_DEVIANCE

      public static final float ALLOWED_DEVIANCE
      Quaternion Epsilon, used with equals method to determine if two Quaternions are close enough to be considered equal.

      Using 9.999999974752427E-7f, which is ~10 times FloatUtil.EPSILON.

      See Also:
  • Constructor Details

    • Quaternion

      public Quaternion()
    • Quaternion

      public Quaternion(Quaternion q)
    • Quaternion

      public Quaternion(float x, float y, float z, float w)
  • Method Details

    • magnitudeSquared

      public final float magnitudeSquared()
      See magnitude() for special handling of epsilon, which is not applied here.
      Returns:
      the squared magnitude of this quaternion.
    • magnitude

      public final float magnitude()
      Return the magnitude of this quaternion, i.e. sqrt(magnitude())

      A magnitude of zero shall equal identity, as performed by normalize().

      Implementation Details:

    • getW

      public final float getW()
    • setW

      public final void setW(float w)
    • getX

      public final float getX()
    • setX

      public final void setX(float x)
    • getY

      public final float getY()
    • setY

      public final void setY(float y)
    • getZ

      public final float getZ()
    • setZ

      public final void setZ(float z)
    • dot

      public final float dot(float x, float y, float z, float w)
      Returns the dot product of this quaternion with the given x,y,z and w components.
    • dot

      public final float dot(Quaternion quat)
      Returns the dot product of this quaternion with the given quaternion
    • isIdentity

      public final boolean isIdentity()
      Returns true if this quaternion has identity.

      Implementation uses epsilon to compare W against 1f and X, Y and Z against zero.

    • setIdentity

      public final Quaternion setIdentity()
      Set this quaternion to identity (x=0,y=0,z=0,w=1)
      Returns:
      this quaternion for chaining.
    • normalize

      public final Quaternion normalize()
      Normalize a quaternion required if to be used as a rotational quaternion.

      Implementation Details:

      Returns:
      this quaternion for chaining.
    • conjugate

      public Quaternion conjugate()
      Conjugates this quaternion [-x, -y, -z, w].
      Returns:
      this quaternion for chaining.
      See Also:
    • invert

      public final Quaternion invert()
      Invert the quaternion If rotational, will produce a the inverse rotation

      Implementation Details:

      Returns:
      this quaternion for chaining.
      See Also:
    • set

      public final Quaternion set(Quaternion src)
      Set all values of this quaternion using the given src.
      Returns:
      this quaternion for chaining.
    • set

      public final Quaternion set(float x, float y, float z, float w)
      Set all values of this quaternion using the given components.
      Returns:
      this quaternion for chaining.
    • add

      public final Quaternion add(Quaternion q)
      Add a quaternion
      Parameters:
      q - quaternion
      Returns:
      this quaternion for chaining.
      See Also:
    • subtract

      public final Quaternion subtract(Quaternion q)
      Subtract a quaternion
      Parameters:
      q - quaternion
      Returns:
      this quaternion for chaining.
      See Also:
    • mult

      public final Quaternion mult(Quaternion q)
      Multiply this quaternion by the param quaternion
      Parameters:
      q - a quaternion to multiply with
      Returns:
      this quaternion for chaining.
      See Also:
    • scale

      public final Quaternion scale(float n)
      Scale this quaternion by a constant
      Parameters:
      n - a float constant
      Returns:
      this quaternion for chaining.
      See Also:
    • rotateByAngleNormalAxis

      public Quaternion rotateByAngleNormalAxis(float angle, float axisX, float axisY, float axisZ)
      Rotate this quaternion by the given angle and axis.

      The axis must be a normalized vector.

      A rotational quaternion is made from the given angle and axis.

      Parameters:
      angle - in radians
      axisX - x-coord of rotation axis
      axisY - y-coord of rotation axis
      axisZ - z-coord of rotation axis
      Returns:
      this quaternion for chaining.
    • rotateByAngleX

      public Quaternion rotateByAngleX(float angle)
      Rotate this quaternion around X axis with the given angle in radians
      Parameters:
      angle - in radians
      Returns:
      this quaternion for chaining.
    • rotateByAngleY

      public Quaternion rotateByAngleY(float angle)
      Rotate this quaternion around Y axis with the given angle in radians
      Parameters:
      angle - in radians
      Returns:
      this quaternion for chaining.
    • rotateByAngleZ

      public Quaternion rotateByAngleZ(float angle)
      Rotate this quaternion around Z axis with the given angle in radians
      Parameters:
      angle - in radians
      Returns:
      this quaternion for chaining.
    • rotateByEuler

      public final Quaternion rotateByEuler(float[] angradXYZ)
      Rotates this quaternion from the given Euler rotation array angradXYZ in radians.

      The angradXYZ array is laid out in natural order:

      • x - bank
      • y - heading
      • z - attitude

      For details see rotateByEuler(float, float, float).
      Parameters:
      angradXYZ - euler angel array in radians
      Returns:
      this quaternion for chaining.
      See Also:
    • rotateByEuler

      public final Quaternion rotateByEuler(float bankX, float headingY, float attitudeZ)
      Rotates this quaternion from the given Euler rotation angles in radians.

      The rotations are applied in the given order and using chained rotation per axis:

      Implementation Details:

      Parameters:
      bankX - the Euler pitch angle in radians. (rotation about the X axis)
      headingY - the Euler yaw angle in radians. (rotation about the Y axis)
      attitudeZ - the Euler roll angle in radians. (rotation about the Z axis)
      Returns:
      this quaternion for chaining.
      See Also:
    • rotateVector

      public final float[] rotateVector(float[] vecOut, int vecOutOffset, float[] vecIn, int vecInOffset)
      Rotate the given vector by this quaternion
      Parameters:
      vecOut - result float[3] storage for rotated vector, maybe equal to vecIn for in-place rotation
      vecOutOffset - offset in result storage
      vecIn - float[3] vector to be rotated
      vecInOffset - offset in vecIn
      Returns:
      the given vecOut store for chaining
      See Also:
    • setSlerp

      public final Quaternion setSlerp(Quaternion a, Quaternion b, float changeAmnt)
      Set this quaternion to a spherical linear interpolation between the given start and end quaternions by the given change amount.

      Note: Method does not normalize this quaternion!

      Parameters:
      a - start quaternion
      b - end quaternion
      changeAmnt - float between 0 and 1 representing interpolation.
      Returns:
      this quaternion for chaining.
      See Also:
    • setLookAt

      public Quaternion setLookAt(float[] directionIn, float[] upIn, float[] xAxisOut, float[] yAxisOut, float[] zAxisOut)
      Set this quaternion to equal the rotation required to point the z-axis at direction and the y-axis to up.

      Implementation generates a 3x3 matrix and is equal with ProjectFloat's lookAt(..).

      Implementation Details:

      Parameters:
      directionIn - where to look at
      upIn - a vector indicating the local up direction.
      xAxisOut - vector storing the orthogonal x-axis of the coordinate system.
      yAxisOut - vector storing the orthogonal y-axis of the coordinate system.
      zAxisOut - vector storing the orthogonal z-axis of the coordinate system.
      Returns:
      this quaternion for chaining.
      See Also:
    • setFromVectors

      public final Quaternion setFromVectors(float[] v1, float[] v2, float[] tmpPivotVec, float[] tmpNormalVec)
      Initialize this quaternion from two vectors
         q = (s,v) = (v1•v2 , v1 × v2),
           angle = angle(v1, v2) = v1•v2
            axis = normal(v1 x v2)
       

      Implementation Details:

      Parameters:
      v1 - not normalized
      v2 - not normalized
      tmpPivotVec - float[3] temp storage for cross product
      tmpNormalVec - float[3] temp storage to normalize vector
      Returns:
      this quaternion for chaining.
    • setFromNormalVectors

      public final Quaternion setFromNormalVectors(float[] v1, float[] v2, float[] tmpPivotVec)
      Initialize this quaternion from two normalized vectors
         q = (s,v) = (v1•v2 , v1 × v2),
           angle = angle(v1, v2) = v1•v2
            axis = v1 x v2
       

      Implementation Details:

      Parameters:
      v1 - normalized
      v2 - normalized
      tmpPivotVec - float[3] temp storage for cross product
      Returns:
      this quaternion for chaining.
    • setFromAngleAxis

      public final Quaternion setFromAngleAxis(float angle, float[] vector, float[] tmpV3f)
      Initialize this quaternion with given non-normalized axis vector and rotation angle

      Implementation Details:

      Parameters:
      angle - rotation angle (rads)
      vector - axis vector not normalized
      tmpV3f - float[3] temp storage to normalize vector
      Returns:
      this quaternion for chaining.
      See Also:
    • setFromAngleNormalAxis

      public final Quaternion setFromAngleNormalAxis(float angle, float[] vector)
      Initialize this quaternion with given normalized axis vector and rotation angle

      Implementation Details:

      Parameters:
      angle - rotation angle (rads)
      vector - axis vector normalized
      Returns:
      this quaternion for chaining.
      See Also:
    • toAngleAxis

      public final float toAngleAxis(float[] axis)
      Transform the rotational quaternion to axis based rotation angles
      Parameters:
      axis - float[3] storage for computed axis
      Returns:
      the rotation angle in radians
      See Also:
    • setFromEuler

      public final Quaternion setFromEuler(float[] angradXYZ)
      Initializes this quaternion from the given Euler rotation array angradXYZ in radians.

      The angradXYZ array is laid out in natural order:

      • x - bank
      • y - heading
      • z - attitude

      For details see setFromEuler(float, float, float).
      Parameters:
      angradXYZ - euler angel array in radians
      Returns:
      this quaternion for chaining.
      See Also:
    • setFromEuler

      public final Quaternion setFromEuler(float bankX, float headingY, float attitudeZ)
      Initializes this quaternion from the given Euler rotation angles in radians.

      The rotations are applied in the given order:

      • y - heading
      • z - attitude
      • x - bank

      Implementation Details:

      Parameters:
      bankX - the Euler pitch angle in radians. (rotation about the X axis)
      headingY - the Euler yaw angle in radians. (rotation about the Y axis)
      attitudeZ - the Euler roll angle in radians. (rotation about the Z axis)
      Returns:
      this quaternion for chaining.
      See Also:
    • toEuler

      public float[] toEuler(float[] result)
      Transform this quaternion to Euler rotation angles in radians (pitchX, yawY and rollZ).
      Parameters:
      result - the float[] array storing the computed angles.
      Returns:
      the double[] array, filled with heading, attitude and bank in that order..
      See Also:
    • setFromMatrix

      public final Quaternion setFromMatrix(float[] m, int m_off)
      Initializes this quaternion from a 4x4 column rotation matrix

      See Graphics Gems Code,
      MatrixTrace.

      Buggy Matrix-FAQ Q55

      Parameters:
      m - 4x4 column matrix
      Returns:
      this quaternion for chaining.
      See Also:
    • setFromMatrix

      public Quaternion setFromMatrix(float m00, float m01, float m02, float m10, float m11, float m12, float m20, float m21, float m22)
      Compute the quaternion from a 3x3 column rotation matrix

      See Graphics Gems Code,
      MatrixTrace.

      Buggy Matrix-FAQ Q55

      Returns:
      this quaternion for chaining.
      See Also:
    • toMatrix

      public final float[] toMatrix(float[] matrix, int mat_offset)
      Transform this quaternion to a normalized 4x4 column matrix representing the rotation.

      Implementation Details:

      Parameters:
      matrix - float[16] store for the resulting normalized column matrix 4x4
      mat_offset -
      Returns:
      the given matrix store
      See Also:
    • copyMatrixColumn

      public float[] copyMatrixColumn(int index, float[] result, int resultOffset)
      Parameters:
      index - the 3x3 rotation matrix column to retrieve from this quaternion (normalized). Must be between 0 and 2.
      result - the vector object to store the result in.
      Returns:
      the result column-vector for chaining.
    • setFromAxes

      public final Quaternion setFromAxes(float[] xAxis, float[] yAxis, float[] zAxis)
      Initializes this quaternion to represent a rotation formed by the given three orthogonal axes.

      No validation whether the axes are orthogonal is performed.

      Parameters:
      xAxis - vector representing the orthogonal x-axis of the coordinate system.
      yAxis - vector representing the orthogonal y-axis of the coordinate system.
      zAxis - vector representing the orthogonal z-axis of the coordinate system.
      Returns:
      this quaternion for chaining.
    • toAxes

      public void toAxes(float[] xAxis, float[] yAxis, float[] zAxis, float[] tmpMat4)
      Extracts this quaternion's orthogonal rotation axes.
      Parameters:
      xAxis - vector representing the orthogonal x-axis of the coordinate system.
      yAxis - vector representing the orthogonal y-axis of the coordinate system.
      zAxis - vector representing the orthogonal z-axis of the coordinate system.
      tmpMat4 - temporary float[4] matrix, used to transform this quaternion to a matrix.
    • isRotationMatrix3f

      public final boolean isRotationMatrix3f(float[] m)
      Check if the the 3x3 matrix (param) is in fact an affine rotational matrix
      Parameters:
      m - 3x3 column matrix
      Returns:
      true if representing a rotational matrix, false otherwise
    • 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.
    • hashCode

      public final int hashCode()
      Overrides:
      hashCode in class Object
    • toString

      public String toString()
      Overrides:
      toString in class Object