Quaternion< ValueType > Class Template Reference

#include <quaternion.h>

Detailed Description

template<typename ValueType>
class maxon::Quaternion< ValueType >

Quaternions extend the concept of rotation in three dimensions to rotation in four dimensions. This avoids the problem of "gimbal-lock" and allows for the implementation of smooth and continuous rotation. In effect, they may be considered to add an additional rotation angle to spherical coordinates ie. Longitude, Latitude and Rotation angles. A Quaternion is defined using four floating point values |v.x v.y v.z w|. These are calculated from the combination of the three coordinates of the rotation axis and the rotation angle. Because the rotation axis is specified as a unit direction vector, it may be calculated through vector mathematics or from spherical coordinates ie. (longitude/latitude). Quaternions offer another advantage in that they be interpolated - this allows for smooth and predictable rotation effects.

Public Member Functions

 Quaternion ()
 
MAXON_IMPLICIT Quaternion (const VectorType &v, const ValueType w)
 
MAXON_IMPLICIT Quaternion (const ValueType x, const ValueType y, const ValueType z, const ValueType w)
 
const QuaternionTypeoperator+= (const QuaternionType &v)
 
const QuaternionTypeoperator-= (const QuaternionType &v)
 
const QuaternionTypeoperator*= (const QuaternionType &v)
 
QuaternionType operator+ (const QuaternionType &v) const
 
QuaternionType operator- (const QuaternionType &v) const
 
QuaternionType operator* (const QuaternionType &v) const
 
QuaternionType operator* (const ValueType s) const
 
void SetMatrix (const MatrixType &m)
 
void SetRotation (const VectorType &rotation)
 
void SetAxisRotation (const VectorType &axis, const ValueType rotation)
 
MatrixType GetMatrix () const
 
Result< void > GetAxisRotation (VectorType &axis, ValueType &angle) const
 
ValueType GetSquaredLength () const
 
ValueType GetLength () const
 
Result< QuaternionTypeGetNormalized () const
 
Result< QuaternionTypeGetInverse () const
 
QuaternionType GetConjugate () const
 
Result< QuaternionTypeGetLog () const
 
Result< QuaternionTypeGetExp () const
 
Result< QuaternionTypeGetPow (const ValueType &t) const
 
String ToString (const FormatStatement *formatStatement=nullptr) const
 
 MAXON_OPERATOR_EQUALITY_HASHCODE (Quaternion, v, w)
 

Static Public Member Functions

static ValueType GetDot (const QuaternionType &q1, const QuaternionType &q2)
 
static Result< QuaternionTypeGetLerp (const QuaternionType &q1, const QuaternionType &q2, const ValueType t)
 
static Result< QuaternionTypeGetSlerp (const QuaternionType &q1, const QuaternionType &q2, const ValueType t)
 
static Result< QuaternionTypeGetSquad (const QuaternionType &qi, const QuaternionType &qi_p1, const QuaternionType &si, const QuaternionType &si_p1, const ValueType t)
 
static Result< QuaternionTypeGetInnerQuaternion (const QuaternionType &qi_m1, const QuaternionType &qi, const QuaternionType &qi_p1)
 
static Result< QuaternionTypeGetSpline (const QuaternionType &qi_m1, const QuaternionType &qi, const QuaternionType &qi_p1, const QuaternionType &qi_p2, const ValueType t)
 
static Result< void > DescribeIO (const DataSerializeInterface &stream)
 

Public Attributes

VectorType v
 
ValueType w
 

Private Types

using VectorType = Vec3< ValueType >
 
using MatrixType = SqrMat3< Vec3< ValueType > >
 
using QuaternionType = Quaternion< ValueType >
 

Private Member Functions

ValueType MyCopysign (const ValueType &x, const ValueType &y) const
 

Friends

QuaternionType operator* (const ValueType s, const QuaternionType &q)
 

Member Typedef Documentation

◆ VectorType

using VectorType = Vec3<ValueType>
private

◆ MatrixType

using MatrixType = SqrMat3<Vec3<ValueType> >
private

◆ QuaternionType

using QuaternionType = Quaternion<ValueType>
private

Constructor & Destructor Documentation

◆ Quaternion() [1/3]

Creates a quaternion initialized with default values (all components 0.0).

◆ Quaternion() [2/3]

Quaternion ( const VectorType v,
const ValueType  w 
)

Creates a quaternion and initialize it with given quaternion values.

◆ Quaternion() [3/3]

Quaternion ( const ValueType  x,
const ValueType  y,
const ValueType  z,
const ValueType  w 
)

Creates a quaternion and initialize it with given quaternion values.

Member Function Documentation

◆ MyCopysign()

ValueType MyCopysign ( const ValueType &  x,
const ValueType &  y 
) const
private

◆ operator+=()

const Quaternion< ValueType > & operator+= ( const QuaternionType v)

Adds the components of two quaternions.

◆ operator-=()

const Quaternion< ValueType > & operator-= ( const QuaternionType v)

Subtract the components of two quaternions.

◆ operator*=()

const Quaternion< ValueType > & operator*= ( const QuaternionType v)

Concatenate two quaternion operations.

◆ operator+()

Quaternion< ValueType > operator+ ( const QuaternionType v) const

Adds the components of two quaternions.

◆ operator-()

Quaternion< ValueType > operator- ( const QuaternionType v) const

Subtracts the components of two quaternions.

◆ operator*() [1/2]

Quaternion< ValueType > operator* ( const QuaternionType v) const

Concatenates two quaternion operations.

◆ operator*() [2/2]

Quaternion< ValueType > operator* ( const ValueType  s) const

Scales the components of a quaternion.

◆ SetMatrix()

void SetMatrix ( const MatrixType m)

Converts a rotation matrix into a quaternion.

Parameters
[in]mRotation matrix (does not need to be normalized).

◆ SetRotation()

void SetRotation ( const VectorType rotation)

Converts a rotation of order X -> Y -> Z into a quaternion.

Parameters
[in]rotationRotation angle vector in radians.

◆ SetAxisRotation()

void SetAxisRotation ( const VectorType axis,
const ValueType  rotation 
)

Converts an axis and angle to a quaternion.

Parameters
[in]axisAxis (does not need to be normalized).
[in]rotationRotation angle in radians.

◆ GetMatrix()

auto GetMatrix ( void  ) const

Derives a rotation matrix from the quaternion.

◆ GetAxisRotation()

Result< void > GetAxisRotation ( VectorType axis,
ValueType &  angle 
) const

Calculate axis and rotation angle from quaternion.

Parameters
[out]axisAxis vector.
[out]angleAngle value in radians.
Returns
OK on success. Returns an error if quaternion is not normalized or the direction of the axis is undefined (singularity at 0 / 180 degree)

◆ GetSquaredLength()

ValueType GetSquaredLength

Calculates the squared magntitude/length/norm of a quaternion.

◆ GetLength()

ValueType GetLength ( void  ) const

Calculates the magntitude/length/norm of a quaternion.

◆ GetNormalized()

Result< Quaternion< ValueType > > GetNormalized

Calculates the normalized quaternion.

Returns
OK on sucess. Returns an error if the length of the quaternion is zero.

◆ GetInverse()

Result< Quaternion< ValueType > > GetInverse

Calculates the inverse of a quaternion.

Returns
OK on sucess. Returns an error if the length of the quaternion is zero.

◆ GetConjugate()

Quaternion< ValueType > GetConjugate

Calculates the conjugate of a quaternion.

Returns
Conjugated quaternion.

◆ GetLog()

Result< Quaternion< ValueType > > GetLog

Calculates the logarithm of a quaternion.

Returns
OK on sucess. Returns an error if the length of the quaternion axis is zero.

◆ GetExp()

Result< Quaternion< ValueType > > GetExp

Calculates the exponential of a quaternion.

Returns
OK on sucess. Returns an error if the length of the quaternion is zero.

◆ GetPow()

Result< Quaternion< ValueType > > GetPow ( const ValueType &  t) const

Calculates the quaternion power q^t.

Parameters
[in]tExponent.
Returns
OK on sucess. Returns an error if the length of the quaternion is zero.

◆ GetDot()

ValueType GetDot ( const QuaternionType q1,
const QuaternionType q2 
)
static

Calculates the dot product of two quaternions.

◆ GetLerp()

Result< Quaternion< ValueType > > GetLerp ( const QuaternionType q1,
const QuaternionType q2,
const ValueType  t 
)
static

Interpolates two quaternions linearly with blend parameter t.

Parameters
[in]q1First quaternion.
[in]q2Second quaternion.
[in]tBlend parameter [0.0, 1.0.]
Returns
The interpolated quaternion.

◆ GetSlerp()

Result< Quaternion< ValueType > > GetSlerp ( const QuaternionType q1,
const QuaternionType q2,
const ValueType  t 
)
static

Interpolates two quaternions spherical linearly with blend parameter t.

Parameters
[in]q1First quaternion.
[in]q2Second quaternion.
[in]tBlend parameter [0.0, 1.0.]
Returns
The interpolated quaternion.

◆ GetSquad()

Result< Quaternion< ValueType > > GetSquad ( const QuaternionType qi,
const QuaternionType qi_p1,
const QuaternionType si,
const QuaternionType si_p1,
const ValueType  t 
)
static

Spherical quadrangle interpolation of a sequence of quaternions qi and qi+1 with blend parameter t Additionally you have to specify the innner quaternions si and si+1.

Parameters
[in]qiMain quaternion at index i.
[in]qi_p1Main quaternion at index i+1
[in]siInner quaterniona at index i.
[in]si_p1Inner quaternion at index i+1
[in]tBlend parameter [0.0, 1.0.]
Returns
The interpolated quaternion.

◆ GetInnerQuaternion()

Result< Quaternion< ValueType > > GetInnerQuaternion ( const QuaternionType qi_m1,
const QuaternionType qi,
const QuaternionType qi_p1 
)
static

Computer the inner quaternion from the series of quaternions qi-1, qi and qi+1

Parameters
[in]qi_m1Quaternion at index i-1
[in]qiQuaternion at index i.
[in]qi_p1Quaternion at index i+1
Returns
The interpolated quaternion.

◆ GetSpline()

Result< Quaternion< ValueType > > GetSpline ( const QuaternionType qi_m1,
const QuaternionType qi,
const QuaternionType qi_p1,
const QuaternionType qi_p2,
const ValueType  t 
)
static

Interpolates two quaternions qi and qi+1 smoothly using spherical spline interpolation with parameter t. qi-1 and qi+2 are used to provide C1 continuity at the borders.

Parameters
[in]qi_m1Quaternion at index i-1
[in]qiQuaternion at index i.
[in]qi_p1Quaternion at index i+1
[in]qi_p2Quaternion at index i+2
[in]tBlend parameter [0.0, 1.0.]
Returns
The interpolated quaternion.

◆ ToString()

String ToString ( const FormatStatement formatStatement = nullptr) const

Returns a readable string of the content.

Parameters
[in]formatStatementNullptr or additional formatting instruction. See also Formatting Floating point values.
Returns
The converted result.

◆ DescribeIO()

Result< void > DescribeIO ( const DataSerializeInterface stream)
static

Describe all elements of this class for I/O operations.

Parameters
[in]streamThe stream that is used to register the class members.
Returns
OK on success.

◆ MAXON_OPERATOR_EQUALITY_HASHCODE()

MAXON_OPERATOR_EQUALITY_HASHCODE ( Quaternion< ValueType >  ,
v  ,
w   
)

Friends And Related Function Documentation

◆ operator*

QuaternionType operator* ( const ValueType  s,
const QuaternionType q 
)
friend

Scales the components of a quaternion with a scalar.

Member Data Documentation

◆ v

direction vector component

◆ w

ValueType w

angle component