com.jme.math
Class Quaternion

java.lang.Object
  extended by com.jme.math.Quaternion
All Implemented Interfaces:
Savable, java.io.Externalizable, java.io.Serializable, java.lang.Cloneable

public class Quaternion
extends java.lang.Object
implements java.io.Externalizable, Savable, java.lang.Cloneable

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}.

Author:
Mark Powell, Joshua Slack
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.
 Quaternion clone()
           
 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.
 Quaternion fromAngleAxis(float angle, Vector3f axis)
          fromAngleAxis sets this quaternion to the values specified by an angle and an axis of rotation.
 Quaternion 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 (y,r,p).
 Quaternion fromAngles(float yaw, float roll, float pitch)
          fromAngles builds a Quaternion from the Euler rotation angles (y,r,p).
 Quaternion fromAxes(Vector3f[] axis)
          fromAxes creates a Quaternion that represents the coordinate system defined by three axes.
 Quaternion fromAxes(Vector3f xAxis, Vector3f yAxis, Vector3f zAxis)
          fromAxes creates a Quaternion that represents the coordinate system defined by three axes.
 Quaternion fromRotationMatrix(float m00, float m01, float m02, float m10, float m11, float m12, float m20, float m21, float m22)
           
 Quaternion fromRotationMatrix(Matrix3f matrix)
          fromRotationMatrix generates a quaternion from a supplied matrix.
 java.lang.Class<? extends Quaternion> getClassTag()
          The peristed type for the object.
 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.
 float getW()
           
 float getX()
           
 float getY()
           
 float getZ()
           
 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.
 boolean isIdentity()
           
 void loadIdentity()
          Sets this Quaternion to {0, 0, 0, 1}.
 void lookAt(Vector3f direction, Vector3f up)
          lookAt is a convienence method for auto-setting the quaternion based on a direction and an up vector.
 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 (q).
 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
 Quaternion opposite()
           
 Quaternion opposite(Quaternion store)
          FIXME: This seems to have singularity type issues with angle == 0, possibly others such as PI.
 Quaternion oppositeLocal()
           
 void read(JMEImporter e)
           
 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.
 Quaternion set(Quaternion q)
          Sets the data in this Quaternion object to be equal to the passed Quaternion object.
 void setW(float w)
           
 void setX(float x)
           
 void setY(float y)
           
 void setZ(float z)
           
 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.
 Quaternion subtractLocal(Quaternion q)
          subtract subtracts the values of the parameter quaternion from those of this quaternion.
 float toAngleAxis(Vector3f axisStore)
          toAngleAxis sets a given angle and axis to that represented by the current quaternion.
 float[] toAngles(float[] angles)
          toAngles returns this quaternion converted to Euler rotation angles (yaw,roll,pitch).
See http://www.euclideanspace.com/maths/geometry/rotations/conversions/quaternionToEuler/index.htm
 void toAxes(Vector3f[] axis)
          toAxes takes in 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 write(JMEExporter e)
           
 void writeExternal(java.io.ObjectOutput out)
          writeExternal writes this quaternion out to a ObjectOutput object.
 
Methods inherited from class java.lang.Object
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 Quaternion 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.
Returns:
this for chaining

loadIdentity

public void loadIdentity()
Sets this Quaternion to {0, 0, 0, 1}. Same as calling set(0,0,0,1).


isIdentity

public boolean isIdentity()
Returns:
true if this Quaternion is {0,0,0,1}

fromAngles

public void fromAngles(float[] angles)
fromAngles builds a quaternion from the Euler rotation angles (y,r,p).

Parameters:
angles - the Euler angles of rotation (in radians).

fromAngles

public Quaternion fromAngles(float yaw,
                             float roll,
                             float pitch)
fromAngles builds a Quaternion from the Euler rotation angles (y,r,p). Note that we are applying in order: roll, pitch, yaw but we've ordered them in x, y, and z for convenience. See: http://www.euclideanspace.com/maths/geometry/rotations/conversions/eulerToQuaternion/index.htm

Parameters:
yaw - the Euler yaw of rotation (in radians). (aka Bank, often rot around x)
roll - the Euler roll of rotation (in radians). (aka Heading, often rot around y)
pitch - the Euler pitch of rotation (in radians). (aka Attitude, often rot around z)

toAngles

