Package gaiasky.util.math

Class Quaterniond

java.lang.Object

gaiasky.util.math.Quaterniond

All Implemented Interfaces:

Serializable

public class Quaterniond
extends Object
implements Serializable

A simple quaternion class.

See Also:

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

Field Summary

Fields

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

Constructor Summary

Constructors

Constructor	Description
Quaterniond()
Quaterniond(double x, double y, double z, double w)	Constructor, sets the four components of the quaternion.
Quaterniond(com.badlogic.gdx.math.Quaternion quaternion)	Constructor, sets the quaternion components from the given quaternion.
Quaterniond(Quaterniond quaternion)	Constructor, sets the quaternion components from the given quaternion.
Quaterniond(Vector3d axis, double 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
Quaterniond	conjugate()	Conjugate the quaternion.
Quaterniond	cpy()
double	dot(double x, double y, double z, double w)	Get the dot product between this and the other quaternion (commutative).
static final double	dot(double x1, double y1, double z1, double w1, double x2, double y2, double z2, double w2)	Get the dot product between the two quaternions (commutative).
double	dot(Quaterniond other)	Get the dot product between this and the other quaternion (commutative).
boolean	equals(Object obj)
double	getAngle()	Get the angle in degrees of the rotation this quaternion represents.
double	getAngleAround(double axisX, double axisY, double axisZ)	Get the angle in degrees of the rotation around the specified axis.
double	getAngleAround(Vector3d axis)	Get the angle in degrees of the rotation around the specified axis.
double	getAngleAroundRad(double axisX, double axisY, double axisZ)	Get the angle in radians of the rotation around the specified axis.
double	getAngleAroundRad(Vector3d axis)	Get the angle in radians of the rotation around the specified axis.
double	getAngleRad()	Get the angle in radians of the rotation this quaternion represents.
double	getAxisAngle(Vector3d axis)	Get the axis angle representation of the rotation in degrees.
double	getAxisAngleRad(Vector3d axis)	Get the axis-angle representation of the rotation in radians.
int	getGimbalPole()	Get the pole of the gimbal lock, if any.
double	getPitch()	Get the pitch euler angle in degrees, which is the rotation around the x axis.
double	getPitchRad()	Get the pitch euler angle in radians, which is the rotation around the x axis.
double	getRoll()	Get the roll euler angle in degrees, which is the rotation around the z axis.
double	getRollRad()	Get the roll euler angle in radians, which is the rotation around the z axis.
void	getSwingTwist(double axisX, double axisY, double axisZ, Quaterniond swing, Quaterniond twist)	Get the swing rotation and twist rotation for the specified axis.
void	getSwingTwist(Vector3d axis, Quaterniond swing, Quaterniond twist)	Get the swing rotation and twist rotation for the specified axis.
double	getYaw()	Get the yaw euler angle in degrees, which is the rotation around the y axis.
double	getYawRad()	Get the yaw euler angle in radians, which is the rotation around the y axis.
int	hashCode()
Quaterniond	idt()	Sets the quaternion to an identity Quaterniond
Quaterniond	inverse()	Sets the value of this quaternion to the quaternion inverse of itself.
boolean	isIdentity()
boolean	isIdentity(double tolerance)
double	len()
static final double	len(double x, double y, double z, double w)
double	len2()
static final double	len2(double x, double y, double z, double w)
Quaterniond	mul(double scalar)	Multiplies the components of this quaternion with the given scalar.
Quaterniond	mul(double x, double y, double z, double w)	Multiplies this quaternion with another one in the form of this = this * other
Quaterniond	mul(Quaterniond other)	Multiplies this quaternion with another one in the form of this = this * other
Quaterniond	mulAdd(Quaterniond q, double s)	Add quaternion q, scaled by s, to this quaternion (this = this + q * s)
Quaterniond	mulInverse(Quaterniond q1)	Multiplies this quaternion by the inverse of quaternion q1 and places the value into this quaternion.
Quaterniond	mulLeft(double x, double y, double z, double w)	Multiplies this quaternion with another one in the form of this = other * this
Quaterniond	mulLeft(Quaterniond other)	Multiplies this quaternion with another one in the form of this = other * this
Quaterniond	mulLeftInverse(Quaterniond q1)	Pre-multiplies this quaternion by the inverse of quaternion q and places the value into this quaternion.
Quaterniond	nor()	Normalizes this quaternion to unit length
Quaterniond	set(double x, double y, double z, double w)	Sets the components of the quaternion
Quaterniond	set(com.badlogic.gdx.math.Quaternion quaternion)	Sets the quaternion components from the given quaternion.
Quaterniond	set(Quaterniond quaternion)	Sets the quaternion components from the given quaternion.
Quaterniond	set(Vector3d axis, double angle)	Sets the quaternion components from the given axis and angle around that axis.
Quaterniond	setEulerAngles(double yaw, double pitch, double roll)	Sets the quaternion to the given euler angles in degrees.
Quaterniond	setEulerAnglesRad(double yaw, double pitch, double roll)	Sets the quaternion to the given euler angles in radians.
Quaterniond	setFromAxes(boolean normalizeAxes, double xx, double xy, double xz, double yx, double yy, double yz, double zx, double zy, double zz)	Sets the Quaterniond from the given x-, y- and z-axis.
Quaterniond	setFromAxes(double xx, double xy, double xz, double yx, double yy, double yz, double zx, double zy, double zz)	Sets the Quaterniond from the given x-, y- and z-axis which have to be orthonormal.
Quaterniond	setFromAxis(double x, double y, double z, double degrees)	Sets the quaternion components from the given axis and angle around that axis.
Quaterniond	setFromAxis(Vector3d axis, double degrees)	Sets the quaternion components from the given axis and angle around that axis.
Quaterniond	setFromAxisRad(double x, double y, double z, double radians)	Sets the quaternion components from the given axis and angle around that axis.
Quaterniond	setFromAxisRad(Vector3d axis, double radians)	Sets the quaternion components from the given axis and angle around that axis.
Quaterniond	setFromBasis(Vector3d dir, Vector3d up)
Quaterniond	setFromCross(double x1, double y1, double z1, double x2, double y2, double z2)	Set this quaternion to the rotation between two vectors.
Quaterniond	setFromCross(Vector3d v1, Vector3d v2)	Set this quaternion to the rotation between two vectors.
Quaterniond	setFromMatrix(boolean normalizeAxes, Matrix4d matrix)	Sets the Quaterniond from the given matrix, optionally removing any scaling.
Quaterniond	setFromMatrix(Matrix4d matrix)	Sets the Quaterniond from the given rotation matrix, which must not contain scaling.
Quaterniond	slerp(Quaterniond end, double alpha)	Spherical linear interpolation between this quaternion and the other quaternion, based on the alpha value in the range [0,1].
void	toMatrix(double[] matrix)	Fills a 4x4 matrix with the rotation matrix represented by this quaternion.
String	toString()
Vector3d	transform(Vector3d 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 double x

y

public double y

z

public double z

w

public double w

Constructor Details

Quaterniond

public Quaterniond(double x,
 double y,
 double z,
 double 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

Quaterniond

public Quaterniond()

Quaterniond

public Quaterniond(Quaterniond quaternion)

Constructor, sets the quaternion components from the given quaternion.

Parameters:

quaternion - The quaternion to copy.

Quaterniond

public Quaterniond(com.badlogic.gdx.math.Quaternion quaternion)

Constructor, sets the quaternion components from the given quaternion.

Parameters:

quaternion - The quaternion to copy.

Quaterniond

public Quaterniond(Vector3d axis,
 double 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

set

public Quaterniond set(double x,
 double y,
 double z,
 double 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 Quaterniond set(Quaterniond quaternion)

Sets the quaternion components from the given quaternion.

Parameters:

quaternion - The quaternion.

Returns:

This quaternion for chaining.

set

public Quaterniond set(com.badlogic.gdx.math.Quaternion quaternion)

Sets the quaternion components from the given quaternion.

Parameters:

quaternion - The quaternion.

Returns:

This quaternion for chaining.

set

public Quaterniond set(Vector3d axis,
 double 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 Quaterniond cpy()

Returns:

a copy of this quaternion

len

public static final double len(double x,
 double y,
 double z,
 double w)

Returns:

the euclidian length of the specified quaternion

len

public double len()

Returns:

the euclidian length of this quaternion

toString

public String toString()

Overrides:

toString in class Object

setEulerAngles

public Quaterniond setEulerAngles(double yaw,
 double pitch,
 double 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 Quaterniond setEulerAnglesRad(double yaw,
 double pitch,
 double 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 double 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 double 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 double 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 double 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 double 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 double 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 static final double len2(double x,
 double y,
 double z,
 double w)

len2

public double len2()

Returns:

the length of this quaternion without square root

nor

public Quaterniond nor()

Normalizes this quaternion to unit length

Returns:

the quaternion for chaining

conjugate

public Quaterniond conjugate()

Conjugate the quaternion.

Returns:

This quaternion for chaining

transform

public Vector3d transform(Vector3d v)

Transforms the given vector using this quaternion

Parameters:

v - Vector to transform

inverse

public Quaterniond inverse()

Sets the value of this quaternion to the quaternion inverse of itself. Warning: this quaternion will NOT be normalized. Note that if q not normalized, then q*qinverse=(0,0,0,1) whereas q*qconjugate =(0,0,0,Norm(q)*Norm(q))

Returns:

Quaternion

mul

public Quaterniond mul(Quaterniond other)

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

Parameters:

other - Quaterniond to multiply with

Returns:

This quaternion for chaining

mul

public Quaterniond mul(double x,
 double y,
 double z,
 double 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 Quaterniond mulLeft(Quaterniond other)

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

Parameters:

other - Quaterniond to multiply with

Returns:

This quaternion for chaining

mulLeft

public Quaterniond mulLeft(double x,
 double y,
 double z,
 double 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

mulInverse

public Quaterniond mulInverse(Quaterniond q1)

Multiplies this quaternion by the inverse of quaternion q1 and places the value into this quaternion. The value of the argument quaternion is preserved (this = this * q^-1). Warning: this quaternion will NOT be normalized.

Parameters:

q1 - the other quaternion

Returns:

Quaterniond

mulLeftInverse

public Quaterniond mulLeftInverse(Quaterniond q1)

Pre-multiplies this quaternion by the inverse of quaternion q and places the value into this quaternion. The value of the argument quaternion is preserved (this = q^-1 * this). Warning: this quaternion will NOT be normalized.

Parameters:

q1 - the other quaternion

Returns:

Quaterniond

toMatrix

public void toMatrix(double[] matrix)

Fills a 4x4 matrix with the rotation matrix represented by this quaternion.

Parameters:

matrix - Matrix to fill

idt

public Quaterniond idt()

Sets the quaternion to an identity Quaterniond

Returns:

this quaternion for chaining

isIdentity

public boolean isIdentity()

Returns:

If this quaternion is an identity Quaterniond

isIdentity

public boolean isIdentity(double tolerance)

Returns:

If this quaternion is an identity Quaterniond

setFromAxis

public Quaterniond setFromAxis(Vector3d axis,
 double 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 Quaterniond setFromAxisRad(Vector3d axis,
 double 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 Quaterniond setFromAxis(double x,
 double y,
 double z,
 double 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 Quaterniond setFromAxisRad(double x,
 double y,
 double z,
 double 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 Quaterniond setFromMatrix(boolean normalizeAxes,
 Matrix4d matrix)

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

setFromMatrix

public Quaterniond setFromMatrix(Matrix4d matrix)

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

setFromBasis

public Quaterniond setFromBasis(Vector3d dir,
 Vector3d up)

setFromAxes

public Quaterniond setFromAxes(double xx,
 double xy,
 double xz,
 double yx,
 double yy,
 double yz,
 double zx,
 double zy,
 double zz)

Sets the Quaterniond 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 Quaterniond setFromAxes(boolean normalizeAxes,
 double xx,
 double xy,
 double xz,
 double yx,
 double yy,
 double yz,
 double zx,
 double zy,
 double zz)

Sets the Quaterniond 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 Quaterniond setFromCross(Vector3d v1,
 Vector3d 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 Quaterniond setFromCross(double x1,
 double y1,
 double z1,
 double x2,
 double y2,
 double 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 Quaterniond slerp(Quaterniond end,
 double alpha)

Spherical linear interpolation between this quaternion and the other quaternion, based on the alpha value in the range [0,1]. Taken from. 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

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

dot

public static final double dot(double x1,
 double y1,
 double z1,
 double w1,
 double x2,
 double y2,
 double z2,
 double 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.

dot

public double dot(Quaterniond 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 double dot(double x,
 double y,
 double z,
 double 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 Quaterniond mul(double scalar)

Multiplies the components of this quaternion with the given scalar.

Parameters:

scalar - the scalar.

Returns:

this quaternion for chaining.

mulAdd

public Quaterniond mulAdd(Quaterniond q,
 double s)

Add quaternion q, scaled by s, to this quaternion (this = this + q * s)

Parameters:

q -

s -

Returns:

this quaternion for chaining.

getAxisAngle

public double getAxisAngle(Vector3d 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 double getAxisAngleRad(Vector3d 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 double getAngleRad()

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

Returns:

the angle in radians of the rotation

getAngle

public double getAngle()

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

Returns:

the angle in degrees of the rotation

getSwingTwist

public void getSwingTwist(double axisX,
 double axisY,
 double axisZ,
 Quaterniond swing,
 Quaterniond 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(Vector3d axis,
 Quaterniond swing,
 Quaterniond 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 double getAngleAroundRad(double axisX,
 double axisY,
 double 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 double getAngleAroundRad(Vector3d 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 double getAngleAround(double axisX,
 double axisY,
 double 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 double getAngleAround(Vector3d 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