raft.jpct.bones

Class Quaternion

java.lang.Object

raft.jpct.bones.Quaternion

All Implemented Interfaces:

Serializable, Cloneable

public class Quaternion
extends Object
implements Serializable, Cloneable

Represents a rotation. Quaternion is a 4 value math object used to describe rotations. It has the advantage of being able to avoid lock by adding a 4th dimension to rotation.

Note: This class is a stripped and modified version of Ardor3D's Quaternion to match jPCT. It may have bugs because of conversion. But especially fromVectorToVector(SimpleVector, SimpleVector), and Matrix in/out methods work ok.

This class will possibly disappear once jPCT has its own Quaternion.

This class is adapted from Ardor3D.

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static Quaternion	IDENTITY x=0, y=0, z=0, w=1
float	w
float	x
float	y
float	z

Constructor Summary

Constructors

Constructor and Description
Quaternion() Constructs a new quaternion set to (0, 0, 0, 1).
Quaternion(float x, float y, float z, float w) Constructs a new quaternion set to (x, y, z, w).
Quaternion(Matrix matrix) Constructs a new quaternion by using rotation information from given matrix.
Quaternion(Quaternion source) Constructs a new quaternion set to the (x, y, z, w) values of the given source quaternion.

Method Summary

Modifier and Type	Method and Description
Quaternion	add(Quaternion quat) Adds another Quaternion to this Quaternion.
float	calcDot(Quaternion quat)
Quaternion	calcSub(Quaternion quat) Calculates the difference vector of two Quaternions.
Quaternion	clone()
boolean	equals(Object o)
Quaternion	fromAngleAxis(float angle, SimpleVector axis) Sets the values of this quaternion to the values represented by a given angle and axis of rotation.
Quaternion	fromAngleNormalAxis(float angle, SimpleVector axis) Sets the values of this quaternion to the values represented by a given angle and unit length axis of rotation.
Quaternion	fromAxes(SimpleVector[] axes) Updates this quaternion to represent a rotation formed by the given three axes.
Quaternion	fromAxes(SimpleVector xAxis, SimpleVector yAxis, SimpleVector zAxis) Updates this quaternion to represent a rotation formed by the given three axes.
Quaternion	fromMatrix(Matrix matrix) Sets the value of this quaternion to the rotation described by the given matrix.
Quaternion	fromVectorToVector(SimpleVector from, SimpleVector to) Sets this quaternion to that which will rotate vector "from" into vector "to".
Matrix	getRotationMatrix() Returns matrix representation of this quaternion.
int	hashCode()
Quaternion	invert() inverse returns the inverse of this quaternion as a new quaternion.
boolean	isIdentity()
boolean	isValid() Check a quaternion...
float	magnitude()
float	magnitudeSquared()
Quaternion	multiply(float qx, float qy, float qz, float qw) Multiplies this quaternion by the supplied quaternion values.
Quaternion	multiply(Quaternion other)
float	norm() norm returns the norm of this quaternion.
Quaternion	normalize() Normalizes this quaternion.
Quaternion	rotate(Matrix matrix) Applies rotation of given matrix to this quaternion.
Quaternion	rotateX(float angle) Rotates the quaternion around X axis.
Quaternion	rotateY(float angle) Rotates the quaternion around Y axis.
Quaternion	rotateZ(float angle) Rotates the quaternion around Z axis.
Quaternion	scalarMul(float scalar) Multiplies each value of this quaternion by the given scalar value.
Quaternion	set(float x, float y, float z, float w) Sets the value of this quaternion to (x, y, z, w)
Quaternion	set(Quaternion source) Sets the value of this quaternion to the (x, y, z, w) values of the provided source quaternion.
Quaternion	setIdentity() Sets the value of this quaternion to (0, 0, 0, 1).
Matrix	setRotation(Matrix matrix) Sets rotation part of given matrix to rotation represented by this quaternion.
Quaternion	slerp(Quaternion source, Quaternion dest, float weight) Does a spherical linear interpolation between the given start and end quaternions by the given change amount.
String	toString()

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

IDENTITY

public static final Quaternion IDENTITY

x=0, y=0, z=0, w=1

x

public float x

y

public float y

z

public float z

w

public float w

Constructor Detail

Quaternion

public Quaternion()

Constructs a new quaternion set to (0, 0, 0, 1).

Quaternion

public Quaternion(Quaternion source)

Constructs a new quaternion set to the (x, y, z, w) values of the given source quaternion.

Parameters:

source -

Quaternion

public Quaternion(float x,
                  float y,
                  float z,
                  float w)

Constructs a new quaternion set to (x, y, z, w).

Parameters:

x -

y -

z -

w -

Quaternion

public Quaternion(Matrix matrix)

Constructs a new quaternion by using rotation information from given matrix. The matrix should be a valid rotation matrix. Otherwise result will be incorrect.

See Also:

fromMatrix(Matrix)

Method Detail

set

public Quaternion set(float x,
                      float y,
                      float z,
                      float w)

Sets the value of this quaternion to (x, y, z, w)

Parameters:

x -

y -

z -

w -

Returns:

this quaternion for chaining

set

public Quaternion set(Quaternion source)

Sets the value of this quaternion to the (x, y, z, w) values of the provided source quaternion.

Parameters:

source -

Returns:

this quaternion for chaining

Throws:

NullPointerException - if source is null.

fromMatrix

public Quaternion fromMatrix(Matrix matrix)

Sets the value of this quaternion to the rotation described by the given matrix. The matrix should be a valid rotation matrix. Otherwise result will be incorrect.

Parameters:

matrix -

Returns:

this quaternion for chaining

Throws:

NullPointerException - if matrix is null.

fromAngleAxis

public Quaternion fromAngleAxis(float angle,
                                SimpleVector axis)

Sets the values of this quaternion to the values represented by a given angle and axis of rotation. Note that this method normalizes given axis vector, so use fromAngleNormalAxis if your axis is already normalized. If axis == 0,0,0 the quaternion is set to identity.

Parameters:

angle - the angle to rotate (in radians).

axis - the axis of rotation.

Returns:

this quaternion for chaining

Throws:

NullPointerException - if axis is null

fromAngleNormalAxis

public Quaternion fromAngleNormalAxis(float angle,
                                      SimpleVector axis)

Sets the values of this quaternion to the values represented by a given angle and unit length axis of rotation. If axis == 0,0,0 the quaternion is set to identity.

Parameters:

angle - the angle to rotate (in radians).

axis - the axis of rotation (already normalized - unit length).

Throws:

NullPointerException - if axis is null

fromVectorToVector

public Quaternion fromVectorToVector(SimpleVector from,
                                     SimpleVector to)

Sets this quaternion to that which will rotate vector "from" into vector "to". from and to do not have to be the same length.

Parameters:

from - the source vector to rotate

to - the destination vector into which to rotate the source vector

Returns:

this quaternion for chaining

normalize

public Quaternion normalize()

Normalizes this quaternion.

Returns:

a new quaternion that represents a unit length version of this Quaternion.

add

public Quaternion add(Quaternion quat)

Adds another Quaternion to this Quaternion.

Parameters:

quat - the Quaternion to add

Returns:

this Quaternion for chaining

calcSub

public Quaternion calcSub(Quaternion quat)

Calculates the difference vector of two Quaternions.

Parameters:

quat - the second Quaternion

Returns:

the difference vector between "this" and "quat"

scalarMul

public Quaternion scalarMul(float scalar)

Multiplies each value of this quaternion by the given scalar value. The result is stored in this quaternion.

Parameters:

scalar - the quaternion to multiply this quaternion by.

Returns:

this quaternion for chaining.

multiply

public Quaternion multiply(Quaternion other)

multiply

public Quaternion multiply(float qx,
                           float qy,
                           float qz,
                           float qw)

Multiplies this quaternion by the supplied quaternion values. The result is stored locally.

Parameters:

qx -

qy -

qz -

qw -

Returns:

this quaternion for chaining

fromAxes

public Quaternion fromAxes(SimpleVector[] axes)