public float[] toAngles(float[] angles)
toAngles returns this quaternion converted to Euler rotation angles (yaw,roll,pitch).
See http://www.euclideanspace.com/maths/geometry/rotations/conversions/quaternionToEuler/index.htm

Parameters:
angles - the float[] in which the angles should be stored, or null if you want a new float[] to be created
Returns:
the float[] in which the angles are stored.

fromRotationMatrix

public Quaternion 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.

fromRotationMatrix

public Quaternion fromRotationMatrix(float m00,
                                     float m01,
                                     float m02,
                                     float m10,
                                     float m11,
                                     float m12,
                                     float m20,
                                     float m21,
                                     float m22)

toRotationMatrix

public Matrix3f toRotationMatrix()
toRotationMatrix converts this quaternion to a rotational matrix. Note: the result is created from a normalized version of this quat.

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. 4th row and 4th column values are untouched. Note: the result is created from a normalized version of this quat.

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. The value is retrieved as if this quaternion was first normalized.

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 Quaternion 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.
Returns:
this quaternion

fromAngleNormalAxis

public Quaternion 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 axisStore)
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:
axisStore - the object we'll store the computed axis in.
Returns:
the angle of rotation in radians.

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.

subtractLocal

public Quaternion subtractLocal(Quaternion q)
subtract subtracts the values of the parameter quaternion from those of this quaternion. The result is stored in this Quaternion.

Parameters:
q - the quaternion to subtract from this.
Returns:
This Quaternion after subtraction.

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 (q). 'this' is not modified. 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 (may be null). If non-null, the input values of 'res' will be ignored and replaced.
Returns:
If specified res is null, then a new Quaternion; otherwise returns the populated 'res'.

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 Quaternion 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.

fromAxes

public Quaternion fromAxes(Vector3f xAxis,
                           Vector3f yAxis,
                           Vector3f zAxis)
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:
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.

toAxes

public void toAxes(Vector3f[] axis)
toAxes takes in 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. 'this' is not modified.

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 This method is very poorly named, since the specified vector is modified and, contrary to the other *Local methods in this and other jME classes, 'this' remains unchanged.

Parameters:
v - the vector which this Quaternion multiplies.
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. 'this' is not modified.

Parameters:
v - the vector to multiply this quaternion by.
store - the vector to store the result in. It IS safe for v and store to be the same object.
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]

Overrides:
toString in class java.lang.Object
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.

Overrides:
equals in class java.lang.Object
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.

Overrides:
hashCode in class java.lang.Object
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

lookAt

public void lookAt(Vector3f direction,
                   Vector3f up)
lookAt is a convienence method for auto-setting the quaternion based on a direction and an up vector. It computes the rotation to transform the z-axis to point into 'direction' and the y-axis to 'up'.

Parameters:
direction - where to look at in terms of local coordinates
up - a vector indicating the local up direction. (typically {0, 1, 0} in jME.)

write

public void write(JMEExporter e)
           throws java.io.IOException
Specified by:
write in interface Savable
Throws:
java.io.IOException

read

public void read(JMEImporter e)
          throws java.io.IOException
Specified by:
read in interface Savable
Throws:
java.io.IOException

getClassTag

public java.lang.Class<? extends Quaternion> getClassTag()
Description copied from interface: Savable
The peristed type for the object. Note that tag here does not mean XML tag, but the class that the object is tagged with.

Specified by:
getClassTag in interface Savable

opposite

public Quaternion opposite()
Returns:
A new quaternion that describes a rotation that would point you in the exact opposite direction of this Quaternion.

opposite

public Quaternion opposite(Quaternion store)
FIXME: This seems to have singularity type issues with angle == 0, possibly others such as PI.

Parameters:
store - A Quaternion to store our result in. If null, a new one is created.
Returns:
The store quaternion (or a new Quaterion, if store is null) that describes a rotation that would point you in the exact opposite direction of this Quaternion.

oppositeLocal

public Quaternion oppositeLocal()
Returns:
This Quaternion, altered to describe a rotation that would point you in the exact opposite direction of where it is pointing currently.

clone

public Quaternion clone()
Overrides:
clone in class java.lang.Object

getX

public float getX()

setX

public void setX(float x)

getY

public float getY()

setY

public void setY(float y)

getZ

public float getZ()

setZ

public void setZ(float z)

getW

public float getW()

setW

public void setW(float w)


Copyright 2003-2009 jMonkeyEngine