Detailed Description

Implementation of a quaternion q=a+bi+cj+dk.

A quaternion is often noted q=(s,v) where s is a scalar and v is a 3D vector, or either noted q=(W,X,Y,Z), where W, X, Y and Z are scalar, and X, Y and Z are the components of vector v in previous notation.

You can set a quaternion using various rotation representation with the help of the CRotation class.

See also:: CRotation, CTransformation

Example:

Using CRotation to construct a CQuaternion from various rotation representations.

        using namespace XSI;
        using namespace MATH;

        CVector3 eulerAngles( PI, PI * 2.0, PI / 2.0 );
        CRotation eulerAnglesRot( eulerAngles, CRotation::siXYZ );
        CQuaternion quat( eulerAnglesRot );

        CVector3 axis( 1.0, 2.0, 3.0 );
        CRotation axisAngleRot( axis, PI );
        quat = axisAngleRot;

        CMatrix3 identityMatrix;
        quat.SetFromRotation( CRotation(identityMatrix) );

Example: Performing linear extrapolation using quaternions

        // Quaternion linear extrapolation example
        using namespace XSI;
        using namespace MATH;

        Application app;
        Model root = app.GetActiveSceneRoot();

        // define start and end point for rotation
        CQuaternion startQuat;
        CRotation rotationEnd( CVector3( PI, 0.0, 0.0 ) );
        CQuaternion endQuat( rotationEnd );

        // number of interpolation to perform + interpolation increment
        const size_t nbInterpolations = 10;
        const double interpolationIncrement = 1.0 / nbInterpolations;

        CQuaternion interpolatedQuaternion;
        CRotation currentRotation;
        X3DObject currentObject;
        CVector3 rotationAngles;

        // Create cubes rotated using interpolated values
        for ( double i = 0.0; i < 1.0; i += interpolationIncrement )
        {
            // interpolate values
            interpolatedQuaternion.Slerp( startQuat, endQuat, i );

            // create cube
            root.AddGeometry( L"Cube", L"MeshSurface", L"", currentObject );

            // apply interpolated value in X
            currentRotation = interpolatedQuaternion;
            rotationAngles = currentRotation.GetXYZAngles();
            KinematicState globalKS = currentObject.GetKinematics().GetGlobal();
            globalKS.PutParameterValue( L"rotx",
                (double)RadiansToDegrees(rotationAngles.GetX()));
        }

#include <xsi_quaternion.h>

List of all members.

Public Member Functions
SICPPSDK_INLINE	CQuaternion ()
SICPPSDK_INLINE	CQuaternion (const CQuaternion &in_quaternion)
	~CQuaternion ()
