Quaternion Class Reference

#include <Quaternion.h>

Inheritance diagram for Quaternion:

List of all members.

---

Detailed Description

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.

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 (Real e0, Real e1, Real e2, Real e3)
	Construct a quaternion and normalize it.
	Quaternion (const Vec4 &q)
	Quaternion (const Rotation &)
	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 ()
void	setQuaternionFromAngleAxis (const Vec4 &av)
	The quaternion that is set by this method has a non-negative first element (canonical form).
void	setQuaternionFromAngleAxis (const Real &a, const UnitVec3 &v)
Vec4	convertQuaternionToAngleAxis () const
	Returns [ a vx vy vz ] with (a,v) in canonical form, i.e., -180 < a <= 180 and |v|=1.
const Vec4 &	asVec4 () const
	Zero-cost cast of a Quaternion to a Vec4.
Quaternion &	normalizeThis ()
	Normalize an already constructed quaternion.
	Quaternion (const Vec4 &v, bool)
	Use this constructor only if you are *sure* v is normalized to 1.0.

---

Constructor & Destructor Documentation

Quaternion

(

)

[inline]

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

Quaternion

(

const Quaternion &

q

)

[inline]

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

Quaternion	(	Real	e0,
		Real	e1,
		Real	e2,
		Real	e3
	)			[inline]

Construct a quaternion and normalize it.

References Quaternion::normalizeThis().

Quaternion

(

const Vec4 &

q

)

[inline, explicit]

References Quaternion::normalizeThis().

Quaternion

(

const Rotation &

)

[explicit]

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

Quaternion	(	const Vec4 &	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

Quaternion& operator=

(

const Quaternion &

q

)

[inline]

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

References Quaternion::asVec4(), and Vec< 4 >::operator=().

void setQuaternionToZeroRotation

(

)

[inline]

The ZeroRotation quaternion is [1 0 0 0].

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

References Vec< 4 >::operator=().

Referenced by Quaternion::normalizeThis().

void setQuaternionToNaN

(

)

[inline]

References Vec< 4 >::setToNaN().

Referenced by Quaternion::normalizeThis().

void setQuaternionFromAngleAxis

(

const Vec4 &

av

)

The quaternion that is set by this method has a non-negative first element (canonical form).

If the "axis" portion of av is a zero vector, the quaternion is set to all-NaN.

void setQuaternionFromAngleAxis	(	const Real &	a,
		const UnitVec3 &	v
	)

Vec4 convertQuaternionToAngleAxis

(

)

const

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

Referenced by Rotation::convertRotationToAngleAxis().

const Vec4& asVec4

(

)

const [inline]

Zero-cost cast of a Quaternion to a Vec4.

Referenced by Quaternion::operator=().

Quaternion& normalizeThis

(

)

[inline]

Normalize an already constructed quaternion.

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.

References SimTK::norm(), Quaternion::setQuaternionToNaN(), and Quaternion::setQuaternionToZeroRotation().

Referenced by Quaternion::Quaternion().

---

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

• Quaternion.h