com.threerings.math
Class Quaternion

java.lang.Object
  com.threerings.math.Quaternion

All Implemented Interfaces:

Encodable, Exportable, com.threerings.io.Streamable

public final class Quaternion
extends Object
implements Encodable, com.threerings.io.Streamable

A unit quaternion. Many of the formulas come from the Matrix and Quaternion FAQ.

Nested Class Summary

Nested classes/interfaces inherited from interface com.threerings.io.Streamable

com.threerings.io.Streamable.Closure

Field Summary

static Quaternion	IDENTITY The identity quaternion.
float	w The components of the quaternion.
float	x The components of the quaternion.
float	y The components of the quaternion.
float	z The components of the quaternion.

Constructor Summary

Quaternion()
Creates an identity quaternion.

Quaternion(float[] values)
Creates a quaternion from an array of values.

Quaternion(float x, float y, float z, float w)
Creates a quaternion from four components.

Quaternion(Quaternion other)
Copy constructor.

Method Summary

void	decodeFromStream(DataInputStream in) Initializes this object with data read from the specified stream.
void	decodeFromString(String string) Initializes this object with the contents of the specified string.
void	encodeToStream(DataOutputStream out) Encodes this object to the specified stream.
String	encodeToString() Returns a string representation of this object.
boolean	equals(Object other)
Quaternion	fromAngleAxis(float angle, float x, float y, float z) Sets this quaternion to the rotation described by the given angle and normalized axis.
Quaternion	fromAngleAxis(float angle, Vector3f axis) Sets this quaternion to the rotation described by the given angle and normalized axis.
Quaternion	fromAngles(float x, float y, float z) Sets this quaternion to one that first rotates about x by the specified number of radians, then rotates about y, then about z.
Quaternion	fromAngles(Vector3f angles) Sets this quaternion to one that first rotates about x by the specified number of radians, then rotates about y, then about z.
Quaternion	fromAnglesXY(float x, float y) Sets this quaternion to one that first rotates about x by the specified number of radians, then rotates about y by the specified number of radians.
Quaternion	fromAnglesXZ(float x, float z) Sets this quaternion to one that first rotates about x by the specified number of radians, then rotates about z by the specified number of radians.
Quaternion	fromAxes(Vector3f nx, Vector3f ny, Vector3f nz) Sets this quaternion to one that rotates onto the given unit axes.
Quaternion	fromVectors(Vector3f from, Vector3f to) Sets this quaternion to the rotation of the first normalized vector onto the second.
void	get(float[] values) Populates the supplied array with the contents of this quaternion.
float	getRotationZ() Returns the amount of rotation about the z axis (for the purpose of flattening the rotation).
int	hashCode()
Quaternion	integrate(Vector3f velocity, float t) Integrates the provided angular velocity over the specified timestep.
Quaternion	integrate(Vector3f velocity, float t, Quaternion result) Integrates the provided angular velocity over the specified timestep, storing the result in the object provided.
Quaternion	integrateLocal(Vector3f velocity, float t) Integrates in-place the provided angular velocity over the specified timestep.
Quaternion	invert() Inverts this quaternion.
Quaternion	invert(Quaternion result) Inverts this quaternion, storing the result in the object provided.
Quaternion	invertLocal() Inverts this quaternion in-place.
Quaternion	mult(Quaternion other) Multiplies this quaternion by another.
Quaternion	mult(Quaternion other, Quaternion result) Multiplies this quaternion by another and stores the result in the provided object.
Quaternion	multLocal(Quaternion other) Multiplies this quaternion in-place by another.
Quaternion	normalize() Normalizes this quaternion.
Quaternion	normalize(Quaternion result) Normalizes this quaternion, storing the result in the object provided.
Quaternion	normalizeLocal() Normalizes this quaternion in-place.
Quaternion	randomize() Sets this to a random rotation obtained from a completely uniform distribution.
Quaternion	set(float[] values) Copies the elements of an array.
Quaternion	set(float x, float y, float z, float w) Sets all of the elements of the quaternion.
Quaternion	set(Quaternion other) Copies the elements of another quaternion.
Quaternion	slerp(Quaternion other, float t) Interpolates between this and the specified other quaternion.
Quaternion	slerp(Quaternion other, float t, Quaternion result) Interpolates between this and the specified other quaternion, placing the result in the object provided.
Quaternion	slerpLocal(Quaternion other, float t) Interpolates in-place between this and the specified other quaternion.
Vector3f	toAngles() Computes and returns the angles to pass to fromAngles(com.threerings.math.Vector3f) to reproduce this rotation.
Vector3f	toAngles(Vector3f result) Computes the angles to pass to fromAngles(com.threerings.math.Vector3f) to reproduce this rotation, placing them in the provided vector.
String	toString()
Vector3f	transform(Vector3f vector) Transforms a vector by this quaternion.
Vector3f	transform(Vector3f vector, Vector3f result) Transforms a vector by this quaternion and places the result in the provided object.
Vector3f	transformAndAdd(Vector3f vector, Vector3f add, Vector3f result) Transforms a vector by this quaternion and adds another vector to it, placing the result in the object provided.
Vector3f	transformLocal(Vector3f vector) Transforms a vector in-place by this quaternion.
Vector3f	transformScaleAndAdd(Vector3f vector, float scale, Vector3f add, Vector3f result) Transforms a vector by this quaternion, applies a uniform scale, and adds another vector to it, placing the result in the object provided.
Vector3f	transformUnitX(Vector3f result) Transforms the unit x vector by this quaternion, placing the result in the provided object.
Vector3f	transformUnitY(Vector3f result) Transforms the unit y vector by this quaternion, placing the result in the provided object.
Vector3f	transformUnitZ(Vector3f result) Transforms the unit z vector by this quaternion, placing the result in the provided object.
float	transformZ(Vector3f vector) Transforms a vector by this quaternion and returns the z coordinate of the result.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

