jme3utilities.math

Class MyQuaternion

java.lang.Object

jme3utilities.math.MyQuaternion

public final class MyQuaternion
extends java.lang.Object

Mathematical utility methods.

Field Summary

Fields

Modifier and Type	Field and Description
static java.util.logging.Logger	logger message logger for this class

Method Summary

Modifier and Type	Method and Description
static void	accumulateScaled(Quaternion total, Quaternion input, float scale) Accumulate a linear combination of quaternions.
static void	cardinalizeLocal(Quaternion input) Find the cardinal rotation most similar to the specified Quaternion.
static Quaternion	conjugate(Quaternion q, Quaternion storeResult) Return the conjugate of a Quaternion.
static java.lang.String	describe(Quaternion q) Generate a textual description of a Quaternion value.
static double	dot(Quaternion q1, Quaternion q2) Return the dot (scalar) product of 2 quaternions.
static Quaternion	exp(Quaternion q, Quaternion storeResult) Return the exponential of a pure Quaternion.
static boolean	isPure(Quaternion q) Test for a pure Quaternion.
static boolean	isRotationIdentity(Quaternion q) Test whether the specified Quaternion represents an identity rotation.
static boolean	isZero(Quaternion q) Test for a zero Quaternion.
static double	lengthSquared(Quaternion q) Return the squared length of the argument.
static Quaternion	log(Quaternion q, Quaternion storeResult) Return the natural logarithm of a normalized quaternion.
static boolean	ne(Quaternion a, Quaternion b) Test whether 2 quaternions are distinct, without distinguishing 0 from -0.
static void	normalizeLocal(Quaternion input) Normalize the specified Quaternion in place.
static Quaternion	pow(Quaternion base, float exponent, Quaternion storeResult) Raise a normalized quaternion to the specified real power.
static Vector3f	rotate(Quaternion rotation, Vector3f input, Vector3f storeResult) Rotate the input vector using the specified quaternion.
static Vector3f	rotateInverse(Quaternion rotation, Vector3f input, Vector3f storeResult) Rotate the input vector using the inverse of the specified quaternion.
static Quaternion	slerp(float t, Quaternion q0, Quaternion q1, Quaternion storeResult) Interpolate between 2 normalized quaternions using spherical linear (Slerp) interpolation.
static Quaternion	squad(float t, Quaternion p, Quaternion a, Quaternion b, Quaternion q, Quaternion storeResult) Interpolate between 4 normalized quaternions using the Squad function.
static Quaternion	squadA(Quaternion q0, Quaternion q1, Quaternion q2, Quaternion storeResult) Return Squad parameter "a" for a continuous first derivative at the middle point of 3 specified control points.
static Quaternion	standardize(Quaternion input, Quaternion storeResult) Standardize a Quaternion in preparation for hashing.
static boolean	validateUnit(Quaternion q, java.lang.String description, float tolerance) Validate a normalized quaternion as a method argument.

Methods inherited from class java.lang.Object

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

Field Detail

logger

public static final java.util.logging.Logger logger

message logger for this class

Method Detail

accumulateScaled

public static void accumulateScaled(Quaternion total,
                                    Quaternion input,
                                    float scale)

Accumulate a linear combination of quaternions.

Parameters:

total - sum of the scaled inputs so far (not null, modified, may be input)

input - the Quaternion to scale and add (not null, unaffected unless it's total)

scale - scale factor to apply to the input

cardinalizeLocal

public static void cardinalizeLocal(Quaternion input)

Find the cardinal rotation most similar to the specified Quaternion. A cardinal rotation is one for which the rotation angles on all 3 axes are integer multiples of Pi/2 radians.

Parameters:

input - the input value (not null, modified)

conjugate

public static Quaternion conjugate(Quaternion q,
                                   Quaternion storeResult)

Return the conjugate of a Quaternion.

For normalized quaternions, the conjugate is a fast way to calculate the inverse.

Parameters:

q - the input value (not null, unaffected unless it's storeResult)

storeResult - storage for the result (modified if not null, may be q)

Returns:

a conjugate quaternion (either storeResult or a new instance)

describe

public static java.lang.String describe(Quaternion q)

Generate a textual description of a Quaternion value.

Parameters:

q - the value to describe (may be null, unaffected)

Returns:

a description (not null, not empty)

dot

public static double dot(Quaternion q1,
                         Quaternion q2)

Return the dot (scalar) product of 2 quaternions.

This method returns a double-precision value for precise comparison of angles.

Parameters:

q1 - the first input value (not null, unaffected)

q2 - the 2nd input value (not null, unaffected)

Returns:

the dot product

exp

public static Quaternion exp(Quaternion q,
                             Quaternion storeResult)

Return the exponential of a pure Quaternion.

Parameters:

q - the input value (not null, w=0, unaffected)

storeResult - storage for the result (modified if not null)

Returns:

the exponential value (either storeResult or a new instance)

isPure

public static boolean isPure(Quaternion q)

Test for a pure Quaternion.

Parameters:

q - the value to test (not null, unaffected)

Returns:

true if w=0, false otherwise

isRotationIdentity

public static boolean isRotationIdentity(Quaternion q)

Test whether the specified Quaternion represents an identity rotation.

Accepts any finite, non-zero value for w.

Parameters:

q - the value to test (not null, unaffected)

Returns:

true for a rotation identity, otherwise false

isZero

public static boolean isZero(Quaternion q)

Test for a zero Quaternion.

Parameters:

q - the value to test (not null, unaffected)

Returns:

true if the argument equals (0,0,0,0), false otherwise

lengthSquared

public static double lengthSquared(Quaternion q)

Return the squared length of the argument.

Unlike Quaternion.norm(), this method returns a double-precision value for precise comparison of lengths.

Parameters:

q - the input value (not null, unaffected)

Returns:

the squared length (≥0)

log

public static Quaternion log(Quaternion q,
                             Quaternion storeResult)

Return the natural logarithm of a normalized quaternion.

In general, the result isn't itself normalized.

Parameters:

q - the input value (not null, norm approximately equal to 1, unaffected unless it's storeResult)

storeResult - storage for the result (modified if not null, may be q)

Returns:

a pure quaternion (either storeResult or a new instance)

ne

public static boolean ne(Quaternion a,
                         Quaternion b)

Test whether 2 quaternions are distinct, without distinguishing 0 from -0.

Parameters:

a - the first input value (not null, unaffected)

b - the 2nd input value (not null, unaffected)

Returns:

true if distinct, otherwise false

normalizeLocal

public static void normalizeLocal(Quaternion input)

Normalize the specified Quaternion in place.

Parameters:

input - the instance to normalize (not null, modified)

pow

public static Quaternion pow(Quaternion base,
                             float exponent,
                             Quaternion storeResult)

Raise a normalized quaternion to the specified real power.

Parameters:

base - the input value (not null, norm approximately equal to 1, unaffected unless it's storeResult)

exponent - the exponent

storeResult - storage for the result (modified if not null, may be base)

Returns:

the power (either storeResult or a new instance)

rotate

public static Vector3f rotate(Quaternion rotation,
                              Vector3f input,
                              Vector3f storeResult)

Rotate the input vector using the specified quaternion.

This method doesn't assume the quaternion is normalized. Instead, rotation is performed using a normalized version of the quaternion.

Parameters:

rotation - the desired rotation (not null, not zero, unaffected)

input - the vector to rotate (not null, finite, unaffected unless it's storeResult)

storeResult - storage for the result (modified if not null, may be input)

Returns:

the rotated vector (either storeResult or a new instance)

rotateInverse

public static Vector3f rotateInverse(Quaternion rotation,
                                     Vector3f input,
                                     Vector3f storeResult)

Rotate the input vector using the inverse of the specified quaternion.

Parameters:

rotation - the rotation (not null, not zero, unaffected)

input - the vector to rotate (not null, finite, unaffected unless it's storeResult)

storeResult - storage for the result (modified if not null, may be input)

Returns:

the rotated vector (either storeResult or a new instance)

slerp

public static Quaternion slerp(float t,
                               Quaternion q0,
                               Quaternion q1,
                               Quaternion storeResult)

Interpolate between 2 normalized quaternions using spherical linear (Slerp) interpolation.

The caller is responsible for flipping the sign of q0 or q1 when it's appropriate to do so.

Parameters:

t - the weight given to q1 (≥0, ≤1)

q0 - the function value at t=0 (not null, norm approximately equal to 1, unaffected unless it's storeResult)

q1 - the function value at t=1 (not null, norm approximately equal to 1, unaffected unless it's storeResult)

storeResult - storage for the result (modified if not null, may be q0 or q1)

Returns:

an interpolated value (either storeResult or a new instance)

squad

public static Quaternion squad(float t,
                               Quaternion p,
                               Quaternion a,
                               Quaternion b,
                               Quaternion q,
                               Quaternion storeResult)

Interpolate between 4 normalized quaternions using the Squad function. The caller is responsible for flipping signs when it's appropriate to do so.

Parameters:

t - the weight given to q (≥0, ≤1)

p - function value at t=0 (not null, norm approximately equal to 1, unaffected unless it's storeResult)

a - the first control point (not null, norm approximately equal to 1, unaffected unless it's storeResult)

b - the 2nd control point (not null, norm approximately equal to 1, unaffected unless it's storeResult)

q - function value at t=1 (not null, norm approximately equal to 1, unaffected unless it's storeResult)

storeResult - storage for the result (modified if not null)

Returns:

the interpolated value (either storeResult or a new instance)

squadA

public static Quaternion squadA(Quaternion q0,
                                Quaternion q1,
                                Quaternion q2,
                                Quaternion storeResult)

Return Squad parameter "a" for a continuous first derivative at the middle point of 3 specified control points.

Parameters:

q0 - the previous control point (not null, norm approximately equal to 1, unaffected unless it's storeResult)

q1 - the current control point (not null, norm approximately equal to 1, unaffected unless it's storeResult)

q2 - the following control point (not null, norm approximately equal to 1, unaffected unless it's storeResult)

storeResult - storage for the result (modified if not null)

Returns:

the Squad parameter (either storeResult or a new instance)

standardize

public static Quaternion standardize(Quaternion input,
                                     Quaternion storeResult)

Standardize a Quaternion in preparation for hashing.

Parameters:

input - the input value (not null, unaffected unless it's storeResult)

storeResult - storage for the result (modified if not null, may be input)

Returns:

an equivalent Quaternion without negative zeros (either storeResult or a new instance)

validateUnit

public static boolean validateUnit(Quaternion q,
                                   java.lang.String description,
                                   float tolerance)

Validate a normalized quaternion as a method argument.

Parameters:

q - the Quaternion to validate (not null, unaffected)

description - description of the Quaternion

tolerance - for the norm (≥0)

Returns:

true

Throws:

java.lang.IllegalArgumentException - if the norm is out of tolerance

java.lang.NullPointerException - if the Quaternion is null