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 Deprecated Methods Modifier and Type Method Description Quaternionadd(Quaternion q)Add a quaternionQuaternionconjugate()Conjugates this quaternion[-x, -y, -z, w].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)inthashCode()Quaternioninvert()Invert the quaternion If rotational, will produce a the inverse rotationbooleanisIdentity()Returnstrueif this quaternion has identity.booleanisRotationMatrix3f(float[] m)Deprecated.floatmagnitude()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 bankX, float headingY, float attitudeZ)Rotates this quaternion from the given Euler rotation angles in radians.QuaternionrotateByEuler(Vec3f angradXYZ)Rotates this quaternion from the given Euler rotation arrayangradXYZin radians.Vec3frotateVector(Vec3f vecIn, Vec3f vecOut)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, Vec3f vector, Vec3f tmpV3f)Initialize this quaternion with given non-normalized axis vector and rotation angleQuaternionsetFromAngleNormalAxis(float angle, Vec3f vector)Initialize this quaternion with given normalized axis vector and rotation angleQuaternionsetFromAxes(Vec3f xAxis, Vec3f yAxis, Vec3f zAxis)Initializes this quaternion to represent a rotation formed by the given three orthogonal axes.QuaternionsetFromEuler(float bankX, float headingY, float attitudeZ)Initializes this quaternion from the given Euler rotation angles in radians.QuaternionsetFromEuler(Vec3f angradXYZ)Initializes this quaternion from the given Euler rotation arrayangradXYZin radians.QuaternionsetFromMatrix(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 matrixQuaternionsetFromMatrix(Matrix4f m)Compute the quaternion from a 3x3 column rotation matrixQuaternionsetFromNormalVectors(Vec3f v1, Vec3f v2, Vec3f tmpPivotVec)Initialize this quaternion from two normalized vectorsQuaternionsetFromVectors(Vec3f v1, Vec3f v2, Vec3f tmpPivotVec, Vec3f tmpNormalVec)Initialize this quaternion from two vectorsQuaternionsetIdentity()Set this quaternion to identity (x=0,y=0,z=0,w=1)QuaternionsetLookAt(Vec3f directionIn, Vec3f upIn, Vec3f xAxisOut, Vec3f yAxisOut, Vec3f 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(Vec3f axis)Transform the rotational quaternion to axis based rotation anglesvoidtoAxes(Vec3f xAxis, Vec3f yAxis, Vec3f zAxis, Matrix4f tmpMat4)Extracts this quaternion's orthogonal rotation axes.Vec3ftoEuler(Vec3f result)Transform this quaternion to Euler rotation angles in radians (pitchX, yawY and rollZ).float[]toMatrix(float[] matrix)Transform this quaternion to a normalized 4x4 column matrix representing the rotation.Matrix4ftoMatrix(Matrix4f matrix)Transform this quaternion to a normalized 4x4 column matrix representing the rotation.StringtoString()floatw()floatx()floaty()floatz()
-
-
-
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
-
w
public final float w()
-
setW
public final void setW(float w)
-
x
public final float x()
-
setX
public final void setX(float x)
-
y
public final float y()
-
setY
public final void setY(float y)
-
z
public final float z()
-
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(Vec3f 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 angle 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 Vec3f rotateVector(Vec3f vecIn, Vec3f vecOut)
Rotate the given vector by this quaternion- Parameters:
vecIn- vector to be rotatedvecOut- result storage for rotated vector, maybe equal to vecIn for in-place rotation- 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(Vec3f directionIn, Vec3f upIn, Vec3f xAxisOut, Vec3f yAxisOut, Vec3f 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(Vec3f v1, Vec3f v2, Vec3f tmpPivotVec, Vec3f 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- temp storage for cross producttmpNormalVec- temp storage to normalize vector- Returns:
- this quaternion for chaining.
-
-
setFromNormalVectors
public final Quaternion setFromNormalVectors(Vec3f v1, Vec3f v2, Vec3f 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- temp storage for cross product- Returns:
- this quaternion for chaining.
-
-
setFromAngleAxis
public final Quaternion setFromAngleAxis(float angle, Vec3f vector, Vec3f 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- temp storage to normalize vector- Returns:
- this quaternion for chaining.
- See Also:
- Matrix-FAQ Q56,
toAngleAxis(Vec3f)
-
-
setFromAngleNormalAxis
public final Quaternion setFromAngleNormalAxis(float angle, Vec3f 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(Vec3f)
-
-
toAngleAxis
public final float toAngleAxis(Vec3f axis)
Transform the rotational quaternion to axis based rotation angles- Parameters:
axis- storage for computed axis- Returns:
- the rotation angle in radians
- See Also:
setFromAngleAxis(float, Vec3f, Vec3f)
-
setFromEuler
public final Quaternion setFromEuler(Vec3f angradXYZ)
Initializes this quaternion from the given Euler rotation arrayangradXYZin radians.The
angradXYZvector is laid out in natural order:- x - bank
- y - heading
- z - attitude
setFromEuler(float, float, float).- Parameters:
angradXYZ- euler angle vector in radians holding x-bank, y-heading and z-attitude- 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(Vec3f)
-
toEuler
public Vec3f toEuler(Vec3f result)
Transform this quaternion to Euler rotation angles in radians (pitchX, yawY and rollZ).The
resultarray is laid out in natural order:- x - bank
- y - heading
- z - attitude
- Parameters:
result- euler angle result vector for radians x-bank, y-heading and z-attitude- Returns:
- the Vec3f `result` filled with x-bank, y-heading and z-attitude
- See Also:
- euclideanspace.com-quaternionToEuler,
setFromEuler(float, float, float)
-
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:
setFromMatrix(Matrix4f)
-
setFromMatrix
public Quaternion setFromMatrix(Matrix4f m)
Compute the quaternion from a 3x3 column rotation matrixSee Graphics Gems Code,
MatrixTrace.Buggy Matrix-FAQ Q55
- Returns:
- this quaternion for chaining.
- See Also:
Matrix4f.getRotation(Quaternion),setFromMatrix(float, float, float, float, float, float, float, float, float)
-
toMatrix
public final float[] toMatrix(float[] matrix)
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 4x4- Returns:
- the given matrix store
- See Also:
- Matrix-FAQ Q54,
setFromMatrix(Matrix4f),setFromMatrix(float, float, float, float, float, float, float, float, float)
- makes identity matrix if
-
toMatrix
public final Matrix4f toMatrix(Matrix4f matrix)
Transform this quaternion to a normalized 4x4 column matrix representing the rotation.Implementation Details:
- makes identity matrix if
magnitudeSquared()isis zerousingepsilon
- Parameters:
matrix- store for the resulting normalized column matrix 4x4- Returns:
- the given matrix store
- See Also:
- Matrix-FAQ Q54,
setFromMatrix(float, float, float, float, float, float, float, float, float),Matrix4f.setToRotation(Quaternion)
- makes identity matrix if
-
setFromAxes
public final Quaternion setFromAxes(Vec3f xAxis, Vec3f yAxis, Vec3f 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(Vec3f xAxis, Vec3f yAxis, Vec3f zAxis, Matrix4f 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
@Deprecated public final boolean isRotationMatrix3f(float[] m)
Deprecated.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)
-
-