Quaternion Class Reference

Quaternions represent rotation around an axis, defined by quaternion components x, y, z and w. More...

Inheritance diagram for Quaternion:

Public Member Functions
	Quaternion ()
	Default constructor, initializes the quaternion components to identity, representing no rotation (x=0, y=0, z=0, w=1).
	Quaternion (float x, float y, float z, float w)
	Constructor, initializes the quaternion components to x, y, z and w.
Quaternion	conjugated ()
	Get conjugated copy of this quaternion.
synchronized void	delete ()
Quaternion	divideByScalar (float scalar)
	Divides each quaternion component with a scalar and returns the result.
boolean	equals (Object obj)
	Indicates whether some other object is "equal to" this one.
float	get (int index)
	Returns individual quaternion element value at index.
float	getW ()
	Get the w component of the quaternion.
float	getX ()
	Get the x component of the quaternion.
float	getY ()
	Get the y component of the quaternion.
float	getZ ()
	Get the z component of the quaternion.
int	hashCode ()
	Returns a hash code value for the object.
Quaternion	multiplyByScalar (float scalar)
	Multiplies each quaternion component with a scalar.
Quaternion	normalized ()
	Get normalized copy of this quaternion.
void	set (int index, float v)
	Sets the individual quaternion element at index to value.
void	setW (float w)
	Sets the w component of the quaternion.
void	setX (float x)
	Sets the x component of the quaternion.
void	setY (float y)
	Sets the y component of the quaternion.
void	setZ (float z)
	Sets the z component of the quaternion.

Static Public Member Functions
static Vector3	calculateEulerAngles (Quaternion quaternion)
	Calculates Euler angles from a quaternion.
static Quaternion	componentWiseMultiply (Quaternion q1, Quaternion q2)
	Multiplies quaternion components component-wise and returns the resulting quaternion.
static Quaternion	createFromEulerAngles (float rotationX, float rotationY, float rotationZ)
	Creates a quaternion from Euler angles.
static Quaternion	createFromEulerAngles (Vector3 anglesInRadians)
	Creates a quaternion from Euler angles.
static Quaternion	createFromVector (Vector3 axis, float angleInRadians)
	Creates quaternion from axis and angle.
static Quaternion	divide (Quaternion q, float scalar)
	Divides each quaternion component with a scalar and returns the result.
static float	dotProduct (Quaternion q1, Quaternion q2)
	Calculates the dot product of two quaternions.
static Quaternion	inverse (Quaternion q)
	Returns an inverse quaternion for a quaternion.
static Quaternion	matrix4x4ToQuaternion (Matrix4x4 matrix)
	Creates a quaternion from Matrix4x4.
static Quaternion	multiply (Quaternion left, Quaternion right)
	Multiplies two quaternions.
static Quaternion	multiply (Quaternion q, float scalar)
	Multiplies each quaternion component with a scalar.
static Quaternion	quaternionSlerp (Quaternion q1, Quaternion q2, float interpolationTime)
	Applies spherical linear interpolation (slerp) to two quaternions using the shortest path.
static Quaternion	quaternionSlerpLongerPath (Quaternion q1, Quaternion q2, float interpolationTime)
	Applies spherical linear interpolation (slerp) to two quaternion using the longer path.
static Matrix4x4	quaternionToMatrix4x4 (Quaternion quaternion)
	Converts a quaternion rotation to a 4x4 rotation matrix.
static Vector3	rotateVector (Quaternion quaternion, Vector3 vector)
	Applies quaternion rotation to a vector.

Protected Member Functions
void	finalize ()
	Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.

Protected Attributes
transient boolean	swigCMemOwn
	Does this object own its native object.

Detailed Description

Quaternions represent rotation around an axis, defined by quaternion components x, y, z and w.

Quaternions are compact, do not suffer from gimbal lock and can be easily interpolated.
Kanzi Engine uses quaternions internally to represent all rotations.
Quaternions are based on complex numbers and are not easy to understand intuitively. You almost never access or modify the individual components.
In most cases you take existing rotations and use them to construct new rotations (e.g. to smoothly interpolate between two rotations).
You can use the Quaternion operator * to rotate one rotation by another, or to rotate a vector by a rotation.

See also

operator*().

rotateVector().

Constructor & Destructor Documentation

Quaternion()

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

Constructor, initializes the quaternion components to x, y, z and w.

Parameters

x	x component of the quaternion.
y	y component of the quaternion.
z	z component of the quaternion.
w	w component of the quaternion.

Member Function Documentation

calculateEulerAngles()

static Vector3 calculateEulerAngles ( Quaternion quaternion )

static

Calculates Euler angles from a quaternion.

Kanzi Engine represents Euler angles as Tait-Bryan angles where the rotations are applied in the order x, y, and z.

Returns

Euler angles in radians.

componentWiseMultiply()

static Quaternion componentWiseMultiply ( Quaternion q1, Quaternion q2 )

static

Multiplies quaternion components component-wise and returns the resulting quaternion.

Parameters

q1	The first quaternion.
q2	The second quaternion.

Returns

The result quaternion.

conjugated()

Quaternion conjugated

(

)

Get conjugated copy of this quaternion.

Conjugation inverses the quaternion axis components x, y and z.
Use this to get the inverse rotation of a quaternion.

Returns

Conjugated quaternion.

createFromEulerAngles() [1/2]

static Quaternion createFromEulerAngles ( float rotationX, float rotationY, float rotationZ )

static

Creates a quaternion from Euler angles.

Kanzi Engine represents Euler angles as Tait-Bryan angles where the rotations are applied in the order x, y and z.

Parameters

rotationX	Rotation angle around the x axis in radians.
rotationY	Rotation angle around the y axis in radians.
rotationZ	Rotation angle around the z axis in radians.

Returns

Rotated quaternion.

createFromEulerAngles() [2/2]

static Quaternion createFromEulerAngles ( Vector3 anglesInRadians )

static

Creates a quaternion from Euler angles.

Kanzi Engine represents Euler angles as Tait-Bryan angles where the rotations are applied in the order x, y and z.

Parameters

anglesInRadians

Euler angles in radians.

Returns

Rotated quaternion.

createFromVector()

static Quaternion createFromVector ( Vector3 axis, float angleInRadians )

static

Creates quaternion from axis and angle.

Use this to create a quaternion from axis of rotation and angle in radians.

Parameters

axis	Axis components in Vector3(x, y, z).
angleInRadians	Angle in radians.

Returns

Rotated quaternion.

divide()

static Quaternion divide ( Quaternion q, float scalar )

static

Divides each quaternion component with a scalar and returns the result.

Parameters

q	Quaternion to divide.
scalar	Divisor for each quaternion component.

Returns

Result quaternion.

divideByScalar()

Quaternion divideByScalar

(

float

scalar

)

Divides each quaternion component with a scalar and returns the result.

Parameters

scalar

Divisor for each quaternion component.

Returns

Result quaternion.

dotProduct()

static float dotProduct ( Quaternion q1, Quaternion q2 )

static

Calculates the dot product of two quaternions.

Parameters

q1	The first quaternion.
q2	The second quaternion.

Returns

The dot product of the quaternions.

equals()

boolean equals

(

Object

obj

)

Indicates whether some other object is "equal to" this one.

Parameters

obj	The reference object with which to compare.

Returns

True if this object is the same as the obj argument, otherwise false.

finalize()

void finalize ( )

protected

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.

Finalization is deprecated and subject to removal in future.

Reimplemented in QuaternionLongerPath.

get()

float get

(

int

index

)

Returns individual quaternion element value at index.

Returns

The quaternion element value at index.

getW()

float getW

(

)

Get the w component of the quaternion.

Returns

The w component.

getX()

float getX

(

)

Get the x component of the quaternion.

Returns

The x component.

getY()

float getY

(

)

Get the y component of the quaternion.

Returns

The y component.

getZ()

float getZ

(

)

Get the z component of the quaternion.

Returns

The z component.

hashCode()

int hashCode

(

)

Returns a hash code value for the object.

Returns

A hash code value for this object.

inverse()

static Quaternion inverse ( Quaternion q )

static

Returns an inverse quaternion for a quaternion.

Parameters

q	Quaternion to invert.

Returns

Inverse quaternion.

matrix4x4ToQuaternion()

