DD::Image::TQuaternion< ValueType > Class Template Reference

A implementation of a way of representing rotations that avoid a lot of the problems that the standard rotation about the axis methods have. More...

#include <Quaternion.h>

Public Member Functions
	TQuaternion ()
	Default constructor.
	TQuaternion (ValueType a, ValueType b, ValueType c, ValueType d)
	Constructor for specifying values.
void	set (ValueType a, ValueType b, ValueType c, ValueType d)
	Set individual quaternion values.
	TQuaternion (ValueType sval, const Vector3 &v)
	This constructor takes an angle in radians and a vector to rotate around.
	TQuaternion (const Matrix4 &mat)
	Constructor. Given a Matrix that represents a rotation, calculate the quaternion that is equivalent to that rotation.
	TQuaternion (const Vector3 &org_vec, const Vector3 &new_vec)
	Constructor from two vectors. The quaternion will represent the angle between the two vectors.
TQuaternion	operator+ (const TQuaternion &q) const
	Addition of two quaternions. This follows this rule:
TQuaternion	operator* (const TQuaternion &q) const
	Multiplication of two quaternions. This follows this rule:
TQuaternion	operator* (ValueType f) const
	Multiplication of a quaternion by a double number. This follows this rule:
TQuaternion	conjugate () const
	Returns the conjugate of this quaternion. This follows this rule: q.conjugate = ( s - v )
ValueType	length_squared () const
	Returns the square of the length of the quaternion. This follows this rule:
ValueType	length () const
	Returns the length of the quaternion. This follows this rule:
ValueType	magnitude () const
	Returns the square of the magnitude of the quaternion. To avoid confusion, pleasse use length()/length_squared() instead. This follows this rule:
TQuaternion	add_inverse () const
	Returns the additive inverse of the quaternion. This is: q.add_inverse = ( -s, -vx, -vy, -vz )
TQuaternion	mult_inverse () const
	Returns the multiplicative inverse of the quaternion. This is: q.mult_inverse = ( 1 / q.magnitude ) * q.conjugate
TQuaternion	slerp (const TQuaternion &end_quat, ValueType t) const
	Spherical linear interpolation.
Matrix4	matrix () const
	Return the transformation matrix that will represent the the Euler angle rotations that this quaternion embodies. Note - this method affects all components of the matrix.
Matrix4	matrix2 () const
	Return the transformation matrix that will represent the the Euler angle rotations that this quaternion embodies. Note - this method only affects the rotation part of the matrix. NOTE: The quaternion must be normalised before using this function.
void	normalize ()

Static Public Member Functions
static TQuaternion	add_identity ()
	Returns the additive identity for quaternions (which is all zeros)
static TQuaternion	mult_identity ()
	Returns the multipicative identity for quaternions (which is 1,0,0,0)

Public Attributes
ValueType	s
ValueType	vx
ValueType	vy
ValueType	vz

Friends
template<typename T >
std::ostream &	operator<< (std::ostream &o, const TQuaternion< T > &q)
	Writes it in nuke/tcl notation "{s x y z}".

Detailed Description

template<class ValueType>
class DD::Image::TQuaternion< ValueType >

A implementation of a way of representing rotations that avoid a lot of the problems that the standard rotation about the axis methods have.

Quaternions are a modification of the concept of a vector in space, but specially tailored for spherical space. The cool thing about quaternions is that they are perfectly suited to representing rotations and orientations of objects in three space.

Basically, in a quaternion there are four values: a scalar part and a vector part. q = ( s, v ). Typically, when dealing with rotations, the scalar part represents the rotation about an arbitrary axis. The axis is represented by a unit vector in the vector part.

Since the quaternion is a representation of a rotation, it can be converted into a Euler angle rotation matrix and a rotation matrix can be converted into a quaternion.

Copyright (c) 2009 The Foundry Visionmongers Ltd. All Rights Reserved.

Constructor & Destructor Documentation

TQuaternion() [1/2]

template<typename ValueType >

TQuaternion::TQuaternion

(

const Matrix4 &

mat

)