SICPPSDK_INLINE CQuaternion &	operator= (const CQuaternion &in_quaternion)
SICPPSDK_INLINE	CQuaternion (const double in_dW, const double in_dX, const double in_dY, const double in_dZ)
SICPPSDK_INLINE	CQuaternion (const CVector3 &in_vct)
SICPPSDK_INLINE	CQuaternion (const CVector4 &in_vct)
SICPPSDK_INLINE	CQuaternion (const CRotation &in_Rot)
CQuaternion &	operator= (const CRotation &in_Rot)
CQuaternion &	SetFromRotation (const CRotation &in_Rot)
CRotation	GetRotation () const
CQuaternion &	Normalize ()
bool	EpsilonEquals (const CQuaternion &in_Quat, double in_dEpsilon) const
SICPPSDK_INLINE bool	Equals (const CQuaternion &in_Quat) const
SICPPSDK_INLINE bool	operator== (const CQuaternion &in_Quat) const
CQuaternion &	Slerp (const CQuaternion &in_Quat1, const CQuaternion &in_Quat2, double in_dU)
SICPPSDK_INLINE CQuaternion &	operator*= (const CQuaternion &in_Quat)
SICPPSDK_INLINE CQuaternion &	MulInPlace (const CQuaternion &in_Quat)
SICPPSDK_INLINE CQuaternion &	Mul (const CQuaternion &in_Quat1, const CQuaternion &in_Quat2)
SICPPSDK_INLINE CQuaternion &	operator-= (const CQuaternion &in_Quat)
SICPPSDK_INLINE CQuaternion &	SubInPlace (const CQuaternion &in_Quat)
SICPPSDK_INLINE CQuaternion &	Sub (const CQuaternion &in_Quat1, const CQuaternion &in_Quat2)
SICPPSDK_INLINE CQuaternion &	NegateInPlace ()
SICPPSDK_INLINE CQuaternion &	Negate (const CQuaternion &in_Quat)
double	GetLengthSquared () const
double	GetLength () const
SICPPSDK_INLINE CQuaternion &	operator+= (const CQuaternion &in_Quat)
SICPPSDK_INLINE CQuaternion &	AddInPlace (const CQuaternion &in_Quat)
SICPPSDK_INLINE CQuaternion &	Add (const CQuaternion &in_Quat1, const CQuaternion &in_Quat2)
SICPPSDK_INLINE CQuaternion &	ConjugateInPlace ()
SICPPSDK_INLINE CQuaternion &	Conjugate (const CQuaternion &in_Quat)
SICPPSDK_INLINE CQuaternion &	InvertInPlace ()
SICPPSDK_INLINE CQuaternion &	Invert (const CQuaternion &in_Quat)
SICPPSDK_INLINE CQuaternion &	SetIdentity ()
SICPPSDK_INLINE CQuaternion &	Copy (const CQuaternion &in_Quat)
SICPPSDK_INLINE void	Get (double &out_dW, double &out_dX, double &out_dY, double &out_dZ) const
CVector3	Get () const
SICPPSDK_INLINE void	Get (CVector4 &io_XYZWVector) const
SICPPSDK_INLINE CQuaternion &	Set (double in_dW, double in_dX, double in_dY, double in_dZ)
SICPPSDK_INLINE CQuaternion &	Set (const CVector3 &in_XYZVector)
SICPPSDK_INLINE CQuaternion &	Set (const CVector4 &in_XYZWVector)
SICPPSDK_INLINE double	GetValue (short in_nIndex) const
SICPPSDK_INLINE CQuaternion &	PutValue (short in_nIndex, double newVal)
SICPPSDK_INLINE double	GetW () const
SICPPSDK_INLINE CQuaternion &	PutW (double newVal)
SICPPSDK_INLINE double	GetZ () const
SICPPSDK_INLINE CQuaternion &	PutZ (double newVal)
SICPPSDK_INLINE double	GetY () const
SICPPSDK_INLINE CQuaternion &	PutY (double newVal)
SICPPSDK_INLINE double	GetX () const
SICPPSDK_INLINE CQuaternion &	PutX (double newVal)
CQuaternion &	SetFromXYZAnglesValues (double x, double y, double z)
void	GetXYZAnglesValues (double &x, double &y, double &z) const
SICPPSDK_INLINE bool	operator!= (const CQuaternion &in_quat) const

Constructor & Destructor Documentation

SICPPSDK_INLINE CQuaternion ( )

Default constructor. Constructs the identity quaternion.

See also:: CQuaternion::SetIdentity

SICPPSDK_INLINE CQuaternion ( const CQuaternion & in_quaternion )

Copy constructor.

Parameters:

in_quaternion constant class object.

~CQuaternion ( ) [inline]

Default destructor.

SICPPSDK_INLINE CQuaternion	(	const double	in_dW,
		const double	in_dX,
		const double	in_dY,
		const double	in_dZ
	)

Constructor.

Parameters:

in_dW	W component
in_dX	X component of the quaternion's vector
in_dY	Y component of the quaternion's vector
in_dZ	Z component of the quaternion's vector

SICPPSDK_INLINE CQuaternion ( const CVector3 & in_vct )

Constructor.

