Stores a Quaternion of type T and provides a set of utility operations on each Quaternion. More...

#include <quaternion.h>

Detailed Description

template<class T>
class mathfu::Quaternion< T >

Stores a Quaternion of type T and provides a set of utility operations on each Quaternion.

Template Parameters

T	Type of each element in the Quaternion.

Public Member Functions
	Quaternion ()
	Construct an uninitialized Quaternion.

	Quaternion (const Quaternion< T > &q)
	Construct a Quaternion from a copy. More...

	Quaternion (const T &s1, const T &s2, const T &s3, const T &s4)
	Construct a Quaternion using scalar values to initialize each element. More...

	Quaternion (const T &s1, const Vector< T, 3 > &v1)
	Construct a quaternion from a scalar and 3-dimensional Vector. More...

T &	scalar ()
	Return the scalar component of the quaternion. More...

const T &	scalar () const
	Return the scalar component of the quaternion. More...

void	set_scalar (const T &s)
	Set the scalar component of the quaternion. More...

Vector< T, 3 > &	vector ()
	Return the vector component of the quaternion. More...

const Vector< T, 3 > &	vector () const
	Return the vector component of the quaternion. More...

void	set_vector (const Vector< T, 3 > &v)
	Set the vector component of the quaternion. More...

Quaternion< T >	Inverse () const
	Calculate the inverse Quaternion. More...

Quaternion< T >	operator* (const Quaternion< T > &q) const
	Multiply this Quaternion with another Quaternion. More...

Quaternion< T >	operator* (const T &s1) const
	Multiply this Quaternion by a scalar. More...

Vector< T, 3 >	operator* (const Vector< T, 3 > &v1) const
	Multiply a Vector by this Quaternion. More...

T	Normalize ()
	Normalize this quaterion (in-place). More...

Quaternion< T >	Normalized () const
	Calculate the normalized version of this quaternion. More...

void	ToAngleAxis (T angle, Vector< T, 3 > axis) const
	Convert this Quaternion to an Angle and axis. More...

Vector< T, 3 >	ToEulerAngles () const
	Convert this Quaternion to 3 Euler Angles. More...

Matrix< T, 3 >	ToMatrix () const
	Convert to a 3x3 Matrix. More...

Matrix< T, 4 >	ToMatrix4 () const
	Convert to a 4x4 Matrix. More...

T &	operator[] (const int i)
	Access an element of the quaternion. More...

const T &	operator[] (const int i) const
	Access an element of the quaternion. More...

Static Public Member Functions
static Quaternion< T >	FromAngleAxis (const T &angle, const Vector< T, 3 > &axis)
	Create a Quaternion from an angle and axis. More...

static Quaternion< T >	FromEulerAngles (const Vector< T, 3 > &angles)
	Create a quaternion from 3 euler angles. More...

static Quaternion< T >	FromMatrix (const Matrix< T, 3 > &m)
	Create a quaternion from a rotation Matrix. More...

static Quaternion< T >	FromMatrix (const Matrix< T, 4 > &m)
	Create a quaternion from the upper-left 3x3 roation Matrix of a 4x4 Matrix. More...

static T	DotProduct (const Quaternion< T > &q1, const Quaternion< T > &q2)
	Calculate the dot product of two Quaternions. More...

static Quaternion< T >	Slerp (const Quaternion< T > &q1, const Quaternion< T > &q2, const T &s1)
	Calculate the spherical linear interpolation between two Quaternions. More...

static Vector< T, 3 >	PerpendicularVector (const Vector< T, 3 > &v)
	Returns a vector that is perpendicular to the supplied vector. More...

static Quaternion< T >	RotateFromToWithAxis (const Vector< T, 3 > &v1, const Vector< T, 3 > &v2, const Vector< T, 3 > &preferred_axis)
	Returns the a Quaternion that rotates from start to end. More...

static Quaternion< T >	RotateFromTo (const Vector< T, 3 > &v1, const Vector< T, 3 > &v2)
	Returns the a Quaternion that rotates from start to end. More...

Static Public Attributes
static Quaternion< T >	identity = Quaternion<T>(1, 0, 0, 0)
	Contains a quaternion doing the identity transform.

Related Functions
(Note that these are not member functions.)
template<class T >
Quaternion< T >	operator* (const T &s, const Quaternion< T > &q)
	Multiply a Quaternion by a scalar. More...

Constructor & Destructor Documentation

template<class T>

mathfu::Quaternion< T >::Quaternion ( const Quaternion< T > & q )

inline

Construct a Quaternion from a copy.

Parameters

q	Quaternion to copy.

template<class T>

mathfu::Quaternion< T >::Quaternion	(	const T &	s1,
		const T &	s2,
		const T &	s3,
		const T &	s4
	)

inline

Construct a Quaternion using scalar values to initialize each element.

Parameters

s1	Scalar component.
s2	First element of the Vector component.
s3	Second element of the Vector component.
s4	Third element of the Vector component.

template<class T>

mathfu::Quaternion< T >::Quaternion	(	const T &	s1,
		const Vector< T, 3 > &	v1
	)

inline

Construct a quaternion from a scalar and 3-dimensional Vector.

Parameters

s1	Scalar component.
v1	Vector component.

Member Function Documentation

template<class T>

static T mathfu::Quaternion< T >::DotProduct	(	const Quaternion< T > &	q1,
		const Quaternion< T > &	q2
	)

inlinestatic

Calculate the dot product of two Quaternions.

Parameters

q1	First quaternion.
q2	Second quaternion

Returns: The scalar dot product of both Quaternions.

template<class T>

static Quaternion<T> mathfu::Quaternion< T >::FromAngleAxis	(	const T &	angle,
		const Vector< T, 3 > &	axis
	)

inlinestatic

Create a Quaternion from an angle and axis.

Parameters

angle	Angle in radians to rotate by.
axis	Axis in 3D space to rotate around.

Returns: Quaternion containing the result.

template<class T>

static Quaternion<T> mathfu::Quaternion< T >::FromEulerAngles ( const Vector< T, 3 > & angles )

inlinestatic

Create a quaternion from 3 euler angles.

Parameters

angles 3-dimensional Vector where each element contains an angle in radius to rotate by about the x, y and z axes.

Returns: Quaternion containing the result.

template<class T>

static Quaternion<T> mathfu::Quaternion< T >::FromMatrix ( const Matrix< T, 3 > & m )

inlinestatic

Create a quaternion from a rotation Matrix.

Parameters

m	3x3 rotation Matrix.

Returns: Quaternion containing the result.

template<class T>

static Quaternion<T> mathfu::Quaternion< T >::FromMatrix ( const Matrix< T, 4 > & m )

inlinestatic

Create a quaternion from the upper-left 3x3 roation Matrix of a 4x4 Matrix.

Parameters

m	4x4 Matrix.

Returns: Quaternion containing the result.

template<class T>

Quaternion<T> mathfu::Quaternion< T >::Inverse ( ) const

inline

Calculate the inverse Quaternion.

This calculates the inverse such that (q * q).Inverse() is the identity.

Returns: Quaternion containing the result.

template<class T>

T mathfu::Quaternion< T >::Normalize ( )

inline

Normalize this quaterion (in-place).

Returns: Length of the quaternion.

template<class T>

Quaternion<T> mathfu::Quaternion< T >::Normalized ( ) const

inline

Calculate the normalized version of this quaternion.

Returns: The normalized quaternion.

template<class T>

Quaternion<T> mathfu::Quaternion< T >::operator* ( const Quaternion< T > & q ) const

inline

Multiply this Quaternion with another Quaternion.

Note: This is equivalent to FromMatrix(ToMatrix() * q.ToMatrix()).

Parameters

q	Quaternion to multiply with.

Returns: Quaternion containing the result.

template<class T>

Quaternion<T> mathfu::Quaternion< T >::operator* ( const T & s1 ) const

inline

Multiply this Quaternion by a scalar.

This multiplies the angle of the rotation by a scalar factor.

Parameters

s1	Scalar to multiply with.

Returns: Quaternion containing the result.

template<class T>

Vector<T, 3> mathfu::Quaternion< T >::operator* ( const Vector< T, 3 > & v1 ) const

inline

Multiply a Vector by this Quaternion.

This will rotate the specified vector by the rotation specified by this Quaternion.

Parameters

v1	Vector to multiply by this Quaternion.

Returns: Rotated Vector.

template<class T>

T& mathfu::Quaternion< T >::operator[] ( const int i )

inline

Access an element of the quaternion.

Parameters

i	Index of the element to access.

Returns: A reference to the accessed data that can be modified by the caller.

template<class T>

const T& mathfu::Quaternion< T >::operator[] ( const int i ) const

inline

Access an element of the quaternion.

Parameters

i	Index of the element to access.

Returns: A const reference to the accessed.

template<class T>

static Vector<T, 3> mathfu::Quaternion< T >::PerpendicularVector ( const Vector< T, 3 > & v )

inlinestatic

Returns a vector that is perpendicular to the supplied vector.

Parameters

v1	An arbitrary vector

Returns: A vector perpendicular to v1. Normally this will just be the cross product of v1, v2. If they are parallel or opposite though, the routine will attempt to pick a vector.

template<class T>

static Quaternion<T> mathfu::Quaternion< T >::RotateFromTo	(	const Vector< T, 3 > &	v1,
		const Vector< T, 3 > &	v2
	)

inlinestatic

Returns the a Quaternion that rotates from start to end.

Parameters

v1	The starting vector
v2	The vector to rotate to

Returns: A Quaternion describing the rotation from v1 to v2. In the case where the vectors are parallel, it returns the identity. In the case where they point in opposite directions, it picks an arbitrary axis. (Since there are technically infinite possible quaternions to represent a 180 degree rotation.)

The final equation used here is fairly elegant, but its derivation is not obvious: We want to find the quaternion that represents the angle between Start and End.

