ARQuaternion Class Reference

#import <ARQuaternion.h>

Inherits NSObject, and <NSCoding>.

Instance Methods
(BOOL)	- equalsQuaternion:withTolerance:
(ARQuaternion *)	- addQuaternion:
(ARQuaternion *)	- localAddQuaternion:
(ARQuaternion *)	- subtractQuaternion:
(ARQuaternion *)	- localSubtractQuaternion:
(ARQuaternion *)	- multiplyByQuaternion:
(ARQuaternion *)	- localMultiplyByQuaternion:
(ARVector3 *)	- multiplyByVector:
(ARVector3 *)	- localMultiplyByVector:
(ARQuaternion *)	- negate
(ARQuaternion *)	- localNegate
(float)	- dotWithQuaternion:
(ARQuaternion *)	- normalise
(ARQuaternion *)	- localNormalise
(ARQuaternion *)	- inverse
(ARQuaternion *)	- localInverse
(ARQuaternion *)	- slerpToQuaternion:atTime:

Class Methods
(ARQuaternion *)	+ quaternionWithIdentity
(ARQuaternion *)	+ quaternionWithX:y:z:w:
(ARQuaternion *)	+ quaternionFromMatrix4:
(ARQuaternion *)	+ quaternionWithDegrees:axisX:y:z:
(ARQuaternion *)	+ quaternionWithRadians:axisX:y:z:
(ARQuaternion *)	+ quaternionWithOML: [implementation]

Properties
float	x
float	y
float	z
float	w
OgreMathLib::Quaternion	quaternionOML [implementation]

Detailed Description

An ARQuaternion is a class that represents a rotation. Working with quaternions is better than simply using Euler angles because quaternions avoid problems such as gimbal lock.

Method Documentation

addQuaternion:

- (ARQuaternion *) addQuaternion:

(ARQuaternion *)

quaternion

Adds the components of two quaternions together and returns the result.

Example of use:

ARQuaternion quaternionOne = [ARQuaternion quaternionWithDegrees:90 axisX:1.0 y:0.0 z:1.0];
ARQuaternion quaternionTwo = [ARQuaternion quaternionWithDegrees:45 axisX:0.0 y:1.0 z:0.0];
ARQuaternion quaternionThree = [quaternionOne addQuaternion:quaternionTwo];

Parameters

quaternion

The quaternion to add to this quaternion.

Returns

A new ARQuaternion with values (X1 + X2, Y1 + Y2, Z1 + Z2, W1 + W2).

dotWithQuaternion:

- (float) dotWithQuaternion:

(ARQuaternion *)

quaternion

Calculates the dot product of this quaternion and another given quaternion and returns the result.

Example of use:

ARQuaternion quaternionOne = [ARQuaternion quaternionWithDegrees:90 axisX:1.0 y:0.0 z:1.0];
ARQuaternion quaternionTwo = [ARQuaternion quaternionWithDegrees:45 axisX:0.0 y:1.0 z:0.0];
float dot = [quaternionOne dotWithQuaternion:quaternionTwo];

Parameters

quaternion

The other quaternion to use for the dot product calculation.

Returns

The dot product of the two quaternions.

equalsQuaternion:withTolerance:

- (BOOL) equalsQuaternion:		(ARQuaternion *)	quaternion
withTolerance:		(float)	tolerance

Checks whether this quaternion is equal to another given quaternion. A tolerance value is used to account for potential floating-point errors.

Example of use:

ARQuaternion quaternionOne = [ARQuaternion quaternionWithDegrees:90 axisX:1.0 y:0.0 z:1.0];
ARQuaternion quaternionTwo = [ARQuaternion quaternionWithRadians:M_PI/2 axisX:1.0 y:0 z:1.0];
 
BOOL isEqual = [quaternionOne equalsQuaternion:quaternionTwo withTolerance:FLT_EPSILON];

Parameters

quaternion	The quaternion to check against.
tolerance	The maximum difference between each component of the quaternion. For example, if the tolerance were 0.1, then a quaternion with values (0.5, 0.5, 0.5, 1.0) would be considered equal to a quaternion with values (0.45, 0.52, 0.59, 1.01). The value FLT_EPSILON is a costant value of 0.00001, or 1e-5.

