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.
#include <Quaternion.h>
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
| Quaternion_ | ( | ) | [inline] |
Default constructor produces the ZeroRotation quaternion [1 0 0 0] (not NaN - even in debug mode).
Referenced by Quaternion_< P >::normalize().
| Quaternion_ | ( | const Quaternion_< P > & | q | ) | [inline] |
Zero-cost copy constructor just copies the source without conversion to canonical form or normalization.
| 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.
References Quaternion_< P >::normalizeThis().
| Quaternion_ | ( | const Vec4P & | q | ) | [inline, explicit] |
Construct a quaternion from a 4-vector and normalize the result, which costs about 40 flops.
References Quaternion_< P >::normalizeThis().
| Quaternion_ | ( | const Rotation_< P > & | ) | [explicit] |
Constructs a canonical quaternion from a rotation matrix (cost is about 60 flops).
| 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
| const Vec4P& asVec4 | ( | ) | const [inline] |
Zero-cost cast of a Quaternion_ to its underlying Vec4; this is not converted to axis-angle form.
Referenced by Quaternion_< P >::operator=().
| Vec4P convertQuaternionToAngleAxis | ( | ) | const |
Returns [ a vx vy vz ] with (a,v) in canonical form, i.e., -180 < a <= 180 and |v|=1.
Referenced by Rotation_< Real >::convertRotationToAngleAxis().
| Quaternion_ 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 Vec< 4, P >.
References Quaternion_< P >::Quaternion_().
| Quaternion_& 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.
References Vec< 4, P >::norm(), Quaternion_< P >::setQuaternionToNaN(), and Quaternion_< P >::setQuaternionToZeroRotation().
Referenced by Quaternion_< P >::Quaternion_().
| Quaternion_& operator= | ( | const Quaternion_< P > & | q | ) | [inline] |
Zero-cost copy assignment just copies the source without conversion to canonical form or normalization.
References Quaternion_< P >::asVec4(), and Vec< 4, P >::operator=().
| 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].
The result will be put in canonical form, i.e., it will have a non-negative first element.
| void 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.
| void 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].
References Vec< 4, P >::setToNaN().
Referenced by Quaternion_< P >::normalizeThis().
| void setQuaternionToZeroRotation | ( | ) | [inline] |
The ZeroRotation quaternion is [1 0 0 0].
Note: Default constructor is ZeroRotation (unlike Vec4P which start as NaN in Debug mode).
References Vec< 4, P >::operator=().
Referenced by Quaternion_< P >::normalizeThis().
The documentation for this class was generated from the following file:
