Package com.jme3.math

Class Quaternion

java.lang.Object

com.jme3.math.Quaternion

All Implemented Interfaces:

Savable, Serializable, Cloneable

public final class Quaternion
extends Object
implements Savable, Cloneable, Serializable

Used to efficiently represent rotations and orientations in 3-dimensional space, without risk of gimbal lock. Each instance has 4 single-precision components: 3 imaginary components (X, Y, and Z) and a real component (W).

Mathematically, quaternions are an extension of complex numbers. In mathematics texts, W often appears first, but in JME it always comes last.

See Also:

• Serialized Form

Field Summary

Fields

Modifier and Type	Field	Description
static final Quaternion	DIRECTION_Z	Another shared instance of the identity quaternion (0, 0, 0, 1).
static final Quaternion	IDENTITY	Shared instance of the identity quaternion (0, 0, 0, 1).
protected float	w	The real (W) component.
protected float	x	The first imaginary (X) component.
protected float	y	The 2nd imaginary (Y) component.
protected float	z	The 3rd imaginary (Z) component.
static final Quaternion	ZERO	Shared instance of the zero quaternion (0, 0, 0, 0).

Constructor Summary

Constructors

Constructor	Description
Quaternion()	Instantiates an identity quaternion: all components zeroed except w, which is set to 1.
Quaternion(float[] angles)	Instantiates a quaternion from Tait-Bryan angles, applying the rotations in x-z-y extrinsic order or y-z'-x" intrinsic order.
Quaternion(float x, float y, float z, float w)	Instantiates a quaternion with the specified components.
Quaternion(Quaternion q)	Instantiates a copy of the argument.
Quaternion(Quaternion q1, Quaternion q2, float interp)	Instantiates a quaternion by interpolating between the specified quaternions.

Method Summary

Modifier and Type	Method	Description
Quaternion	add(Quaternion q)	Adds the argument and returns the sum as a new instance.
Quaternion	addLocal(Quaternion q)	Adds the argument and returns the (modified) current instance.
void	apply(Matrix3f matrix)	Applies the rotation represented by the argument to the current instance.
Quaternion	clone()	Creates a copy.
float	dot(Quaternion q)	Returns the dot product with the argument.
boolean	equals(Object o)	Tests for exact equality with the argument, distinguishing -0 from 0.
Quaternion	fromAngleAxis(float angle, Vector3f axis)	Sets the quaternion from the specified rotation angle and axis of rotation.
Quaternion	fromAngleNormalAxis(float angle, Vector3f axis)	Sets the quaternion from the specified rotation angle and normalized axis of rotation.
Quaternion	fromAngles(float[] angles)	Sets the quaternion from the specified Tait-Bryan angles, applying the rotations in x-z-y extrinsic order or y-z'-x" intrinsic order.
Quaternion	fromAngles(float xAngle, float yAngle, float zAngle)	Sets the quaternion from the specified Tait-Bryan angles, applying the rotations in x-z-y extrinsic order or y-z'-x" intrinsic order.
Quaternion	fromAxes(Vector3f[] axis)	Sets the quaternion from the specified orthonormal basis.
Quaternion	fromAxes(Vector3f xAxis, Vector3f yAxis, Vector3f zAxis)	Sets the quaternion from the specified orthonormal basis.
Quaternion	fromRotationMatrix(float m00, float m01, float m02, float m10, float m11, float m12, float m20, float m21, float m22)	Sets the quaternion from a rotation matrix with the specified elements.
Quaternion	fromRotationMatrix(Matrix3f matrix)	Sets the quaternion from the specified rotation matrix.
Vector3f	getRotationColumn(int i)	Calculates one of the basis vectors of the rotation.
Vector3f	getRotationColumn(int i, Vector3f store)	Calculates one of the basis vectors of the rotation.
float	getW()	Returns the W (real) component.
float	getX()	Returns the X component.
float	getY()	Returns the Y component.
float	getZ()	Returns the Z component.
int	hashCode()	Returns a hash code.
Quaternion	inverse()	Returns the multiplicative inverse.
Quaternion	inverseLocal()	Inverts the quaternion and returns the (modified) current instance.
boolean	isIdentity()	Compares with the identity quaternion, without distinguishing -0 from 0.
boolean	isSimilar(Quaternion other, float epsilon)	Tests for approximate equality with the specified quaternion, using the specified tolerance.
static boolean	isValidQuaternion(Quaternion quaternion)	Tests whether the argument is a valid quaternion, returning false if it's null or if any component is NaN or infinite.
void	loadIdentity()	Sets all components to zero except w, which is set to 1.
Quaternion	lookAt(Vector3f direction, Vector3f up)	Convenience method to set the quaternion based on a "look" (Z-axis) direction and an "up" (Y-axis) direction.
Quaternion	mult(float scalar)	Multiplies with the scalar argument and returns the product as a new instance.
Quaternion	mult(Quaternion q)	Multiplies by the argument and returns the product as a new instance.
Quaternion	mult(Quaternion q, Quaternion storeResult)	Multiplies by the specified quaternion and returns the product in a 3rd quaternion.
Vector3f	mult(Vector3f v)	Rotates the argument vector and returns the result as a new vector.
Vector3f	mult(Vector3f v, Vector3f store)	Rotates a specified vector and returns the result in another vector.
Quaternion	multLocal(float scalar)	Multiplies by the scalar argument and returns the (modified) current instance.
Quaternion	multLocal(float qx, float qy, float qz, float qw)	Multiplies by a quaternion with the specified components and returns the (modified) current instance.
Quaternion	multLocal(Quaternion q)	Multiplies by the argument and returns the (modified) current instance.
Vector3f	multLocal(Vector3f v)	Rotates the argument vector.
void	negate()	Deprecated. The naming of this method doesn't follow convention.
Quaternion	negateLocal()	Negates all 4 components and returns the (modified) current instance.
void	nlerp(Quaternion q2, float blend)	Interpolates quickly between the current instance and q2 using nlerp, and stores the result in the current instance.
float	norm()	Returns the norm, defined as the dot product of the quaternion with itself.
Quaternion	normalizeLocal()	Scales the quaternion to have norm=1 and returns the (modified) current instance.
Quaternion	opposite()
Quaternion	opposite(Quaternion store)	Returns a rotation with the same axis and the angle increased by 180 degrees.
Quaternion	oppositeLocal()	Changes the quaternion to a rotation with the same axis and the angle increased by 180 degrees.
void	read(JmeImporter importer)	De-serializes from the specified importer, for example when loading from a J3O file.
void	readExternal(ObjectInput in)	Sets the quaternion from an ObjectInput object.
Quaternion	set(float x, float y, float z, float w)	Sets all 4 components to specified values.
Quaternion	set(Quaternion q)	Copies all 4 components from the argument.
void	slerp(Quaternion q2, float changeAmount)	Interpolates between the current instance and q2 and stores the result in the current instance.
Quaternion	slerp(Quaternion q1, Quaternion q2, float t)	Interpolates between the specified quaternions and stores the result in the current instance.
Quaternion	subtract(Quaternion q)	Subtracts the argument and returns difference as a new instance.
Quaternion	subtractLocal(Quaternion q)	Subtracts the argument and returns the (modified) current instance.
float	toAngleAxis(Vector3f axisStore)	Converts the quaternion to a rotation angle and axis of rotation, storing the axis in the argument (if it's non-null) and returning the angle.
float[]	toAngles(float[] angles)	Converts to equivalent Tait-Bryan angles, to be applied in x-z-y intrinsic order or y-z'-x" extrinsic order, for instance by fromAngles(float[]).
void	toAxes(Vector3f[] axes)	Converts the quaternion to a rotated coordinate system and stores the resulting axes in the argument.
Matrix3f	toRotationMatrix()	Converts to an equivalent rotation matrix.
Matrix3f	toRotationMatrix(Matrix3f result)	Converts to an equivalent rotation matrix.
Matrix4f	toRotationMatrix(Matrix4f result)	Sets the rotation component of the specified transform matrix.
String	toString()	Returns a string representation of the quaternion, which is unaffected.
Matrix4f	toTransformMatrix(Matrix4f store)	Sets the rotation component of the specified transform matrix.
void	write(JmeExporter e)	Serializes to the specified exporter, for example when saving to a J3O file.
void	writeExternal(ObjectOutput out)	Writes the quaternion to an ObjectOutput object.

Methods inherited from class java.lang.Object

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

Field Details

IDENTITY

public static final Quaternion IDENTITY

Shared instance of the identity quaternion (0, 0, 0, 1). Do not modify!

This is the usual representation for a null rotation.

DIRECTION_Z

public static final Quaternion DIRECTION_Z

Another shared instance of the identity quaternion (0, 0, 0, 1). Do not modify!

ZERO

public static final Quaternion ZERO

Shared instance of the zero quaternion (0, 0, 0, 0). Do not modify!

The zero quaternion doesn't represent any valid rotation.

x

protected float x

The first imaginary (X) component. Not an angle!

y

protected float y

The 2nd imaginary (Y) component. Not an angle!

z

protected float z

The 3rd imaginary (Z) component. Not an angle!

w

protected float w

The real (W) component. Not an angle!

Constructor Details

Quaternion

public Quaternion()

Instantiates an identity quaternion: all components zeroed except w, which is set to 1.

Quaternion

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

Instantiates a quaternion with the specified components.

Parameters:

x - the desired X component

y - the desired Y component

z - the desired Z component

w - the desired W component

Quaternion

public Quaternion(float[] angles)

Instantiates a quaternion from Tait-Bryan angles, applying the rotations in x-z-y extrinsic order or y-z'-x" intrinsic order.

Parameters:

angles - an array of Tait-Bryan angles (in radians, exactly 3 elements, the X angle in angles[0], the Y angle in angles[1], and the Z angle in angles[2], not null, unaffected)

Quaternion

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

Instantiates a quaternion by interpolating between the specified quaternions.

Uses slerp(com.jme3.math.Quaternion, com.jme3.math.Quaternion, float), which is fast but inaccurate.

Parameters:

q1 - the desired value when interp=0 (not null, unaffected)

q2 - the desired value when interp=1 (not null, may be modified)

interp - the fractional change amount

Quaternion

public Quaternion(Quaternion q)

Instantiates a copy of the argument.

Parameters:

q - the quaternion to copy (not null, unaffected)

Method Details

getX

public float getX()

Returns the X component. The quaternion is unaffected.

Returns:

the value of the x component

getY

public float getY()

Returns the Y component. The quaternion is unaffected.

Returns:

the value of the y component

getZ

public float getZ()

Returns the Z component. The quaternion is unaffected.

Returns:

the value of the z component

getW

public float getW()

Returns the W (real) component. The quaternion is unaffected.

Returns:

the value of the w component

set

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

Sets all 4 components to specified values.

Parameters:

x - the desired X component

y - the desired Y component

z - the desired Z component

w - the desired W component

Returns:

the (modified) current instance (for chaining)

set

public Quaternion set(Quaternion q)

Copies all 4 components from the argument.

Parameters:

q - the quaternion to copy (not null, unaffected)

Returns:

the (modified) current instance (for chaining)

loadIdentity

public void loadIdentity()

Sets all components to zero except w, which is set to 1.

isIdentity

public boolean isIdentity()

Compares with the identity quaternion, without distinguishing -0 from 0. The current instance is unaffected.

Returns:

true if the current quaternion equals the identity, otherwise false

fromAngles

public Quaternion fromAngles(float[] angles)

Sets the quaternion from the specified Tait-Bryan angles, applying the rotations in x-z-y extrinsic order or y-z'-x" intrinsic order.

Parameters:

angles - an array of Tait-Bryan angles (in radians, exactly 3 elements, the X angle in angles[0], the Y angle in angles[1], and the Z angle in angles[2], not null, unaffected)

Returns:

the (modified) current instance (for chaining)

Throws:

IllegalArgumentException - if angles.length != 3

fromAngles

public Quaternion fromAngles(float xAngle,
 float yAngle,
 float zAngle)

Sets the quaternion from the specified Tait-Bryan angles, applying the rotations in x-z-y extrinsic order or y-z'-x" intrinsic order.

Parameters:

xAngle - the X angle (in radians)

yAngle - the Y angle (in radians)

zAngle - the Z angle (in radians)

Returns:

the (modified) current instance (for chaining)

See Also:

• http://www.euclideanspace.com/maths/geometry/rotations/conversions/eulerToQuaternion/index.htm

toAngles

public float[] toAngles(float[] angles)

Converts to equivalent Tait-Bryan angles, to be applied in x-z-y intrinsic order or y-z'-x" extrinsic order, for instance by fromAngles(float[]). The current instance is unaffected.

Parameters:

angles - storage for the result, or null for a new float[3]

Returns:

an array of 3 angles (in radians, either angles or a new float[3], the X angle in angles[0], the Y angle in angles[1], and the Z angle in angles[2])

Throws:

IllegalArgumentException - if angles.length != 3

See Also:

• http://www.euclideanspace.com/maths/geometry/rotations/conversions/quaternionToEuler/index.htm

fromRotationMatrix

public Quaternion fromRotationMatrix(Matrix3f matrix)

Sets the quaternion from the specified rotation matrix.

Does not verify that the argument is a valid rotation matrix. Positive scaling is compensated for, but not reflection or shear.

Parameters:

matrix - the input matrix (not null, unaffected)

Returns:

the (modified) current instance (for chaining)

fromRotationMatrix

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

Sets the quaternion from a rotation matrix with the specified elements.

Does not verify that the arguments form a valid rotation matrix. Positive scaling is compensated for, but not reflection or shear.

Parameters:

m00 - the matrix element in row 0, column 0

m01 - the matrix element in row 0, column 1

m02 - the matrix element in row 0, column 2

m10 - the matrix element in row 1, column 0

m11 - the matrix element in row 1, column 1

m12 - the matrix element in row 1, column 2

m20 - the matrix element in row 2, column 0

m21 - the matrix element in row 2, column 1

m22 - the matrix element in row 2, column 2

Returns:

the (modified) current instance (for chaining)

toRotationMatrix

public Matrix3f toRotationMatrix()

Converts to an equivalent rotation matrix. The current instance is unaffected.

Note: the result is created from a normalized version of the current instance.

Returns:

a new 3x3 rotation matrix

toRotationMatrix

public Matrix3f toRotationMatrix(Matrix3f result)

Converts to an equivalent rotation matrix. The current instance is unaffected.

Note: the result is created from a normalized version of the current instance.

Parameters:

result - storage for the result (not null)

Returns:

result, configured as a 3x3 rotation matrix

toTransformMatrix

public Matrix4f toTransformMatrix(Matrix4f store)

Sets the rotation component of the specified transform matrix. The current instance is unaffected.

Note: preserves the translation component of store but not its scaling component.

Note: the result is created from a normalized version of the current instance.

Parameters:

store - storage for the result (not null)

Returns:

store, with 9 of its 16 elements modified

toRotationMatrix

public Matrix4f toRotationMatrix(Matrix4f result)

Sets the rotation component of the specified transform matrix. The current instance is unaffected.

Note: preserves the translation and scaling components of result unless result includes reflection.

Note: the result is created from a normalized version of the current instance.

Parameters:

result - storage for the result (not null)

Returns:

result, with 9 of its 16 elements modified

getRotationColumn

public Vector3f getRotationColumn(int i)

Calculates one of the basis vectors of the rotation. The current instance is unaffected.

Note: the result is created from a normalized version of the current instance.

Parameters:

i - which basis vector to retrieve (≥0, <3, 0→X-axis, 1→Y-axis, 2→Z-axis)

Returns:

the basis vector (a new Vector3f)

getRotationColumn

public Vector3f getRotationColumn(int i,
 Vector3f store)

Calculates one of the basis vectors of the rotation. The current instance is unaffected.

Note: the result is created from a normalized version of the current instance.

Parameters:

i - which basis vector to retrieve (≥0, <3, 0→X-axis, 1→Y-axis, 2→Z-axis)

store - storage for the result, or null for a new Vector3f

Returns:

the basis vector (either store or a new Vector3f)

Throws:

IllegalArgumentException - if index is not 0, 1, or 2

fromAngleAxis

public Quaternion fromAngleAxis(float angle,
 Vector3f axis)

Sets the quaternion from the specified rotation angle and axis of rotation. This method creates garbage, so use fromAngleNormalAxis(float, com.jme3.math.Vector3f) if the axis is known to be normalized.

Parameters:

angle - the desired rotation angle (in radians)

axis - the desired axis of rotation (not null, unaffected)

Returns:

the (modified) current instance (for chaining)

fromAngleNormalAxis

public Quaternion fromAngleNormalAxis(float angle,
 Vector3f axis)

Sets the quaternion from the specified rotation angle and normalized axis of rotation. If the axis might not be normalized, use fromAngleAxis(float, com.jme3.math.Vector3f) instead.

Parameters:

angle - the desired rotation angle (in radians)

axis - the desired axis of rotation (not null, length=1, unaffected)

Returns:

the (modified) current instance (for chaining)

toAngleAxis

public float toAngleAxis(Vector3f axisStore)

Converts the quaternion to a rotation angle and axis of rotation, storing the axis in the argument (if it's non-null) and returning the angle.

If the quaternion has x*x + y*y + z*z == 0, then (1,0,0) is stored and 0 is returned. (This might happen if the rotation angle is very close to 0.)

Otherwise, the quaternion is assumed to be normalized (norm=1). No error checking is performed; the caller must ensure that the quaternion is normalized.

In all cases, the current instance is unaffected.

Parameters:

axisStore - storage for the axis (modified if not null)

Returns:

the rotation angle (in radians)

slerp

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

Interpolates between the specified quaternions and stores the result in the current instance.

Parameters:

q1 - the desired value when interp=0 (not null, unaffected)

q2 - the desired value when interp=1 (not null, may be modified)

t - the fractional change amount

Returns:

the (modified) current instance (for chaining)

slerp

public void slerp(Quaternion q2,
 float changeAmount)

Interpolates between the current instance and q2 and stores the result in the current instance.

This method is often more accurate than nlerp(com.jme3.math.Quaternion, float), but slower.

Parameters:

q2 - the desired value when changeAmnt=1 (not null, may be modified)

changeAmount - the fractional change amount

nlerp

public void nlerp(Quaternion q2,
 float blend)

Interpolates quickly between the current instance and q2 using nlerp, and stores the result in the current instance.

This method is often faster than slerp(com.jme3.math.Quaternion, float), but less accurate.

Parameters:

q2 - the desired value when blend=1 (not null, unaffected)

blend - the fractional change amount

add

public Quaternion add(Quaternion q)

Adds the argument and returns the sum as a new instance. The current instance is unaffected.

Seldom used. To combine rotations, use mult(com.jme3.math.Quaternion) instead of this method.

Parameters:

q - the quaternion to add (not null, unaffected)

Returns:

a new Quaternion

addLocal

public Quaternion addLocal(Quaternion q)

Adds the argument and returns the (modified) current instance.

Seldom used. To combine rotations, use multLocal(com.jme3.math.Quaternion) or mult(com.jme3.math.Quaternion, com.jme3.math.Quaternion) instead of this method.

Parameters:

q - the quaternion to add (not null, unaffected unless it's this)

Returns:

the (modified) current instance (for chaining)

subtract

public Quaternion subtract(Quaternion q)

Subtracts the argument and returns difference as a new instance. The current instance is unaffected.

Parameters:

q - the quaternion to subtract (not null, unaffected)

Returns:

a new Quaternion

subtractLocal

public Quaternion subtractLocal(Quaternion q)

Subtracts the argument and returns the (modified) current instance.

To quantify the similarity of 2 normalized quaternions, use dot(com.jme3.math.Quaternion).

Parameters:

q - the quaternion to subtract (not null, unaffected unless it's this)

Returns:

the (modified) current instance

mult

public Quaternion mult(Quaternion q)

Multiplies by the argument and returns the product as a new instance. The current instance is unaffected.

This method is used to combine rotations. Note that quaternion multiplication is noncommutative, so generally q * p != p * q.

Parameters:

q - the right factor (not null, unaffected)

Returns:

this * q (a new Quaternion)

mult

public Quaternion mult(Quaternion q,
 Quaternion storeResult)

Multiplies by the specified quaternion and returns the product in a 3rd quaternion. The current instance is unaffected, unless it's storeResult.

This method is used to combine rotations. Note that quaternion multiplication is noncommutative, so generally q * p != p * q.

It is safe for q and storeResult to be the same object. However, if this and storeResult are the same object, the result is undefined.

Parameters:

q - the right factor (not null, unaffected unless it's storeResult)

storeResult - storage for the product, or null for a new Quaternion

Returns:

this * q (either storeResult or a new Quaternion)

apply

public void apply(Matrix3f matrix)

Applies the rotation represented by the argument to the current instance.

Does not verify that matrix is a valid rotation matrix. Positive scaling is compensated for, but not reflection or shear.

Parameters:

matrix - the rotation matrix to apply (not null, unaffected)

fromAxes

public Quaternion fromAxes(Vector3f[] axis)

Sets the quaternion from the specified orthonormal basis.

The 3 basis vectors describe the axes of a rotated coordinate system. They are assumed to be normalized, mutually orthogonal, and in right-hand order. No error checking is performed; the caller must ensure that the specified vectors represent a right-handed coordinate system.

Parameters:

axis - the array of desired basis vectors (not null, array length=3, each vector having length=1, unaffected)

Returns:

the (modified) current instance (for chaining)

Throws:

IllegalArgumentException - if axis.length != 3

fromAxes

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

Sets the quaternion from the specified orthonormal basis.

The 3 basis vectors describe the axes of a rotated coordinate system. They are assumed to be normalized, mutually orthogonal, and in right-hand order. No error checking is performed; the caller must ensure that the specified vectors represent a right-handed coordinate system.

Parameters:

xAxis - the X axis of the desired coordinate system (not null, length=1, unaffected)

yAxis - the Y axis of the desired coordinate system (not null, length=1, unaffected)

zAxis - the Z axis of the desired coordinate system (not null, length=1, unaffected)

Returns:

the (modified) current instance (for chaining)

toAxes

public void toAxes(Vector3f[] axes)

Converts the quaternion to a rotated coordinate system and stores the resulting axes in the argument. The current instance is unaffected.

The resulting vectors form the basis of a rotated coordinate system. They will be normalized, mutually orthogonal, and in right-hand order.

Parameters:

axes - storage for the results (not null, length=3, each element non-null, elements modified)

Throws:

IllegalArgumentException - if axes.length != 3

mult

public Vector3f mult(Vector3f v)

Rotates the argument vector and returns the result as a new vector. The current instance is unaffected.

The quaternion is assumed to be normalized (norm=1). No error checking is performed; the caller must ensure that the norm is approximately equal to 1.

Despite the name, the result differs from the mathematical definition of vector-quaternion multiplication.

Parameters:

v - the vector to rotate (not null, unaffected)

Returns:

a new Vector3f

multLocal

public Vector3f multLocal(Vector3f v)

Rotates the argument vector. Despite the name, the current instance is unaffected.

The quaternion is assumed to be normalized (norm=1). No error checking is performed; the caller must ensure that the norm is approximately equal to 1.

Despite the name, the result differs from the mathematical definition of vector-quaternion multiplication.

Parameters:

v - the vector to rotate (not null)

Returns:

the (modified) vector v

multLocal

public Quaternion multLocal(Quaternion q)

Multiplies by the argument and returns the (modified) current instance.

This method is used to combine rotations. Note that quaternion multiplication is noncommutative, so generally q * p != p * q.

Parameters:

q - the right factor (not null, unaffected unless it's this)

Returns:

the (modified) current instance (for chaining)

multLocal

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

Multiplies by a quaternion with the specified components and returns the (modified) current instance.

This method is used to combine rotations. Note that quaternion multiplication is noncommutative, so generally q * p != p * q.

Parameters:

qx - the X component of the right factor

qy - the Y component of the right factor

qz - the Z component of the right factor

qw - the W component of the right factor

Returns:

the (modified) current instance (for chaining)

mult

public Vector3f mult(Vector3f v,
 Vector3f store)

Rotates a specified vector and returns the result in another vector. The current instance is unaffected.

The quaternion is assumed to be normalized (norm=1). No error checking is performed; the caller must ensure that the norm is approximately equal to 1.

It is safe for v and store to be the same object.

Despite the name, the result differs from the mathematical definition of vector-quaternion multiplication.

Parameters:

v - the vector to rotate (not null, unaffected unless it's store)

store - storage for the result, or null for a new Vector3f

Returns:

the rotated vector (either store or a new Vector3f)

mult

public Quaternion mult(float scalar)

Multiplies with the scalar argument and returns the product as a new instance. The current instance is unaffected.

Parameters:

scalar - the scaling factor

Returns:

a new Quaternion

multLocal

public Quaternion multLocal(float scalar)

Multiplies by the scalar argument and returns the (modified) current instance.

Parameters:

scalar - the scaling factor

Returns:

the (modified) current instance (for chaining)

dot

public float dot(Quaternion q)

Returns the dot product with the argument. The current instance is unaffected.

This method can be used to quantify the similarity of 2 normalized quaternions.

Parameters:

q - the quaternion to multiply (not null, unaffected)

Returns:

the dot product

norm

public float norm()

Returns the norm, defined as the dot product of the quaternion with itself. The current instance is unaffected.

Returns:

the sum of the squared components (not negative)

normalizeLocal

public Quaternion normalizeLocal()

Scales the quaternion to have norm=1 and returns the (modified) current instance. For a quaternion with norm=0, the result is undefined.

Returns:

the (modified) current instance (for chaining)

inverse

public Quaternion inverse()

Returns the multiplicative inverse. For a quaternion with norm=0, null is returned. Either way, the current instance is unaffected.

Returns:

a new Quaternion or null

inverseLocal

public Quaternion inverseLocal()

Inverts the quaternion and returns the (modified) current instance. For a quaternion with norm=0, the current instance is unchanged.

Returns:

the current instance (for chaining)

negate

@Deprecated
public void negate()

Deprecated.

The naming of this method doesn't follow convention. Please use negateLocal() instead.

Negates all 4 components.

negateLocal

public Quaternion negateLocal()

Negates all 4 components and returns the (modified) current instance.

Returns:

the (modified) current instance (for chaining)

toString

public String toString()

Returns a string representation of the quaternion, which is unaffected. For example, the identity quaternion is represented by:

 (0.0, 0.0, 0.0, 1.0)
 

Overrides:

toString in class Object

Returns:

the string representation (not null, not empty)

equals

public boolean equals(Object o)

Tests for exact equality with the argument, distinguishing -0 from 0. If o is null, false is returned. Either way, the current instance is unaffected.

Overrides:

equals in class Object

Parameters:

o - the object to compare (may be null, unaffected)

Returns:

true if this and o have identical values, otherwise false

isSimilar

public boolean isSimilar(Quaternion other,
 float epsilon)

Tests for approximate equality with the specified quaternion, using the specified tolerance. The current instance is unaffected.

To quantify the similarity of 2 normalized quaternions, use dot(com.jme3.math.Quaternion).

Parameters:

other - the quaternion to compare (not null, unaffected)

epsilon - the tolerance for each component

Returns:

true if all 4 components are within tolerance, otherwise false

hashCode

public int hashCode()

Returns a hash code. If two quaternions have identical values, they will have the same hash code. The current instance is unaffected.

Overrides:

hashCode in class Object

Returns:

a 32-bit value for use in hashing

See Also:

• Object.hashCode()

readExternal

public void readExternal(ObjectInput in)
                  throws IOException

Sets the quaternion from an ObjectInput object.

Used with serialization. Should not be invoked directly by application code.

Parameters:

in - the object to read from (not null)

Throws:

IOException - if the ObjectInput cannot read a float

See Also:

• Externalizable

writeExternal

public void writeExternal(ObjectOutput out)
                   throws IOException

Writes the quaternion to an ObjectOutput object.

Used with serialization. Should not be invoked directly by application code.

Parameters:

out - the object to write to (not null)

Throws:

IOException - if the ObjectOutput cannot write a float

See Also:

• Externalizable

lookAt

public Quaternion lookAt(Vector3f direction,
 Vector3f up)

Convenience method to set the quaternion based on a "look" (Z-axis) direction and an "up" (Y-axis) direction.

If either vector has length=0, the result is undefined.

If the vectors are parallel, the result is undefined.

Parameters:

direction - the desired Z-axis direction (in local coordinates, not null, length>0, unaffected)

up - the desired Y-axis direction (in local coordinates, not null, length>0, unaffected, typically (0,1,0) )

Returns:

the (modified) current instance (for chaining)

write

public void write(JmeExporter e)
           throws IOException

Serializes to the specified exporter, for example when saving to a J3O file. The current instance is unaffected.

Specified by:

write in interface Savable

Parameters:

e - the exporter to use (not null)

Throws:

IOException - from the exporter

read

public void read(JmeImporter importer)
          throws IOException

De-serializes from the specified importer, for example when loading from a J3O file.

Specified by:

read in interface Savable

Parameters:

importer - the importer to use (not null)

Throws:

IOException - from the importer

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)

Returns a rotation with the same axis and the angle increased by 180 degrees. If the quaternion isn't normalized, or if the rotation angle is very small, the result is undefined.

The current instance is unaffected, unless store is this.

Parameters:

store - storage for the result, or null for a new Quaternion

Returns:

either store or a new Quaternion

oppositeLocal

public Quaternion oppositeLocal()

Changes the quaternion to a rotation with the same axis and the angle increased by 180 degrees. If the quaternion isn't normalized, or if the rotation angle is very small, the result is undefined.

Returns:

the (modified) current instance

clone

public Quaternion clone()

Creates a copy. The current instance is unaffected.

Overrides:

clone in class Object

Returns:

a new instance, equivalent to the current one

isValidQuaternion

public static boolean isValidQuaternion(Quaternion quaternion)

Tests whether the argument is a valid quaternion, returning false if it's null or if any component is NaN or infinite.

Parameters:

quaternion - the quaternion to test (unaffected)

Returns:

true if non-null and finite, otherwise false