com.kauailabs.sf2.orientation

Class Quaternion

java.lang.Object

com.kauailabs.sf2.orientation.Quaternion

All Implemented Interfaces:

IInterpolate<Quaternion>, ICopy<Quaternion>, IQuantity

public class Quaternion
extends java.lang.Object
implements IInterpolate<Quaternion>, ICopy<Quaternion>, IQuantity

The Quaternion class provides methods to operate on a quaternion. Quaternions are used among other things to describe rotation in 3D dimensions. This is typically performed using a Unit Quaternion (also known as a "Versor".

Provided Quaternion operations include basic mathematic operations as well as a method for interpolation.

Quaternions actually describe 4 separate rotations - 3 dimensions of rotation about a coordinate reference frame, and then a fourth rotation of the coodinate reference frame to another reference frame.

At their core, Quaternions are comprised of W, X, Y and Z components, which in the case of the Unit Quaternion are expressed in units of Radians which have a range from -2 to 2.

From a number theory perspecive, a quaternion is a complex number. A quaternion is a formal sum of a real number and real multiples of the symbols i, j, and k. For example,

q = W + Xi + Yj + Zk

A Unit Quaternion can express not only rotations, but also the gravity vector. Therefore, the Quaternion class provides methods for deriving the gravity vector as well as the more commonly-used Yaw, Pitch and Roll angles (also known as Tait/Bryan angles).

Constructor Summary

Constructors

Constructor and Description
Quaternion() Constructs a Quaternion instance, using default values for a Unit Quaternion.
Quaternion(float w, float x, float y, float z) Constructs a Quaternion instance, using the provides w, x, y and z valuese.
Quaternion(Quaternion src) Constructs a Quaternion instance, using values from another Quaternion instance.

Method Summary

Modifier and Type	Method and Description
void	conjugate() Modifies the Quaternion to be its complex conjugate.
void	copy(Quaternion t)
static void	difference(Quaternion qa, Quaternion qb, Quaternion q_diff) Divides two quaternions.
void	divide(float s) Modifies a quaternion, scaling it by the provided parameter.
float	dotProduct(Quaternion q1, Quaternion q2)
boolean	getContainedQuantities(java.util.ArrayList<IQuantity> quantities)
boolean	getContainedQuantityNames(java.util.ArrayList<java.lang.String> quantity_names)
void	getPitch(Scalar pitch) Extracts the pitch angle value from the Quaternion.
boolean	getPrintableString(java.lang.StringBuilder printable_string)
void	getRoll(Scalar roll) Extracts the roll angle value from the Quaternion.
static Unit.IUnit[]	getUnits()
float	getW() Accessor for the Quaternion's W component value.
float	getX() Accessor for the Quaternion's X component value.
float	getY() Accessor for the Quaternion's Y component value.
void	getYawRadians(Scalar yaw) Extracts the yaw angle value from the Quaternion.
float	getZ() Accessor for the Quaternion's Z component value.
Quaternion	instantiate_copy()
void	interpolate(Quaternion to, double time_ratio, Quaternion out)
void	inverse() Modifies the Quaternion to be its inverse (reciprocal).
void	multiply(Quaternion q) Modifies this quaternion (the multiplicand) to be the product of multiplication by a multiplier Quaternion.
void	set(float w, float x, float y, float z) Modifies the Quaternion by setting the component W, X, Y and Z value.
void	set(Quaternion src) Modifes the Quaternion to be equal to the provided Quaternion.
static void	slerp(Quaternion qa, Quaternion qb, double t, Quaternion out) Estimates an intermediate Quaternion given Quaternions representing each end of the path, and an interpolation ratio from 0.0 t0 1.0.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Quaternion

public Quaternion()

Constructs a Quaternion instance, using default values for a Unit Quaternion.

Quaternion

public Quaternion(Quaternion src)

Constructs a Quaternion instance, using values from another Quaternion instance.

Parameters:

src - - the Quaternion instance used to initialize this Quaternion.

Quaternion

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

Constructs a Quaternion instance, using the provides w, x, y and z valuese.

Parameters:

w - - the Quaternion W component value.

x - - the Quaternion X component value.

y - - the Quaternion Y component value.

z - - the Quaternion Z component value.

Method Detail

set

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

Modifies the Quaternion by setting the component W, X, Y and Z value.

Parameters:

w - - the Quaternion W component value.

x - - the Quaternion X component value.

y - - the Quaternion Y component value.

z - - the Quaternion Z component value.

set

public void set(Quaternion src)

Modifes the Quaternion to be equal to the provided Quaternion.

Parameters:

src - - the Quaternion instance used to initialize this Quaternion.

getYawRadians

public void getYawRadians(Scalar yaw)

Extracts the yaw angle value from the Quaternion. The Return value is in units of Radians.

getPitch

public void getPitch(Scalar pitch)

Extracts the pitch angle value from the Quaternion. The Return value is in units of Radians.

getRoll

public void getRoll(Scalar roll)

Extracts the roll angle value from the Quaternion. The Return value is in units of Radians.

slerp

public static void slerp(Quaternion qa,
                         Quaternion qb,
                         double t,
                         Quaternion out)

Estimates an intermediate Quaternion given Quaternions representing each end of the path, and an interpolation ratio from 0.0 t0 1.0. Uses Quaternion SLERP (Spherical Linear Interpolation), an algorithm originally introduced by Ken Shoemake in the context of quaternion interpolation for the purpose of animating 3D rotation. This estimation is based upon the assumption of constant-speed motion along a unit-radius great circle arc. For more info: http://www.euclideanspace.com/maths/algebra/realNormedAlgebra/quaternions /slerp/index.htm

conjugate

public void conjugate()

Modifies the Quaternion to be its complex conjugate. The complex conjugate of a complex number is the number with equal real part and imaginary part equal in magnitude but opposite in sign.

inverse

public void inverse()

Modifies the Quaternion to be its inverse (reciprocal). The quaternion inverse of a rotation is the opposite rotation, so it can be thought of as a mirror image of the original quaternion

multiply

public void multiply(Quaternion q)

Modifies this quaternion (the multiplicand) to be the product of multiplication by a multiplier Quaternion. Key point: the result of multiplying two Quaternions is to logically add together their respective rotations. Note that Quaternion multiplication is NOT commutative , in other words when multiplying Quaternions, the result of a * b is NOT the same as b * a.

Parameters:

q - - the multiplier quaternion.

divide

public void divide(float s)

Modifies a quaternion, scaling it by the provided parameter.

Parameters:

s - - the value by which to divide each Quaternion component value.

dotProduct

public float dotProduct(Quaternion q1,
                        Quaternion q2)

difference

public static void difference(Quaternion qa,
                              Quaternion qb,
                              Quaternion q_diff)

Divides two quaternions. Since Quaternion multiplication is not commutative, to perform this operation, the multiplicand Quaternion is multiplied by the inverse of the multiplier Quaternion. Key point: the result of dividing two Quaternions is to logically subtract their respective rotations. Thus, use difference() to calculate the amount of 3D rotation between two Quaternions.

Parameters:

qa - - the dividend Quaternion

qb - - the divisor Quaternion

q_diff - - the resulting quotient Quaternion representing the difference in rotation

getW

public float getW()

Accessor for the Quaternion's W component value.

Returns:

Quaternion W component value.

getX

public float getX()

Accessor for the Quaternion's X component value.

Returns:

Quaternion X component value.

getY

public float getY()

Accessor for the Quaternion's Y component value.

Returns:

Quaternion Y component value.

getZ

public float getZ()

Accessor for the Quaternion's Z component value.

Returns:

Quaternion Z component value.

interpolate

public void interpolate(Quaternion to,
                        double time_ratio,
                        Quaternion out)

Specified by:

interpolate in interface IInterpolate<Quaternion>

copy

public void copy(Quaternion t)

Specified by:

copy in interface ICopy<Quaternion>

instantiate_copy

public Quaternion instantiate_copy()

Specified by:

instantiate_copy in interface ICopy<Quaternion>

getUnits

public static Unit.IUnit[] getUnits()

getPrintableString

public boolean getPrintableString(java.lang.StringBuilder printable_string)

Specified by:

getPrintableString in interface IQuantity

getContainedQuantities

public boolean getContainedQuantities(java.util.ArrayList<IQuantity> quantities)

Specified by:

getContainedQuantities in interface IQuantity

getContainedQuantityNames

public boolean getContainedQuantityNames(java.util.ArrayList<java.lang.String> quantity_names)

Specified by:

getContainedQuantityNames in interface IQuantity