static Quaternion matrix4x4ToQuaternion ( Matrix4x4 matrix )

static

Creates a quaternion from Matrix4x4.

Extracts and calculates the quaternion components from passed in Matrix4x4.
Use this when you already have the rotation stored in a 4x4 matrix and want to extract the rotation angles to a quaternion.

Parameters

matrix

Matrix4x4 from which to extract and calculate the quaternion components.

Returns

Rotated and normalized quaternion.

multiply() [1/2]

static Quaternion multiply ( Quaternion left, Quaternion right )

static

Multiplies two quaternions.

You can combine a quaternion rotations by multiplying them:
rotating a vector v by quaternion q1 * q2 is the same as rotating the vector first by q2 and then by q1.

Returns

Multiplied quaternion.

multiply() [2/2]

static Quaternion multiply ( Quaternion q, float scalar )

static

Multiplies each quaternion component with a scalar.

Parameters

q	Quaternion to multiply.
scalar	Multiplier for each quaternion component.

Returns

This quaternion.

multiplyByScalar()

Quaternion multiplyByScalar

(

float

scalar

)

Multiplies each quaternion component with a scalar.

Parameters

scalar

Multiplier for each quaternion component.

Returns

This quaternion.

normalized()

Quaternion normalized

(

)

Get normalized copy of this quaternion.

Normalized quaternion is called an unit quaternion.
Calculates the magnitude from the dot product of the quaternion components, and divides all the quaternion components with the magnitude.
Use this when rotating or transforming a vector with a quaternion, and when generating a rotation or transformation matrix from quaternion.
Using unnormalized quaternion in calculations can lead to floating point rounding errors. The errors that result from using an unnormalized
quaternion in calculations are proportional to the square of the quaternion's magnitude.

Returns

Normalized quaternion.

quaternionSlerp()

static Quaternion quaternionSlerp ( Quaternion q1, Quaternion q2, float interpolationTime )

static

Applies spherical linear interpolation (slerp) to two quaternions using the shortest path.

Use this to evaluate interpolation between two rotations at given interpolation time.
Takes the shortest path of interpolation between two degrees, which amounts to maximum of 180 degrees of rotation in any direction.

Parameters

q1	First quaternion.
q2	Second quaternion.
interpolationTime	Interpolation parameter in range [0 .. 1].

Returns

Interpolated rotated quaternion.

quaternionSlerpLongerPath()

static Quaternion quaternionSlerpLongerPath ( Quaternion q1, Quaternion q2, float interpolationTime )

static

Applies spherical linear interpolation (slerp) to two quaternion using the longer path.

Use this to evaluate interpolation between two rotations at given interpolation time.
Takes the longer path to the result. Interpolates the whole angle difference between the two quaternion rotations. For example, from 0 to 270 rotates the whole 270 degrees.

Parameters

q1	First quaternion.
q2	Second quaternion.
interpolationTime	Interpolation parameter in range [0 .. 1].

Returns

Interpolated rotated quaternion.

quaternionToMatrix4x4()

static Matrix4x4 quaternionToMatrix4x4 ( Quaternion quaternion )

static

Converts a quaternion rotation to a 4x4 rotation matrix.

Parameters

quaternion

Quaternion rotation.

Returns

Matrix4x4 with rotation values extracted from quaternion.

rotateVector()

static Vector3 rotateVector ( Quaternion quaternion, Vector3 vector )

static

Applies quaternion rotation to a vector.

Calculates q * v * q.conjugated(), for a quaternion q and a vector v.

Parameters

quaternion	Quaternion rotation.
vector	Vector that you want to rotate.

Returns

The rotated vector.

set()

void set	(	int	index,
		float	v )

Sets the individual quaternion element at index to value.

Parameters

index

Quaternion element index to set.

setW()

void setW

(

float

w

)

Sets the w component of the quaternion.

Parameters

w	The new value of the w component.

setX()

void setX

(

float

x

)

Sets the x component of the quaternion.

Parameters

x	The new value of the x component.

setY()

void setY

(

float

y

)

Sets the y component of the quaternion.

Parameters

y	The new value of the y component.

setZ()

void setZ

(

float

z

)

Sets the z component of the quaternion.

Parameters

z	The new value of the z component.