Quat Class Reference

#include <quat.h>

Class Description

See also

Class Point3, Class Matrix3, Class AngAxis.

Description:

This class provides a compact representation for orientation in three space and provides methods to perform Quaternion algebra.

Quaternions provide an alternative representation for orientation in three-space. To reduce computing, you can substitute quaternion multiplication for rotation-matrix composition.

A quaternion is made up of four terms: a real scalar part which specifies the amount of rotation and an imaginary vector part which defines the axis of rotation. If the quaternion is normalized, the scalar term equals the cosine of half the angle of rotation, the vector term is the axis of rotation, and the magnitude of the vector term equals the sine of half the angle of rotation.

Interpolation between two key frame orientations is much easier using quaternions and produces smooth and natural motion. Unlike Euler angles, no numerical integration is necessary; quaternions provide an analytic result (no approximations).

The rotation convention in the 3ds Max API is the left-hand-rule. Note that this is different from the right-hand-rule used in the 3ds Max user interface.

For additional information see: Quaternion operations:

From "Quaternion Calculus and Fast Animation",

by Ken Shoemake, in notes for SIGGRAPH 1987 Course # 10,

"Computer Animation: 3-D Motion Specification and Control".

All methods of this class are implemented by the system.

Data Members:

float x,y,z,w;

The x, y, z values make up the vector portion. w is the angle of rotation about the vector (see remarks above for details).

Inheritance diagram for Quat:

Public Member Functions
	Quat ()
	Quat (float X, float Y, float Z, float W)
	Quat (double X, double Y, double Z, double W)
	Quat (const Quat &a)
	Quat (float af[4])
	Quat (const Matrix3 &mat)
	Quat (const AngAxis &aa)
	Quat (const Point3 &V, float W)
float &	operator[] (int i)
const float &	operator[] (int i) const
float	Scalar ()
Point3	Vector ()
	operator float * ()
Quat	operator- () const
Quat	operator+ () const
Quat	Inverse () const
Quat	Conjugate () const
Quat	LogN () const
Quat	Exp () const
Quat &	operator-= (const Quat &)
Quat &	operator+= (const Quat &)
Quat &	operator*= (const Quat &)
Quat &	operator*= (float)
Quat &	operator/= (float)
Quat &	Set (float X, float Y, float Z, float W)
Quat &	Set (double X, double Y, double Z, double W)
Quat &	Set (const Matrix3 &mat)
Quat &	Set (const AngAxis &aa)
Quat &	Set (const Point3 &V, float W)
Quat &	SetEuler (float X, float Y, float Z)
Quat &	Invert ()
Quat &	MakeClosest (const Quat &qto)
int	operator== (const Quat &a) const
int	operator!= (const Quat &a) const
int	Equals (const Quat &a, float epsilon=1E-6f) const
void	Identity ()
int	IsIdentity () const
void	Normalize ()
void	MakeMatrix (Matrix3 &mat, bool flag=false) const
void	GetEuler (float *X, float *Y, float *Z) const
Quat	operator- (const Quat &) const
Quat	operator+ (const Quat &) const
Quat	operator* (const Quat &) const
Quat	operator/ (const Quat &) const
float	operator% (const Quat &) const
Quat	Plus (const Quat &) const
Quat	Minus (const Quat &) const

Public Attributes
float	x
float	y
float	z
float	w

Additional Inherited Members
Static Public Member Functions inherited from MaxHeapOperators
static UtilExport void *	operator new (size_t size)
	Standard new operator used to allocate objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, const std::nothrow_t &e)
	Standard new operator used to allocate objects if there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new (size_t size, const char *filename, int line)
	New operator used to allocate objects that takes the filename and line number where the new was called If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, int block_type, const char *filename, int line)
	New operator used to allocate objects that takes the type of memory, filename and line number where the new was called If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, const std::nothrow_t &e, const char *filename, int line)
	New operator used to allocate objects that takes the filename and line number where the new was called If there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new (size_t size, unsigned long flags)
	New operator used to allocate objects that takes extra flags to specify special operations If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, const std::nothrow_t &e, unsigned long flags)
	New operator used to allocate objects that takes extra flags to specify special operations If there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new[] (size_t size)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new[] (size_t size, const char *filename, int line)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new[] (size_t size, int block_type, const char *filename, int line)
	New operator used to allocate arrays of objects. More...
