Public Member Functions
CQuaternion Class Reference

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 CQuaternionoperator= (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)
CQuaternionoperator= (const CRotation &in_Rot)
CQuaternionSetFromRotation (const CRotation &in_Rot)
CRotation GetRotation () const
CQuaternionNormalize ()
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
CQuaternionSlerp (const CQuaternion &in_Quat1, const CQuaternion &in_Quat2, double in_dU)
SICPPSDK_INLINE CQuaternionoperator*= (const CQuaternion &in_Quat)
SICPPSDK_INLINE CQuaternionMulInPlace (const CQuaternion &in_Quat)
SICPPSDK_INLINE CQuaternionMul (const CQuaternion &in_Quat1, const CQuaternion &in_Quat2)
SICPPSDK_INLINE CQuaternionoperator-= (const CQuaternion &in_Quat)
SICPPSDK_INLINE CQuaternionSubInPlace (const CQuaternion &in_Quat)
SICPPSDK_INLINE CQuaternionSub (const CQuaternion &in_Quat1, const CQuaternion &in_Quat2)
SICPPSDK_INLINE CQuaternionNegateInPlace ()
SICPPSDK_INLINE CQuaternionNegate (const CQuaternion &in_Quat)
double GetLengthSquared () const
double GetLength () const
SICPPSDK_INLINE CQuaternionoperator+= (const CQuaternion &in_Quat)
SICPPSDK_INLINE CQuaternionAddInPlace (const CQuaternion &in_Quat)
SICPPSDK_INLINE CQuaternionAdd (const CQuaternion &in_Quat1, const CQuaternion &in_Quat2)
SICPPSDK_INLINE CQuaternionConjugateInPlace ()
SICPPSDK_INLINE CQuaternionConjugate (const CQuaternion &in_Quat)
SICPPSDK_INLINE CQuaternionInvertInPlace ()
SICPPSDK_INLINE CQuaternionInvert (const CQuaternion &in_Quat)
SICPPSDK_INLINE CQuaternionSetIdentity ()
SICPPSDK_INLINE CQuaternionCopy (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 CQuaternionSet (double in_dW, double in_dX, double in_dY, double in_dZ)
SICPPSDK_INLINE CQuaternionSet (const CVector3 &in_XYZVector)
SICPPSDK_INLINE CQuaternionSet (const CVector4 &in_XYZWVector)
SICPPSDK_INLINE double GetValue (short in_nIndex) const
SICPPSDK_INLINE CQuaternionPutValue (short in_nIndex, double newVal)
SICPPSDK_INLINE double GetW () const
SICPPSDK_INLINE CQuaternionPutW (double newVal)
SICPPSDK_INLINE double GetZ () const
SICPPSDK_INLINE CQuaternionPutZ (double newVal)
SICPPSDK_INLINE double GetY () const
SICPPSDK_INLINE CQuaternionPutY (double newVal)
SICPPSDK_INLINE double GetX () const
SICPPSDK_INLINE CQuaternionPutX (double newVal)
CQuaternionSetFromXYZAnglesValues (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_quaternionconstant 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_dWW component
in_dXX component of the quaternion's vector
in_dYY component of the quaternion's vector
in_dZZ 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_vctVector containing the X, Y and Z values
SICPPSDK_INLINE CQuaternion ( const CVector4 in_vct)

Constructor.

Parameters:
in_vctVector containing the X, Y, Z and W values
SICPPSDK_INLINE CQuaternion ( const CRotation in_Rot)

Constructor (from a rotation).

Parameters:
in_RotRotation to construct from

Member Function Documentation

SICPPSDK_INLINE CQuaternion & operator= ( const CQuaternion in_quaternion)

Assignment operator.

Parameters:
in_quaternionconstant class object.
Returns:
This quaternion
CQuaternion& operator= ( const CRotation in_Rot)

Sets the quaternion from a rotation

Parameters:
in_RotRotation to set from
Returns:
This quaternion
CQuaternion& SetFromRotation ( const CRotation in_Rot)

Sets the quaternion from a rotation

Parameters:
in_RotRotation 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_QuatQuaternion to compare against
in_dEpsilonTolerance. 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_QuatQuaternion 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_QuatQuaternion 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_Quat1First quaternion
in_Quat2Second quaternion
in_dUInterpolation 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_QuatQuaternion 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_QuatQuaternion 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_Quat1First quaternion
in_Quat2Second quaternion
Returns:
This quaternion
SICPPSDK_INLINE CQuaternion & operator-= ( const CQuaternion in_Quat)

Subtracts a quaternion from the current quaternion in place.

Parameters:
in_QuatQuaternion 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_QuatQuaternion 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_Quat1First quaternion
in_Quat2Second 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_QuatQuaternion 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_QuatQuaternion to add
See also:
CQuaternion::AddInPlace, CQuaternion::Add
SICPPSDK_INLINE CQuaternion & AddInPlace ( const CQuaternion in_Quat)

Adds a quaternion to this quaternion.

Parameters:
in_QuatQuaternion 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_Quat1First quaternion
in_Quat2Second 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_QuatQuaternion 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_QuatQuaternion 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_QuatQuaternion 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_dWThe current value of the W component
out_dXThe current value of the X component
out_dYThe current value of the Y component
out_dZThe 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_XYZWVectorVector 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_dWNew value for the W component
in_dXNew value for the X component
in_dYNew value for the Y component
in_dZNew 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_XYZVectorVector 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_XYZWVectorVector 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_nIndex0-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_nIndex0-based index of the component to set. This value can be 0 (W), 1(X), 2(Y) or 3(Z).
newValnew 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:
newValThe 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:
newValThe 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:
newValThe 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:
newValThe 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:
xThe Euler X value in radians
yThe Euler Y value in radians
zThe 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:
xThe Euler X value in radians
yThe Euler Y value in radians
zThe 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_quatOperand quaternion.
Returns:
true if equal else false.
See also:
CQuaternion::Equals

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