IDENTITY

public static final Quaternion IDENTITY

The identity quaternion.

x

public float x

The components of the quaternion.

y

public float y

The components of the quaternion.

z

public float z

The components of the quaternion.

w

public float w

The components of the quaternion.

Constructor Detail

Quaternion

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

Creates a quaternion from four components.

Quaternion

public Quaternion(float[] values)

Creates a quaternion from an array of values.

Quaternion

public Quaternion(Quaternion other)

Copy constructor.

Quaternion

public Quaternion()

Creates an identity quaternion.

Method Detail

fromVectors

public Quaternion fromVectors(Vector3f from,
                              Vector3f to)

Sets this quaternion to the rotation of the first normalized vector onto the second.

Returns:

a reference to this quaternion, for chaining.

fromAxes

public Quaternion fromAxes(Vector3f nx,
                           Vector3f ny,
                           Vector3f nz)

Sets this quaternion to one that rotates onto the given unit axes.

Returns:

a reference to this quaternion, for chaining.

fromAngleAxis

public Quaternion fromAngleAxis(float angle,
                                Vector3f axis)

Sets this quaternion to the rotation described by the given angle and normalized axis.

Returns:

a reference to this quaternion, for chaining.

fromAngleAxis

public Quaternion fromAngleAxis(float angle,
                                float x,
                                float y,
                                float z)

Sets this quaternion to the rotation described by the given angle and normalized axis.

Returns:

a reference to this quaternion, for chaining.

randomize

public Quaternion randomize()

Sets this to a random rotation obtained from a completely uniform distribution.

fromAnglesXZ

public Quaternion fromAnglesXZ(float x,
                               float z)

Sets this quaternion to one that first rotates about x by the specified number of radians, then rotates about z by the specified number of radians.

fromAnglesXY

public Quaternion fromAnglesXY(float x,
                               float y)

Sets this quaternion to one that first rotates about x by the specified number of radians, then rotates about y by the specified number of radians.

fromAngles

public Quaternion fromAngles(Vector3f angles)

Sets this quaternion to one that first rotates about x by the specified number of radians, then rotates about y, then about z.

fromAngles

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

Sets this quaternion to one that first rotates about x by the specified number of radians, then rotates about y, then about z.

toAngles

public Vector3f toAngles(Vector3f result)

Computes the angles to pass to fromAngles(com.threerings.math.Vector3f) to reproduce this rotation, placing them in the provided vector. This uses the factorization method described in David Eberly's Euler Angle Formulas.

Returns:

a reference to the result vector, for chaining.

toAngles

public Vector3f toAngles()

Computes and returns the angles to pass to fromAngles(com.threerings.math.Vector3f) to reproduce this rotation.

Returns:

a new vector containing the resulting angles.

normalizeLocal

public Quaternion normalizeLocal()

Normalizes this quaternion in-place.

Returns:

a reference to this quaternion, for chaining.

normalize

public Quaternion normalize()

Normalizes this quaternion.

Returns:

a new quaternion containing the result.

normalize

public Quaternion normalize(Quaternion result)

Normalizes this quaternion, storing the result in the object provided.

Returns:

a reference to the result, for chaining.

invertLocal

public Quaternion invertLocal()

Inverts this quaternion in-place.

Returns:

a reference to this quaternion, for chaining.

invert

public Quaternion invert()

Inverts this quaternion.

Returns:

a new quaternion containing the result.

invert

public Quaternion invert(Quaternion result)

Inverts this quaternion, storing the result in the object provided.

Returns:

a reference to the result, for chaining.

multLocal

public Quaternion multLocal(Quaternion other)

Multiplies this quaternion in-place by another.

Returns:

a reference to this quaternion, for chaining.