Returns

True if each component of the two quaternions are within the tolerance range, false otherwise.

inverse

- (ARQuaternion *) inverse

Finds the inverse rotation of this quaternion and returns the result. This is useful for rotating something back to its original position.

Example of use:

ARQuaternion quaternion = [ARQuaternion quaternionWithDegrees:90 axisX:1.0 y:0.0 z:1.0];
ARQuaternion inverseQuaternion = [quaternion inverse];

Returns

A new ARQuaternion containing the inverse rotation of this quaternion.

localAddQuaternion:

- (ARQuaternion *) localAddQuaternion:

(ARQuaternion *)

quaternion

Adds the components of two quaternions together and stores the result in this quaternion.

Example of use:

ARQuaternion quaternionOne = [ARQuaternion quaternionWithDegrees:90 axisX:1.0 y:0.0 z:1.0];
ARQuaternion quaternionTwo = [ARQuaternion quaternionWithDegrees:45 axisX:0.0 y:1.0 z:0.0];
[quaternionOne localAddQuaternion:quaternionTwo];

Parameters

quaternion

The quaternion to add to this quaternion.

Returns

This quaternion with values (X1 + X2, Y1 + Y2, Z1 + Z2, W1 + W2).

localInverse

- (ARQuaternion *) localInverse

Finds the inverse rotation of this quaternion and stores the result in this quaternion.

Example of use:

ARQuaternion quaternion = [ARQuaternion quaternionWithDegrees:90 axisX:1.0 y:0.0 z:1.0];
[quaternion inverse];

Returns

This quaternion containing its inverse rotation.

localMultiplyByQuaternion:

- (ARQuaternion *) localMultiplyByQuaternion:

(ARQuaternion *)

quaternion

Multiplies this quaternion's components by the components of a given quaternion and stores the result in this quaternion. This is NOT the same as the Dot Product. It simply multiplies the components together.

Example of use:

ARQuaternion quaternionOne = [ARQuaternion quaternionWithDegrees:90 axisX:1.0 y:0.0 z:1.0];
ARQuaternion quaternionTwo = [ARQuaternion quaternionWithDegrees:45 axisX:0.0 y:1.0 z:0.0];
[quaternionOne localMultiplyByquaternion:quaternionTwo];

Parameters

quaternion

The quaternion to multiply with this quaternion.

Returns

This quaternion with values (X1 * X2, Y1 * Y2, Z1 * Z2, W1 * W2).

localMultiplyByVector:

- (ARVector3 *) localMultiplyByVector:

(ARVector3 *)

vector

Multiplies this quaternion by an ARVector3 and stores the resulting rotated vector in the given vector.

Example of use:

ARQuaternion quaternion = [ARQuaternion quaternionWithDegrees:90 axisX:1.0 y:0.0 z:1.0];
ARVector3 vector = [ARVector3 vectorWithValuesX:1.0 y:2.0 z:3.0];
[quaternion localMultiplyByVector:vector];

Parameters

vector

The vector to multiply this quaternion by.

Returns

A new ARVector3 containing the given vector rotated by this quaternion.

localNegate

- (ARQuaternion *) localNegate

Multiplies this quaternion by -1 and stores the result in this quaternion.

Example of use:

ARQuaternion quaternion = [ARQuaternion quaternionWithDegrees:90 axisX:1.0 y:0.0 z:1.0];
[quaternion localNegate];

Returns

This quaternion with values (-X, -Y, -Z, -W).

localNormalise

- (ARQuaternion *) localNormalise

Normliases this quaternion so that each component of the quaternion is in the range 0..1 and stores the result in this quaternion.

Example of use:

ARQuaternion quaternion = [ARQuaternion quaternionWithDegrees:90 axisX:1.0 y:0.0 z:1.0];
[quaternion localNormalise];

Returns

This quaternion containing the normalised quaternion.

localSubtractQuaternion:

- (ARQuaternion *) localSubtractQuaternion:

(ARQuaternion *)

quaternion

Subtracts a given quaternion's components from the components of this quaternion and stores the result in this quaternion.

Example of use:

ARQuaternion quaternionOne = [ARQuaternion quaternionWithDegrees:90 axisX:1.0 y:0.0 z:1.0];
ARQuaternion quaternionTwo = [ARQuaternion quaternionWithDegrees:45 axisX:0.0 y:1.0 z:0.0];
[quaternionOne localSubtractQuaternion:quaternionTwo];

Parameters

quaternion

The quaternion to subtract from this quaternion.

Returns

This quaternion with values (X1 - X2, Y1 - Y2, Z1 - Z2, W1 - W2).

multiplyByQuaternion:

- (ARQuaternion *) multiplyByQuaternion:

(ARQuaternion *)

quaternion

Multiplies this quaternion's components by the components of a given quaternion and returns the result. This is NOT the same as the Dot Product OR the Cross Product. It simply multiplies the components together.

Example of use:

ARQuaternion quaternionOne = [ARQuaternion quaternionWithDegrees:90 axisX:1.0 y:0.0 z:1.0];
ARQuaternion quaternionTwo = [ARQuaternion quaternionWithDegrees:45 axisX:0.0 y:1.0 z:0.0];
ARQuaternion quaternionThree = [quaternionOne multiplyByquaternion:quaternionTwo];

Parameters

quaternion

The quaternion to multiply with this quaternion.

Returns

A new ARQuaternion with values (X1 * X2, Y1 * Y2, Z1 * Z2, W1 * W2).

multiplyByVector:

- (ARVector3 *) multiplyByVector:

(ARVector3 *)

vector

Multiplies this quaternion by an ARVector3 and returns the resulting rotated vector.

Example of use:

ARQuaternion quaternion = [ARQuaternion quaternionWithDegrees:90 axisX:1.0 y:0.0 z:1.0];
ARVector3 vector = [ARVector3 vectorWithValuesX:1.0 y:2.0 z:3.0];
ARVector3 rotatedVector = [quaternion multiplyByVector:vector];

Parameters

vector

The vector to multiply this quaternion by.

Returns

A new ARVector3 containing the given vector rotated by this quaternion.

negate

- (ARQuaternion *) negate

Multiplies this quaternion by -1 and returns the result.

Example of use:

ARQuaternion quaternion = [ARQuaternion quaternionWithDegrees:90 axisX:1.0 y:0.0 z:1.0];
ARQuaternion negatedQuaternion = [quaternion negate];

Returns

A new ARQuaternion with values (-X, -Y, -Z, -W).

normalise

- (ARQuaternion *) normalise

Normliases this quaternion so that each component of the quaternion is in the range 0..1 and returns the result.

Example of use:

ARQuaternion quaternion = [ARQuaternion quaternionWithDegrees:90 axisX:1.0 y:0.0 z:1.0];
ARQuaternion normalisedQuaternion = [quaternion normalise];

Returns

A new ARQuaternion containing the normalised quaternion.

quaternionFromMatrix4:

+ (ARQuaternion *) quaternionFromMatrix4:

(ARMatrix4 *)

matrix

Creates an ARQuaternion from a 4x4 matrix.

Example of use:

ARQuaternion quaternion = [ARQuaternion quaternionFromMatrix4:[ARMatrix4 matrixWithIdentity];

Parameters

matrix

The 4x4 matrix to convert to a quaternion.

Returns

A new ARQuaternion made from the given matrix.

quaternionWithDegrees:axisX:y:z:

+ (ARQuaternion *) quaternionWithDegrees:		(float)	angle
axisX:		(float)	x
y:		(float)	y
z:		(float)	z

Creates an ARQuaternion representing a rotation of the given angle in degrees around the constructed axis.

Example of use:

ARQuaternion quaternion = [ARQuaternion quaternionWithDegrees:45 axisX:1.0 y:0.0 z:1.0];

Parameters

angle	The number of degrees around the axes this quaternion should rotate.
x	The x component of the axis.
y	The y component of the axis.
z	The z component of the axis.

Returns

A new ARQuaternion of rotation angle degrees around the axis (X, Y, Z).

quaternionWithIdentity

+ (ARQuaternion *) quaternionWithIdentity

Creates an ARQuaternion with identity, representing no rotation.

Example of use:

ARQuaternion quaternion = [ARQuaternion quaternionWithIdentity];

Returns

A new ARQuaternion with values (0, 0, 0, 1).

quaternionWithRadians:axisX:y:z:

+ (ARQuaternion *) quaternionWithRadians:		(float)	angle
axisX:		(float)	x
y:		(float)	y
z:		(float)	z

Creates an ARQuaternion representing a rotation of the given angle in radians around the constructed axis.

Example of use:

ARQuaternion quaternion = [ARQuaternion quaternionWithRadisn:M_PI/2 axisX:1.0 y:0.0 z:1.0];

Parameters

angle	The number of radians around the axes this quaternion should rotate.
x	The x component of the axis.
y	The y component of the axis.
z	The z component of the axis.

Returns

A new ARQuaternion of rotation angle degrees around the axis (X, Y, Z).

quaternionWithX:y:z:w:

+ (ARQuaternion *) quaternionWithX:		(float)	x
y:		(float)	y
z:		(float)	z
w:		(float)	w

Creates an ARQuaternion with the given values.

Example of use:

ARQuaternion quaternion = [ARQuaternion quaternionWithX:0.0 y:1.0 z:0.0 w:1.0];

Parameters

x	The value to give the X component of this quaternion.
y	The value to give the Y component of this quaternion.
z	The value to give the Z component of this quaternion.
w	The value to give the W component of this quaternion.

Returns

A new ARQuaternion with values (X, Y, Z, W).

slerpToQuaternion:atTime:

- (ARQuaternion *) slerpToQuaternion:		(ARQuaternion *)	quaternion
atTime:		(float)	time

Spherically interpolates between this quaternion and another given quaternion and returns the result. Slerp provides a "slow in" and "slow out" effect. Each step is not equidstant. When time = 0 this quaternion will be return. When time = 1 the given quaternion is returned. When time = 0.5 a rotation halfway between the two quaternions will be returned. Values below 0 or above 1 will return a larger rotation than either of the two.

£xample of use:

ARQuaternion quaternionOne = [ARQuaternion quaternionWithDegrees:90 axisX:1.0 y:0.0 z:1.0];
ARQuaternion quaternionTwo = [ARQuaternion quaternionWithDegrees:45 axisX:0.0 y:1.0 z:0.0];
ARQuaternion slerpQuaternion = [quaternionOne slerpToQuaternion:quaternionTwo atTime:0.5];

Parameters

quaternion	The other quaternion to use for the interpolation calculation.
time	Represents a percentage of how much of a rotation between the two quaternions the result should represent.

Returns

A new ARQuaternion representing a rotation between this quaternion and the given quaternion.

subtractQuaternion:

- (ARQuaternion *) subtractQuaternion:

(ARQuaternion *)

quaternion

Subtracts a given quaternion's components from the components of this quaternion and returns the result.

Example of use:

ARQuaternion quaternionOne = [ARQuaternion quaternionWithDegrees:90 axisX:1.0 y:0.0 z:1.0];
ARQuaternion quaternionTwo = [ARQuaternion quaternionWithDegrees:45 axisX:0.0 y:1.0 z:0.0];
ARQuaternion quaternionThree = [quaternionOne subtractQuaternion:quaternionTwo];

Parameters

quaternion

The quaternion to subtract from this quaternion.

Returns

A new ARQuaternion with values (X1 - X2, Y1 - Y2, Z1 - Z2, W1 - W2).

Property Documentation

w

- (float) w

readnonatomicassign

The w value of the quaternion.

x

- (float) x

readnonatomicassign

The x value of the quaternion.

y

- (float) y

readnonatomicassign

The y value of the quaternion.

z

- (float) z

readnonatomicassign

The z value of the quaternion.

---

The documentation for this class was generated from the following files:

• ARQuaternion.h
• ARQuaternion.mm