static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e, const char *filename, int line)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new[] (size_t size, unsigned long flags)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e, unsigned long flags)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...
static UtilExport void	operator delete (void *ptr)
	Standard delete operator used to deallocate an object If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete (void *ptr, const std::nothrow_t &e)
	Standard delete operator used to deallocate an object If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete (void *ptr, const char *filename, int line)
	Delete operator used to deallocate an object that takes the filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete (void *ptr, int block_type, const char *filename, int line)
	Delete operator used to deallocate an object that takes the type of memory, filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete (void *ptr, const std::nothrow_t &e, const char *filename, int line)
	Delete operator used to deallocate an object that takes the filename and line number where the delete was called If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete (void *ptr, unsigned long flags)
	Delete operator used to deallocate an object that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete (void *ptr, const std::nothrow_t &e, unsigned long flags)
	Delete operator used to deallocate an object that takes extra flags to specify special operations If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete[] (void *ptr)
	Standard delete operator used to deallocate an array of objects If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete[] (void *ptr, const std::nothrow_t &e)
	Standard delete operator used to deallocate an array of objects If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete[] (void *ptr, const char *filename, int line)
	Delete operator used to deallocate an array of objects that takes the filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete[] (void *ptr, int block_type, const char *filename, int line)
	Delete operator used to deallocate an array of objects that takes the type of memory, filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete[] (void *ptr, const std::nothrow_t &e, const char *filename, int line)
	Delete operator used to deallocate an array of objects that takes the filename and line number where the delete was called If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete[] (void *ptr, unsigned long flags)
	Delete operator used to deallocate an array of objects that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete[] (void *ptr, const std::nothrow_t &e, unsigned long flags)
	Delete operator used to deallocate an array of objects that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, void *placement_ptr)
	Placement new operator. More...
static UtilExport void	operator delete (void *ptr, void *placement_ptr)
	Placement delete operator. More...
static UtilExport void *	aligned_malloc (size_t size, size_t alignment)
	Allocates memory on a specified alignment boundary. More...
static UtilExport void *	aligned_realloc (void *ptr, size_t size, size_t alignment)
	Reallocates memory on a specified alignment boundary. More...
static UtilExport void	aligned_free (void *ptr)
	Frees a block of memory that was allocated with aligned_malloc/aligned_realloc. More...

Constructor & Destructor Documentation

Quat ( )

inline

Remarks

Constructor.

: x(0.0f),y(0.0f),z(0.0f),w(1.0f) {}

Quat ( float  X, float  Y, float  Z, float  W  )

inline

Remarks

Constructor. The data members are initialized to the values passed.

{ x = X; y = Y; z = Z; w = W; }

Quat ( double  X, double  Y, double  Z, double  W  )

inline

Remarks

Constructor. The data members are initialized to the values passed (cast as floats).

                                                 { 
      x = (float)X; y = (float)Y; z = (float)Z; w = (float)W;  
      }

Quat ( const Quat &  a )

inline

Remarks

Constructor. The data members are initialized to the Quat passed.

{ x = a.x; y = a.y; z = a.z; w = a.w; } 

Quat ( float  af[4] )

inline

Remarks

Constructor. The data members are initialized to the values passed.

x = af[0]; y = af[1]; z = af[2]; w = af[3];

{ x = af[0]; y = af[1]; z = af[2]; w = af[3]; }

Quat

(

const Matrix3 &

mat

)

Remarks

Constructor. Convert the specified 3x3 rotation matrix to a unit quaternion.

Quat

(

const AngAxis &

aa

)

Remarks

Constructor. The Quat is initialized to the AngAxis passed.

Quat	(	const Point3 &	V,
		float	W
	)

Remarks

Constructor. The quaternion is initialized from the vector V and angle W passed. The quaternion is then normalized.

Member Function Documentation

float& operator[] ( int  i )

inline

Remarks

Array access operator. Valid i values: 0=x, 1=y, 2=z, 3=w.

{ return (&x)[i]; }     

const float& operator[] ( int  i ) const

inline

Remarks

Array access operator. Valid i values: 0=x, 1=y, 2=z, 3=w.

{ return (&x)[i]; }

float Scalar ( )

inline

