Package icyllis.arc3d.core

Class Quaternion

java.lang.Object

icyllis.arc3d.core.Quaternion

public class Quaternion
extends Object

Represents a Quaternion, mostly used for rotations.

Field Summary

Fields

Modifier and Type	Field	Description
protected float	w
protected float	x
protected float	y
protected float	z

Constructor Summary

Constructors

Constructor	Description
Quaternion()	Create a zero quaternion.
Quaternion(float x, float y, float z, float w)	Create a quaternion with given components.

Method Summary

Modifier and Type	Method	Description
void	add(Quaternion q)	Add a quaternion to this quaternion.
void	conjugate()	Conjugate this quaternion [-x, -y, -z, w].
Quaternion	copy()
static Quaternion	copy(Quaternion q)	Create a copy of q if it's not null, or an identity quaternion otherwise.
float	dot(float x, float y, float z, float w)	Returns the dot product of this quaternion with the given x, y, z and w components.
float	dot(Quaternion q)	Returns the dot product of this quaternion with the given quaternion.
boolean	equals(Object o)
int	hashCode()
static Quaternion	identity()	Create a new identity quaternion.
void	inverse()	Calculate the inverse of this quaternion.
boolean	isApproxEqual(Quaternion q)	Returns whether this quaternion is equivalent to given quaternion.
boolean	isIdentity()	Calculate whether this quaternion is equivalent to an identity quaternion.
boolean	isNormalized()	Returns whether this quaternion is normalized.
float	length()	Returns the magnitude of this quaternion, namely the 2-norm (euclidean norm) or the length.
float	lengthSq()
static Quaternion	makeAxisAngle(float axisX, float axisY, float axisZ, float angle)	Create a quaternion from the given axis and angle.
static Quaternion	makeAxisAngle(Vector3 axis, float angle)	Create a quaternion from the given axis and angle.
static Quaternion	makeEulerAngles(float rotationX, float rotationY, float rotationZ)	Create a quaternion from the given Euler rotation angles in radians.
void	multiply(float s)	Multiply this quaternion by a factor.
void	multiply(Quaternion q)	Multiply this quaternion by some other quaternion.
void	negate()	Negate this quaternion [-x, -y, -z, -w].
void	normalize()	Normalize this quaternion to unit length.
void	rotateByAxis(float axisX, float axisY, float axisZ, float angle)	Rotate this quaternion by the given axis and angle.
void	rotateByAxis(Vector3 axis, float angle)	Rotate this quaternion by the given axis and angle.
void	rotateByEuler(float rotationX, float rotationY, float rotationZ)	Rotates this quaternion from the given Euler rotation angles in radians.
void	rotateX(float angle)	Rotate this quaternion around X axis with the given angle in radians.
void	rotateY(float angle)	Rotate this quaternion around Y axis with the given angle in radians.
void	rotateZ(float angle)	Rotate this quaternion around Z axis with the given angle in radians.
void	set(float x, float y, float z, float w)	Set all values of this quaternion using the given components.
void	set(Quaternion q)	Set all values of this quaternion using the given quaternion.
void	setFromAxisAngle(float axisX, float axisY, float axisZ, float angle)	Set this quaternion components from the given axis and angle.
void	setFromAxisAngle(Vector3 axis, float angle)	Set this quaternion components from the given axis and angle.
void	setFromEulerAngles(float rotationX, float rotationY, float rotationZ)	Set this quaternion components from the given Euler rotation angles in radians.
void	setIdentity()	Set this quaternion to the identity quaternion [0, 0, 0, 1].
void	setZero()	Set this quaternion to the zero quaternion.
void	slerp(Quaternion a, float t)	Set this quaternion to a spherical linear interpolation between this and given quaternion by a factor.
void	slerp(Quaternion a, Quaternion b, float t)	Set this quaternion to a spherical linear interpolation between two quaternions by the given factor.
void	subtract(Quaternion q)	Subtract a quaternion from this quaternion.
float	toAxisAngle(float[] axis)	Transform the rotational quaternion to axis based rotation angles.
float	toAxisAngle(Vector3 axis)	Transform the rotational quaternion to axis based rotation angles.
void	toEulerAngles(float[] angles)	Transform this quaternion to Euler rotation angles in radians (pitchX, yawY and rollZ).
void	toEulerAngles(Vector3 result)	Transform this quaternion to Euler rotation angles in radians (pitchX, yawY and rollZ).
Matrix3	toMatrix3()	Transform this quaternion to a normalized 3x3 row-major matrix representing the rotation.
Matrix3	toMatrix3(Matrix3 out)	Transform this quaternion to a normalized 3x3 row-major matrix representing the rotation.
Matrix4	toMatrix4()	Transform this quaternion to a normalized 4x4 row-major matrix representing the rotation.
Matrix4	toMatrix4(Matrix4 out)	Transform this quaternion to a normalized 4x4 row-major matrix representing the rotation.
String	toString()

Methods inherited from class java.lang.Object

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

