Public Member Functions | Public Attributes | Static Public Attributes | Friends

MQuaternion Class Reference

Search for all occurrences

Detailed Description

Quaternion math.

This class provides methods for working with Quaternions. Quaternions can be used to specify orientations and rotations of 3-D objects relative to a starting reference, similar to the way that cartesian vectors can be used to specify positions and translations of 3-D objects relative to an origin. Quaternions represent orientations as a single rotation, just as rectangular co-ordinates represent position as a single vector.

Examples:

customAttrManip.cpp, hwReflectBumpShader_NV20.h, hwRefractReflectShader_NV20.cpp, and rockingTransform.cpp.

#include <MQuaternion.h>

List of all members.

Public Member Functions

 MQuaternion ()
 The default class constructor.
 MQuaternion (const MQuaternion &src)
 The copy constructor.
 MQuaternion (double xx, double yy, double zz, double ww)
 Class constructor.
 MQuaternion (const double q[4])
 Class constructor.
 MQuaternion (const MVector &a, const MVector &b)
 Class constructor.
 MQuaternion (const MVector &a, const MVector &b, double angleFactor)
 Class constructor.
 MQuaternion (double angle, const MVector &axisb)
 This constructor creates a new quaternion whose rotation is expressed by a pivot axis and a rotation (in radians) about that axis.
 ~MQuaternion ()
 Class destructor.
MQuaternionoperator= (const MQuaternion &src)
 The assignment operator.
MQuaternionoperator= (const MMatrix &matrix)
 Convert the given 4X4 homogeneous rotation matrix to a quaternion of unit length.
MQuaternionoperator= (const MEulerRotation &matrix)
 Convert the given euler rotation to a quaternion.
MMatrix asMatrix () const
 Converts a quaternion to a 4X4 homogeneous rotation matrix.
MEulerRotation asEulerRotation () const
 Converts a quaternion to an euler rotation.
MQuaternionsetAxisAngle (const MVector &axis, double theta)
 Sets this quaternion to be the rotation as expressed by a pivot axis and a rotation theta (in radians) about that axis.
bool getAxisAngle (MVector &axis, double &theta) const
 Converts this quaternion into a user understandable representation.
MQuaternionsetToXAxis (double theta)
 Sets this quaternion to be the rotation about the X axis of theta (in radians).
MQuaternionsetToYAxis (double theta)
 Sets this quaternion to be the rotation about the Y axis of theta (in radians).
MQuaternionsetToZAxis (double theta)
 Sets this quaternion to be the rotation about the Z axis of theta (in radians).
MStatus get (double dest[4]) const
 Extracts the x, y, z, and w components of the quaternion and places them in elements 0, 1, 2, and 3 of the double array passed.
double operator[] (unsigned int i) const
 The index operator.
MQuaternion operator+ (const MQuaternion &other) const
 The quaternion addition operator.
MQuaternion operator* (const MQuaternion &other) const
 This quaternion multiplication operator.
MQuaternionoperator*= (const MQuaternion &rhs)
 The in place quaternion multiplication operator.
MQuaternion operator- (const MQuaternion &other) const
 The quaternion subtraction operator.
MQuaternion operator- () const
 The unary minus operator.
MQuaternionnegateIt ()
 Performs an in place negation of the quaternion.
bool operator== (const MQuaternion &other) const
 The quaternion equality operator.
bool operator!= (const MQuaternion &other) const
 The quaternion inequality operator.
bool isEquivalent (const MQuaternion &other, double tolerance=kQuaternionEpsilon) const
 This method returns true if this quaternion is equal, within some given tolerance, to the other quaternion.
MQuaternionscaleIt (double scale)
 Performs an in place scaling of the quaternion.
MQuaternion normal () const
 Returns the normal of this quaternion.
MQuaternionnormalizeIt ()
 Performs an in place normalization of this quaternion.
MQuaternion conjugate () const
 Returns the conjugate of this quaternion.
MQuaternionconjugateIt ()
 Performs an in place conjugation of this quaternion.
MQuaternion inverse () const
 Returns the inverse of this quaternion.
MQuaternioninvertIt ()
 Performs an in place inversion of this quaternion.
MQuaternion log () const
 Returns the natural log of a quaternion.
MQuaternion exp () const
 Exponentiates a quaternion that has a scalar part of zero.
double & operator[] (unsigned int i)
 NO SCRIPT SUPPORT.
 operator MMatrix () const
 NO SCRIPT SUPPORT.

