Package net.risingworld.api.utils

Class Quaternion

java.lang.Object

net.risingworld.api.utils.Quaternion

All Implemented Interfaces:

Serializable

public class Quaternion
extends Object
implements Serializable

A quaternion which describes a rotation.

See Also:

• http://www.euclideanspace.com/maths/algebra/realNormedAlgebra/quaternions/index.htm
• Serialized Form

Field Summary

Fields

Modifier and Type	Field	Description
static final Quaternion	IDENTITY	A quaternion representing no rotation
float	w	The W value of this Quaternion (scalar part)
float	x	The X value of this Quaternion (vector part)
float	y	The Y value of this Quaternion (vector part)
float	z	The Z value of this Quaternion (vector part)
static final Quaternion	ZERO	An "empty" quaternion.

Constructor Summary

Constructors

Constructor	Description
Quaternion()
Quaternion(float x, float y, float z, float w)
Quaternion(Quaternion copy)

Method Summary

Modifier and Type	Method	Description
float	angle(Quaternion quaternion)	Gets the angle (in degrees) between this quaternion and the other quaternion.
Quaternion	copy()	Creates a copy of this Quaternion.
float	dot(Quaternion quaternion)	Gets the dot product of this quaternion with the provided quaternion.
boolean	equals(float x, float y, float z, float w)
boolean	equals(Object o)	Gets whether or not this quaternion is equal to another object.
Quaternion	fromAngles(float[] angles)	Calculates this quaternion from the given Euler rotation angles (pitch, yaw, roll) aka (attitude, heading, bank) aka (x, y, z).
Quaternion	fromAngles(float pitch, float yaw, float roll)	Calculates this quaternion from the given Euler rotation angles (pitch, yaw, roll) aka (attitude, heading, bank) aka (x, y, z).
Quaternion	fromString(String input)
float	getPitch()	Gets the pitch (aka attitude aka x euler angle) of this quaternion.
float	getRoll()	Gets the roll (aka bank aka z euler angle) of this quaternion.
float	getW()	Returns the W value of this Quaternion.
float	getX()	Returns the X value of this Quaternion.
float	getY()	Returns the Y value of this Quaternion.
float	getYaw()	Gets the yaw (aka heading aka y euler angle) of this quaternion.
float	getZ()	Returns the Z value of this Quaternion.
int	hashCode()	Gets a unique* hash code for this quaternion, based on its values.
Quaternion	inverse()	Gets the inverse of this quaternion as a new quaternion.
Quaternion	inverseLocal()	Calculates the inverse of this quaternion and stores the result in this quaternion.
boolean	isNaN()	Checks if this quaternion is invalid, or more precisely, if any of its values is NaN (not a number).
Quaternion	loadIdentity()	Sets this quaternion to 0, 0, 0, 1.
Quaternion	lookAt(float directionx, float directiony, float directionz)	"Looks at" a given direction, i.e the quaternion will be set based on the direction.
Quaternion	lookAt(Vector3f direction)	"Looks at" a given direction, i.e the quaternion will be set based on the direction.
Quaternion	lookAt(Vector3f direction, Vector3f up)	"Looks at" a given direction, i.e the quaternion will be set based on the direction and an up vector.
Vector3f	mult(Vector3f vector)	Multiplies the quaternion by a Vector3f.
Quaternion	multLocal(float scalar)	Multiplies the quaternion by a scalar.
Quaternion	multLocal(float qx, float qy, float qz, float qw)	Multiplies this quaternion by the provided values.
Quaternion	multLocal(Quaternion quaternion)	Multiplies this quaternion by the provided quaternion.
Vector3f	multLocal(Vector3f vector)	Multiplies the quaternion by a Vector3f.
Quaternion	negateLocal()	Negates the values of this quaternion.
float	norm()	Gets the norm of this quaternion, i.e the dot product of this quaternion with itself.
Quaternion	normalize()	Gets the normalized quaternion as a new quaternion.
Quaternion	normalizeLocal()	Normalizes this quaternion.
Quaternion	set(float x, float y, float z, float w)	Sets the X, Y, Z and W values of this Quaternion to the provided values.
Quaternion	set(Quaternion quaternion)	Sets the X, Y, Z and W values of this Quaternion to the values of the provided quaternion.
Quaternion	setW(float w)	Sets the Z value of this Quaternion.
Quaternion	setX(float x)	Sets the X value of this Vector3f.
Quaternion	setY(float y)	Sets the Y value of this Vector3f.
Quaternion	setZ(float z)	Sets the Z value of this Quaternion.
float[]	toAngles()	Calculates the according Euler rotation angles (pitch, yaw, roll) for this quaternion and stores them in the provided float array.
float[]	toAngles(float[] storeTo)	Calculates the according Euler rotation angles (pitch, yaw, roll) for this quaternion and stores them in the provided float array.
String	toString()	Gets a String representation of this quaternion, for example (0.0, 1.25, -0.7, 1.0)

Methods inherited from class java.lang.Object

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

Field Details

IDENTITY

public static final Quaternion IDENTITY

A quaternion representing no rotation

ZERO

public static final Quaternion ZERO

An "empty" quaternion. If you're looking for a quaternion with no rotation instead, check out IDENTITY

x

public float x

The X value of this Quaternion (vector part)

y

public float y

The Y value of this Quaternion (vector part)

z

public float z

The Z value of this Quaternion (vector part)

w

public float w

The W value of this Quaternion (scalar part)

Constructor Details

Quaternion

public Quaternion()

Quaternion

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

Quaternion

public Quaternion(Quaternion copy)

Method Details

copy

public Quaternion copy()

Creates a copy of this Quaternion.

Returns:

a new instance with the same values of this Quaternion.

set

public Quaternion set(Quaternion quaternion)

Sets the X, Y, Z and W values of this Quaternion to the values of the provided quaternion.

Parameters:

quaternion - the Quaternion to copy.

Returns:

this Quaternion.

set

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

Sets the X, Y, Z and W values of this Quaternion to the provided values.

Parameters:

x - the X value.

y - the Y value.

z - the Z value.

w - the W value.

Returns:

this Quaternion.

setX

public Quaternion setX(float x)

Sets the X value of this Vector3f.

Parameters:

x - the new X value.

Returns:

this Vector3f.

setY

public Quaternion setY(float y)

Sets the Y value of this Vector3f.

Parameters:

y - the new Y value.

Returns:

this Vector3f.

setZ

public Quaternion setZ(float z)

Sets the Z value of this Quaternion.

Parameters:

z - the new Z value.

Returns:

this Quaternion.

setW

public Quaternion setW(float w)

Sets the Z value of this Quaternion.

Parameters:

w - the new W value.

Returns:

this Quaternion.

getX

public float getX()

Returns the X value of this Quaternion.

Returns:

the current X value.

getY

public float getY()

Returns the Y value of this Quaternion.

Returns:

the current Y value.

getZ

public float getZ()

Returns the Z value of this Quaternion.

Returns:

the current Z value.

getW

public float getW()

Returns the W value of this Quaternion.

Returns:

the current W value.

getPitch

public float getPitch()

Gets the pitch (aka attitude aka x euler angle) of this quaternion.

Returns:

the pitch/attitude as euler angle in degrees.

getYaw

public float getYaw()

Gets the yaw (aka heading aka y euler angle) of this quaternion.

Returns:

the yaw/heading as euler angle in degrees.

getRoll

public float getRoll()

Gets the roll (aka bank aka z euler angle) of this quaternion.

Returns:

the roll/bank as euler angle in degrees.

loadIdentity

public Quaternion loadIdentity()

Sets this quaternion to 0, 0, 0, 1. i.e it does no longer represent any rotation.

Returns:

this quaternion.

fromAngles

public Quaternion fromAngles(float[] angles)

Calculates this quaternion from the given Euler rotation angles (pitch, yaw, roll) aka (attitude, heading, bank) aka (x, y, z). The rotation will be applied in the order: y, z, x

Parameters:

angles - Euler rotation angles (pitch, yaw, roll) in degrees as a float array.

Returns:

this quaternion.

fromAngles

public Quaternion fromAngles(float pitch,
 float yaw,
 float roll)

Calculates this quaternion from the given Euler rotation angles (pitch, yaw, roll) aka (attitude, heading, bank) aka (x, y, z). The rotation will be applied in the order: x, y, z

Parameters:

pitch - Euler pitch (attitude) rotation in degrees.

yaw - Euler yaw (heading) rotation in degrees.

roll - Euler roll (bank) rotation in degrees.

Returns:

this quaternion.

See Also:

• http://www.euclideanspace.com/maths/geometry/rotations/conversions/eulerToQuaternion/index.htm

toAngles

public float[] toAngles()

Calculates the according Euler rotation angles (pitch, yaw, roll) for this quaternion and stores them in the provided float array.

Returns:

a float array containing the Euler angles (pitch, yaw, roll).

toAngles

public float[] toAngles(float[] storeTo)

Calculates the according Euler rotation angles (pitch, yaw, roll) for this quaternion and stores them in the provided float array. The angles are stored in degrees.

Parameters:

storeTo - the float array in which the angles should be stored. This array needs to be able to hold at least three elements. If null is provided, a new float array will be created.

Returns:

the float array containing the Euler angles (in degrees).

See Also:

• http://www.euclideanspace.com/maths/geometry/rotations/conversions/quaternionToEuler/index.htm

angle

public float angle(Quaternion quaternion)

Gets the angle (in degrees) between this quaternion and the other quaternion.

Parameters:

quaternion - the other quaternion.

Returns:

the angle between the two quaternions (in degrees).

multLocal

public Quaternion multLocal(Quaternion quaternion)

Multiplies this quaternion by the provided quaternion. The result is stored in this quaternion.

Parameters:

quaternion - the quaternion to multiply this one by.

Returns:

this quaternion.

multLocal

public Quaternion multLocal(float qx,
 float qy,
 float qz,
 float qw)

Multiplies this quaternion by the provided values. The result is stored in this quaternion.

Parameters:

qx - the x compontent to multiply this quaternion by.

qy - the y compontent to multiply this quaternion by.

qz - the z compontent to multiply this quaternion by.

qw - the w compontent to multiply this quaternion by.

Returns:

this quaternion.

multLocal

public Quaternion multLocal(float scalar)

Multiplies the quaternion by a scalar. The result is stored in this quaternion.

Parameters:

scalar - the scalar value.

Returns:

this quaternion.

multLocal

public Vector3f multLocal(Vector3f vector)

Multiplies the quaternion by a Vector3f. The result is stored in the vector. You can use this method to apply a rotation (represented by the quaternion) to a vector.

Parameters:

vector - the Vector3f to multiply this quaternion by.

Returns:

the vector.

mult

public Vector3f mult(Vector3f vector)

Multiplies the quaternion by a Vector3f. The result is returned as a new vector. You can use this method to apply a rotation (represented by the quaternion) to a vector.

Parameters:

vector - the Vector3f to multiply this quaternion by.

Returns:

a new vector.

Example: Turn a rotation in a direction

1	//Get an arbitrary rotation
2	Quaternion rotation = new Quaternion().fromAngles(45f, 90f, 0f);
3
4	//Apply rotation to a vector to get a direction (unit vector)
5	Vector3f direction = rotation.mult(Vector3f.FORWARD);

negateLocal

public Quaternion negateLocal()

Negates the values of this quaternion.

Returns:

this quaternion.

inverse

public Quaternion inverse()

Gets the inverse of this quaternion as a new quaternion. The inverse quaternion represents the same rotation, but in the opposite direction.
If this quaternion does not have an inverse, null is returned.

Returns:

a new quaternion containing the inverse of this quaternion, or null if there is no inverse for this quaternion.

inverseLocal

public Quaternion inverseLocal()

Calculates the inverse of this quaternion and stores the result in this quaternion. The inverse quaternion represents the same rotation, but in the opposite direction.
If this quaternion does not have an inverse, nothing happens.

