Detailed Description

template<typename Type>
class walberla::math::Quaternion< Type >

Efficient implementation of a quaternion.

Quaternions are a superior way to deal with rotations and orientations. This quaternion consists of 4 statically allocated elements, where the first element represents the real part and the three other elements represent the three imaginary parts. The naming convention of the elements is as following:

                      \f[\left(\begin{array}{*{4}{c}}
                      r & i & j & k \\
                      \end{array}\right)\f]

These elements can be accessed directly with the subscript operator. The numbering of the quaternion elements is

                      \f[\left(\begin{array}{*{4}{c}}
                      0 & 1 & 2 & 3 \\
                      \end{array}\right)\f]

Note: The Quaternion class can only be instantiated for non-cv-qualified floating point types! Therefore the only possible Quaternion instantiations are

Quaternion<float>
Quaternion<double>
Quaternion<long double>

The attempt to create a quaternion with an integral data type results in a compile time error.

#include <Types.h>

Public Types
using	ElementType = Type
	Type of the quaternion elements. More...

Public Member Functions
template<typename Other >
Quaternion< Type > &	operator= (const Quaternion< Other > &rhs)
	Assignment operator for different Quaternion instances. More...

Constructors
	Quaternion ()=default

	Quaternion (Type r, Type i, Type j, Type k)
	Constructor for a direct initialization of all quaternion elements. More...

template<typename Axis >
	Quaternion (Vector3< Axis > axis, Type angle)
	Constructor for a quaternion depending on a rotation axis and angle. More...

	Quaternion (Type xangle, Type yangle, Type zangle)
	Constructor for a quaternion rotated by the Euler angles xangle, yangle and zangle. More...

template<typename Other >
	Quaternion (const Vector3< Other > &euler)
	Constructor for a quaternion rotated by the Euler angles euler. More...

	Quaternion (const Quaternion &q)=default

template<typename Other >
	Quaternion (const Quaternion< Other > &q)
	Conversion constructor from different Quaternion instances. More...

Operators
Quaternion &	operator= (const Quaternion &rhs)=default

template<typename Other >
Quaternion &	operator= (const Quaternion< Other > &rhs)

Type	operator[] (size_t index) const
	Subscript operator for the direct access to the quaternion elements. More...

Utility functions
Quaternion &	set (Type r, Type i, Type j, Type k)
	Setting the value of the quaternion elements. More...

void	reset ()
	Reset to the default initial values. More...

Quaternion &	invert ()
	Inversion of the quaternion ( \( \hat{q} = \hat{q}^{-1} \)). More...

const Quaternion	getInverse () const
	Calculation of the inverse quaternion ( \( \hat{q} = \hat{p}^{-1} \)). More...

const Matrix3< Type >	toRotationMatrix () const
	Conversion to a rotation matrix. More...

Type	getAngle () const
	Calculation of the inherent rotation angle. More...

const Vector3< Type >	getAxis () const
	Calculation of the inherent rotation axis. More...

void	rotateX (Type angle)
	Rotating the quaternion around the global x-axis by angle degrees (radian measure). More...

void	rotateY (Type angle)
	Rotating the quaternion around the global y-axis by angle degrees (radian measure). More...

void	rotateZ (Type angle)
	Rotating the quaternion around the global z-axis by angle degrees (radian measure). More...

void	swap (Quaternion &q)
	Swapping the contents of two quaternions. More...

const Vector3< Type >	getEulerAnglesXYZ () const
	Returns the euler angles in xyz order. More...

Type *	data ()

const Type *	data () const

Math functions
The return type of the math functions depends on the involved data types of the quaternions, matrices and vectors (for further detail see the MathTrait class description).
template<typename Other >
const Vector3< typename MathTrait< Type, Other >::MultType >	rotate (const Vector3< Other > &v) const
	Rotation of a vector v ( \( \vec{rot} = \hat{q} \cdot \vec{v} \cdot \hat{q}^{-1} \)). More...

