Class Quaternion
- java.lang.Object
-
- nub.primitives.Quaternion
-
public class Quaternion extends Object
A 4 element unit quaternion represented by single precision floating point x,y,z,w coordinates. This class API aims to conform that of the great libQGLViewer Quaternion.
-
-
Field Summary
Fields Modifier and Type Field Description float[]
_quaternion
The x, y, z, and w coordinates of the quaternion represented as a public array.static Quaternion
identity
Returns a quaternion whose components are set to(0, 0, 0, 1)
.
-
Constructor Summary
Constructors Constructor Description Quaternion()
Constructs and initializes a quaternion to (0.0,0.0,0.0,1.0), i.e., an identity rotation.Quaternion(float angle)
Same asfromAxisAngle(new Vector(0,0,1), angle)
.Quaternion(float[] source)
Convenience constructor that simply callsthis(source, true)
Quaternion(float[] source, boolean normalize)
Constructs and initializes a quaternion from the array of length 4.Quaternion(float roll, float pitch, float yaw)
Constructs a quaternion from the given Euler angles.Quaternion(float x, float y, float z, float w)
Default constructor for Quaternion(float x, float y, float z, float w, boolean normalize), withnormalize=true
.Quaternion(float x, float y, float z, float w, boolean normalize)
Constructs and initializes a quaternion from the specified xyzw coordinates.Quaternion(Matrix matrix)
Constructs a quaternion from a (supposedly correct) 3x3 rotation matrix given in the upper left 3x3 sub-matrix of the Matrix.Quaternion(Quaternion quaternion, boolean normalize)
Copy constructor.Quaternion(Vector axis, float angle)
Quaternion(Vector from, Vector to)
Constructs a quaternion that will rotate from thefrom
direction to theto
direction.Quaternion(Vector X, Vector Y, Vector Z)
Constructs a quaternion from the three rotated vectors of an orthogonal basis.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description float
angle()
Returns theangle
(in radians) of the rotation represented by the quaternion.float
angle2D()
Same asreturn axis().z() > 0 ? angle() : -angle()
.Vector
axis()
Returns the normalized axis direction of the rotation represented by the quaternion.void
compose(Quaternion quaternion)
Same asmultiply(quaternion)
.static Quaternion
compose(Quaternion a, Quaternion b)
Same asreturn multiply(a, b)
.void
conjugate()
Sets this as its conjugate.void
conjugate(Quaternion quaternion)
Sets this as the quaternion conjugate.Quaternion
copy()
Returns a deep copy of this quaternion.static float
dot(Quaternion a, Quaternion b)
Returns the "dot" product ofa
andb
:float
dotProduct(Quaternion quaternion)
Returns the "dot" product of this quaternion andquaternion
:Vector
eulerAngles()
Converts this quaternion to Euler rotation anglesroll
,pitch
andyaw
in radians.Quaternion
exp()
Returns the quaternion exponential.static Quaternion
from(Object... params)
Converts various orientation representations to quaternion form and returns it.void
fromAxisAngle(Vector axis, float angle)
void
fromEulerAngles(float roll, float pitch, float yaw)
Converts Euler rotation anglesroll
,pitch
andyaw
, respectively defined to the x, y and z axes, to this quaternion.void
fromMatrix(Matrix matrix)
Set the quaternion from a (supposedly correct) 3x3 rotation matrix given in the upper left 3x3 sub-matrix of the Matrix.void
fromRotatedBasis(Vector X, Vector Y, Vector Z)
Sets the quaternion from the three rotated vectors of an orthogonal basis.void
fromTo(Vector from, Vector to)
Sets the quaternion as a rotation from thefrom
direction to theto
direction.float[]
get(float[] target)
Returns a copy of this quaternion into the four lengthtarget
array.Quaternion
inverse()
Returns the inverse quaternion (inverse rotation).Matrix
inverseMatrix()
Returns the associated inverse rotation matrix.Vector
inverseRotate(Vector vector)
Returns the image ofvector
by the quaternioninverse()
rotation.void
invert()
Sets the value of this to the inverse of itself.void
invert(Quaternion quaternion)
Sets the value of this to the Quaternion inverse ofquaternion
.static Quaternion
lnDif(Quaternion a, Quaternion b)
Simply returnslog(a. inverse() * b)
.Quaternion
log()
Returns the quaternion logarithm.boolean
matches(Quaternion quaternion)
Returns whether or not this quaternion matches other.Matrix
matrix()
Returns the rotation matrix associated with the quaternion.void
multiply(Quaternion quaternion)
Sets this as the quaternion product of itself andquaternion
, (i.e.,this = this * quaternion
).static Quaternion
multiply(Quaternion a, Quaternion b)
Returns the product of quaternionsa
andb
.static Vector
multiply(Quaternion quaternion, Vector vector)
Returns the image ofvector
by the rotationquaternion
.Vector
multiply(Vector vector)
Returns the image ofvector
by the rotation of this vector.void
multiplyInverse(Quaternion q1)
Multiplies this by the inverse of Quaternionq1
and places the value into this (i.e.,this = this * q^-1
).static Quaternion
multiplyInverse(Quaternion q1, Quaternion q2)
Returns the product of quaternionq1
by the inverse of quaternionq2
(i.e.,q1 * q2^-1
).void
negate()
Negates all the coefficients of the quaternion.float
norm()
Returns the norm of this quaternion.float
normalize()
Normalize this quaternion return itsnorm()
.static Quaternion
random()
Returns a normalized random quaternion.void
randomize()
Randomize this quaternion.void
reset()
Make this an identity quaternion.Vector
rotate(Vector vector)
Returns the image ofvector
by the quaternion rotation.void
set(float[] source)
Sets this quaternion from the four lengthsource
array.void
set(Quaternion quaternion)
Convenience function that simply callsset(quaternion, true);
void
set(Quaternion quaternion, boolean normalize)
Set this from quaternionquaternion
.void
setW(float w)
Sets the Quaternion w componentvoid
setX(float x)
Sets the Quaternion x componentvoid
setY(float y)
Sets the Quaternion y componentvoid
setZ(float z)
Sets the Quaternion z componentstatic Quaternion
slerp(Quaternion a, Quaternion b, float t)
Wrapper function that simply callsslerp(a, b, t, true)
.static Quaternion
slerp(Quaternion a, Quaternion b, float t, boolean allowFlip)
Returns the slerp interpolation of quaternionsa
andb
, at timet
.static Quaternion
squad(Quaternion a, Quaternion tgA, Quaternion tgB, Quaternion b, float t)
Returns the slerp interpolation of the two quaternionsa
andb
, at timet
, using tangentstgA
andtgB
.static Quaternion
squadTangent(Quaternion before, Quaternion center, Quaternion after)
Returns a tangent quaternion forcenter
, defined bybefore
andafter
quaternions.static float
squaredNorm(Quaternion quaternion)
Utility function that returns the squared norm of the quaternion.String
toString()
Return this quaternion components as a String.float
w()
float
x()
float
y()
float
z()
-
-
-
Field Detail
-
_quaternion
public float[] _quaternion
The x, y, z, and w coordinates of the quaternion represented as a public array.
-
identity
public static final Quaternion identity
Returns a quaternion whose components are set to(0, 0, 0, 1)
.- See Also:
from(Object...)
-
-
Constructor Detail
-
Quaternion
public Quaternion()
Constructs and initializes a quaternion to (0.0,0.0,0.0,1.0), i.e., an identity rotation.
-
Quaternion
public Quaternion(float x, float y, float z, float w)
Default constructor for Quaternion(float x, float y, float z, float w, boolean normalize), withnormalize=true
.
-
Quaternion
public Quaternion(float x, float y, float z, float w, boolean normalize)
Constructs and initializes a quaternion from the specified xyzw coordinates.- Parameters:
x
- the x coordinatey
- the y coordinatez
- the z coordinatew
- the w scalar componentnormalize
- tells whether or not the constructed Quaternion should be normalized.
-
Quaternion
public Quaternion(float[] source)
Convenience constructor that simply callsthis(source, true)
-
Quaternion
public Quaternion(float[] source, boolean normalize)
Constructs and initializes a quaternion from the array of length 4.- Parameters:
source
- the array of length 4 containing xyzw in order
-
Quaternion
public Quaternion(Quaternion quaternion, boolean normalize)
- Parameters:
quaternion
- the Quaternion containing the initialization x y z w data
-
Quaternion
public Quaternion(float angle)
Same asfromAxisAngle(new Vector(0,0,1), angle)
.Constructs and initializes a quaternion from the specified 2d rotation
angle
(in radians). The axis of the quaternion is Z.- Parameters:
angle
- the angle in radians- See Also:
fromAxisAngle(Vector, float)
-
Quaternion
public Quaternion(Vector axis, float angle)
Constructs and initializes a quaternion from the specified rotationaxis
(non null) andangle
(in radians).- Parameters:
axis
- the Vector representing the axisangle
- the angle in radians- See Also:
fromAxisAngle(Vector, float)
-
Quaternion
public Quaternion(Vector from, Vector to)
Constructs a quaternion that will rotate from thefrom
direction to theto
direction.- Parameters:
from
- the first Vectorto
- the second Vector- See Also:
fromTo(Vector, Vector)
-
Quaternion
public Quaternion(float roll, float pitch, float yaw)
Constructs a quaternion from the given Euler angles.- Parameters:
roll
- Rotation angle in radians around the x-Axispitch
- Rotation angle in radians around the y-Axisyaw
- Rotation angle in radians around the z-Axis- See Also:
fromEulerAngles(float, float, float)
-
Quaternion
public Quaternion(Matrix matrix)
Constructs a quaternion from a (supposedly correct) 3x3 rotation matrix given in the upper left 3x3 sub-matrix of the Matrix.- Parameters:
matrix
-- See Also:
fromMatrix(Matrix)
-
Quaternion
public Quaternion(Vector X, Vector Y, Vector Z)
Constructs a quaternion from the three rotated vectors of an orthogonal basis.- Parameters:
X
- 1st Orthogonal VectorY
- 2nd Orthogonal VectorZ
- 3rd Orthogonal Vector- See Also:
fromRotatedBasis(Vector, Vector, Vector)
-
-
Method Detail
-
matches
public boolean matches(Quaternion quaternion)
Returns whether or not this quaternion matches other.- Parameters:
quaternion
- other quaternion
-
copy
public Quaternion copy()
Returns a deep copy of this quaternion.
-
from
public static final Quaternion from(Object... params)
Converts various orientation representations to quaternion form and returns it. According to the numbers and types of params passed the following representations are supported:- One
params
: if its type isMatrix
it returns a quaternion from the given 'matrix-form' (seeQuaternion(Matrix)
). If its type isQuaternion
then the quaternion is cloned (seecopy()
) and returned. If it's of typefloat[]
then a quaternion is returned from the 4-array elements (seeQuaternion(float[])
). - Two
params
: if both params are of typeVector
it returns the quaternion which would produce the rotation from the first vector param to the second (seeQuaternion(Vector, Vector)
). If the firstparams
is of typeVector
and the second of typeFloat
it returns the quaternion from the given 'axis-angle form', (seeQuaternion(Vector, float)
). - Three
params
: If the threeparams
are of typeFloat
it returns a quaternion from the given 'Euler angles form', (seeQuaternion(float, float, float)
). If the threeparams
are of typeVector
it returns a quaternion from the given 'rotated-basis form', (seeQuaternion(Vector, Vector, Vector)
).
params
cannot be parsed a new Quaternion (#identity
) is returned. - One
-
randomize
public void randomize()
Randomize this quaternion. The quaternion is normalized too.- See Also:
random()
-
random
public static Quaternion random()
Returns a normalized random quaternion.- See Also:
randomize()
-
reset
public void reset()
Make this an identity quaternion.
-
get
public float[] get(float[] target)
Returns a copy of this quaternion into the four lengthtarget
array.
-
set
public void set(float[] source)
Sets this quaternion from the four lengthsource
array.
-
x
public float x()
- Returns:
- Quaternion x component
-
y
public float y()
- Returns:
- Quaternion y component
-
z
public float z()
- Returns:
- Quaternion z component
-
w
public float w()
- Returns:
- Quaternion w component
-
setX
public void setX(float x)
Sets the Quaternion x component
-
setY
public void setY(float y)
Sets the Quaternion y component
-
setZ
public void setZ(float z)
Sets the Quaternion z component
-
setW
public void setW(float w)
Sets the Quaternion w component
-
set
public void set(Quaternion quaternion)
Convenience function that simply callsset(quaternion, true);
- See Also:
set(Quaternion, boolean)
-
set
public void set(Quaternion quaternion, boolean normalize)
-
conjugate
public void conjugate()
Sets this as its conjugate.
-
conjugate
public void conjugate(Quaternion quaternion)
Sets this as the quaternion conjugate.- Parameters:
quaternion
- the source vector
-
negate
public void negate()
Negates all the coefficients of the quaternion.
-
dotProduct
public float dotProduct(Quaternion quaternion)
Returns the "dot" product of this quaternion andquaternion
:this._quaternion[0] * quaternion._quaternion[0] + this._quaternion[1] * quaternion._quaternion[1] + this._quaternion[2] * quaternion._quaternion[2] + this._quaternion[3] * quaternion._quaternion[3]
- Parameters:
quaternion
- the Quaternion
-
dot
public static float dot(Quaternion a, Quaternion b)
Returns the "dot" product ofa
andb
:a.x * b.x + a.y * b.y + a.z * b.z + a.w * b.w
- Parameters:
a
- the first Quaternionb
- the second Quaternion
-
compose
public void compose(Quaternion quaternion)
Same asmultiply(quaternion)
.- See Also:
multiply(Quaternion)
-
multiply
public void multiply(Quaternion quaternion)
Sets this as the quaternion product of itself andquaternion
, (i.e.,this = this * quaternion
).- Parameters:
quaternion
- the other Quaternion
-
compose
public static Quaternion compose(Quaternion a, Quaternion b)
Same asreturn multiply(a, b)
.- See Also:
multiply(Quaternion, Vector)
-
multiply
public static Quaternion multiply(Quaternion a, Quaternion b)
Returns the product of quaternionsa
andb
.- Parameters:
a
- the first Quaternionb
- the second Quaternion
-
multiply
public Vector multiply(Vector vector)
Returns the image ofvector
by the rotation of this vector. Same asthis.rotate(vector)
.- Parameters:
vector
- the Vector- See Also:
rotate(Vector)
,inverseRotate(Vector)
-
multiply
public static Vector multiply(Quaternion quaternion, Vector vector)
Returns the image ofvector
by the rotationquaternion
. Same asquaternion.rotate(vector)
.- Parameters:
quaternion
- the Quaternionvector
- the Vector- See Also:
rotate(Vector)
,inverseRotate(Vector)
-
multiplyInverse
public void multiplyInverse(Quaternion q1)
Multiplies this by the inverse of Quaternionq1
and places the value into this (i.e.,this = this * q^-1
). The value of the argument quaternion is preserved.- Parameters:
q1
- the other Quaternion
-
multiplyInverse
public static Quaternion multiplyInverse(Quaternion q1, Quaternion q2)
Returns the product of quaternionq1
by the inverse of quaternionq2
(i.e.,q1 * q2^-1
). The value of both argument quaternions is preserved.- Parameters:
q1
- the first Quaternionq2
- the second Quaternion
-
inverse
public Quaternion inverse()
Returns the inverse quaternion (inverse rotation).The result has a negated
axis()
direction and the sameangle()
.A composition of a quaternion and its
inverse()
results in an identity function. Useinvert()
to actually modify the quaternion.- See Also:
invert()
-
invert
public void invert()
Sets the value of this to the inverse of itself.- See Also:
inverse()
-
invert
public void invert(Quaternion quaternion)
Sets the value of this to the Quaternion inverse ofquaternion
.- Parameters:
quaternion
- the Quaternion to be inverted
-
normalize
public float normalize()
Normalize this quaternion return itsnorm()
.
-
norm
public float norm()
Returns the norm of this quaternion.
-
rotate
public Vector rotate(Vector vector)
Returns the image ofvector
by the quaternion rotation.- Parameters:
vector
- the Vector
-
inverseRotate
public Vector inverseRotate(Vector vector)
Returns the image ofvector
by the quaternioninverse()
rotation.rotate(Vector)
performs an inverse transformation.- Parameters:
vector
- the Vector
-
fromAxisAngle
public void fromAxisAngle(Vector axis, float angle)
Sets the quaternion as a rotation ofaxis
andangle
(in radians).The
axis
does not need to be normalized. A nullaxis
will result in an identity quaternion.- Parameters:
axis
- the Vector representing the axisangle
- the angle in radians- See Also:
fromTo(Vector, Vector)
,fromMatrix(Matrix)
,fromRotatedBasis(Vector, Vector, Vector)
,fromEulerAngles(float, float, float)
-
fromEulerAngles
public void fromEulerAngles(float roll, float pitch, float yaw)
Converts Euler rotation anglesroll
,pitch
andyaw
, respectively defined to the x, y and z axes, to this quaternion. In the convention used here these angles represent a composition of extrinsic rotations (rotations about the reference node axes), which is also known as Tait-Bryan angles (See http://en.wikipedia.org/wiki/Euler_angles and http://en.wikipedia.org/wiki/Tait-Bryan_angles).eulerAngles()
performs the inverse operation.Each rotation angle is converted to an axis-angle pair, with the axis corresponding to one of the Euclidean axes. The axis-angle pairs are converted to quaternions and multiplied together. The order of the rotations is: y,z,x which follows the convention found here: http://www.euclideanspace.com/maths/geometry/rotations/euler/index.htm
-
eulerAngles
public Vector eulerAngles()
Converts this quaternion to Euler rotation anglesroll
,pitch
andyaw
in radians.fromEulerAngles(float, float, float)
performs the inverse operation. The code was adapted from: http://www.euclideanspace.com/maths/geometry/rotations/conversions/ quaternionToEuler/index.htm. Attention: This method assumes that this quaternion is normalized.- Returns:
- the Vector holding the roll (x coordinate of the vector), pitch (y coordinate of
the vector) and yaw angles (z coordinate of the vector). Note: The
order of the rotations that would produce this Quaternion (i.e., as with
fromEulerAngles(roll, pitch, yaw)
) is: y,z,x. - See Also:
fromEulerAngles(float, float, float)
-
fromTo
public void fromTo(Vector from, Vector to)
Sets the quaternion as a rotation from thefrom
direction to theto
direction. Attention: this rotation is not uniquely defined. The selected axis is usually orthogonal tofrom
andto
, minimizing the rotation angle. This method is robust and can handle small or almost identical vectors.
-
fromMatrix
public void fromMatrix(Matrix matrix)
Set the quaternion from a (supposedly correct) 3x3 rotation matrix given in the upper left 3x3 sub-matrix of the Matrix.
-
fromRotatedBasis
public void fromRotatedBasis(Vector X, Vector Y, Vector Z)
Sets the quaternion from the three rotated vectors of an orthogonal basis.The three vectors do not have to be normalized but must be orthogonal and direct (i,e.,
X^Y=k*Z, with k>0
).- Parameters:
X
- the first VectorY
- the second VectorZ
- the third Vector- See Also:
fromTo(Vector, Vector)
,fromEulerAngles(float, float, float)
,fromMatrix(Matrix)
,fromAxisAngle(Vector, float)
,fromRotatedBasis(Vector, Vector, Vector)
,Quaternion(Vector, Vector)
-
axis
public Vector axis()
Returns the normalized axis direction of the rotation represented by the quaternion.The result is
(0,0,0)
for an identity quaternion.- See Also:
angle()
-
angle
public float angle()
Returns theangle
(in radians) of the rotation represented by the quaternion.This value is always in the range
[0-pi]
. Larger rotational angles are obtained by inverting theaxis()
direction.- See Also:
axis()
-
angle2D
public float angle2D()
Same asreturn axis().z() > 0 ? angle() : -angle()
.- See Also:
angle()
-
matrix
public Matrix matrix()
Returns the rotation matrix associated with the quaternion.
-
inverseMatrix
public Matrix inverseMatrix()
Returns the associated inverse rotation matrix. This is simplymatrix()
of theinverse()
. Attention: The result is only valid until the next call toinverseMatrix()
. Use it immediately (as inapplyMatrix(q.inverseMatrix())
).
-
log
public Quaternion log()
Returns the quaternion logarithm.- See Also:
exp()
-
exp
public Quaternion exp()
Returns the quaternion exponential.- See Also:
log()
-
slerp
public static Quaternion slerp(Quaternion a, Quaternion b, float t)
Wrapper function that simply callsslerp(a, b, t, true)
.See
slerp(Quaternion, Quaternion, float, boolean)
for details.
-
slerp
public static Quaternion slerp(Quaternion a, Quaternion b, float t, boolean allowFlip)
Returns the slerp interpolation of quaternionsa
andb
, at timet
.t
should range in[0,1]
. Result isa
whent=0
andb
whent=1
.When
allowFlip
is true (default) the slerp interpolation will always use the "shortest path" between the quaternions' orientations, by "flipping" the source quaternion if needed (seenegate()
).- Parameters:
a
- the first Quaternionb
- the second Quaterniont
- the t interpolation parameterallowFlip
- tells whether or not the interpolation allows axis flip
-
squad
public static Quaternion squad(Quaternion a, Quaternion tgA, Quaternion tgB, Quaternion b, float t)
Returns the slerp interpolation of the two quaternionsa
andb
, at timet
, using tangentstgA
andtgB
.The resulting quaternion is "between"
a
andb
(result isa
whent=0
andb
fort=1
).Use
squadTangent(Quaternion, Quaternion, Quaternion)
to define the quaternion tangentstgA
andtgB
.- Parameters:
a
- the first QuaterniontgA
- the first tangent QuaterniontgB
- the second tangent Quaternionb
- the second Quaterniont
- the t interpolation parameter
-
lnDif
public static Quaternion lnDif(Quaternion a, Quaternion b)
Simply returnslog(a. inverse() * b)
.Useful for
squadTangent(Quaternion, Quaternion, Quaternion)
.- Parameters:
a
- the first Quaternionb
- the second Quaternion
-
squadTangent
public static Quaternion squadTangent(Quaternion before, Quaternion center, Quaternion after)
Returns a tangent quaternion forcenter
, defined bybefore
andafter
quaternions.- Parameters:
before
- the first Quaternioncenter
- the second Quaternionafter
- the third Quaternion
-
squaredNorm
public static float squaredNorm(Quaternion quaternion)
Utility function that returns the squared norm of the quaternion.
-
-