Field Details

x

protected float x

y

protected float y

z

protected float z

w

protected float w

Constructor Details

Quaternion

public Quaternion()

Create a zero quaternion.

Quaternion

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

Create a quaternion with given components.

Parameters:

x - the x-component of the quaternion

y - the y-component of the quaternion

z - the z-component of the quaternion

w - the w-component of the quaternion

Method Details

copy

@Nonnull
public static Quaternion copy(@Nullable
 Quaternion q)

Create a copy of q if it's not null, or an identity quaternion otherwise.

Parameters:

q - the quaternion to copy from

Returns:

a copy of the quaternion

identity

@Nonnull
public static Quaternion identity()

Create a new identity quaternion.

Returns:

an identity quaternion

makeEulerAngles

@Nonnull
public static Quaternion makeEulerAngles(float rotationX,
 float rotationY,
 float rotationZ)

Create a quaternion from the given Euler rotation angles in radians. The returned quaternion will be a normalized rotational quaternion.

Parameters:

rotationX - the Euler pitch angle in radians. (rotation about the X axis)

rotationY - the Euler yaw angle in radians. (rotation about the Y axis)

rotationZ - the Euler roll angle in radians. (rotation about the Z axis)

Returns:

the resulting quaternion

makeAxisAngle

@Nonnull
public static Quaternion makeAxisAngle(@Nonnull
 Vector3 axis,
 float angle)

Create a quaternion from the given axis and angle. The axis must be a normalized (unit) vector.

Parameters:

axis - the rotation axis

angle - rotation angle in radians

Returns:

the resulting quaternion

makeAxisAngle

@Nonnull
public static Quaternion makeAxisAngle(float axisX,
 float axisY,
 float axisZ,
 float angle)

Create a quaternion from the given axis and angle. The axis must be a normalized (unit) vector.

Parameters:

axisX - x-coordinate of rotation axis

axisY - y-coordinate of rotation axis

axisZ - z-coordinate of rotation axis

angle - rotation angle in radians

Returns:

the resulting quaternion

set

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

Set all values of this quaternion using the given components.

Parameters:

x - the x-component to set

y - the y-component to set

z - the z-component to set

w - the w-component to set

set

public void set(@Nonnull
 Quaternion q)

Set all values of this quaternion using the given quaternion.

Parameters:

q - the quaternion to copy from

add

public void add(@Nonnull
 Quaternion q)

Add a quaternion to this quaternion.

Parameters:

q - the quaternion to add

subtract

public void subtract(@Nonnull
 Quaternion q)

Subtract a quaternion from this quaternion.

Parameters:

q - the quaternion to subtract

multiply

public void multiply(float s)

Multiply this quaternion by a factor.

Parameters:

s - the factor to multiply.

multiply

public void multiply(@Nonnull
 Quaternion q)

Multiply this quaternion by some other quaternion.

Parameters:

q - the quaternion to multiply with

length

public float length()

Returns the magnitude of this quaternion, namely the 2-norm (euclidean norm) or the length.

Returns:

the magnitude of this quaternion

lengthSq

public float lengthSq()

dot

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

Returns the dot product of this quaternion with the given x, y, z and w components.

dot

public float dot(@Nonnull
 Quaternion q)

Returns the dot product of this quaternion with the given quaternion.

Parameters:

q - the quaternion to dot product with.

inverse

public void inverse()

Calculate the inverse of this quaternion. If rotational, it will produce the inverse rotation.

isNormalized

public boolean isNormalized()

Returns whether this quaternion is normalized.

Returns:

true if is normalized, false otherwise

normalize

public void normalize()

Normalize this quaternion to unit length.

setZero

public void setZero()

Set this quaternion to the zero quaternion.

isIdentity

public boolean isIdentity()

Calculate whether this quaternion is equivalent to an identity quaternion.

Returns:

true if this quaternion is identity.

setIdentity

public void setIdentity()

Set this quaternion to the identity quaternion [0, 0, 0, 1].

conjugate

public void conjugate()

Conjugate this quaternion [-x, -y, -z, w].

negate

public void negate()

Negate this quaternion [-x, -y, -z, -w].

slerp

public void slerp(@Nonnull
 Quaternion a,
 float t)

Set this quaternion to a spherical linear interpolation between this and given quaternion by a factor. The two quaternions should be rotational so they should be normalized. This method does not normalize this quaternion.

Parameters:

a - the end quaternion

t - a value between 0.0 and 1.0 representing interpolation

slerp

public void slerp(@Nonnull
 Quaternion a,
 @Nonnull
 Quaternion b,
 float t)

Set this quaternion to a spherical linear interpolation between two quaternions by the given factor. The two quaternions should be rotational so they should be normalized. This method does not normalize this quaternion.

Parameters:

a - the start quaternion

b - the end quaternion

t - a value between 0.0 and 1.0 representing interpolation

rotateByAxis

public void rotateByAxis(@Nonnull
 Vector3 axis,
 float angle)