Public Attributes

double x
 The quaternion's imaginary x component.
double y
 The quaternion's imaginary y component.
double z
 The quaternion's imaginary z component.
double w
 The quaternion's real component.

Static Public Attributes

static const MQuaternion identity
 The multiplicative identity.

Friends

OPENMAYA_EXPORT MQuaternion operator* (double scale, const MQuaternion &other)
 NO SCRIPT SUPPORT.
OPENMAYA_EXPORT MQuaternion slerp (const MQuaternion &p, const MQuaternion &q, double t)
 Spherical linear interpolation (abbreviated as slerp) of unit quaternions.
OPENMAYA_EXPORT MQuaternion slerp (const MQuaternion &p, const MQuaternion &q, double t, short spin)
 NO SCRIPT SUPPORT.
OPENMAYA_EXPORT MQuaternion squad (const MQuaternion &p, const MQuaternion &a, const MQuaternion &b, const MQuaternion &q, double t)
 NO SCRIPT SUPPORT.
OPENMAYA_EXPORT MQuaternion squad (const MQuaternion &p, const MQuaternion &a, const MQuaternion &b, const MQuaternion &q, double t, short spin)
 NO SCRIPT SUPPORT.
OPENMAYA_EXPORT MQuaternion squadPt (const MQuaternion &q0, const MQuaternion &q1, const MQuaternion &q2)
 NO SCRIPT SUPPORT.
OPENMAYA_EXPORT std::ostream & operator<< (std::ostream &os, const MQuaternion &q)
 NO SCRIPT SUPPORT.

Constructor & Destructor Documentation

The default class constructor.

Initializes the quaternion to the multiplicative identity.

MQuaternion ( const MQuaternion src)

The copy constructor.

Creates a new quaternion and initializes it to the same values as the given quaternion.

Parameters:
[in]srcthe quaternion object to copy
MQuaternion ( double  xx,
double  yy,
double  zz,
double  ww 
)

Class constructor.

Initializes the quaternion with the explicit x, y, z, and w values provided as arguments.

Parameters:
[in]xxthe x component of the quaternion
[in]yythe y component of the quaternion
[in]zzthe z component of the quaternion.
[in]wwthe w component of the quaternion.
MQuaternion ( const double  q[4])

Class constructor.

Initializes the quaternion with the explicit x, y, z, and w values provided in the given double array.

Parameters:
[in]qthe 4 element array containing the initial x, y, z, and w values
MQuaternion ( const MVector a,
const MVector b 
)

Class constructor.

Creates a new quaternion that will rotate vector a into vector b about their mutually perpendicular axis.

Parameters:
[in]avector to rotate from
[in]bvector to rotate to
MQuaternion ( const MVector a,
const MVector b,
double  angleFactor 
)

Class constructor.

Creates a new quaternion that will rotate vector a into vector b about their mutually perpendicular axis by a given factor.

Parameters:
[in]avector to rotate from
[in]bvector to rotate to
[in]angleFactorthe factor by which the rotation should be multiplied; a factor of 1.0 is equivalent to a rotation of vector a into vector b
MQuaternion ( double  angle,
const MVector axis 
)

This constructor creates a new quaternion whose rotation is expressed by a pivot axis and a rotation (in radians) about that axis.

If the length of the axis is too small the quaternion returned will be the identity quaternion.

Parameters:
[in]anglethe amount of rotation around the axis
[in]axisthe axis about which the rotation occurs

Member Function Documentation

MQuaternion & operator= ( const MQuaternion src)

The assignment operator.

Parameters:
[in]srcthe source quaternion
Returns:
A reference to the quaternion that has been assigned to the source quaternion
MQuaternion & operator= ( const MMatrix matrix)

Convert the given 4X4 homogeneous rotation matrix to a quaternion of unit length.

This methods always returns a quaternion of unit length if it is given a proper orthogonal matrix. A proper othogonal matrix is one such that the determinant of the matrix is one. (If the determinant were -1, this would imply that the orthogonal matrix is also producing a reflection, in addition to a rotation.)

Parameters:
[in]matrixthe matrix to be converted to a quaternion
Returns:
A reference to the quaternion that has been converted from the rotation matrix
MQuaternion & operator= ( const MEulerRotation euler)

Convert the given euler rotation to a quaternion.

Parameters:
[in]eulerthe euler rotation to be converted to a quaternion
Returns:
A reference to the quaternion that has been converted from the euler rotation
MMatrix asMatrix ( ) const

Converts a quaternion to a 4X4 homogeneous rotation matrix.

The construction of the matrix assumes that the vectors are going to be multiplied on the left side of the matrix. If the quaternion's length has degenerated, this method will still produce a well behaved matrix.

ReturnValue

  • the matrix converted from a quaternion
Examples:
rockingTransform.cpp.
MEulerRotation asEulerRotation ( ) const

Converts a quaternion to an euler rotation.

ReturnValue

  • the euler rotation converted from a quaternion
MQuaternion & setAxisAngle ( const MVector axis,
double  theta 
)

Sets this quaternion to be the rotation as expressed by a pivot axis and a rotation theta (in radians) about that axis.

If the axis is too small the quaternion returned will be the identity quaternion.

Parameters:
[in]axisthe axis about which to rotate
[in]thetathe angle of rotation about the axis in radians
Returns:
A reference to the quaternion that has had its axis and angle set
bool getAxisAngle ( MVector axis,
double &  theta 
) const

Converts this quaternion into a user understandable representation.

That is, the quaternion is represented as a pivot vector 'axis' and a rotation 'theta' (in radians) about that pivot vector.

If the identity unit quaternion is attempted to be converted to the pivot axis and angle representation it will be set to a zero degree rotation about the axis that was passed in. (Note that any axis will do, since an infinity of axis with rotation of zero satisfy the identity rotation.) If the axis is zero length, then an arbitrary axis will be chosen (z-axis).

Parameters:
[out]axisthe axis about which the rotation occurs
[out]thetathe angle of rotation about the axis in radians
Returns:
  • true angle != 0
  • false angle == 0 (uses arbitrary axis, if given axis not valid)
Examples:
hwRefractReflectShader_NV20.cpp.
MQuaternion & setToXAxis ( double  theta)

Sets this quaternion to be the rotation about the X axis of theta (in radians).

If the length of the axis is too small the quaternion returned will be the identity quaternion.

Parameters:
[in]thetathe angle of rotation about the X axis in radians
Returns:
A reference to the quaternion that has been set to rotate about the X axis by the given amount
Examples:
rockingTransform.cpp.
MQuaternion & setToYAxis ( double  theta)

Sets this quaternion to be the rotation about the Y axis of theta (in radians).

If the length of the axis is too small the quaternion returned will be the identity quaternion.

Parameters:
[in]thetathe angle of rotation about the Y axis in radians
Returns:
A reference to the quaternion that has been set to rotate about the Y axis by the given amount
MQuaternion & setToZAxis ( double  theta)

Sets this quaternion to be the rotation about the Z axis of theta (in radians).

If the length of the axis is too small the quaternion returned will be the identity quaternion.

Parameters:
[in]thetathe angle of rotation about the Z axis in radians
Returns:
A reference to the quaternion that has been set to rotate about the Z axis by the given amount
MStatus get ( double  dest[4]) const

Extracts the x, y, z, and w components of the quaternion and places them in elements 0, 1, 2, and 3 of the double array passed.

Parameters:
[out]destthe array of 4 doubles into which the results are placed.
Returns:
MS::kSuccess if dest is a non-zero pointer and MS::kFailure otherwise
double operator[] ( unsigned int  i) const

The index operator.

If its argument is 0 it will return the x component of the quaternion. If its argument is 1 it will return the y component of the quaternion. If its argument is 2 it will return the z component of the quaternion. If its argument is 3 it will return the w component of the quaternion.

Parameters:
[in]ivalue indicating which component to return
Returns:
The component of the quaternion corresponding to the index
MQuaternion operator+ ( const MQuaternion other) const

The quaternion addition operator.

Parameters:
[in]otherthe quaternion to be added to this quaternion
Returns:
The sum of the two quaternions
MQuaternion operator* ( const MQuaternion other) const

This quaternion multiplication operator.

Quaternions in Maya multiply on the right (post-multiply) the same as matrices. Many popular quaternion papers (Shoemake) use pre-multiplication where quaternions pre-multiply on the left so you must be aware of this when using quaternions.

In general, if p and q are quaternions, pq != qp, i.e., multiplication does not commute!

Parameters:
[in]otherthe quaternion to be multiplied with this quaternion
Returns:
The product of the two quaternions
MQuaternion & operator*= ( const MQuaternion other)

The in place quaternion multiplication operator.

Quaternions in Maya multiply on the right (post-multiply) the same as matrices.

Parameters:
[in]otherthe quaternion to be multiplied with this quaternion
Returns:
A reference to this quaternion which has been multiplied with the other quaternion
MQuaternion operator- ( const MQuaternion other) const

The quaternion subtraction operator.

Parameters:
[in]otherthe quaternion to be subtracted from this quaternion
Returns:
The quaternion that results from the subtraction
MQuaternion operator- ( ) const

The unary minus operator.

Negates the value of each of the x, y, z, and w components of the quaternion.

Returns:
Quaternion that results from the negation
MQuaternion & negateIt ( )

Performs an in place negation of the quaternion.

The result is a quaternion whose x, y, z, and w values have been negated.

Returns:
A reference to the quaternion that has been negated
bool operator== ( const MQuaternion other) const

The quaternion equality operator.

This returns true if all four of the x, y, z, and w components are identical.

Parameters:
[in]otherthe quaternion to be compared with this quaternion
Returns:
  • true the quaternions are identical
  • false the quaternions are not identical
bool operator!= ( const MQuaternion other) const

The quaternion inequality operator.

This returns false if all four of the x, y, z, and w components are identical.

Parameters:
[in]otherthe quaternion to be compared with this quaternion
Returns:
  • true the quaternions are not identical
  • false the quaternions are identical
bool isEquivalent ( const MQuaternion other,
double  tolerance = kQuaternionEpsilon 
) const

This method returns true if this quaternion is equal, within some given tolerance, to the other quaternion.

'tolerance' defaults to kQuaternionEpsilon which is 1.0e-10

Parameters:
[in]otherthe quaternion to be compared with this quaternion
[in]tolerancethe amount of variation allowed for equivalency
Returns:
  • true the quaternions are equivalent
  • false the quaternions are not equivalent
MQuaternion & scaleIt ( double  scale)

Performs an in place scaling of the quaternion.

The result is a quaternion whose x, y, z, and w values have been scaled by the specified amount.

Parameters:
[in]scalethe amount by which the quaternion should be scaled
Returns:
A reference to the quaternion that has been scaled
MQuaternion normal ( ) const

Returns the normal of this quaternion.

The result is a quaternion of unit length.

If the quaternion is zero or has a very small length it will instead be set to the multiplicative identity.

Returns:
Quaternion that is the normal of this quaternion
MQuaternion & normalizeIt ( )

Performs an in place normalization of this quaternion.

The result is a quaternion of unit length.

If the quaternion is zero or has a very small length it will instead be set to the multiplicative identity.

Returns:
A reference to the quaternion that has been normalized
MQuaternion conjugate ( ) const

Returns the conjugate of this quaternion.

The result is a quaternion whose x, y, and z values have been negated.

Returns:
Quaternion that is the conjugate of this quaternion
MQuaternion & conjugateIt ( )

Performs an in place conjugation of this quaternion.

The result is a quaternion whose x, y, and z values have been negated.

Returns:
A reference to the quaternion that has been conjugated
MQuaternion inverse ( ) const

Returns the inverse of this quaternion.

Returns:
Quaternion that is the inverse of this quaternion
MQuaternion & invertIt ( )

Performs an in place inversion of this quaternion.

Returns:
A reference to the quaternion that has been inverted
MQuaternion log ( ) const

Returns the natural log of a quaternion.

The precondition for using this method is that the quaternion must be normalized.

Note that the log of a unit quaternion is not necessarily a unit quaternion.

Returns:
Quaternion that is the log of this quaternion
MQuaternion exp ( ) const

Exponentiates a quaternion that has a scalar part of zero.

The precondition for using this method is that w is zero.

Returns:
Quaternion that is the result of exponentiating this quaternion
double & operator[] ( unsigned int  i)

NO SCRIPT SUPPORT.

The index operator.

If its argument is 0 it will return the x component of the quaternion. If its argument is 1 it will return the y component of the quaternion. If its argument is 2 it will return the z component of the quaternion. If its argument is 3 it will return the w component of the quaternion.

Parameters:
[in]ivalue indicating which component to return
Returns:
A reference to the component of the quaternion corresponding to the index
operator MMatrix ( ) const

NO SCRIPT SUPPORT.

Casts a quaternion to a matrix.

Returns:
A matrix that is casted from a quaternion

Friends And Related Function Documentation

OPENMAYA_EXPORT MQuaternion operator* ( double  scale,
const MQuaternion other 
) [friend]

NO SCRIPT SUPPORT.

Parameters:
[in]scalethe amount by which the quaternion should be scaled
[in]otherthe quaternion to which the scale should be applied
Returns:
Quaternion that is the result of scaling the other quaternion
OPENMAYA_EXPORT MQuaternion slerp ( const MQuaternion p,
const MQuaternion q,
double  t 
) [friend]

Spherical linear interpolation (abbreviated as slerp) of unit quaternions.

As t goes from 0 to 1, the quaternion returned goes from p to q. The interpolation always takes shortest path (in quaternion space) from p to q.

Parameters:
[in]pquaternion to rotate from
[in]qquaternion to rotate to
[in]tinterpolation value
Returns:
Quaternion that has been interpolated from p to q
OPENMAYA_EXPORT MQuaternion slerp ( const MQuaternion p,
const MQuaternion q,
double  t,
short  spin 
) [friend]

NO SCRIPT SUPPORT.

As t goes from 0 to 1, the quaternion returned goes from p to q. The spin parameter determines how many complete revolutions around the axis will occur as p goes to q. Negative spins will take the "long way" around the great sphere when rotating. (-1 can be used to interpolate using the "long" path on the quaternion sphere without any extra spins.)

Parameters:
[in]pquaternion to rotate from
[in]qquaternion to rotate to
[in]tinterpolation value
[in]spinthe number of complete revolutions around the axis
Returns:
Quaternion that has been interpolated from p to q
OPENMAYA_EXPORT MQuaternion squad ( const MQuaternion p,
const MQuaternion a,
const MQuaternion b,
const MQuaternion q,
double  t 
) [friend]

NO SCRIPT SUPPORT.

Need to use squadPoint or some other suitable method for finding a and b

Parameters:
[in]pquaternion to rotate from
[in]aintermediate squad point
[in]bintermediate squad point
[in]qquaternion to rotate to
[in]tinterpolation value
Returns:
Quaternion that has been interpolated from p to q
OPENMAYA_EXPORT MQuaternion squad ( const MQuaternion p,
const MQuaternion a,
const MQuaternion b,
const MQuaternion q,
double  t,
short  spin 
) [friend]

NO SCRIPT SUPPORT.

Need to use squadPoint or some other suitable method for finding a and b

Parameters:
[in]pquaternion to rotate from
[in]aintermediate squad point
[in]bintermediate squad point
[in]qquaternion to rotate to
[in]tinterpolation value
[in]spinnumber of full spins
Returns:
Quaternion that has been interpolated from p to q
OPENMAYA_EXPORT MQuaternion squadPt ( const MQuaternion q0,
const MQuaternion q1,
const MQuaternion q2 
) [friend]

NO SCRIPT SUPPORT.

This method uses the average of the tangents of arcs to adjacent points. Therefore, to squad from p to q we need to find a and b in the following manner:

Given: unit quaternion control points we wish to interpolate (q0, q1,..., p-1, p, q, q+1,..., qN)

Want: a, b such that squad(p, a, b, q, t) generates a C1 continuous cubic curve from p to q as we vary t from 0 to 1.

Calculation: a = squadPoint(p-1, p, q); b = squadPoint(p, q, q+1);

Notes: We only need to compute one squadPoint for each segment (except at endpoints) since the next 'a' value is simply our current 'b' value (ie. a(i) = b(i-1) or b(i) = a(i+1)).

Parameters:
[in]q0quaternion from which the squad is computed
[in]q1quaternion from which the squad is computed
[in]q2quaternion from which the squad is computed
Returns:
Unit quaternion resulting from the squad computation
OPENMAYA_EXPORT std::ostream& operator<< ( std::ostream &  os,
const MQuaternion q 
) [friend]

NO SCRIPT SUPPORT.

The format used is [x: x, y: y, z: z, w: w].

Parameters:
[in]osthe ostream to print to
[in]qthe quaternion to be printed
Returns:
The ostream reference, os, provided as the first parameter.

MQuaternion MQuaternion MQuaternion MQuaternion MQuaternion MQuaternion MQuaternion MQuaternion MQuaternion MQuaternion
MQuaternion MQuaternion MQuaternion MQuaternion MQuaternion MQuaternion MQuaternion MQuaternion MQuaternion MQuaternion