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[]_quaternionThe x, y, z, and w coordinates of the quaternion represented as a public array.static QuaternionidentityReturns 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 thefromdirection to thetodirection.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 floatangle()Returns theangle(in radians) of the rotation represented by the quaternion.floatangle2D()Same asreturn axis().z() > 0 ? angle() : -angle().Vectoraxis()Returns the normalized axis direction of the rotation represented by the quaternion.voidcompose(Quaternion quaternion)Same asmultiply(quaternion).static Quaternioncompose(Quaternion a, Quaternion b)Same asreturn multiply(a, b).voidconjugate()Sets this as its conjugate.voidconjugate(Quaternion quaternion)Sets this as the quaternion conjugate.Quaternioncopy()Returns a deep copy of this quaternion.static floatdot(Quaternion a, Quaternion b)Returns the "dot" product ofaandb:floatdotProduct(Quaternion quaternion)Returns the "dot" product of this quaternion andquaternion:VectoreulerAngles()Converts this quaternion to Euler rotation anglesroll,pitchandyawin radians.Quaternionexp()Returns the quaternion exponential.static Quaternionfrom(Object... params)Converts various orientation representations to quaternion form and returns it.voidfromAxisAngle(Vector axis, float angle)voidfromEulerAngles(float roll, float pitch, float yaw)Converts Euler rotation anglesroll,pitchandyaw, respectively defined to the x, y and z axes, to this quaternion.voidfromMatrix(Matrix matrix)Set the quaternion from a (supposedly correct) 3x3 rotation matrix given in the upper left 3x3 sub-matrix of the Matrix.voidfromRotatedBasis(Vector X, Vector Y, Vector Z)Sets the quaternion from the three rotated vectors of an orthogonal basis.voidfromTo(Vector from, Vector to)Sets the quaternion as a rotation from thefromdirection to thetodirection.float[]get(float[] target)Returns a copy of this quaternion into the four lengthtargetarray.Quaternioninverse()Returns the inverse quaternion (inverse rotation).MatrixinverseMatrix()Returns the associated inverse rotation matrix.VectorinverseRotate(Vector vector)Returns the image ofvectorby the quaternioninverse()rotation.voidinvert()Sets the value of this to the inverse of itself.voidinvert(Quaternion quaternion)Sets the value of this to the Quaternion inverse ofquaternion.static QuaternionlnDif(Quaternion a, Quaternion b)Simply returnslog(a. inverse() * b).Quaternionlog()Returns the quaternion logarithm.booleanmatches(Quaternion quaternion)Returns whether or not this quaternion matches other.Matrixmatrix()Returns the rotation matrix associated with the quaternion.voidmultiply(Quaternion quaternion)Sets this as the quaternion product of itself andquaternion, (i.e.,this = this * quaternion).static Quaternionmultiply(Quaternion a, Quaternion b)Returns the product of quaternionsaandb.static Vectormultiply(Quaternion quaternion, Vector vector)Returns the image ofvectorby the rotationquaternion.Vectormultiply(Vector vector)Returns the image ofvectorby the rotation of this vector.voidmultiplyInverse(Quaternion q1)Multiplies this by the inverse of Quaternionq1and places the value into this (i.e.,this = this * q^-1).static QuaternionmultiplyInverse(Quaternion q1, Quaternion q2)Returns the product of quaternionq1by the inverse of quaternionq2(i.e.,q1 * q2^-1).voidnegate()Negates all the coefficients of the quaternion.floatnorm()Returns the norm of this quaternion.floatnormalize()Normalize this quaternion return itsnorm().static Quaternionrandom()Returns a normalized random quaternion.voidrandomize()Randomize this quaternion.voidreset()Make this an identity quaternion.Vectorrotate(Vector vector)Returns the image ofvectorby the quaternion rotation.voidset(float[] source)Sets this quaternion from the four lengthsourcearray.voidset(Quaternion quaternion)Convenience function that simply callsset(quaternion, true);voidset(Quaternion quaternion, boolean normalize)Set this from quaternionquaternion.voidsetW(float w)Sets the Quaternion w componentvoidsetX(float x)Sets the Quaternion x componentvoidsetY(float y)Sets the Quaternion y componentvoidsetZ(float z)Sets the Quaternion z componentstatic Quaternionslerp(Quaternion a, Quaternion b, float t)Wrapper function that simply callsslerp(a, b, t, true).static Quaternionslerp(Quaternion a, Quaternion b, float t, boolean allowFlip)Returns the slerp interpolation of quaternionsaandb, at timet.static Quaternionsquad(Quaternion a, Quaternion tgA, Quaternion tgB, Quaternion b, float t)Returns the slerp interpolation of the two quaternionsaandb, at timet, using tangentstgAandtgB.static QuaternionsquadTangent(Quaternion before, Quaternion center, Quaternion after)Returns a tangent quaternion forcenter, defined bybeforeandafterquaternions.static floatsquaredNorm(Quaternion quaternion)Utility function that returns the squared norm of the quaternion.StringtoString()Return this quaternion components as a String.floatw()floatx()floaty()floatz()
-
-
-
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 thefromdirection to thetodirection.- 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 isMatrixit returns a quaternion from the given 'matrix-form' (seeQuaternion(Matrix)). If its type isQuaternionthen 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 typeVectorit returns the quaternion which would produce the rotation from the first vector param to the second (seeQuaternion(Vector, Vector)). If the firstparamsis of typeVectorand the second of typeFloatit returns the quaternion from the given 'axis-angle form', (seeQuaternion(Vector, float)). - Three
params: If the threeparamsare of typeFloatit returns a quaternion from the given 'Euler angles form', (seeQuaternion(float, float, float)). If the threeparamsare of typeVectorit returns a quaternion from the given 'rotated-basis form', (seeQuaternion(Vector, Vector, Vector)).
paramscannot 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 lengthtargetarray.
-
set
public void set(float[] source)
Sets this quaternion from the four lengthsourcearray.
-
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 ofaandb: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 quaternionsaandb.- Parameters:
a- the first Quaternionb- the second Quaternion
-
multiply
public Vector multiply(Vector vector)
Returns the image ofvectorby 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 ofvectorby 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 Quaternionq1and 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 quaternionq1by 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 ofvectorby the quaternion rotation.- Parameters:
vector- the Vector
-
inverseRotate
public Vector inverseRotate(Vector vector)
Returns the image ofvectorby 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 ofaxisandangle(in radians).The
axisdoes not need to be normalized. A nullaxiswill 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,pitchandyaw, 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,pitchandyawin 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 thefromdirection to thetodirection. Attention: this rotation is not uniquely defined. The selected axis is usually orthogonal tofromandto, 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 quaternionsaandb, at timet.tshould range in[0,1]. Result isawhent=0andbwhent=1.When
allowFlipis 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 quaternionsaandb, at timet, using tangentstgAandtgB.The resulting quaternion is "between"
aandb(result isawhent=0andbfort=1).Use
squadTangent(Quaternion, Quaternion, Quaternion)to define the quaternion tangentstgAandtgB.- 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 bybeforeandafterquaternions.- 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.
-
-