The angle can be expressed as a quaternion with the values: angle: ArcCos(dotproduct(start, end) / (|start|*|end|) axis: crossproduct(start, end).normalized * sin(angle/2)

or written as: quaternion(cos(angle/2), axis * sin(angle/2))

Using the trig identity: sin(angle * 2) = 2 * sin(angle) * cos*angle) Via substitution, we can turn this into: sin(angle/2) = 0.5 * sin(angle)/cos(angle/2)

Using this substitution, we get: quaternion( cos(angle/2), 0.5 * crossproduct(start, end).normalized

sin(angle) / cos(angle/2))

If we scale the whole thing up by 2 * cos(angle/2) then we get: quaternion(2 * cos(angle/2) * cos(angle/2), crossproduct(start, end).normalized * sin(angle))

(Note that the quaternion is no longer normalized after this scaling)

Another trig identity: cos(angle/2) = sqrt((1 + cos(angle) / 2)

Substituting this in, we can simplify the quaternion scalar:

quaternion(1 + cos(angle), crossproduct(start, end).normalized * sin(angle))

Because cross(start, end) has a magnitude of |start|*|end|*sin(angle), crossproduct(start,end).normalized is equivalent to crossproduct(start,end) / |start| * |end| * sin(angle) So after that substitution:

quaternion(1 + cos(angle), crossproduct(start, end) / (|start| * |end|))

dotproduct(start, end) has the value of |start| * |end| * cos(angle), so by algebra, cos(angle) = dotproduct(start, end) / (|start| * |end|) we can replace our quaternion scalar here also:

quaternion(1 + dotproduct(start, end) / (|start| * |end|), crossproduct(start, end) / (|start| * |end|))

If start and end are normalized, then |start| * |end| = 1, giving us a final quaternion of:

quaternion(1 + dotproduct(start, end), crossproduct(start, end))

template<class T>

static Quaternion<T> mathfu::Quaternion< T >::RotateFromToWithAxis	(	const Vector< T, 3 > &	v1,
		const Vector< T, 3 > &	v2,
		const Vector< T, 3 > &	preferred_axis
	)

inlinestatic

Returns the a Quaternion that rotates from start to end.

Parameters

v1	The starting vector
v2	The vector to rotate to
preferred_axis	the axis to use, if v1 and v2 are parallel.

Returns: A Quaternion describing the rotation from v1 to v2 See the comment on RotateFromToWithAxis for an explanation of the math.

template<class T>

T& mathfu::Quaternion< T >::scalar ( )

inline

Return the scalar component of the quaternion.

Returns: The scalar component

template<class T>

const T& mathfu::Quaternion< T >::scalar ( ) const

inline

Return the scalar component of the quaternion.

Returns: The scalar component

template<class T>

void mathfu::Quaternion< T >::set_scalar ( const T & s )

inline

Set the scalar component of the quaternion.

Parameters

s	Scalar component.

template<class T>

void mathfu::Quaternion< T >::set_vector ( const Vector< T, 3 > & v )

inline

Set the vector component of the quaternion.

Parameters

v	Vector component.

template<class T>

static Quaternion<T> mathfu::Quaternion< T >::Slerp	(	const Quaternion< T > &	q1,
		const Quaternion< T > &	q2,
		const T &	s1
	)

inlinestatic

Calculate the spherical linear interpolation between two Quaternions.

Parameters

q1	Start Quaternion.
q2	End Quaternion.
s1	The scalar value determining how far from q1 and q2 the resulting quaternion should be. A value of 0 corresponds to q1 and a value of 1 corresponds to q2.

Returns: Quaternion containing the result.

template<class T>

void mathfu::Quaternion< T >::ToAngleAxis	(	T *	angle,
		Vector< T, 3 > *	axis
	)		const

inline

Convert this Quaternion to an Angle and axis.

The returned angle is the size of the rotation in radians about the axis represented by this Quaternion.

Parameters

angle	Receives the angle.
axis	Receives the normalized axis.

template<class T>

Vector<T, 3> mathfu::Quaternion< T >::ToEulerAngles ( ) const

inline

Convert this Quaternion to 3 Euler Angles.

Returns: 3-dimensional Vector where each element is a angle of rotation (in radians) around the x, y, and z axes.

template<class T>

Matrix<T, 3> mathfu::Quaternion< T >::ToMatrix ( ) const

inline

Convert to a 3x3 Matrix.

Returns: 3x3 rotation Matrix.

template<class T>

Matrix<T, 4> mathfu::Quaternion< T >::ToMatrix4 ( ) const

inline

Convert to a 4x4 Matrix.

Returns: 4x4 transform Matrix.

template<class T>

Vector<T, 3>& mathfu::Quaternion< T >::vector ( )

inline

Return the vector component of the quaternion.

Returns: The scalar component

template<class T>

const Vector<T, 3>& mathfu::Quaternion< T >::vector ( ) const

inline

Return the vector component of the quaternion.

Returns: The scalar component

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

quaternion.h

Detailed Description

template<class T> class mathfu::Quaternion< T >

Public Member Functions

Static Public Member Functions

Static Public Attributes

Related Functions

Constructor & Destructor Documentation

Member Function Documentation

template<class T>
class mathfu::Quaternion< T >