SimTK::Quaternion_< P > Class Template Reference

A Quaternion is a Vec4 with the following behavior:

• its length is always 1 (or else it is all NaN)
• it is equivalent to an angle/axis rotation for angle a, axis unit vector v, as: q = [ cos(a/2) sin(a/2)*v ] A quaternion is in "canonical form" when its first element is nonnegative.

More...

#include <Quaternion.h>

Inheritance diagram for SimTK::Quaternion_< P >:

List of all members.

Public Member Functions
	Quaternion_ ()
	Default constructor produces the ZeroRotation quaternion [1 0 0 0] (not NaN - even in debug mode).
	Quaternion_ (const Quaternion_ &q)
	Zero-cost copy constructor just copies the source without conversion to canonical form or normalization.
Quaternion_ &	operator= (const Quaternion_ &q)
	Zero-cost copy assignment just copies the source without conversion to canonical form or normalization.
	Quaternion_ (RealP e0, RealP e1, RealP e2, RealP e3)
	Construct a quaternion from four scalars and normalize the result, which costs about 40 flops.
	Quaternion_ (const Vec4P &q)
	Construct a quaternion from a 4-vector and normalize the result, which costs about 40 flops.
	Quaternion_ (const Rotation_< P > &)
	Constructs a canonical quaternion from a rotation matrix (cost is about 60 flops).
void	setQuaternionToZeroRotation ()
	The ZeroRotation quaternion is [1 0 0 0].
void	setQuaternionToNaN ()
	Set quaternion to all-NaN.
void	setQuaternionFromAngleAxis (const Vec4P &av)
	Set this quaternion from an angle-axis rotation packed into a 4-vector as [a vx vy vz].
void	setQuaternionFromAngleAxis (const RealP &a, const UnitVec< P, 1 > &v)
	Set this quaternion from an angle-axis rotation provided as an angle a and a separate unit vector [vx vy vz].
Vec4P	convertQuaternionToAngleAxis () const
	Returns [ a vx vy vz ] with (a,v) in canonical form, i.e., -180 < a <= 180 and |v|=1.
const Vec4P &	asVec4 () const
	Zero-cost cast of a Quaternion_ to its underlying Vec4; this is not converted to axis-angle form.
Quaternion_ &	normalizeThis ()
	Normalize an already constructed quaternion in place; but do you really need to do this? Quaternions should be kept normalized at all times.
Quaternion_	normalize () const
	Return a normalized copy of this quaternion; but do you really need to do this? Quaternions should be kept normalized at all times.
	Quaternion_ (const Vec4P &v, bool)
	Use this constructor only if you are *sure* v is normalized to 1.0.

---

Detailed Description

template<class P>
class SimTK::Quaternion_< P >

A Quaternion is a Vec4 with the following behavior:

• its length is always 1 (or else it is all NaN)
• it is equivalent to an angle/axis rotation for angle a, axis unit vector v, as: q = [ cos(a/2) sin(a/2)*v ] A quaternion is in "canonical form" when its first element is nonnegative.

This corresponds to rotation angles in the range -180 < a <= 180 degrees. Quaternions are not required to be in canonical form (e.g., during numerical integration). When appropriate, they are put in canonical form.

Conversion from quaternion to (angle,axis) form is handled here also. (angle,axis) is in canonical form when -180 < angle <= 180 and |axis|=1. However, (angle,axis) is meaningful for any angle and for any axis where |axis| > 0.

---

Constructor & Destructor Documentation

template<class P >

SimTK::Quaternion_< P >::Quaternion_

(

)

[inline]

Default constructor produces the ZeroRotation quaternion [1 0 0 0] (not NaN - even in debug mode).

template<class P >

SimTK::Quaternion_< P >::Quaternion_

(

const Quaternion_< P > &

q

)

[inline]

Zero-cost copy constructor just copies the source without conversion to canonical form or normalization.

template<class P >

SimTK::Quaternion_< P >::Quaternion_	(	RealP	e0,
		RealP	e1,
		RealP	e2,
		RealP	e3
	)		[inline]

Construct a quaternion from four scalars and normalize the result, which costs about 40 flops.

template<class P >

SimTK::Quaternion_< P >::Quaternion_

(

const Vec4P &

q

)

[inline, explicit]

Construct a quaternion from a 4-vector and normalize the result, which costs about 40 flops.

template<class P >

SimTK::Quaternion_< P >::Quaternion_

(

const Rotation_< P > &

)

[explicit]

Constructs a canonical quaternion from a rotation matrix (cost is about 60 flops).

template<class P >

SimTK::Quaternion_< P >::Quaternion_	(	const Vec4P &	v,
		bool
	)		[inline]

Use this constructor only if you are *sure* v is normalized to 1.0.

This zero cost method is faster than the Quaternion(Vec4) constructor which normalizes the Vec4. The second argument forces the compiler to call the fast constructor; it is otherwise ignored. By convention, set the second argument to "true".

---

Member Function Documentation

template<class P >

Quaternion_& SimTK::Quaternion_< P >::operator=

(

const Quaternion_< P > &

q

)

[inline]

Zero-cost copy assignment just copies the source without conversion to canonical form or normalization.

template<class P >

void SimTK::Quaternion_< P >::setQuaternionToZeroRotation

(

)

[inline]

The ZeroRotation quaternion is [1 0 0 0].

Note: Default constructor is ZeroRotation (unlike Vec4P which start as NaN in Debug mode).

template<class P >

void SimTK::Quaternion_< P >::setQuaternionToNaN

(

)

[inline]

Set quaternion to all-NaN.

Note that this is not the same as produced by default construction, even in Debug mode -- default construction always produces an identity rotation of [1 0 0 0].

template<class P >

void SimTK::Quaternion_< P >::setQuaternionFromAngleAxis

(

const Vec4P &

av

)

Set this quaternion from an angle-axis rotation packed into a 4-vector as [a vx vy vz].

The result will be put in canonical form, i.e., it will have a non-negative first element. If the "axis" portion of av is a zero vector on input, the quaternion is set to all-NaN.

template<class P >

void SimTK::Quaternion_< P >::setQuaternionFromAngleAxis	(	const RealP &	a,
		const UnitVec< P, 1 > &	v
	)

Set this quaternion from an angle-axis rotation provided as an angle a and a separate unit vector [vx vy vz].

The result will be put in canonical form, i.e., it will have a non-negative first element.

template<class P >

Vec4P SimTK::Quaternion_< P >::convertQuaternionToAngleAxis

(

)

const

Returns [ a vx vy vz ] with (a,v) in canonical form, i.e., -180 < a <= 180 and |v|=1.

template<class P >

const Vec4P& SimTK::Quaternion_< P >::asVec4

(

)

const [inline]

Zero-cost cast of a Quaternion_ to its underlying Vec4; this is not converted to axis-angle form.

template<class P >

Quaternion_& SimTK::Quaternion_< P >::normalizeThis

(

)

[inline]

Normalize an already constructed quaternion in place; but do you really need to do this? Quaternions should be kept normalized at all times.

One of the advantages of using them is that you don't have to check if they are normalized or renormalize them. However, under some situations they do need renormalization, but it is costly if you don't actually need it. If the quaternion is exactly zero, set it to [1 0 0 0]. If its magnitude is 0 < magnitude < epsilon (epsilon is machine tolerance), set it to NaN (treated as an error). Otherwise, normalize the quaternion which costs about 40 flops. The quaternion is NOT put in canonical form.

template<class P >

Quaternion_ SimTK::Quaternion_< P >::normalize

(

)

const [inline]

Return a normalized copy of this quaternion; but do you really need to do this? Quaternions should be kept normalized at all times.

One of the advantages of using them is that you don't have to check if they are normalized or renormalize them. However, under some situations they do need renormalization, but it is costly if you don't actually need it.

See also:

normalizeThis() for details.

Reimplemented from SimTK::Vec< 4, P >.

---

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

• Quaternion.h