Package arc.math.geom

Class Quat

java.lang.Object

arc.math.geom.Quat

public class Quat
extends Object

A simple quaternion class.

See Also:

• http://en.wikipedia.org/wiki/Quaternion

Field Summary

Fields

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

Constructor Summary

Constructors

Constructor	Description
Quat()
Quat(float x, float y, float z, float w)	Constructor, sets the four components of the quaternion.
Quat(Quat quat)	Constructor, sets the quaternion components from the given quaternion.
Quat(Vec3 axis, float angle)	Constructor, sets the quaternion from the given axis vector and the angle around that axis in degrees.

Method Summary

Modifier and Type	Method	Description
Quat	add(float qx, float qy, float qz, float qw)	Add the x,y,z,w components of the passed in quaternion to the ones of this quaternion
Quat	add(Quat quat)	Add the x,y,z,w components of the passed in quaternion to the ones of this quaternion
Quat	conjugate()	Conjugate the quaternion.
Quat	cpy()
float	dot(float x, float y, float z, float w)	Get the dot product between this and the other quaternion (commutative).
static float	dot(float x1, float y1, float z1, float w1, float x2, float y2, float z2, float w2)	Get the dot product between the two quaternions (commutative).
float	dot(Quat other)	Get the dot product between this and the other quaternion (commutative).
boolean	equals(Object obj)
Quat	exp(float alpha)	Calculates (this quaternion)^alpha where alpha is a real number and stores the result in this quaternion.
float	getAngle()	Get the angle in degrees of the rotation this quaternion represents.
float	getAngleAround(float axisX, float axisY, float axisZ)	Get the angle in degrees of the rotation around the specified axis.
float	getAngleAround(Vec3 axis)	Get the angle in degrees of the rotation around the specified axis.
float	getAngleAroundRad(float axisX, float axisY, float axisZ)	Get the angle in radians of the rotation around the specified axis.
float	getAngleAroundRad(Vec3 axis)	Get the angle in radians of the rotation around the specified axis.
float	getAngleRad()	Get the angle in radians of the rotation this quaternion represents.
float	getAxisAngle(Vec3 axis)	Get the axis angle representation of the rotation in degrees.
float	getAxisAngleRad(Vec3 axis)	Get the axis-angle representation of the rotation in radians.
int	getGimbalPole()	Get the pole of the gimbal lock, if any.
float	getPitch()	Get the pitch euler angle in degrees, which is the rotation around the x axis.
float	getPitchRad()	Get the pitch euler angle in radians, which is the rotation around the x axis.
float	getRoll()	Get the roll euler angle in degrees, which is the rotation around the z axis.
float	getRollRad()	Get the roll euler angle in radians, which is the rotation around the z axis.
void	getSwingTwist(float axisX, float axisY, float axisZ, Quat swing, Quat twist)	Get the swing rotation and twist rotation for the specified axis.
void	getSwingTwist(Vec3 axis, Quat swing, Quat twist)	Get the swing rotation and twist rotation for the specified axis.
float	getYaw()	Get the yaw euler angle in degrees, which is the rotation around the y axis.
float	getYawRad()	Get the yaw euler angle in radians, which is the rotation around the y axis.
int	hashCode()
Quat	idt()	Sets the quaternion to an identity Quaternion
boolean	isIdentity()
boolean	isIdentity(float tolerance)
float	len()
static float	len(float x, float y, float z, float w)
float	len2()
static float	len2(float x, float y, float z, float w)
Quat	mul(float scalar)	Multiplies the components of this quaternion with the given scalar.
Quat	mul(float x, float y, float z, float w)	Multiplies this quaternion with another one in the form of this = this * other
Quat	mul(Quat other)	Multiplies this quaternion with another one in the form of this = this * other
Quat	mulLeft(float x, float y, float z, float w)	Multiplies this quaternion with another one in the form of this = other * this
Quat	mulLeft(Quat other)	Multiplies this quaternion with another one in the form of this = other * this
Quat	nor()	Normalizes this quaternion to unit length
Quat	set(float x, float y, float z, float w)	Sets the components of the quaternion
Quat	set(Quat quat)	Sets the quaternion components from the given quaternion.
Quat	set(Vec3 axis, float angle)	Sets the quaternion components from the given axis and angle around that axis.
Quat	setEulerAngles(float yaw, float pitch, float roll)	Sets the quaternion to the given euler angles in degrees.
Quat	setEulerAnglesRad(float yaw, float pitch, float roll)	Sets the quaternion to the given euler angles in radians.
Quat	setFromAxes(boolean normalizeAxes, float xx, float xy, float xz, float yx, float yy, float yz, float zx, float zy, float zz)	Sets the Quaternion from the given x-, y- and z-axis.
Quat	setFromAxes(float xx, float xy, float xz, float yx, float yy, float yz, float zx, float zy, float zz)	Sets the Quaternion from the given x-, y- and z-axis which have to be orthonormal.
Quat	setFromAxis(float x, float y, float z, float degrees)	Sets the quaternion components from the given axis and angle around that axis.
Quat	setFromAxis(Vec3 axis, float degrees)	Sets the quaternion components from the given axis and angle around that axis.
Quat	setFromAxisRad(float x, float y, float z, float radians)	Sets the quaternion components from the given axis and angle around that axis.
Quat	setFromAxisRad(Vec3 axis, float radians)	Sets the quaternion components from the given axis and angle around that axis.
Quat	setFromCross(float x1, float y1, float z1, float x2, float y2, float z2)	Set this quaternion to the rotation between two vectors.
Quat	setFromCross(Vec3 v1, Vec3 v2)	Set this quaternion to the rotation between two vectors.
Quat	setFromMatrix(boolean normalizeAxes, Mat3D matrix)	Sets the Quaternion from the given matrix, optionally removing any scaling.
Quat	setFromMatrix(boolean normalizeAxes, Mat matrix)	Sets the Quaternion from the given matrix, optionally removing any scaling.
Quat	setFromMatrix(Mat3D matrix)	Sets the Quaternion from the given rotation matrix, which must not contain scaling.
Quat	setFromMatrix(Mat matrix)	Sets the Quaternion from the given rotation matrix, which must not contain scaling.
Quat	slerp(Quat[] q)	Spherical linearly interpolates multiple quaternions and stores the result in this Quaternion.
Quat	slerp(Quat[] q, float[] w)	Spherical linearly interpolates multiple quaternions by the given weights and stores the result in this Quaternion.
Quat	slerp(Quat end, float alpha)	Spherical Linear interpolation between this quaternion and the other quaternion, based on the alpha value in the range [0,1].
void	toMatrix(float[] matrix)
String	toString()
Vec3	transform(Vec3 v)	Transforms the given vector using this quaternion

Methods inherited from class java.lang.Object

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

Field Details

x

public float x

y

public float y

z

public float z

w

public float w

Constructor Details

Quat

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

Constructor, sets the four components of the quaternion.

Parameters:

x - The x-component

y - The y-component

z - The z-component

w - The w-component

Quat

public Quat()

Quat

public Quat(Quat quat)

Constructor, sets the quaternion components from the given quaternion.

Parameters:

quat - The quaternion to copy.

Quat

public Quat(Vec3 axis,
 float angle)

Constructor, sets the quaternion from the given axis vector and the angle around that axis in degrees.

Parameters:

axis - The axis

angle - The angle in degrees.

Method Details

len

public static float len(float x,
 float y,
 float z,
 float w)

Returns:

the euclidean length of the specified quaternion

len2

public static float len2(float x,
 float y,
 float z,
 float w)

dot

public static float dot(float x1,
 float y1,
 float z1,
 float w1,
 float x2,
 float y2,
 float z2,
 float w2)

Get the dot product between the two quaternions (commutative).

Parameters:

x1 - the x component of the first quaternion

y1 - the y component of the first quaternion

z1 - the z component of the first quaternion

w1 - the w component of the first quaternion

x2 - the x component of the second quaternion

y2 - the y component of the second quaternion

z2 - the z component of the second quaternion

w2 - the w component of the second quaternion

Returns:

the dot product between the first and second quaternion.

set

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

Sets the components of the quaternion

Parameters:

x - The x-component

y - The y-component

z - The z-component

w - The w-component

Returns:

This quaternion for chaining

set

public Quat set(Quat quat)

Sets the quaternion components from the given quaternion.

Parameters:

quat - The quaternion.

Returns:

This quaternion for chaining.

set

public Quat set(Vec3 axis,
 float angle)

Sets the quaternion components from the given axis and angle around that axis.

Parameters:

axis - The axis

angle - The angle in degrees

Returns:

This quaternion for chaining.

cpy

public Quat cpy()

Returns:

a copy of this quaternion

len

public float len()

Returns:

the euclidean length of this quaternion

toString

public String toString()

Overrides:

toString in class Object

setEulerAngles

public Quat setEulerAngles(float yaw,
 float pitch,
 float roll)

Sets the quaternion to the given euler angles in degrees.

Parameters:

yaw - the rotation around the y axis in degrees

pitch - the rotation around the x axis in degrees

roll - the rotation around the z axis degrees

Returns:

this quaternion

setEulerAnglesRad

public Quat setEulerAnglesRad(float yaw,
 float pitch,
 float roll)

Sets the quaternion to the given euler angles in radians.

Parameters:

yaw - the rotation around the y axis in radians

pitch - the rotation around the x axis in radians

roll - the rotation around the z axis in radians

Returns:

this quaternion

getGimbalPole

public int getGimbalPole()

Get the pole of the gimbal lock, if any.

Returns:

positive (+1) for north pole, negative (-1) for south pole, zero (0) when no gimbal lock

getRollRad

public float getRollRad()

Get the roll euler angle in radians, which is the rotation around the z axis. Requires that this quaternion is normalized.

Returns:

the rotation around the z axis in radians (between -PI and +PI)

getRoll

public float getRoll()

Get the roll euler angle in degrees, which is the rotation around the z axis. Requires that this quaternion is normalized.

Returns:

the rotation around the z axis in degrees (between -180 and +180)

getPitchRad

public float getPitchRad()

Get the pitch euler angle in radians, which is the rotation around the x axis. Requires that this quaternion is normalized.

Returns:

the rotation around the x axis in radians (between -(PI/2) and +(PI/2))

getPitch

public float getPitch()

Get the pitch euler angle in degrees, which is the rotation around the x axis. Requires that this quaternion is normalized.

Returns:

the rotation around the x axis in degrees (between -90 and +90)

getYawRad

public float getYawRad()

Get the yaw euler angle in radians, which is the rotation around the y axis. Requires that this quaternion is normalized.

Returns:

the rotation around the y axis in radians (between -PI and +PI)

getYaw

public float getYaw()

Get the yaw euler angle in degrees, which is the rotation around the y axis. Requires that this quaternion is normalized.

Returns:

the rotation around the y axis in degrees (between -180 and +180)

len2

public float len2()

Returns:

the length of this quaternion without square root

nor

public Quat nor()

Normalizes this quaternion to unit length

Returns:

the quaternion for chaining

conjugate

public Quat conjugate()

Conjugate the quaternion.

Returns:

This quaternion for chaining

transform

public Vec3 transform(Vec3 v)

Transforms the given vector using this quaternion

Parameters:

v - Vector to transform

mul

public Quat mul(Quat other)

Multiplies this quaternion with another one in the form of this = this * other

Parameters:

other - Quaternion to multiply with

Returns:

This quaternion for chaining

mul

public Quat mul(float x,
 float y,
 float z,
 float w)

Multiplies this quaternion with another one in the form of this = this * other

Parameters:

x - the x component of the other quaternion to multiply with

y - the y component of the other quaternion to multiply with

z - the z component of the other quaternion to multiply with

w - the w component of the other quaternion to multiply with

Returns:

This quaternion for chaining

mulLeft

public Quat mulLeft(Quat other)

Multiplies this quaternion with another one in the form of this = other * this

Parameters:

other - Quaternion to multiply with

Returns:

This quaternion for chaining

mulLeft

public Quat mulLeft(float x,
 float y,
 float z,
 float w)

Multiplies this quaternion with another one in the form of this = other * this

Parameters:

x - the x component of the other quaternion to multiply with

y - the y component of the other quaternion to multiply with

z - the z component of the other quaternion to multiply with

w - the w component of the other quaternion to multiply with

Returns:

This quaternion for chaining

add

public Quat add(Quat quat)

Add the x,y,z,w components of the passed in quaternion to the ones of this quaternion

add

public Quat add(float qx,
 float qy,
 float qz,
 float qw)

Add the x,y,z,w components of the passed in quaternion to the ones of this quaternion

toMatrix

public void toMatrix(float[] matrix)

idt

public Quat idt()

Sets the quaternion to an identity Quaternion

Returns:

this quaternion for chaining

isIdentity

public boolean isIdentity()

Returns:

If this quaternion is an identity Quaternion

isIdentity

public boolean isIdentity(float tolerance)

Returns:

If this quaternion is an identity Quaternion

setFromAxis

public Quat setFromAxis(Vec3 axis,
 float degrees)

Sets the quaternion components from the given axis and angle around that axis.

Parameters:

axis - The axis

degrees - The angle in degrees

Returns:

This quaternion for chaining.

setFromAxisRad

public Quat setFromAxisRad(Vec3 axis,
 float radians)

Sets the quaternion components from the given axis and angle around that axis.

Parameters:

axis - The axis

radians - The angle in radians

Returns:

This quaternion for chaining.

setFromAxis

public Quat setFromAxis(float x,
 float y,
 float z,
 float degrees)

Sets the quaternion components from the given axis and angle around that axis.

Parameters:

x - X direction of the axis

y - Y direction of the axis

z - Z direction of the axis

degrees - The angle in degrees

Returns:

This quaternion for chaining.

setFromAxisRad

public Quat setFromAxisRad(float x,
 float y,
 float z,
 float radians)

Sets the quaternion components from the given axis and angle around that axis.

Parameters:

x - X direction of the axis

y - Y direction of the axis

z - Z direction of the axis

radians - The angle in radians

Returns:

This quaternion for chaining.

setFromMatrix

public Quat setFromMatrix(boolean normalizeAxes,
 Mat3D matrix)

Sets the Quaternion from the given matrix, optionally removing any scaling.

setFromMatrix

public Quat setFromMatrix(Mat3D matrix)

Sets the Quaternion from the given rotation matrix, which must not contain scaling.

setFromMatrix

public Quat setFromMatrix(boolean normalizeAxes,
 Mat matrix)

Sets the Quaternion from the given matrix, optionally removing any scaling.

setFromMatrix

public Quat setFromMatrix(Mat matrix)

Sets the Quaternion from the given rotation matrix, which must not contain scaling.

setFromAxes

public Quat setFromAxes(float xx,
 float xy,
 float xz,
 float yx,
 float yy,
 float yz,
 float zx,
 float zy,
 float zz)

Sets the Quaternion from the given x-, y- and z-axis which have to be orthonormal.

Taken from Bones framework for JPCT, see http://www.aptalkarga.com/bones/ which in turn took it from Graphics Gem code at ftp://ftp.cis.upenn.edu/pub/graphics/shoemake/quatut.ps.Z.

Parameters:

xx - x-axis x-coordinate

xy - x-axis y-coordinate

xz - x-axis z-coordinate

yx - y-axis x-coordinate

yy - y-axis y-coordinate

yz - y-axis z-coordinate

zx - z-axis x-coordinate

zy - z-axis y-coordinate

zz - z-axis z-coordinate

setFromAxes

public Quat setFromAxes(boolean normalizeAxes,
 float xx,
 float xy,
 float xz,
 float yx,
 float yy,
 float yz,
 float zx,
 float zy,
 float zz)

Sets the Quaternion from the given x-, y- and z-axis.

Taken from Bones framework for JPCT, see http://www.aptalkarga.com/bones/ which in turn took it from Graphics Gem code at ftp://ftp.cis.upenn.edu/pub/graphics/shoemake/quatut.ps.Z.

Parameters:

normalizeAxes - whether to normalize the axes (necessary when they contain scaling)

xx - x-axis x-coordinate

xy - x-axis y-coordinate

xz - x-axis z-coordinate

yx - y-axis x-coordinate

yy - y-axis y-coordinate

yz - y-axis z-coordinate

zx - z-axis x-coordinate

zy - z-axis y-coordinate

zz - z-axis z-coordinate

setFromCross

public Quat setFromCross(Vec3 v1,
 Vec3 v2)

Set this quaternion to the rotation between two vectors.

Parameters:

v1 - The base vector, which should be normalized.

v2 - The target vector, which should be normalized.

Returns:

This quaternion for chaining

setFromCross

public Quat setFromCross(float x1,
 float y1,
 float z1,
 float x2,
 float y2,
 float z2)

Set this quaternion to the rotation between two vectors.

Parameters:

x1 - The base vectors x value, which should be normalized.

y1 - The base vectors y value, which should be normalized.

z1 - The base vectors z value, which should be normalized.

x2 - The target vector x value, which should be normalized.

y2 - The target vector y value, which should be normalized.

z2 - The target vector z value, which should be normalized.

Returns:

This quaternion for chaining

slerp

public Quat slerp(Quat end,
 float alpha)

Spherical Linear interpolation between this quaternion and the other quaternion, based on the alpha value in the range [0,1]. Taken from Bones framework for JPCT, see http://www.aptalkarga.com/bones/

Parameters:

end - the end quaternion

alpha - alpha in the range [0,1]

Returns:

this quaternion for chaining

slerp

public Quat slerp(Quat[] q)

Spherical linearly interpolates multiple quaternions and stores the result in this Quaternion. Will not destroy the data previously inside the elements of q. result = (q_1^w_1)*(q_2^w_2)* ... *(q_n^w_n) where w_i=1/n.

Parameters:

q - List of quaternions

Returns:

This quaternion for chaining

slerp

public Quat slerp(Quat[] q,
 float[] w)

Spherical linearly interpolates multiple quaternions by the given weights and stores the result in this Quaternion. Will not destroy the data previously inside the elements of q or w. result = (q_1^w_1)*(q_2^w_2)* ... *(q_n^w_n) where the sum of w_i is 1. Lists must be equal in length.

Parameters:

q - List of quaternions

w - List of weights

Returns:

This quaternion for chaining

exp

public Quat exp(float alpha)

Calculates (this quaternion)^alpha where alpha is a real number and stores the result in this quaternion. See http://en.wikipedia.org/wiki/Quaternion#Exponential.2C_logarithm.2C_and_power

Parameters:

alpha - Exponent

Returns:

This quaternion for chaining

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

dot

public float dot(Quat other)

Get the dot product between this and the other quaternion (commutative).

Parameters:

other - the other quaternion.

Returns:

the dot product of this and the other quaternion.

dot

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

Get the dot product between this and the other quaternion (commutative).

Parameters:

x - the x component of the other quaternion

y - the y component of the other quaternion

z - the z component of the other quaternion

w - the w component of the other quaternion

Returns:

the dot product of this and the other quaternion.

mul

public Quat mul(float scalar)

Multiplies the components of this quaternion with the given scalar.

Parameters:

scalar - the scalar.

Returns:

this quaternion for chaining.

getAxisAngle

public float getAxisAngle(Vec3 axis)

Get the axis angle representation of the rotation in degrees. The supplied vector will receive the axis (x, y and z values) of the rotation and the value returned is the angle in degrees around that axis. Note that this method will alter the supplied vector, the existing value of the vector is ignored.

This will normalize this quaternion if needed. The received axis is a unit vector. However, if this is an identity quaternion (no rotation), then the length of the axis may be zero.

Parameters:

axis - vector which will receive the axis

Returns:

the angle in degrees

See Also:

• wikipedia
• calculation

getAxisAngleRad

public float getAxisAngleRad(Vec3 axis)

Get the axis-angle representation of the rotation in radians. The supplied vector will receive the axis (x, y and z values) of the rotation and the value returned is the angle in radians around that axis. Note that this method will alter the supplied vector, the existing value of the vector is ignored.

This will normalize this quaternion if needed. The received axis is a unit vector. However, if this is an identity quaternion (no rotation), then the length of the axis may be zero.

Parameters:

axis - vector which will receive the axis

Returns:

the angle in radians

See Also:

• wikipedia
• calculation

getAngleRad

public float getAngleRad()

Get the angle in radians of the rotation this quaternion represents. Does not normalize the quaternion. Use getAxisAngleRad(Vec3) to get both the axis and the angle of this rotation. Use getAngleAroundRad(Vec3) to get the angle around a specific axis.

Returns:

the angle in radians of the rotation

getAngle

public float getAngle()

Get the angle in degrees of the rotation this quaternion represents. Use getAxisAngle(Vec3) to get both the axis and the angle of this rotation. Use getAngleAround(Vec3) to get the angle around a specific axis.

Returns:

the angle in degrees of the rotation

getSwingTwist

public void getSwingTwist(float axisX,
 float axisY,
 float axisZ,
 Quat swing,
 Quat twist)

Get the swing rotation and twist rotation for the specified axis. The twist rotation represents the rotation around the specified axis. The swing rotation represents the rotation of the specified axis itself, which is the rotation around an axis perpendicular to the specified axis.

The swing and twist rotation can be used to reconstruct the original quaternion: this = swing * twist

Parameters:

axisX - the X component of the normalized axis for which to get the swing and twist rotation

axisY - the Y component of the normalized axis for which to get the swing and twist rotation

axisZ - the Z component of the normalized axis for which to get the swing and twist rotation

swing - will receive the swing rotation: the rotation around an axis perpendicular to the specified axis

twist - will receive the twist rotation: the rotation around the specified axis

See Also:

• calculation

getSwingTwist

public void getSwingTwist(Vec3 axis,
 Quat swing,
 Quat twist)

Get the swing rotation and twist rotation for the specified axis. The twist rotation represents the rotation around the specified axis. The swing rotation represents the rotation of the specified axis itself, which is the rotation around an axis perpendicular to the specified axis.

The swing and twist rotation can be used to reconstruct the original quaternion: this = swing * twist

Parameters:

axis - the normalized axis for which to get the swing and twist rotation

swing - will receive the swing rotation: the rotation around an axis perpendicular to the specified axis

twist - will receive the twist rotation: the rotation around the specified axis

See Also:

• calculation

getAngleAroundRad

public float getAngleAroundRad(float axisX,
 float axisY,
 float axisZ)

Get the angle in radians of the rotation around the specified axis. The axis must be normalized.

Parameters:

axisX - the x component of the normalized axis for which to get the angle

axisY - the y component of the normalized axis for which to get the angle

axisZ - the z component of the normalized axis for which to get the angle

Returns:

the angle in radians of the rotation around the specified axis

getAngleAroundRad

public float getAngleAroundRad(Vec3 axis)

Get the angle in radians of the rotation around the specified axis. The axis must be normalized.

Parameters:

axis - the normalized axis for which to get the angle

Returns:

the angle in radians of the rotation around the specified axis

getAngleAround

public float getAngleAround(float axisX,
 float axisY,
 float axisZ)

Get the angle in degrees of the rotation around the specified axis. The axis must be normalized.

Parameters:

axisX - the x component of the normalized axis for which to get the angle

axisY - the y component of the normalized axis for which to get the angle

axisZ - the z component of the normalized axis for which to get the angle

Returns:

the angle in degrees of the rotation around the specified axis

getAngleAround

public float getAngleAround(Vec3 axis)

Get the angle in degrees of the rotation around the specified axis. The axis must be normalized.

Parameters:

axis - the normalized axis for which to get the angle

Returns:

the angle in degrees of the rotation around the specified axis