com.jme.math
Class Quaternion

java.lang.Object
  com.jme.math.Quaternion

All Implemented Interfaces:

java.io.Externalizable, java.io.Serializable

public class Quaternion

extends java.lang.Object

implements java.io.Externalizable

Quaternion defines a single example of a more general class of hypercomplex numbers. Quaternions extends a rotation in three dimensions to a rotation in four dimensions. This avoids "gimbal lock" and allows for smooth continuous rotation. Quaternion is defined by four floating point numbers: {x y z w}.

Version:

$Id: Quaternion.java,v 1.33 2005/04/06 20:24:25 renanse Exp $

Author:

Mark Powell, Joshua Slack - Optimizations

See Also:

Serialized Form

Field Summary

float	w
float	x
float	y
float	z

Constructor Summary

Quaternion()
Constructor instantiates a new Quaternion object initializing all values to zero, except w which is initialized to 1.

Quaternion(float[] angles)
Constructor instantiates a new Quaternion object from a collection of rotation angles.

Quaternion(float x, float y, float z, float w)
Constructor instantiates a new Quaternion object from the given list of parameters.

Quaternion(Quaternion q)
Constructor instantiates a new Quaternion object from an existing quaternion, creating a copy.

Quaternion(Quaternion q1, Quaternion q2, float interp)
Constructor instantiates a new Quaternion object from an interpolation between two other quaternions.

Method Summary

Quaternion	add(Quaternion q) add adds the values of this quaternion to those of the parameter quaternion.
Quaternion	addLocal(Quaternion q) add adds the values of this quaternion to those of the parameter quaternion.
void	apply(Matrix3f matrix) apply multiplies this quaternion by a parameter matrix internally.
float	dot(Quaternion q) dot calculates and returns the dot product of this quaternion with that of the parameter quaternion.
boolean	equals(java.lang.Object o) equals determines if two quaternions are logically equal, that is, if the values of (x, y, z, w) are the same for both quaternions.
void	fromAngleAxis(float angle, Vector3f axis) fromAngleAxis sets this quaternion to the values specified by an angle and an axis of rotation.
void	fromAngleNormalAxis(float angle, Vector3f axis) fromAngleNormalAxis sets this quaternion to the values specified by an angle and a normalized axis of rotation.
void	fromAngles(float[] angles) fromAngles builds a quaternion from the Euler rotation angles (x,y,z).
void	fromAxes(Vector3f[] axis) fromAxes creates a Quaternion that represents the coordinate system defined by three axes.
void	fromRotationMatrix(Matrix3f matrix) fromRotationMatrix generates a quaternion from a supplied matrix.
Vector3f	getRotationColumn(int i) getRotationColumn returns one of three columns specified by the parameter.
Vector3f	getRotationColumn(int i, Vector3f store) getRotationColumn returns one of three columns specified by the parameter.
int	hashCode() hashCode returns the hash code value as an integer and is supported for the benefit of hashing based collection classes such as Hashtable, HashMap, HashSet etc.
Quaternion	inverse() inverse returns the inverse of this quaternion as a new quaternion.
Quaternion	inverseLocal() inverse calculates the inverse of this quaternion and returns this quaternion after it is calculated.
Quaternion	mult(float scalar) mult multiplies this quaternion by a parameter scalar.
Quaternion	mult(Quaternion q) mult multiplies this quaternion by a parameter quaternion.
Quaternion	mult(Quaternion q, Quaternion res) mult multiplies this quaternion by a parameter quaternion.
Vector3f	mult(Vector3f v) mult multiplies this quaternion by a parameter vector.
Vector3f	mult(Vector3f v, Vector3f store) mult multiplies this quaternion by a parameter vector.
Quaternion	multLocal(float scalar) mult multiplies this quaternion by a parameter scalar.
Quaternion	multLocal(float qx, float qy, float qz, float qw) Multiplies this Quaternion by the supplied quaternion.
Quaternion	multLocal(Quaternion q) Multiplies this Quaternion by the supplied quaternion.
Vector3f	multLocal(Vector3f v) mult multiplies this quaternion by a parameter vector.
void	negate() negate inverts the values of the quaternion.
float	norm() norm returns the norm of this quaternion.
void	normalize() normalize normalizes the current Quaternion
void	readExternal(java.io.ObjectInput in) readExternal builds a quaternion from an ObjectInput object.
void	set(float x, float y, float z, float w) sets the data in a Quaternion object from the given list of parameters.
void	set(Quaternion q) Sets the data in this Quaternion object to be equal to the passed Quaternion object.
void	slerp(Quaternion q2, float changeAmnt) Sets the values of this quaternion to the slerp from itself to q2 by changeAmnt
Quaternion	slerp(Quaternion q1, Quaternion q2, float t) slerp sets this quaternion's value as an interpolation between two other quaternions.
Quaternion	subtract(Quaternion q) subtract subtracts the values of the parameter quaternion from those of this quaternion.
float	toAngleAxis(Vector3f axis) toAngleAxis sets a given angle and axis to that represented by the current quaternion.
void	toAxes(Vector3f[] axis) toAxes builds an array of three vectors.
Matrix3f	toRotationMatrix() toRotationMatrix converts this quaternion to a rotational matrix.
Matrix3f	toRotationMatrix(Matrix3f result) toRotationMatrix converts this quaternion to a rotational matrix.
Matrix4f	toRotationMatrix(Matrix4f result) toRotationMatrix converts this quaternion to a rotational matrix.
java.lang.String	toString() toString creates the string representation of this Quaternion.
void	writeExternal(java.io.ObjectOutput out) writeExternal writes this quaternion out to a ObjectOutput object.