Constructor. Given a Matrix that represents a rotation, calculate the quaternion that is equivalent to that rotation.

Given a Matrix that represents a rotation, calculate the quaternion that is equivalent to that rotation. A matrix3 could be used instead, last row and column are ignored.

TQuaternion() [2/2]

template<typename ValueType >

TQuaternion::TQuaternion	(	const Vector3 &	org_vec,
		const Vector3 &	new_vec
	)

Constructor from two vectors. The quaternion will represent the angle between the two vectors.

Constructor from two vectors. The quaternion will represent the angle between the two vectors.

References DD::Image::Vector3::cross(), DD::Image::Vector3::length(), DD::Image::Vector3::lengthSquared(), and DD::Image::Vector3::normalize().

Member Function Documentation

operator+()

template<class ValueType >

TQuaternion DD::Image::TQuaternion< ValueType >::operator+ ( const TQuaternion< ValueType > &  q ) const

inline

Addition of two quaternions. This follows this rule:

q1 + q2 = ( s1 + s2, vx1 + vx2, vy1 + vy2, vz1 + vz2 )

operator*() [1/2]

template<class ValueType >

TQuaternion DD::Image::TQuaternion< ValueType >::operator* ( const TQuaternion< ValueType > &  q ) const

inline

Multiplication of two quaternions. This follows this rule:

q1 q2 = ( s1 s2 - vx1 vx2 - vy1 vy2 - vz1 vz2,
vy1 vz2 - vy2 vz1 + s1 vx2 + s2 vx1,
vz1 vx2 - vz2 vx1 + s1 vy2 + s2 vy1,
vx1 vy2 - vx2 vy1 + s1 vz2 + s2 vz1 ))

The result is a quaternion representing the rotation specifed by this quaternion followed by that of q.

operator*() [2/2]

template<class ValueType >

TQuaternion DD::Image::TQuaternion< ValueType >::operator* ( ValueType  f ) const

inline

Multiplication of a quaternion by a double number. This follows this rule:

f * q = ( f * s, f * vx, f * vy, f * vz )

References DD::Image::TQuaternion< ValueType >::TQuaternion().

length_squared()

template<class ValueType >

ValueType DD::Image::TQuaternion< ValueType >::length_squared ( ) const

inline

Returns the square of the length of the quaternion. This follows this rule:

q.lengthSquared = s^2 + vx^2 + vy^2 + vz^2

length()

template<class ValueType >

ValueType DD::Image::TQuaternion< ValueType >::length ( ) const

inline

Returns the length of the quaternion. This follows this rule:

q.length = sqrt(s^2 + vx^2 + vy^2 + vz^2 )

Referenced by DD::Image::TQuaternion< ValueType >::mult_inverse().

magnitude()

template<class ValueType >

ValueType DD::Image::TQuaternion< ValueType >::magnitude ( ) const

inline

Returns the square of the magnitude of the quaternion. To avoid confusion, pleasse use length()/length_squared() instead. This follows this rule:

q.magnitude = q q.conjugate = s^2 + vx^2 + vy^2 + vz^2

References DD::Image::TQuaternion< ValueType >::conjugate().

slerp()

template<typename ValueType >

TQuaternion< ValueType > TQuaternion::slerp	(	const TQuaternion< ValueType > &	end_quat,
		ValueType	t
	)		const

Spherical linear interpolation.

This method interpolates smoothly between two quaternions. The value t should be a number between 0.0 and 1.0. When t = 0.0, *this is returned. When t = 1.0, end_quat is returned.

Because of the way quaternions work, you can't just linearly interpolate between two of them. You must interpolate along the surface of a sphere. This method returns a quaternion that is between the current quaternion and the end_quat. The value of t (which should be between 0 and 1) determines the amount of interpolation.

matrix()

template<typename ValueType >

Matrix4 TQuaternion::matrix

Return the transformation matrix that will represent the the Euler angle rotations that this quaternion embodies. Note - this method affects all components of the matrix.

Return the transformation matrix that will represent the the Euler angle rotations that this quaternion embodies.

References DD::Image::Matrix4::transpose().