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 float
ALLOWED_DEVIANCE
Quaternion 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 Quaternion
add(Quaternion q)
Add a quaternionQuaternion
conjugate()
Conjugates this quaternion[-x, -y, -z, w]
.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.float
dot(Quaternion quat)
Returns the dot product of this quaternion with the given quaternionboolean
equals(Object o)
int
hashCode()
Quaternion
invert()
Invert the quaternion If rotational, will produce a the inverse rotationboolean
isIdentity()
Returnstrue
if this quaternion has identity.boolean
isRotationMatrix3f(float[] m)
Deprecated.float
magnitude()
Return the magnitude of this quaternion, i.e.float
magnitudeSquared()
Seemagnitude()
for special handling ofepsilon
, which is not applied here.Quaternion
mult(Quaternion q)
Multiply this quaternion by the param quaternionQuaternion
normalize()
Normalize a quaternion required if to be used as a rotational quaternion.Quaternion
rotateByAngleNormalAxis(float angle, float axisX, float axisY, float axisZ)
Rotate this quaternion by the given angle and axis.Quaternion
rotateByAngleX(float angle)
Rotate this quaternion around X axis with the given angle in radiansQuaternion
rotateByAngleY(float angle)
Rotate this quaternion around Y axis with the given angle in radiansQuaternion
rotateByAngleZ(float angle)
Rotate this quaternion around Z axis with the given angle in radiansQuaternion
rotateByEuler(float bankX, float headingY, float attitudeZ)
Rotates this quaternion from the given Euler rotation angles in radians.Quaternion
rotateByEuler(Vec3f angradXYZ)
Rotates this quaternion from the given Euler rotation arrayangradXYZ
in radians.Vec3f
rotateVector(Vec3f vecIn, Vec3f vecOut)
Rotate the given vector by this quaternionQuaternion
scale(float n)
Scale this quaternion by a constantQuaternion
set(float x, float y, float z, float w)
Set all values of this quaternion using the given components.Quaternion
set(Quaternion src)
Set all values of this quaternion using the given src.Quaternion
setFromAngleAxis(float angle, Vec3f vector, Vec3f tmpV3f)
Initialize this quaternion with given non-normalized axis vector and rotation angleQuaternion
setFromAngleNormalAxis(float angle, Vec3f vector)
Initialize this quaternion with given normalized axis vector and rotation angleQuaternion
setFromAxes(Vec3f xAxis, Vec3f yAxis, Vec3f zAxis)
Initializes this quaternion to represent a rotation formed by the given three orthogonal axes.Quaternion
setFromEuler(float bankX, float headingY, float attitudeZ)
Initializes this quaternion from the given Euler rotation angles in radians.Quaternion
setFromEuler(Vec3f angradXYZ)
Initializes this quaternion from the given Euler rotation arrayangradXYZ
in radians.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 matrixQuaternion
setFromMatrix(Matrix4f m)
Compute the quaternion from a 3x3 column rotation matrixQuaternion
setFromNormalVectors(Vec3f v1, Vec3f v2, Vec3f tmpPivotVec)
Initialize this quaternion from two normalized vectorsQuaternion
setFromVectors(Vec3f v1, Vec3f v2, Vec3f tmpPivotVec, Vec3f tmpNormalVec)
Initialize this quaternion from two vectorsQuaternion
setIdentity()
Set this quaternion to identity (x=0,y=0,z=0,w=1)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.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.void
setW(float w)
void
setX(float x)
void
setY(float y)
void
setZ(float z)
Quaternion
subtract(Quaternion q)
Subtract a quaternionfloat
toAngleAxis(Vec3f axis)
Transform the rotational quaternion to axis based rotation anglesvoid
toAxes(Vec3f xAxis, Vec3f yAxis, Vec3f zAxis, Matrix4f tmpMat4)
Extracts this quaternion's orthogonal rotation axes.Vec3f
toEuler(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.Matrix4f
toMatrix(Matrix4f matrix)
Transform this quaternion to a normalized 4x4 column matrix representing the rotation.String
toString()
float
w()
float
x()
float
y()
float
z()
-
-
-
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 zero
usingepsilon
- returns 1f if
magnitudeSquared()
isequals 1f
usingepsilon
- 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()
Returnstrue
if this quaternion has identity.Implementation uses
epsilon
to compareW
against 1f
andX
,Y
andZ
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()
ifmagnitude()
isis zero
usingepsilon
- 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:
-
conjugates
ifmagnitudeSquared()
is isequals 1f
usingepsilon
- 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 arrayangradXYZ
in radians.The
angradXYZ
array 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 zero
usingepsilon
- 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 zero
usingepsilon
- 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 v2
Implementation Details:
-
setIdentity()
if square vector-length isis zero
usingepsilon
- 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 zero
usingepsilon
- 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 zero
usingepsilon
- 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 arrayangradXYZ
in radians.The
angradXYZ
vector 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 zero
usingepsilon
- 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
result
array 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 zero
usingepsilon
- 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 zero
usingepsilon
- 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)
-
-