Methods inherited from class java.lang.Object

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

Field Detail

x

public float x

y

public float y

z

public float z

w

public float w

Constructor Detail

Quaternion

public Quaternion()

Constructor instantiates a new Quaternion object initializing all values to zero, except w which is initialized to 1.

Quaternion

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

Constructor instantiates a new Quaternion object from the given list of parameters.

Parameters:

x - the x value of the quaternion.

y - the y value of the quaternion.

z - the z value of the quaternion.

w - the w value of the quaternion.

Quaternion

public Quaternion(float[] angles)

Constructor instantiates a new Quaternion object from a collection of rotation angles.

Parameters:

angles - the angles of rotation (x, y, z) that will define the Quaternion.

Quaternion

public Quaternion(Quaternion q1,
                  Quaternion q2,
                  float interp)

Constructor instantiates a new Quaternion object from an interpolation between two other quaternions.

Parameters:

q1 - the first quaternion.

q2 - the second quaternion.

interp - the amount to interpolate between the two quaternions.

Quaternion

public Quaternion(Quaternion q)

Constructor instantiates a new Quaternion object from an existing quaternion, creating a copy.

Parameters:

q - the quaternion to copy.

Method Detail

set

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

sets the data in a Quaternion object from the given list of parameters.

Parameters:

x - the x value of the quaternion.

y - the y value of the quaternion.

z - the z value of the quaternion.

w - the w value of the quaternion.

set

public void set(Quaternion q)

Sets the data in this Quaternion object to be equal to the passed Quaternion object. The values are copied producing a new object.

Parameters:

q - The Quaternion to copy values from.

fromAngles

public void fromAngles(float[] angles)

fromAngles builds a quaternion from the Euler rotation angles (x,y,z).

Parameters:

angles - the Euler angles of rotation.

fromRotationMatrix

public void fromRotationMatrix(Matrix3f matrix)

fromRotationMatrix generates a quaternion from a supplied matrix. This matrix is assumed to be a rotational matrix.

Parameters:

matrix - the matrix that defines the rotation.

toRotationMatrix

public Matrix3f toRotationMatrix()

toRotationMatrix converts this quaternion to a rotational matrix.

Returns:

the rotation matrix representation of this quaternion.

toRotationMatrix

public Matrix3f toRotationMatrix(Matrix3f result)

toRotationMatrix converts this quaternion to a rotational matrix. The result is stored in result.

Parameters:

result - The Matrix3f to store the result in.

Returns:

the rotation matrix representation of this quaternion.

toRotationMatrix

public Matrix4f toRotationMatrix(Matrix4f result)

toRotationMatrix converts this quaternion to a rotational matrix. The result is stored in result. The outer col, row is 0, with 3,3 = 1

Parameters:

result - The Matrix4f to store the result in.

Returns:

the rotation matrix representation of this quaternion.

getRotationColumn

public Vector3f getRotationColumn(int i)

getRotationColumn returns one of three columns specified by the parameter. This column is returned as a Vector3f object.

Parameters:

i - the column to retrieve. Must be between 0 and 2.

Returns:

the column specified by the index.

getRotationColumn

public Vector3f getRotationColumn(int i,
                                  Vector3f store)

getRotationColumn returns one of three columns specified by the parameter. This column is returned as a Vector3f object.

Parameters:

i - the column to retrieve. Must be between 0 and 2.

store - the vector object to store the result in. if null, a new one is created.

Returns:

the column specified by the index.

fromAngleAxis

public void fromAngleAxis(float angle,
                          Vector3f axis)

fromAngleAxis sets this quaternion to the values specified by an angle and an axis of rotation. This method creates an object, so use fromAngleNormalAxis if your axis is already normalized.

Parameters:

angle - the angle to rotate (in radians).

axis - the axis of rotation.

fromAngleNormalAxis

public void fromAngleNormalAxis(float angle,
                                Vector3f axis)

fromAngleNormalAxis sets this quaternion to the values specified by an angle and a normalized axis of rotation.

Parameters:

angle - the angle to rotate (in radians).

axis - the axis of rotation (already normalized).

toAngleAxis

public float toAngleAxis(Vector3f axis)

toAngleAxis sets a given angle and axis to that represented by the current quaternion. The values are stored as following: The axis is provided as a parameter and built by the method, the angle is returned as a float.

Parameters:

axis - the object to contain the axis.

Returns:

the angle of rotation in degrees.

slerp

public Quaternion slerp(Quaternion q1,
                        Quaternion q2,
                        float t)

slerp sets this quaternion's value as an interpolation between two other quaternions.

Parameters:

q1 - the first quaternion.

q2 - the second quaternion.

t - the amount to interpolate between the two quaternions.

slerp

public void slerp(Quaternion q2,
                  float changeAmnt)

Sets the values of this quaternion to the slerp from itself to q2 by changeAmnt

Parameters:

q2 - Final interpolation value

changeAmnt - The amount diffrence

add

public Quaternion add(Quaternion q)

add adds the values of this quaternion to those of the parameter quaternion. The result is returned as a new quaternion.

Parameters:

q - the quaternion to add to this.

Returns:

the new quaternion.

addLocal

public Quaternion addLocal(Quaternion q)

add adds the values of this quaternion to those of the parameter quaternion. The result is stored in this Quaternion..

Parameters:

q - the quaternion to add to this.

Returns:

This Quaternion after addition.

subtract

public Quaternion subtract(Quaternion q)

subtract subtracts the values of the parameter quaternion from those of this quaternion. The result is returned as a new quaternion.

Parameters:

q - the quaternion to subtract from this.

Returns:

the new quaternion.

mult

public Quaternion mult(Quaternion q)

mult multiplies this quaternion by a parameter quaternion. The result is returned as a new quaternion. It should be noted that quaternion multiplication is not cummulative so q * p != p * q.

Parameters:

q - the quaternion to multiply this quaternion by.

Returns:

the new quaternion.

mult

public Quaternion mult(Quaternion q,
                       Quaternion res)

mult multiplies this quaternion by a parameter quaternion. The result is returned as a new quaternion. It should be noted that quaternion multiplication is not cummulative so q * p != p * q. It IS safe for q and res to be the same object.

Parameters:

q - the quaternion to multiply this quaternion by.

res - the quaternion to store the result in.

Returns:

the new quaternion.

apply

public void apply(Matrix3f matrix)

apply multiplies this quaternion by a parameter matrix internally.

Parameters:

matrix - the matrix to apply to this quaternion.

fromAxes

public void fromAxes(Vector3f[] axis)

fromAxes creates a Quaternion that represents the coordinate system defined by three axes. These axes are assumed to be orthogonal and no error checking is applied. Thus, the user must insure that the three axes being provided indeed represents a proper right handed coordinate system.

Parameters:

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

toAxes

public void toAxes(Vector3f[] axis)