Note:: The W component of the quaternion will be set to 1.0

Parameters:

in_vct Vector containing the X, Y and Z values

SICPPSDK_INLINE CQuaternion ( const CVector4 & in_vct )

Constructor.

Parameters:

in_vct Vector containing the X, Y, Z and W values

SICPPSDK_INLINE CQuaternion ( const CRotation & in_Rot )

Constructor (from a rotation).

Parameters:

in_Rot Rotation to construct from

Member Function Documentation

SICPPSDK_INLINE CQuaternion & operator= ( const CQuaternion & in_quaternion )

Assignment operator.

Parameters:

in_quaternion constant class object.

Returns:: This quaternion

CQuaternion& operator= ( const CRotation & in_Rot )

Sets the quaternion from a rotation

Parameters:

in_Rot Rotation to set from

Returns:: This quaternion

CQuaternion& SetFromRotation ( const CRotation & in_Rot )

Sets the quaternion from a rotation

Parameters:

in_Rot Rotation to set from

Returns:: This quaternion

CRotation GetRotation ( ) const

Returns a rotation that represents the current quaternion

Returns:: CRotation

CQuaternion& Normalize ( )

Normalizes the quaternion

bool EpsilonEquals	(	const CQuaternion &	in_Quat,
		double	in_dEpsilon
	)		const

Tests the equality of this quaternion against in_Quat, with a tolerance of in_dEpsilon.

Parameters:

in_Quat	Quaternion to compare against
in_dEpsilon	Tolerance. Quaternions are considered equal if each parameter pair have a difference lower than in_dEpsilon.

Returns:: true Quaternions are approximately equal; false Quarternions are not equal

SICPPSDK_INLINE bool Equals ( const CQuaternion & in_Quat ) const

Performs an exact comparison of two quaternions.

Note:: Each parameter of both quaternions must be exactly the same fora match.

Parameters:

in_Quat Quaternion to compare against

See also:: CQuaternion::EpsilonEquals

SICPPSDK_INLINE bool operator== ( const CQuaternion & in_Quat ) const

Performs a comparison.

Note:: Each parameter of both quaternions must be exactly the same for a match.

Parameters:

in_Quat Quaternion to compare against

See also:: CQuaternion::EpsilonEquals, CQuaternion::Equals

CQuaternion& Slerp	(	const CQuaternion &	in_Quat1,
		const CQuaternion &	in_Quat2,
		double	in_dU
	)

Performs spherical linear interpolation of two unit quaternions whithin this quaternion.

Parameters:

in_Quat1	First quaternion
in_Quat2	Second quaternion
in_dU	Interpolation factor within [0.0 .. 1.0].

Returns:: This quaternion

SICPPSDK_INLINE CQuaternion & operator*= ( const CQuaternion & in_Quat )

Multiplies this quaternion with another one in place.

Parameters:

in_Quat Quaternion to multiply

Returns:: This quaternion

See also:: CQuaternion::Mul, CQuaternion::MulInPlace

SICPPSDK_INLINE CQuaternion & MulInPlace ( const CQuaternion & in_Quat )

Multiplies this quaternion with another one in place.

Parameters:

in_Quat Quaternion to multiply

Returns:: This quaternion

See also:: CQuaternion::Mul

SICPPSDK_INLINE CQuaternion & Mul	(	const CQuaternion &	in_Quat1,
		const CQuaternion &	in_Quat2
	)

Stores the result of the multiplication of two quaternions.

Parameters:

in_Quat1	First quaternion
in_Quat2	Second quaternion

Returns:: This quaternion

SICPPSDK_INLINE CQuaternion & operator-= ( const CQuaternion & in_Quat )

Subtracts a quaternion from the current quaternion in place.

Parameters:

in_Quat Quaternion to subtract

Returns:: This quaternion

See also:: CQuaternion::SubInPlace, CQuaternion::Sub