template<typename Other >
const Matrix3< typename MathTrait< Type, Other >::MultType >	rotate (const Matrix3< Other > &m) const
	Rotation of a matrix. More...

template<typename Other >
const Matrix3< typename MathTrait< Type, Other >::MultType >	diagRotate (const Matrix3< Other > &m) const
	Rotation of a diagonal matrix. More...

template<typename Other >
MathTrait< Type, Other >::HighType	calcAngle (const Vector3< Other > &axis) const
	Returns the angle in radian measure between the quaternion and a given axis. More...

Private Attributes
Member variables
Type	v_ [4] = {Type(1), Type(0), Type(0), Type(0)}
	The four statically allocated quaternion elements. More...

Member Typedef Documentation

◆ ElementType

template<typename Type >

using walberla::math::Quaternion< Type >::ElementType = Type

Type of the quaternion elements.

Constructor & Destructor Documentation

◆ Quaternion() [1/7]

template<typename Type >

walberla::math::Quaternion< Type >::Quaternion ( )

inlineexplicitdefault

◆ Quaternion() [2/7]

template<typename Type >

walberla::math::Quaternion< Type >::Quaternion	(	Type	r,
		Type	i,
		Type	j,
		Type	k
	)

inlineexplicit

Constructor for a direct initialization of all quaternion elements.

Parameters

r	The initial value for the real part.
i	The initial value for the first imaginary part.
j	The initial value for the second imaginary part.
k	The initial value for the third imaginary part.

The initial values for the quaternion have to be chosen such that the length of the quaternion is 1.

◆ Quaternion() [3/7]

template<typename Type >

template<typename Axis >

walberla::math::Quaternion< Type >::Quaternion	(	Vector3< Axis >	axis,
		Type	angle
	)

inlineexplicit

Constructor for a quaternion depending on a rotation axis and angle.

Parameters

axis	The rotation axis.
angle	The rotation angle (radian measure).

This constructor creates a quaternion from the rotation axis axis and the rotation angle angle. axis may be an arbitrary, non-zero vector of any length. However, it is allowed to use the zero vector (0,0,0) in combination with an angle of 0. This combination results in a default quaternion

    \f[ \left(\begin{array}{c} 1 \\ 0 \\ 0 \\ 0 \end{array}\right) \f]

◆ Quaternion() [4/7]

template<typename Type >

walberla::math::Quaternion< Type >::Quaternion	(	Type	xangle,
		Type	yangle,
		Type	zangle
	)

inlineexplicit

Constructor for a quaternion rotated by the Euler angles xangle, yangle and zangle.

Parameters

xangle	Rotation around the x-axis (radian measure).
yangle	Rotation around the y-axis (radian measure).
zangle	Rotation around the z-axis (radian measure).

This constructor creates a quaternion rotated by the Euler angles xangle, yangle and zangle (all in radian measure). The rotations are applied in the order x, y, and z.

◆ Quaternion() [5/7]

template<typename Type >

template<typename Other >

walberla::math::Quaternion< Type >::Quaternion ( const Vector3< Other > & euler )

inlineexplicit

Constructor for a quaternion rotated by the Euler angles euler.

Parameters

euler 3-dimensional vector of the three rotation angles (radian measure).

This constructor creates a quaternion rotated by the Euler angles euler (all components in radian measure). The rotations are applied in the order x, y, and z.

◆ Quaternion() [6/7]

template<typename Type >

walberla::math::Quaternion< Type >::Quaternion ( const Quaternion< Type > & q )

inlinedefault

◆ Quaternion() [7/7]

template<typename Type >

template<typename Other >

walberla::math::Quaternion< Type >::Quaternion ( const Quaternion< Other > & q )

inline

Conversion constructor from different Quaternion instances.

Parameters

q	Quaternion to be copied.

Member Function Documentation

◆ calcAngle()

template<typename Type >

template<typename Other >

MathTrait< Type, Other >::HighType walberla::math::Quaternion< Type >::calcAngle ( const Vector3< Other > & axis ) const

inline

Returns the angle in radian measure between the quaternion and a given axis.

Parameters

axis	The given axis.

Returns: The angle in radian measure.

◆ data() [1/2]

template<typename Type >

Type* walberla::math::Quaternion< Type >::data ( )

inline

◆ data() [2/2]

template<typename Type >

const Type* walberla::math::Quaternion< Type >::data ( ) const

inline

◆ diagRotate()

template<typename Type >

template<typename Other >

const Matrix3< typename MathTrait< Type, Other >::MultType > walberla::math::Quaternion< Type >::diagRotate ( const Matrix3< Other > & m ) const

inline

Rotation of a diagonal matrix.

Parameters

m	The diagonal matrix to be rotated.

Returns: The rotated matrix.

The DiagRotate function is a special case of the rotate function. The matrix is assumed to be a diagonal matrix, which reduces the number of floating point operations of the rotation. The function is selected for matrices of different data type (in case Type and Other are supported by the MathTrait class). The function returns a matrix of the higher-order data type of the two involved data types.

◆ getAngle()

template<typename Type >

Type walberla::math::Quaternion< Type >::getAngle

inline

Calculation of the inherent rotation angle.

Returns: The rotation angle (radian measure).

◆ getAxis()

template<typename Type >

const Vector3< Type > walberla::math::Quaternion< Type >::getAxis

inline

Calculation of the inherent rotation axis.

Returns: The rotation axis

If the angle is (close to) zero, the return value is set to (1,0,0)

◆ getEulerAnglesXYZ()

template<typename Type >

const Vector3< Type > walberla::math::Quaternion< Type >::getEulerAnglesXYZ

inline

Returns the euler angles in xyz order.

◆ getInverse()

template<typename Type >

const Quaternion< Type > walberla::math::Quaternion< Type >::getInverse

inline

Calculation of the inverse quaternion ( \( \hat{q} = \hat{p}^{-1} \)).

Returns: The inverse quaternion.

◆ invert()

template<typename Type >

Quaternion< Type > & walberla::math::Quaternion< Type >::invert

inline

Inversion of the quaternion ( \( \hat{q} = \hat{q}^{-1} \)).

Returns: Reference to the inverted quaternion.

◆ operator=() [1/3]

template<typename Type >

Quaternion& walberla::math::Quaternion< Type >::operator= ( const Quaternion< Type > & rhs )

inlinedefault

◆ operator=() [2/3]

template<typename Type >

template<typename Other >

Quaternion& walberla::math::Quaternion< Type >::operator= ( const Quaternion< Other > & rhs )

inline

◆ operator=() [3/3]

template<typename Type >

template<typename Other >

Quaternion<Type>& walberla::math::Quaternion< Type >::operator= ( const Quaternion< Other > & rhs )

inline

Assignment operator for different Quaternion instances.

Parameters

rhs	Quaternion to be copied.

Returns: Reference to the assigned quaternion.

◆ operator[]()

template<typename Type >

Type walberla::math::Quaternion< Type >::operator[] ( size_t index ) const

inline

Subscript operator for the direct access to the quaternion elements.

Parameters

index Access index. The index has to be in the range \([0..3]\).

Returns: Copy of the accessed element.

When compiled in Debug mode, this operator performs an index check.

◆ reset()

template<typename Type >

void walberla::math::Quaternion< Type >::reset

inline

Reset to the default initial values.

Returns: void

This function resets the quaternion to the default initial values. The real part of the quaternion is reset to 1, whereas the imaginary parts are reset to 0:

                      \f[\left(\begin{array}{*{4}{c}}
                      1 & 0 & 0 & 0 \\
                      \end{array}\right)\f]

◆ rotate() [1/2]

template<typename Type >

template<typename Other >

const Matrix3< typename MathTrait< Type, Other >::MultType > walberla::math::Quaternion< Type >::rotate ( const Matrix3< Other > & m ) const

inline

Rotation of a matrix.

Parameters

m	The matrix to be rotated.

Returns: The rotated matrix.

The function is selected for matrices of different data type (in case Type and Other are supported by the MathTrait class). The function returns a matrix of the higher-order data type of the two involved data types.

◆ rotate() [2/2]

template<typename Type >

template<typename Other >

const Vector3< typename MathTrait< Type, Other >::MultType > walberla::math::Quaternion< Type >::rotate ( const Vector3< Other > & v ) const

inline

Rotation of a vector v ( \( \vec{rot} = \hat{q} \cdot \vec{v} \cdot \hat{q}^{-1} \)).

Parameters

v	The vector to be rotated.

Returns: The rotated vector.

The function is selected for vectors of different data type (in case Type and Other are supported by the MathTrait class). The function returns a vector of the higher-order data type of the two involved data types.

◆ rotateX()

template<typename Type >

void walberla::math::Quaternion< Type >::rotateX ( Type angle )

inline

Rotating the quaternion around the global x-axis by angle degrees (radian measure).

Parameters

angle The rotation angle (radian measure).

Returns: void

◆ rotateY()

template<typename Type >

void walberla::math::Quaternion< Type >::rotateY ( Type angle )

inline

Rotating the quaternion around the global y-axis by angle degrees (radian measure).

Parameters

angle The rotation angle (radian measure).

Returns: void

◆ rotateZ()

template<typename Type >

void walberla::math::Quaternion< Type >::rotateZ ( Type angle )

inline

Rotating the quaternion around the global z-axis by angle degrees (radian measure).

Parameters

angle The rotation angle (radian measure).

Returns: void

◆ set()

template<typename Type >

Quaternion< Type > & walberla::math::Quaternion< Type >::set	(	Type	r,
		Type	i,
		Type	j,
		Type	k
	)

inline

Setting the value of the quaternion elements.

Parameters

r	The value for the real part.
i	The value for the first imaginary part.
j	The value for the second imaginary part.
k	The value for the third imaginary part.

◆ swap()

template<typename Type >

void walberla::math::Quaternion< Type >::swap ( Quaternion< Type > & q )

inline

Swapping the contents of two quaternions.

Parameters

q	The quaternion to be swapped.

Returns: void

Exceptions

no-throw guarantee.

◆ toRotationMatrix()

template<typename Type >

const Matrix3< Type > walberla::math::Quaternion< Type >::toRotationMatrix

inline

Conversion to a rotation matrix.

Returns: The resulting rotation matrix.

Member Data Documentation

◆ v_

template<typename Type >

Type walberla::math::Quaternion< Type >::v_[4] = {Type(1), Type(0), Type(0), Type(0)}

private

The four statically allocated quaternion elements.

Access to the quaternion values is gained via the subscript operator. The order of the elements is

\[\left(\begin{array}{*{4}{c}} 0 & 1 & 2 & 3 \\ \end{array}\right)\]

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

/builds/administration/walberla-website/walberla/src/core/math/Quaternion.h

Detailed Description

template<typename Type> class walberla::math::Quaternion< Type >

Public Types

Public Member Functions

Private Attributes

Member Typedef Documentation

◆ ElementType

Constructor & Destructor Documentation

◆ Quaternion() [1/7]

◆ Quaternion() [2/7]

◆ Quaternion() [3/7]

◆ Quaternion() [4/7]

◆ Quaternion() [5/7]

◆ Quaternion() [6/7]

◆ Quaternion() [7/7]

Member Function Documentation

◆ calcAngle()

◆ data() [1/2]

◆ data() [2/2]

◆ diagRotate()

◆ getAngle()

◆ getAxis()

◆ getEulerAnglesXYZ()

◆ getInverse()

◆ invert()

◆ operator=() [1/3]

◆ operator=() [2/3]

◆ operator=() [3/3]

◆ operator[]()

◆ reset()

◆ rotate() [1/2]

◆ rotate() [2/2]

◆ rotateX()

◆ rotateY()

◆ rotateZ()

◆ set()

◆ swap()

◆ toRotationMatrix()

Member Data Documentation

◆ v_

template<typename Type>
class walberla::math::Quaternion< Type >