Updates this quaternion to represent a rotation formed by the given three axes. These axes are assumed to be orthogonal and no error checking is applied. It is the user's job to insure that the three axes being provided indeed represent a proper right handed coordinate system.

Parameters:

axes - the array containing the three vectors representing the coordinate system.

Returns:

this quaternion for chaining

Throws:

IllegalArgumentException - if the given axes array is smaller than 3 elements.

fromAxes

public Quaternion fromAxes(SimpleVector xAxis,
                           SimpleVector yAxis,
                           SimpleVector zAxis)

Updates this quaternion to represent a rotation formed by the given three axes. These axes are assumed to be orthogonal and no error checking is applied. It is the user's job to insure that the three axes being provided indeed represent a proper right handed coordinate system.

Parameters:

xAxis - vector representing the x-axis of the coordinate system.

yAxis - vector representing the y-axis of the coordinate system.

zAxis - vector representing the z-axis of the coordinate system.

Returns:

this quaternion for chaining

slerp

public Quaternion slerp(Quaternion source,
                        Quaternion dest,
                        float weight)

Does a spherical linear interpolation between the given start and end quaternions by the given change amount. Stores the result locally.

Parameters:

source -

dest -

weight -

Returns:

this quaternion for chaining.

Throws:

NullPointerException - if startQuat or endQuat are null.

magnitudeSquared

public float magnitudeSquared()

Returns:

the squared magnitude of this quaternion.

magnitude

public float magnitude()

Returns:

the magnitude of this quaternion. basically sqrt(magnitude())

calcDot

public float calcDot(Quaternion quat)

Parameters:

quat -

Returns:

the dot product of this quaternion with the given quaternion.

setIdentity

public Quaternion setIdentity()

Sets the value of this quaternion to (0, 0, 0, 1). Equivalent to calling set(0, 0, 0, 1)

Returns:

this quaternion for chaining

isIdentity

public boolean isIdentity()

Returns:

true if this quaternion is (0, 0, 0, 1)

isValid

public boolean isValid()

Check a quaternion... if values are NaN or infinite, return false. Else return true.

Returns:

true or false as stated above.

toString

public String toString()

Overrides:

toString in class Object

Returns:

the string representation of this quaternion.

hashCode

public int hashCode()

Overrides:

hashCode in class Object

Returns:

returns a unique code for this quaternion object based on its values. If two quaternions are numerically equal, they will return the same hash code value.

equals

public boolean equals(Object o)

Overrides:

equals in class Object

Parameters:

o - the object to compare for equality

Returns:

true if this quaternion and the provided quaternion have the same x, y, z and w values.

clone

public Quaternion clone()

Overrides:

clone in class Object

getRotationMatrix

public Matrix getRotationMatrix()

Returns matrix representation of this quaternion.

Returns:

the rotation matrix representation of this quaternion (normalized)

setRotation

public Matrix setRotation(Matrix matrix)

Sets rotation part of given matrix to rotation represented by this quaternion.

Parameters:

matrix - the matrix to store the result

Returns:

the rotation matrix representation of this quaternion (normalized)

rotateX

public Quaternion rotateX(float angle)

Rotates the quaternion around X axis. uses Matrix.rotateX(float) behind the scenes.

rotateY

public Quaternion rotateY(float angle)

Rotates the quaternion around Y axis. uses Matrix.rotateY(float) behind the scenes.

rotateZ

public Quaternion rotateZ(float angle)

Rotates the quaternion around Z axis. uses Matrix.rotateZ(float) behind the scenes.

rotate

public Quaternion rotate(Matrix matrix)

Applies rotation of given matrix to this quaternion. uses Matrix.matMul(Matrix) behind the scenes.

invert

public Quaternion invert()

inverse returns the inverse of this quaternion as a new quaternion. If this quaternion does not have an inverse (if its normal is 0 or less), then an IllegalStateException is thrown.

Returns:

the inverse of this quaternion or null if the inverse does not exist.

Throws:

IllegalStateException - if can not be inverted

norm

public float norm()

norm returns the norm of this quaternion. This is the dot product of this quaternion with itself.

Returns:

the norm of the quaternion.