toAxes builds an array of three vectors. Each vector corresponds to an axis of the coordinate system defined by the quaternion rotation.

Parameters:

axis - the array of vectors to be filled.

mult

public Vector3f mult(Vector3f v)

mult multiplies this quaternion by a parameter vector. The result is returned as a new vector.

Parameters:

v - the vector to multiply this quaternion by.

Returns:

the new vector.

multLocal

public Vector3f multLocal(Vector3f v)

mult multiplies this quaternion by a parameter vector. The result is stored in the supplied vector

Parameters:

v - the vector to multiply this quaternion by.

Returns:

v

multLocal

public Quaternion multLocal(Quaternion q)

Multiplies this Quaternion by the supplied quaternion. The result is stored in this Quaternion, which is also returned for chaining. Similar to this *= q.

Parameters:

q - The Quaternion to multiply this one by.

Returns:

This Quaternion, after multiplication.

multLocal

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

Multiplies this Quaternion by the supplied quaternion. The result is stored in this Quaternion, which is also returned for chaining. Similar to this *= q.

Parameters:

qx - - quat x value

qy - - quat y value

qz - - quat z value

qw - - quat w value

Returns:

This Quaternion, after multiplication.

mult

public Vector3f mult(Vector3f v,
                     Vector3f store)

mult multiplies this quaternion by a parameter vector. The result is returned as a new vector.

Parameters:

v - the vector to multiply this quaternion by.

store - the vector to store the result in

Returns:

the result vector.

mult

public Quaternion mult(float scalar)

mult multiplies this quaternion by a parameter scalar. The result is returned as a new quaternion.

Parameters:

scalar - the quaternion to multiply this quaternion by.

Returns:

the new quaternion.

multLocal

public Quaternion multLocal(float scalar)

mult multiplies this quaternion by a parameter scalar. The result is stored locally.

Parameters:

scalar - the quaternion to multiply this quaternion by.

Returns:

this.

dot

public float dot(Quaternion q)

dot calculates and returns the dot product of this quaternion with that of the parameter quaternion.

Parameters:

q - the quaternion to calculate the dot product of.

Returns:

the dot product of this and the parameter quaternion.

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.

normalize

public void normalize()

normalize normalizes the current Quaternion

inverse

public Quaternion inverse()

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 null is returned.

Returns:

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

inverseLocal

public Quaternion inverseLocal()

inverse calculates the inverse of this quaternion and returns this quaternion after it is calculated. If this quaternion does not have an inverse (if it's norma is 0 or less), nothing happens

Returns:

the inverse of this quaternion

negate

public void negate()

negate inverts the values of the quaternion.

toString

public java.lang.String toString()

toString creates the string representation of this Quaternion. The values of the quaternion are displace (x, y, z, w), in the following manner:
com.jme.math.Quaternion: [x=1" y=2 z=3 w=1]

Returns:

the string representation of this object.

See Also:

Object.toString()

equals

public boolean equals(java.lang.Object o)

equals determines if two quaternions are logically equal, that is, if the values of (x, y, z, w) are the same for both quaternions.

Parameters:

o - the object to compare for equality

Returns:

true if they are equal, false otherwise.

hashCode

public int hashCode()

hashCode returns the hash code value as an integer and is supported for the benefit of hashing based collection classes such as Hashtable, HashMap, HashSet etc.

Returns:

the hashcode for this instance of Quaternion.

See Also:

Object.hashCode()

readExternal

public void readExternal(java.io.ObjectInput in)
                  throws java.io.IOException

readExternal builds a quaternion from an ObjectInput object.
NOTE: Used with serialization. Not to be called manually.

Specified by:

readExternal in interface java.io.Externalizable

Parameters:

in - the ObjectInput value to read from.

Throws:

java.io.IOException - if the ObjectInput value has problems reading a float.

See Also:

Externalizable

writeExternal

public void writeExternal(java.io.ObjectOutput out)
                   throws java.io.IOException

writeExternal writes this quaternion out to a ObjectOutput object. NOTE: Used with serialization. Not to be called manually.

Specified by:

writeExternal in interface java.io.Externalizable

Parameters:

out - the object to write to.

Throws:

java.io.IOException - if writing to the ObjectOutput fails.

See Also:

Externalizable