Returns:

this quaternion containing the inverse of this quaternion.

normalize

public Quaternion normalize()

Gets the normalized quaternion as a new quaternion.

Returns:

a new quaternion containing the normalized values of this quaternion.

normalizeLocal

public Quaternion normalizeLocal()

Normalizes this quaternion.

Returns:

this quaternion.

dot

public float dot(Quaternion quaternion)

Gets the dot product of this quaternion with the provided quaternion.

Parameters:

quaternion - the quaternion to calculate the dot product with.

Returns:

the dot product.

norm

public float norm()

Gets the norm of this quaternion, i.e the dot product of this quaternion with itself.

Returns:

the norm of this quaternion.

lookAt

public Quaternion lookAt(Vector3f direction)

"Looks at" a given direction, i.e the quaternion will be set based on the direction. The resulting quaternion represents the rotation for transforming a z-axis to point into the given direction.

Parameters:

direction - the direction (where to "look at").

Returns:

this quaternion.

Example:

1	//Our target position
2	Vector3f targetPosition = ...;
3
4	//Our start position (e.g player position)
5	Vector3f startPosition = player.getPosition();
6
7	//Calculate "target-start" to get a direction vector from start to target
8	Vector3f direction = targetPosition.subtract(startPosition);
9
10	//Normalize the vector, i.e turn it into a unit vector
11	direction.normalizeLocal();
12
13	//Create a new quaternion looking at this direction
14	Quaternion rotation = new Quaternion().lookAt(direction);

Example: Simplified version

1	//Use Utils method to calculate direction
2	Vector3f direction = Utils.VectorUtils.getDirection(startPosition, targetPosition);
3
4	//Create a new quaternion looking at this direction
5	Quaternion rotation = new Quaternion().lookAt(direction);

lookAt

public Quaternion lookAt(float directionx,
 float directiony,
 float directionz)

"Looks at" a given direction, i.e the quaternion will be set based on the direction. The resulting quaternion represents the rotation for transforming a z-axis to point into the given direction.

Parameters:

directionx - the x component of the direction vector.

directiony - the y component of the direction vector.

directionz - the z component of the direction vector.

Returns:

this quaternion.

See Also:

• lookAt(net.risingworld.api.utils.Vector3f)

lookAt

public Quaternion lookAt(Vector3f direction,
 Vector3f up)

"Looks at" a given direction, i.e the quaternion will be set based on the direction and an up vector. The resulting quaternion represents the rotation for transforming a z-axis to point into the given direction.

Parameters:

direction - the direction (where to "look at").

up - the according up-vector, typically (0, 1, 0);

Returns:

this quaternion.

See Also:

• lookAt(net.risingworld.api.utils.Vector3f)

isNaN

public boolean isNaN()

Checks if this quaternion is invalid, or more precisely, if any of its values is NaN (not a number).

Returns:

true if this quaternion contains any NaN values, false if not.

equals

public boolean equals(float x,
 float y,
 float z,
 float w)

equals

public boolean equals(Object o)

Gets whether or not this quaternion is equal to another object. This function returns true, if the other object is a Quaternion and if it has exactly the same x, y, z and w values.

Overrides:

equals in class Object

Parameters:

o - the object to compare for equality.

Returns:

true if the other object is a Quaternion and has the same values as this quaternion, false if not.

hashCode

public int hashCode()

Gets a unique* hash code for this quaternion, based on its values. If two quaternions have the same x, y, z and w values, they will return the same hash code.

* Please keep in mind that the uniqueness is not fully reliable. There is always a small chance that collisions occur (i.e two completely different quaternions return the same hash code). But usually the reliability is sufficient.

Overrides:

hashCode in class Object

Returns:

the hash code for this quaternion.

toString

public String toString()

Gets a String representation of this quaternion, for example (0.0, 1.25, -0.7, 1.0)

Overrides:

toString in class Object

Returns:

a string representing the values of this quaternion.

fromString

public Quaternion fromString(String input)