Class Quaternion

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:

  • returns 0f if magnitudeSquared() is is zero using epsilon
  • returns 1f if magnitudeSquared() is equals 1f using epsilon

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

  • setIdentity() if magnitude() is is zero using epsilon

  Returns:

  this quaternion for chaining.

• conjugate

  public Quaternion conjugate()

  Conjugates this quaternion [-x, -y, -z, w].

  Returns:

  this quaternion for chaining.

  See Also:

  • Matrix-FAQ Q49

• invert

  public final Quaternion invert()

  Invert the quaternion If rotational, will produce a the inverse rotation

  Implementation Details:

  • conjugates if magnitudeSquared() is is equals 1f using epsilon

  Returns:

  this quaternion for chaining.

  See Also:

  • Matrix-FAQ Q50

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

  • euclideanspace.com-QuaternionAdd

• subtract

  public final Quaternion subtract(Quaternion q)

  Subtract a quaternion

  Parameters:

  q - quaternion

  Returns:

  this quaternion for chaining.

  See Also:

  • euclideanspace.com-QuaternionAdd

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

  • Matrix-FAQ Q53
  • euclideanspace.com-QuaternionMul

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

  • euclideanspace.com-QuaternionScale

• 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(float, float, float)

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

  • y - heading - rotateByAngleY(float)
  • z - attitude - rotateByAngleZ(float)
  • x - bank - rotateByAngleX(float)

  Implementation Details:

  • NOP if all angles are is zero using epsilon
  • result is normalize()ed

  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:

  • rotateByAngleY(float)
  • rotateByAngleZ(float)
  • rotateByAngleX(float)
  • setFromEuler(float, float, float)

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

  • Matrix-FAQ Q63

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

  • euclideanspace.com-QuaternionSlerp

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

  • result is normalize()ed

  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:

  • euclideanspace.com-LookUp

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

  • setIdentity() if square vector-length is is zero using epsilon

  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:

  • setIdentity() if square vector-length is is zero using epsilon

  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:

  • setIdentity() if axis is is zero using epsilon

  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:

  • Matrix-FAQ Q56
  • toAngleAxis(float[])

• setFromAngleNormalAxis

  public final Quaternion setFromAngleNormalAxis(float angle, float[] vector)

  Initialize this quaternion with given normalized axis vector and rotation angle

  Implementation Details:

  • setIdentity() if axis is is zero using epsilon

  Parameters:

  angle - rotation angle (rads)

  vector - axis vector normalized

  Returns:

  this quaternion for chaining.

  See Also:

  • Matrix-FAQ Q56
  • toAngleAxis(float[])

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

  • setFromAngleAxis(float, float[], float[])

• 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(float, float, float)

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

  • setIdentity() if all angles are is zero using epsilon
  • result is normalize()ed

  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:

  • Matrix-FAQ Q60
  • Gems
  • euclideanspace.com-eulerToQuaternion
  • toEuler(float[])

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

  • euclideanspace.com-quaternionToEuler
  • setFromEuler(float, float, float)

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

  • toMatrix(float[], int)

• 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(float[], int)

• toMatrix

  public final float[] toMatrix(float[] matrix, int mat_offset)

  Transform this quaternion to a normalized 4x4 column matrix representing the rotation.

  Implementation Details:

  • makes identity matrix if magnitudeSquared() is is zero using epsilon

  Parameters:

  matrix - float[16] store for the resulting normalized column matrix 4x4

  mat_offset -

  Returns:

  the given matrix store

  See Also:

  • Matrix-FAQ Q54
  • setFromMatrix(float[], int)

• 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