{ return w; }

Point3 Vector ( )

inline

{ return Point3(x, y, z); }

operator float * ( )

inline

Remarks

Returns the address of the Quaternion.

Unary operators

{ return(&x); }

Quat operator- ( ) const

inline

Remarks

Unary negation. Returns Quat(-x,-y,-z,-w).

{ return(Quat(-x,-y,-z,-w)); } 

Quat operator+ ( ) const

inline

Remarks

Unary +. Returns the Quat unaltered.

Assignment operators

{ return *this; }

Quat Inverse

(

)

const

Remarks

Returns the inverse of this quaternion (1/q).

Quat Conjugate

(

)

const

Remarks

Returns the conjugate of a quaternion.

Quat LogN

(

)

const

Remarks

Returns the natural logarithm of a UNIT quaternion.

Quat Exp

(

)

const

Remarks

Returns the exponentiate quaternion (where q.w==0).

Operators:

Quat& operator-=

(

const Quat &

)

Remarks

This operator is the same as the /= operator.

Quat& operator+=

(

const Quat &

)

Remarks

This operator is the same as the *= operator..

Quat& operator*=

(

const Quat &

)

Remarks

Multiplies this quaternion by a quaternion.

Quat& operator*=

(

float

)

Remarks

Multiplies this quaternion by a floating point value.

Quat& operator/=

(

float

)

Remarks

Divides this quaternion by a floating point value.

Quat& Set ( float  X, float  Y, float  Z, float  W  )

inline

      { x = X; y = Y; z = Z; w = W; return *this; }

Quat& Set ( double  X, double  Y, double  Z, double  W  )

inline

      { x = (float)X; y = (float)Y; z = (float)Z; w = (float)W;
        return *this; }

Quat& Set

(

const Matrix3 &

mat

)

Quat& Set

(

const AngAxis &

aa

)

Quat& Set ( const Point3 &  V, float  W  )

inline

      { x = V.x; y = V.y; z = V.z; w = W; return *this; } 

Quat& SetEuler	(	float	X,
		float	Y,
		float	Z
	)

Quat& Invert

(

)

Quat& MakeClosest

(

const Quat &

qto

)

Remarks

Modifies q so it is on same side of hypersphere as qto.

int operator==

(

const Quat &

a

)

const

Remarks

Returns nonzero if the quaternions are equal; otherwise 0.

int operator!=

(

const Quat &

a

)

const

int Equals	(	const Quat &	a,
		float	epsilon = 1E-6f
	)		const

void Identity ( )

inline

Remarks

Sets this quaternion to the identity quaternion (x=y=z=0.0; w=1.0).

{ x = y = z = 0.0f; w = 1.0f; }

int IsIdentity

(

)

const

Remarks

Returns nonzero if the quaternion is the identity; otherwise 0.

void Normalize

(

)

Remarks

Normalizes this quaternion, dividing each term by a scale factor such that the resulting sum or the squares of all parts equals unity.

void MakeMatrix	(	Matrix3 &	mat,
		bool	flag = false
	)		const

Remarks

Converts the quaternion to a 3x3 rotation matrix. The quaternion need not be unit magnitude.

Parameters:

Matrix3 &mat

The matrix.

BOOL b=FALSE

This parameter is available in release 4.0 and later only.

When this argument is set to false (or omitted), each function performs as it did before version 4.0. When the boolean is TRUE, the matrix is made with its terms transposed. When this transposition is specified, EulerToQuat() and QuatToEuler() are consistent with one another. (In 3ds Max 3, they have opposite handedness).

void GetEuler	(	float *	X,
		float *	Y,
		float *	Z
	)		const

Quat operator-

(

const Quat &

)

const

Remarks

This operator is the same as the / operator.

Quat operator+

(

const Quat &

)

const

Remarks

This operator is the same as the * operator.

Quat operator*

(

const Quat &

)

const

Remarks

Returns the product of two quaternions.

Quat operator/

(

const Quat &

)

const

Remarks

Returns the ratio of two quaternions: This creates a result quaternion r = p/q, such that q*r = p. (Order of multiplication is important)

float operator%

(

const Quat &

)

const

Quat Plus

(

const Quat &

)

const

Quat Minus

(

const Quat &

)

const

Member Data Documentation

float x

float y

float z

float w