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
-
-
Field Summary
Fields Modifier and Type Field Description static floatALLOWED_DEVIANCEQuaternion Epsilon, used with equals method to determine if two Quaternions are close enough to be considered equal.
-
Constructor Summary
Constructors Constructor Description Quaternion()Quaternion(float x, float y, float z, float w)Quaternion(Quaternion q)
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description Quaternionadd(Quaternion q)Add a quaternionQuaternionconjugate()Conjugates this quaternion[-x, -y, -z, w].float[]copyMatrixColumn(int index, float[] result, int resultOffset)floatdot(float x, float y, float z, float w)Returns the dot product of this quaternion with the given x,y,z and w components.floatdot(Quaternion quat)Returns the dot product of this quaternion with the given quaternionbooleanequals(Object o)floatgetW()floatgetX()floatgetY()floatgetZ()inthashCode()Quaternioninvert()Invert the quaternion If rotational, will produce a the inverse rotationbooleanisIdentity()Returnstrueif this quaternion has identity.booleanisRotationMatrix3f(float[] m)Check if the the 3x3 matrix (param) is in fact an affine rotational matrixfloatmagnitude()Return the magnitude of this quaternion, i.e.floatmagnitudeSquared()Seemagnitude()for special handling ofepsilon, which is not applied here.Quaternionmult(Quaternion q)Multiply this quaternion by the param quaternionQuaternionnormalize()Normalize a quaternion required if to be used as a rotational quaternion.QuaternionrotateByAngleNormalAxis(float angle, float axisX, float axisY, float axisZ)Rotate this quaternion by the given angle and axis.QuaternionrotateByAngleX(float angle)Rotate this quaternion around X axis with the given angle in radiansQuaternionrotateByAngleY(float angle)Rotate this quaternion around Y axis with the given angle in radiansQuaternionrotateByAngleZ(float angle)Rotate this quaternion around Z axis with the given angle in radiansQuaternionrotateByEuler(float[] angradXYZ)Rotates this quaternion from the given Euler rotation arrayangradXYZin radians.QuaternionrotateByEuler(float bankX, float headingY, float attitudeZ)Rotates this quaternion from the given Euler rotation angles in radians.float[]rotateVector(float[] vecOut, int vecOutOffset, float[] vecIn, int vecInOffset)Rotate the given vector by this quaternionQuaternionscale(float n)Scale this quaternion by a constantQuaternionset(float x, float y, float z, float w)Set all values of this quaternion using the given components.Quaternionset(Quaternion src)Set all values of this quaternion using the given src.QuaternionsetFromAngleAxis(float angle, float[] vector, float[] tmpV3f)Initialize this quaternion with given non-normalized axis vector and rotation angleQuaternionsetFromAngleNormalAxis(float angle, float[] vector)Initialize this quaternion with given normalized axis vector and rotation angleQuaternionsetFromAxes(float[] xAxis, float[] yAxis, float[] zAxis)Initializes this quaternion to represent a rotation formed by the given three orthogonal axes.QuaternionsetFromEuler(float[] angradXYZ)Initializes this quaternion from the given Euler rotation arrayangradXYZin radians.QuaternionsetFromEuler(float bankX, float headingY, float attitudeZ)Initializes this quaternion from the given Euler rotation angles in radians.QuaternionsetFromMatrix(float[] m, int m_off)Initializes this quaternion from a 4x4 column rotation matrixQuaternionsetFromMatrix(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 matrixQuaternionsetFromNormalVectors(float[] v1, float[] v2, float[] tmpPivotVec)Initialize this quaternion from two normalized vectorsQuaternionsetFromVectors(float[] v1, float[] v2, float[] tmpPivotVec, float[] tmpNormalVec)Initialize this quaternion from two vectorsQuaternionsetIdentity()Set this quaternion to identity (x=0,y=0,z=0,w=1)QuaternionsetLookAt(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.QuaternionsetSlerp(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.voidsetW(float w)voidsetX(float x)voidsetY(float y)voidsetZ(float z)Quaternionsubtract(Quaternion q)Subtract a quaternionfloattoAngleAxis(float[] axis)Transform the rotational quaternion to axis based rotation anglesvoidtoAxes(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).float[]toMatrix(float[] matrix, int mat_offset)Transform this quaternion to a normalized 4x4 column matrix representing the rotation.StringtoString()
-
-
-
Field Detail
-
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:
- Constant Field Values
-
-
Constructor Detail
-
Quaternion
public Quaternion()
-
Quaternion
public Quaternion(Quaternion q)
-
Quaternion
public Quaternion(float x, float y, float z, float w)
-
-
Method Detail
-
magnitudeSquared
public final float magnitudeSquared()
Seemagnitude()for special handling ofepsilon, 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 bynormalize().Implementation Details:
- returns 0f if
magnitudeSquared()isis zerousingepsilon - returns 1f if
magnitudeSquared()isequals 1fusingepsilon
- returns 0f if
-
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()
Returnstrueif this quaternion has identity.Implementation uses
epsilonto compareWagainst 1fandX,YandZagainst 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()ifmagnitude()isis zerousingepsilon
- 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 rotationImplementation Details:
-
conjugatesifmagnitudeSquared()is isequals 1fusingepsilon
- 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 radiansaxisX- x-coord of rotation axisaxisY- y-coord of rotation axisaxisZ- 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 arrayangradXYZin radians.The
angradXYZarray is laid out in natural order:- x - bank
- y - heading
- z - attitude
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 zerousingepsilon - 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)
- y - heading -
-
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 rotationvecOutOffset- offset in result storagevecIn- float[3] vector to be rotatedvecInOffset- 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 quaternionb- end quaternionchangeAmnt- 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 atupIn- 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
- result is
-
setFromVectors
public final Quaternion setFromVectors(float[] v1, float[] v2, float[] tmpPivotVec, float[] tmpNormalVec)
Initialize this quaternion from two vectorsq = (s,v) = (v1•v2 , v1 × v2), angle = angle(v1, v2) = v1•v2 axis = normal(v1 x v2)Implementation Details:
-
setIdentity()if square vector-length isis zerousingepsilon
- Parameters:
v1- not normalizedv2- not normalizedtmpPivotVec- float[3] temp storage for cross producttmpNormalVec- 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 vectorsq = (s,v) = (v1•v2 , v1 × v2), angle = angle(v1, v2) = v1•v2 axis = v1 x v2Implementation Details:
-
setIdentity()if square vector-length isis zerousingepsilon
- Parameters:
v1- normalizedv2- normalizedtmpPivotVec- 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 angleImplementation Details:
-
setIdentity()if axis isis zerousingepsilon
- Parameters:
angle- rotation angle (rads)vector- axis vector not normalizedtmpV3f- 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 angleImplementation Details:
-
setIdentity()if axis isis zerousingepsilon
- 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 arrayangradXYZin radians.The
angradXYZarray is laid out in natural order:- x - bank
- y - heading
- z - attitude
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 areis zerousingepsilon - 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 matrixSee 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 matrixSee 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()isis zerousingepsilon
- Parameters:
matrix- float[16] store for the resulting normalized column matrix 4x4mat_offset-- Returns:
- the given matrix store
- See Also:
- Matrix-FAQ Q54,
setFromMatrix(float[], int)
- makes identity matrix if
-
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)
-
-