com.io7m.jtensors.core.quaternions

Class Quaternions4D

java.lang.Object

com.io7m.jtensors.core.quaternions.Quaternions4D

public final class Quaternions4D
extends Object

Functions over Quaternion4D values.

See "Mathematics for 3D Game Programming and Computer Graphics" 2nd Ed for the derivations of most of the code in this class (ISBN: 1-58450-277-0).

Since:

8.0.0

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	Quaternions4D.ComponentComparatorType The type of comparison functions for values of type Quaternion4D.

Method Summary

Modifier and Type	Method and Description
static Quaternion4D	add(Quaternion4D q0, Quaternion4D q1) Add q0 to q1.
static Quaternion4D	conjugate(Quaternion4D q) Calculate the conjugate of the input quaternion q.
static double	dotProduct(Quaternion4D q0, Quaternion4D q1) Calculate the scalar product of the quaternions q0 and q1.
static Quaternion4D	identity() The identity quaternion.
static Quaternion4D	interpolateLinear(Quaternion4D q0, Quaternion4D q1, double alpha) Linearly interpolate between q0 and q1 by the amount alpha, such that:
static Quaternion4D	interpolateSphericalLinear(Quaternion4D q0, Quaternion4D q1, double alpha) Interpolate between q0 and q1, using spherical linear interpolation, by the amount alpha, such that:
static boolean	isNegationOf(Quaternions4D.ComponentComparatorType c, Quaternion4D qa, Quaternion4D qb) Return true iff qa is the negation of qb.
static double	magnitude(Quaternion4D q0) Calculate the magnitude of the quaternion q0.
static double	magnitudeSquared(Quaternion4D q0) Calculate the squared magnitude of the quaternion q0.
static Quaternion4D	multiply(Quaternion4D q0, Quaternion4D q1) Multiply the quaternion q0 by the quaternion q1.
static Quaternion4D	negate(Quaternion4D q) Calculate the negation of the input quaternion q.
static Quaternion4D	normalize(Quaternion4D q0) Normalize the quaternion q0.
static Quaternion4D	ofAxisAngle(double axis_x, double axis_y, double axis_z, double r) Calculate a quaternion that represents a rotation of r radians around the axis (axis_x, axis_y, axis_z).
static Quaternion4D	ofMatrix4x4(Matrix4x4D m) Calculate a quaternion that represents the rotation given by the matrix m.
static <A,B> Quaternion4D	ofPMatrix4x4(PMatrix4x4D<A,B> m) Calculate a quaternion that represents the rotation given by the matrix m.
static Quaternion4D	scale(Quaternion4D q0, double r) Scale q0 by r.
static Quaternion4D	subtract(Quaternion4D q0, Quaternion4D q1) Add q0 to q1.
static Matrix4x4D	toMatrix4x4(Quaternion4D q) Create a 4x4 matrix from the quaternion q.
static <A,B> PMatrix4x4D<A,B>	toPMatrix4x4(Quaternion4D q) Create a 4x4 matrix from the quaternion q.
static Quaternion4D	zero() The zero quaternion.

Methods inherited from class java.lang.Object

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

Method Detail

add

public static Quaternion4D add(Quaternion4D q0,
                               Quaternion4D q1)

Add q0 to q1.

Parameters:

q0 - The left quaternion

q1 - The right quaternion

Returns:

(q0.x + q1.x, q0.y + q0.y, q0.z + q1.z, q0.w + q1.w)

conjugate

public static Quaternion4D conjugate(Quaternion4D q)

Calculate the conjugate of the input quaternion q.

Parameters:

q - The input quaternion

Returns:

The conjugate of the input quaternion

dotProduct

public static double dotProduct(Quaternion4D q0,
                                Quaternion4D q1)

Calculate the scalar product of the quaternions q0 and q1.

Parameters:

q0 - The left input quaternion

q1 - The right input quaternion

Returns:

The scalar product of the two quaternions

identity

public static Quaternion4D identity()

The identity quaternion.

Returns:

(0, 0, 0, 1)

interpolateLinear

public static Quaternion4D interpolateLinear(Quaternion4D q0,
                                             Quaternion4D q1,
                                             double alpha)

Linearly interpolate between q0 and q1 by the amount alpha, such that:

• interpolateLinear(q0, q1, 0.0) = q0
• interpolateLinear(q0, q1, 1.0) = q1

Parameters:

q0 - The left input quaternion

q1 - The right input quaternion

alpha - The interpolation value, between 0.0 and 1.0

Returns:

(1 - alpha) * q0 + alpha * q1

interpolateSphericalLinear

public static Quaternion4D interpolateSphericalLinear(Quaternion4D q0,
                                                      Quaternion4D q1,
                                                      double alpha)

Interpolate between q0 and q1, using spherical linear interpolation, by the amount alpha, such that:

• interpolateSphericalLinear(q0, q1, 0.0) = normalize(q0)
• interpolateSphericalLinear(q0, q1, 1.0) = normalize(q1)

Note that unlike simple linear interpolation, this function is guaranteed to return a normalized quaternion.

Parameters:

q0 - The left input quaternion

q1 - The right input quaternion

alpha - The interpolation value, between 0.0 and 1.0

Returns:

A spherical-linearly interpolated quaternion between q0 and q1

isNegationOf

public static boolean isNegationOf(Quaternions4D.ComponentComparatorType c,
                                   Quaternion4D qa,
                                   Quaternion4D qb)

Return true iff qa is the negation of qb.

Parameters:

qa - The left quaternion

qb - The right quaternion

Returns:

true iff qa is the negation of qb

magnitudeSquared

public static double magnitudeSquared(Quaternion4D q0)

Calculate the squared magnitude of the quaternion q0.

Parameters:

q0 - The quaternion

Returns:

The squared magnitude of the quaternion

magnitude

public static double magnitude(Quaternion4D q0)

Calculate the magnitude of the quaternion q0.

Parameters:

q0 - The quaternion

Returns:

The magnitude of the quaternion

multiply

public static Quaternion4D multiply(Quaternion4D q0,
                                    Quaternion4D q1)

Multiply the quaternion q0 by the quaternion q1.

Note that this operation is not commutative.

The function is most often used to concatenate quaternions to combine rotations. As an example, assuming that:

• qx represents some rotation around the X axis
• qy represents some rotation around the Y axis
• qz represents some rotation around the Z axis

The following code produces a quaternion qr1 that represents a rotation around the X axis, followed by a rotation around the Y axis, followed by a rotation around the Z axis:

qr0 = multiply(qy, qx); qr1 = multiply(qz, qy);

Parameters:

q0 - The left input quaternion

q1 - The right input quaternion

Returns:

The multiplication of the input quaternions

normalize

public static Quaternion4D normalize(Quaternion4D q0)

Normalize the quaternion q0.

If the magnitude of the quaternion is zero, the function returns q0.

Parameters:

q0 - The quaternion

Returns:

A normalized copy of q0

negate

public static Quaternion4D negate(Quaternion4D q)

Calculate the negation of the input quaternion q.

Parameters:

q - The input quaternion

Returns:

The negation of the input quaternion

ofAxisAngle

public static Quaternion4D ofAxisAngle(double axis_x,
                                       double axis_y,
                                       double axis_z,
                                       double r)

Calculate a quaternion that represents a rotation of r radians around the axis (axis_x, axis_y, axis_z).

Parameters:

r - The rotation in radians

axis_x - The X component of the axis

axis_y - The Y component of the axis

axis_z - The Z component of the axis

Returns:

A quaternion

ofMatrix4x4

public static Quaternion4D ofMatrix4x4(Matrix4x4D m)

Calculate a quaternion that represents the rotation given by the matrix m.

Parameters:

m - The matrix

Returns:

A quaternion

ofPMatrix4x4

public static <A,B> Quaternion4D ofPMatrix4x4(PMatrix4x4D<A,B> m)

Calculate a quaternion that represents the rotation given by the matrix m.

Type Parameters:

A - A phantom type parameter, possibly representing a source coordinate system

B - A phantom type parameter, possibly representing a target coordinate system

Parameters:

m - The matrix

Returns:

A quaternion

scale

public static Quaternion4D scale(Quaternion4D q0,
                                 double r)

Scale q0 by r.

Parameters:

q0 - The left quaternion

r - The scaling value

Returns:

(q0.x * r, q0.y * r, q0.z * r, q0.w * r)

subtract

public static Quaternion4D subtract(Quaternion4D q0,
                                    Quaternion4D q1)

Add q0 to q1.

Parameters:

q0 - The left quaternion

q1 - The right quaternion

Returns:

(q0.x - q1.x, q0.y - q0.y, q0.z - q1.z, q0.w - q1.w)

toMatrix4x4

public static Matrix4x4D toMatrix4x4(Quaternion4D q)

Create a 4x4 matrix from the quaternion q.

Parameters:

q - The quaternion

Returns:

A matrix based on q

toPMatrix4x4

public static <A,B> PMatrix4x4D<A,B> toPMatrix4x4(Quaternion4D q)

Create a 4x4 matrix from the quaternion q.

Type Parameters:

A - A phantom type parameter, possibly representing a source coordinate system

B - A phantom type parameter, possibly representing a target coordinate system

Parameters:

q - The quaternion

Returns:

A matrix based on q

zero

public static Quaternion4D zero()

The zero quaternion.

Returns:

(0, 0, 0, 0)