mult

public Quaternion mult(Quaternion other)

Multiplies this quaternion by another.

Returns:

a new quaternion containing the result.

mult

public Quaternion mult(Quaternion other,
                       Quaternion result)

Multiplies this quaternion by another and stores the result in the provided object.

Returns:

a reference to the result, for chaining.

slerpLocal

public Quaternion slerpLocal(Quaternion other,
                             float t)

Interpolates in-place between this and the specified other quaternion.

Returns:

a reference to this quaternion, for chaining.

slerp

public Quaternion slerp(Quaternion other,
                        float t)

Interpolates between this and the specified other quaternion.

Returns:

a new quaternion containing the result.

slerp

public Quaternion slerp(Quaternion other,
                        float t,
                        Quaternion result)

Interpolates between this and the specified other quaternion, placing the result in the object provided. Based on the code in Nick Bobick's article, Rotating Objects Using Quaternions.

Returns:

a reference to the result quaternion, for chaining.

transformLocal

public Vector3f transformLocal(Vector3f vector)

Transforms a vector in-place by this quaternion.

Returns:

a reference to the vector, for chaining.

transform

public Vector3f transform(Vector3f vector)

Transforms a vector by this quaternion.

Returns:

a new vector containing the result.

transform

public Vector3f transform(Vector3f vector,
                          Vector3f result)

Transforms a vector by this quaternion and places the result in the provided object.

Returns:

a reference to the result, for chaining.

transformUnitX

public Vector3f transformUnitX(Vector3f result)

Transforms the unit x vector by this quaternion, placing the result in the provided object.

Returns:

a reference to the result, for chaining.

transformUnitY

public Vector3f transformUnitY(Vector3f result)

Transforms the unit y vector by this quaternion, placing the result in the provided object.

Returns:

a reference to the result, for chaining.

transformUnitZ

public Vector3f transformUnitZ(Vector3f result)

Transforms the unit z vector by this quaternion, placing the result in the provided object.

Returns:

a reference to the result, for chaining.

transformAndAdd

public Vector3f transformAndAdd(Vector3f vector,
                                Vector3f add,
                                Vector3f result)

Transforms a vector by this quaternion and adds another vector to it, placing the result in the object provided.

Returns:

a reference to the result, for chaining.

transformScaleAndAdd

public Vector3f transformScaleAndAdd(Vector3f vector,
                                     float scale,
                                     Vector3f add,
                                     Vector3f result)

Transforms a vector by this quaternion, applies a uniform scale, and adds another vector to it, placing the result in the object provided.

Returns:

a reference to the result, for chaining.

transformZ

public float transformZ(Vector3f vector)

Transforms a vector by this quaternion and returns the z coordinate of the result.

getRotationZ

public float getRotationZ()

Returns the amount of rotation about the z axis (for the purpose of flattening the rotation).

integrateLocal

public Quaternion integrateLocal(Vector3f velocity,
                                 float t)

Integrates in-place the provided angular velocity over the specified timestep.

Returns:

a reference to this quaternion, for chaining.

integrate

public Quaternion integrate(Vector3f velocity,
                            float t)

Integrates the provided angular velocity over the specified timestep.

Returns:

a new quaternion containing the result.

integrate

public Quaternion integrate(Vector3f velocity,
                            float t,
                            Quaternion result)

Integrates the provided angular velocity over the specified timestep, storing the result in the object provided.

Returns:

a reference to the result object, for chaining.

set

public Quaternion set(Quaternion other)

Copies the elements of another quaternion.

Returns:

a reference to this quaternion, for chaining.

set

public Quaternion set(float[] values)

Copies the elements of an array.

Returns:

a reference to this quaternion, for chaining.

set

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

Sets all of the elements of the quaternion.

Returns:

a reference to this quaternion, for chaining.

get

public void get(float[] values)

Populates the supplied array with the contents of this quaternion.

encodeToString

public String encodeToString()

Description copied from interface: Encodable

Returns a string representation of this object.

Specified by:

encodeToString in interface Encodable

decodeFromString

public void decodeFromString(String string)
                      throws Exception

Description copied from interface: Encodable

Initializes this object with the contents of the specified string.

Specified by:

decodeFromString in interface Encodable

Throws:

Exception

encodeToStream

public void encodeToStream(DataOutputStream out)
                    throws IOException

Description copied from interface: Encodable

Encodes this object to the specified stream.

Specified by:

encodeToStream in interface Encodable

Throws:

IOException

decodeFromStream

public void decodeFromStream(DataInputStream in)
                      throws IOException

Description copied from interface: Encodable

Initializes this object with data read from the specified stream.

Specified by:

decodeFromStream in interface Encodable

Throws:

IOException

toString

public String toString()

Overrides:

toString in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object other)

Overrides:

equals in class Object