SICPPSDK_INLINE CQuaternion & SubInPlace ( const CQuaternion & in_Quat )

Subtracts a quaternion from the current quaternion in place.

Parameters:

in_Quat Quaternion to subtract

Returns:: This quaternion

See also:: CQuaternion::Sub

SICPPSDK_INLINE CQuaternion & Sub	(	const CQuaternion &	in_Quat1,
		const CQuaternion &	in_Quat2
	)

Stores the result of the subtraction of two quaternions.

Parameters:

in_Quat1	First quaternion
in_Quat2	Second quaternion

Returns:: This quaternion

See also:: CQuaternion::SubInPlace

SICPPSDK_INLINE CQuaternion & NegateInPlace ( )

Negates all the components of this quaternion.

Returns:: This quaternion

See also:: CQuaternion::Negate

SICPPSDK_INLINE CQuaternion & Negate ( const CQuaternion & in_Quat )

Stores the result of the negation of a given quaternion without changing it.

Parameters:

in_Quat Quaternion to negate

Returns:: This quaternion

See also:: CQuaternion::NegateInPlace

SICPPSDK_INLINE double GetLengthSquared ( ) const

Returns the squared length of this quaternion.

Returns:: The squared length

See also:: CQuaternion::GetLength

double GetLength ( ) const

Returns the length of this quaternion.

Returns:: Length of this quaternion

See also:: CQuaternion::GetLengthSquared

SICPPSDK_INLINE CQuaternion & operator+= ( const CQuaternion & in_Quat )

Adds a quaternion to this quaternion.

Parameters:

in_Quat Quaternion to add

See also:: CQuaternion::AddInPlace, CQuaternion::Add

SICPPSDK_INLINE CQuaternion & AddInPlace ( const CQuaternion & in_Quat )

Adds a quaternion to this quaternion.

Parameters:

in_Quat Quaternion to add

See also:: CQuaternion::Add

SICPPSDK_INLINE CQuaternion & Add	(	const CQuaternion &	in_Quat1,
		const CQuaternion &	in_Quat2
	)

Stores the result of the addition of two quaternions.

Parameters:

in_Quat1	First quaternion
in_Quat2	Second quaternion

Returns:: This quaternion

See also:: CQuaternion::AddInPlace

SICPPSDK_INLINE CQuaternion & ConjugateInPlace ( )

Conjugates this quaternion.

Returns:: This quaternion

See also:: CQuaternion::ConjugateInPlace

SICPPSDK_INLINE CQuaternion & Conjugate ( const CQuaternion & in_Quat )

Stores the conjugate of a quaternion without changing it.

Parameters:

in_Quat Quaternion to conjugate.

Returns:: This quaternion

See also:: CQuaternion::ConjugateInPlace

SICPPSDK_INLINE CQuaternion & InvertInPlace ( )

Inverts this quaternion.

Returns:: This quaternion

See also:: CQuaternion::Invert

SICPPSDK_INLINE CQuaternion & Invert ( const CQuaternion & in_Quat )

Stores the invert of a quaternion without changing it.

Parameters:

in_Quat Quaternion to invert

Returns:: This quaternion

See also:: CQuaternion::Invert

SICPPSDK_INLINE CQuaternion & SetIdentity ( )

Sets this quaternion to identity quaternion.

Returns:: This quaternion

SICPPSDK_INLINE CQuaternion & Copy ( const CQuaternion & in_Quat )

Copies the content of a quaternion.

Parameters:

in_Quat Quaternion to copy

Returns:: This quaternion

SICPPSDK_INLINE void Get	(	double &	out_dW,
		double &	out_dX,
		double &	out_dY,
		double &	out_dZ
	)		const

Returns the components of this quaternion.

Return values:

out_dW	The current value of the W component
out_dX	The current value of the X component
out_dY	The current value of the Y component
out_dZ	The current value of the Z component

CVector3 Get ( ) const

Returns the components of this quaternion.

Returns:: Vector that holds the values of the X, Y and Z components