Rotate this quaternion by the given axis and angle. The axis must be a normalized (unit) vector.

Parameters:

axis - the rotation axis

angle - rotation angle in radians

rotateByAxis

public void rotateByAxis(float axisX,
 float axisY,
 float axisZ,
 float angle)

Rotate this quaternion by the given axis and angle. The axis must be a normalized (unit) vector.

Parameters:

axisX - x-coordinate of rotation axis

axisY - y-coordinate of rotation axis

axisZ - z-coordinate of rotation axis

angle - rotation angle in radians

rotateX

public void rotateX(float angle)

Rotate this quaternion around X axis with the given angle in radians.

Parameters:

angle - rotation angle in radians

rotateY

public void rotateY(float angle)

Rotate this quaternion around Y axis with the given angle in radians.

Parameters:

angle - rotation angle in radians

rotateZ

public void rotateZ(float angle)

Rotate this quaternion around Z axis with the given angle in radians.

Parameters:

angle - rotation angle in radians

rotateByEuler

public void rotateByEuler(float rotationX,
 float rotationY,
 float rotationZ)

Rotates this quaternion from the given Euler rotation angles in radians.

The rotations are applied in the given order and using chained rotation per axis:

• x - pitch - rotateX(float)
• y - yaw - rotateY(float)
• z - roll - rotateZ(float)

Parameters:

rotationX - the Euler pitch angle in radians. (rotation about the X axis)

rotationY - the Euler yaw angle in radians. (rotation about the Y axis)

rotationZ - the Euler roll angle in radians. (rotation about the Z axis)

See Also:

• rotateY(float)
• rotateZ(float)
• rotateX(float)

setFromAxisAngle

public void setFromAxisAngle(@Nonnull
 Vector3 axis,
 float angle)

Set this quaternion components from the given axis and angle. The axis must be a normalized (unit) vector.

Parameters:

axis - the rotation axis

angle - rotation angle in radians

setFromAxisAngle

public void setFromAxisAngle(float axisX,
 float axisY,
 float axisZ,
 float angle)

Set this quaternion components from the given axis and angle. The axis must be a normalized (unit) vector.

Parameters:

axisX - x-coordinate of rotation axis

axisY - y-coordinate of rotation axis

axisZ - z-coordinate of rotation axis

angle - rotation angle in radians

setFromEulerAngles

public void setFromEulerAngles(float rotationX,
 float rotationY,
 float rotationZ)

Set this quaternion components from the given Euler rotation angles in radians.

Parameters:

rotationX - the Euler pitch angle in radians. (rotation about the X axis)

rotationY - the Euler yaw angle in radians. (rotation about the Y axis)

rotationZ - the Euler roll angle in radians. (rotation about the Z axis)

toAxisAngle

public float toAxisAngle(@Nonnull
 Vector3 axis)

Transform the rotational quaternion to axis based rotation angles.

Parameters:

axis - the vector for storing the axis coordinates.

Returns:

the rotation angle in radians.

toAxisAngle

public float toAxisAngle(@Nonnull
 float[] axis)

Transform the rotational quaternion to axis based rotation angles.

Parameters:

axis - the array for storing the axis coordinates.

Returns:

the rotation angle in radians.

toEulerAngles

public void toEulerAngles(@Nonnull
 Vector3 result)

Transform this quaternion to Euler rotation angles in radians (pitchX, yawY and rollZ).

Parameters:

result - the vector for storing the result.

toEulerAngles

public void toEulerAngles(@Nonnull
 float[] angles)

Transform this quaternion to Euler rotation angles in radians (pitchX, yawY and rollZ).

Parameters:

angles - the array for storing the result.

toMatrix3

@Nonnull
public Matrix3 toMatrix3()

Transform this quaternion to a normalized 3x3 row-major matrix representing the rotation.

Returns:

the resulting matrix

toMatrix4

@Nonnull
public Matrix4 toMatrix4()

Transform this quaternion to a normalized 4x4 row-major matrix representing the rotation.

Returns:

the resulting matrix

toMatrix3

@Nonnull
public Matrix3 toMatrix3(@Nullable
 Matrix3 out)

Transform this quaternion to a normalized 3x3 row-major matrix representing the rotation. If recycle matrix is null, a new matrix will be returned.

Parameters:

out - a matrix for storing the result

Returns:

the resulting matrix

toMatrix4

@Nonnull
public Matrix4 toMatrix4(@Nullable
 Matrix4 out)

Transform this quaternion to a normalized 4x4 row-major matrix representing the rotation. If recycle matrix is null, a new matrix will be returned.

Parameters:

out - a matrix for storing the result

Returns:

the resulting matrix

isApproxEqual

public boolean isApproxEqual(@Nonnull
 Quaternion q)

Returns whether this quaternion is equivalent to given quaternion.

Parameters:

q - the quaternion to compare.

Returns:

true if this quaternion is equivalent to other one.

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object

copy

@Nonnull
public Quaternion copy()