SICPPSDK_INLINE void Get ( CVector4 & io_XYZWVector ) const

Returns the components of this quaternion.

Parameters:

io_XYZWVector Vector that holds the values of the X, Y, Z and W components

SICPPSDK_INLINE CQuaternion & Set	(	double	in_dW,
		double	in_dX,
		double	in_dY,
		double	in_dZ
	)

Sets the quaternion's components.

Parameters:

in_dW	New value for the W component
in_dX	New value for the X component
in_dY	New value for the Y component
in_dZ	New value for the Z component

Returns:: This quaternion

SICPPSDK_INLINE CQuaternion & Set ( const CVector3 & in_XYZVector )

Sets the quaternion's components.

Note:: The W value is left as is.

Parameters:

in_XYZVector Vector that holds the new values for the X, Y and Z components

Returns:: This quaternion

SICPPSDK_INLINE CQuaternion & Set ( const CVector4 & in_XYZWVector )

Sets the quaternion's components.

Parameters:

in_XYZWVector Vector that holds the new values for the X, Y and Z components. The W component is set to 1.0.

Returns:: This quaternion

SICPPSDK_INLINE double GetValue ( short in_nIndex ) const

Gets the value of a single component.

Parameters:

in_nIndex 0-based index of the component to get. This value can be 0 (W), 1(X), 2(Y) or 3(Z).

Returns:: The requested value; 0.0 if an invalid index was provided.

See also:: CQuaternion::PutValue

SICPPSDK_INLINE CQuaternion & PutValue	(	short	in_nIndex,
		double	newVal
	)

Sets the value of a single component.

Note:: The quaternion is unchanged if the provided index is invalid

Parameters:

in_nIndex	0-based index of the component to set. This value can be 0 (W), 1(X), 2(Y) or 3(Z).
newVal	new value

Returns:: This quaternion

See also:: CQuaternion::SetValue

SICPPSDK_INLINE double GetW ( ) const

Returns the W component.

Returns:: The W component

SICPPSDK_INLINE CQuaternion & PutW ( double newVal )

Sets the W component.

Parameters:

newVal The new value for the component

Returns:: This quaternion

SICPPSDK_INLINE double GetZ ( ) const

Returns the Z component.

Returns:: The Z component

SICPPSDK_INLINE CQuaternion & PutZ ( double newVal )

Sets the Z component.

Parameters:

newVal The new value for the component

Returns:: This quaternion

SICPPSDK_INLINE double GetY ( ) const

Returns the Y component.

Returns:: The Y component

SICPPSDK_INLINE CQuaternion & PutY ( double newVal )

Sets the Y component.

Parameters:

newVal The new value for the component

Returns:: This quaternion

SICPPSDK_INLINE double GetX ( ) const

Returns the X component.

Returns:: The X component

SICPPSDK_INLINE CQuaternion & PutX ( double newVal )

Sets the X component.

Parameters:

newVal The new value for the component

Returns:: This quaternion

CQuaternion& SetFromXYZAnglesValues	(	double	x,
		double	y,
		double	z
	)

Sets the quaternion using X,Y,Z Euler angles (in radians).

Parameters:

x	The Euler X value in radians
y	The Euler Y value in radians
z	The Euler Z value in radians

Returns:: This quaternion

void GetXYZAnglesValues	(	double &	x,
		double &	y,
		double &	z
	)		const

Returns the X,Y,Z Euler angles (in radians) for this quaternion.

Return values:

x	The Euler X value in radians
y	The Euler Y value in radians
z	The Euler Z value in radians

SICPPSDK_INLINE bool operator!= ( const CQuaternion & in_quat ) const

Inequality operator (tests the strict inequality of this quaternion with the quaternion in_quat).

Parameters:

in_quat Operand quaternion.

Returns:: true if equal else false.

See also:: CQuaternion::Equals

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

xsi_quaternion.h

Detailed Description

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation