chrono::ChQuaternion< Real > Class Template Reference

Description

template<class Real = double>
class chrono::ChQuaternion< Real >

Class defining quaternion objects, that is four-dimensional numbers, also known as Euler parameters.

Quaternions are very useful when used to represent rotations in 3d.

Further info at the Quaternions manual page.

#include <ChQuaternion.h>

Public Member Functions

 ChQuaternion ()
 Default constructor. More...
 
 ChQuaternion (Real e0, Real e1, Real e2, Real e3)
 Constructor from four scalars. The first is the real part, others are i,j,k imaginary parts.
 
 ChQuaternion (Real s, const ChVector< Real > &v)
 Constructor from real part, and vector with i,j,k imaginary part.
 
 ChQuaternion (const ChQuaternion< Real > &other)
 Copy constructor.
 
template<class RealB >
 ChQuaternion (const ChQuaternion< RealB > &other)
 Copy constructor with type change.
 
Real & e0 ()
 Access to components.
 
Real & e1 ()
 
Real & e2 ()
 
Real & e3 ()
 
const Real & e0 () const
 
const Real & e1 () const
 
const Real & e2 () const
 
const Real & e3 () const
 
void Set (Real e0, Real e1, Real e2, Real e3)
 Sets the four values of the quaternion at once.
 
void Set (const ChQuaternion< Real > &q)
 Sets the quaternion as a copy of another quaternion.
 
void Set (Real s)
 Sets the quaternion with four components as a sample scalar.
 
void SetNull ()
 Sets the quaternion as a null quaternion.
 
void SetUnit ()
 Sets the quaternion as a unit quaternion.
 
void SetScalar (Real s)
 Sets the scalar part only.
 
void SetVector (const ChVector< Real > &v)
 Sets the vectorial part only.
 
bool Equals (const ChQuaternion< Real > &other) const
 Return true if quaternion is identical to other quaternion.
 
bool Equals (const ChQuaternion< Real > &other, Real tol) const
 Return true if quaternion equals another quaternion, within a tolerance 'tol'.
 
ChVector< Real > GetVector () const
 Gets the vectorial part only.
 
ChVector< Real > GetXaxis () const
 Get the X axis of a coordsystem, given the quaternion which represents the alignment of the coordsystem. More...
 
ChVector< Real > GetYaxis () const
 Get the Y axis of a coordsystem, given the quaternion which represents the alignment of the coordsystem. More...
 
ChVector< Real > GetZaxis () const
 Get the Z axis of a coordsystem, given the quaternion which represents the alignment of the coordsystem. More...
 
Real Length () const
 Compute the euclidean norm of the quaternion, that is its length or magnitude.
 
Real Length2 () const
 Compute the squared euclidean norm of the quaternion.
 
Real LengthInf () const
 Compute the infinity norm of the quaternion, that is the maximum absolute value of one of its elements.
 
Real & operator[] (unsigned index)
 Subscript operator.
 
const Real & operator[] (unsigned index) const
 
ChQuaternion< Real > & operator= (const ChQuaternion< Real > &other)
 Assignment operator: copy from another quaternion.
 
ChQuaternion< Real > operator+ () const
 Operator for sign change.
 
ChQuaternion< Real > operator- () const
 
ChQuaternion< Real > operator! () const
 Operator for making a conjugate quaternion (the original is not changed). More...
 
ChQuaternion< Real > operator+ (const ChQuaternion< Real > &other) const
 Operator for quaternion sum.
 
ChQuaternion< Real > & operator+= (const ChQuaternion< Real > &other)
 
ChQuaternion< Real > operator- (const ChQuaternion< Real > &other) const
 Operator for quaternion difference.
 
ChQuaternion< Real > & operator-= (const ChQuaternion< Real > &other)
 
ChQuaternion< Real > operator* (const ChQuaternion< Real > &other) const
 Operator for quaternion product: A*B means the typical quaternion product. More...
 
ChQuaternion< Real > & operator*= (const ChQuaternion< Real > &other)
 Operator for quaternion product and assignment: A*=B means A'=A*B, with typical quaternion product. More...
 
ChQuaternion< Real > operator>> (const ChQuaternion< Real > &other) const
 Operator for 'specular' quaternion product: A>>B = B*A. More...
 
ChQuaternion< Real > & operator>>= (const ChQuaternion< Real > &other)
 Operator for quaternion 'specular' product and assignment: A>>=B means A'=A>>B, or A'=B*A with typical quaternion product. More...
 
ChQuaternion< Real > operator* (Real s) const
 
ChQuaternion< Real > & operator*= (Real s)
 
ChQuaternion< Real > operator/ (const ChQuaternion< Real > &other) const
 Operator for element-wise division. More...
 
ChQuaternion< Real > & operator/= (const ChQuaternion< Real > &other)
 
ChQuaternion< Real > operator/ (Real s) const
 Operator for scaling the quaternion by inverse of a scalar value, as q/s.
 
ChQuaternion< Real > & operator/= (Real s)
 
ChQuaternion< Real > operator% (const ChQuaternion< Real > &other) const
 Operator for quaternion product: AB means the typical quaternion product AxB. More...
 
ChQuaternion< Real > & operator%= (const ChQuaternion< Real > &other)
 
Real operator^ (const ChQuaternion< Real > &other) const
 Operator for dot product: A^B means the scalar dot-product A*B. More...
 
bool operator<= (const ChQuaternion< Real > &other) const
 Component-wise comparison operators.
 
bool operator>= (const ChQuaternion< Real > &other) const
 
bool operator< (const ChQuaternion< Real > &other) const
 
bool operator> (const ChQuaternion< Real > &other) const
 
bool operator== (const ChQuaternion< Real > &other) const
 
bool operator!= (const ChQuaternion< Real > &other) const
 
void Add (const ChQuaternion< Real > &A, const ChQuaternion< Real > &B)
 Set this quaternion to the sum of A and B: this = A + B.
 
void Sub (const ChQuaternion< Real > &A, const ChQuaternion< Real > &B)
 Set this quaternion to the difference of A and B: this = A - B.
 
void Cross (const ChQuaternion< Real > &qa, const ChQuaternion< Real > &qb)
 Set this quaternion to the quaternion product of the two quaternions A and B, following the classic Hamilton rule: this = AxB. More...
 
Real Dot (const ChQuaternion< Real > &B) const
 Return the dot product with another quaternion: result = this ^ B.
 
void Mul (const ChQuaternion< Real > &A, Real s)
 Set this quaternion to the product of a quaternion A and scalar s: this = A * s.
 
void Scale (Real s)
 Scale this quaternion by a scalar: this *= s.
 
bool Normalize ()
 Normalize this quaternion in place, so that its euclidean length is 1. More...
 
ChQuaternion< Real > GetNormalized () const
 Return a normalized copy of this quaternion, with euclidean length = 1. More...
 
void Conjugate (const ChQuaternion< Real > &A)
 Set this quaternion to the conjugate of the A quaternion.
 
void Conjugate ()
 Conjugate this quaternion in place (its vectorial part changes sign).
 
ChQuaternion< Real > GetConjugate () const
 Return a conjugated version of this quaternion.
 
ChQuaternion< Real > GetInverse () const
 Return the inverse of this quaternion.
 
ChVector< Real > Rotate (const ChVector< Real > &A) const
 Rotate the vector A on the basis of this quaternion: res=p*[0,A]*p' (speed-optimized version). More...
 
ChVector< Real > RotateBack (const ChVector< Real > &A) const
 Rotate the vector A on the basis of conjugate of this quaternion: res=p'*[0,A]*p (speed-optimized version). More...
 
void Q_from_Rotv (const ChVector< Real > &angle_axis)
 Set the quaternion from a rotation vector (ie. More...
 
ChVector< Real > Q_to_Rotv ()
 Get the rotation vector (ie. More...
 
void Q_from_AngAxis (Real angle, const ChVector< Real > &axis)
 Set the quaternion from an agle of rotation and an axis, defined in absolute coords. More...
 
void Q_from_AngX (Real angleX)
 Set the quaternion from an agle of rotation about X axis.
 
void Q_from_AngY (Real angleY)
 Set the quaternion from an agle of rotation about Y axis.
 
void Q_from_AngZ (Real angleZ)
 Set the quaternion from an agle of rotation about Z axis.
 
void Q_to_AngAxis (Real &a_angle, ChVector< Real > &a_axis) const
 Convert the quaternion to an agle of rotation and an axis, defined in absolute coords. More...
 
void Q_from_NasaAngles (const ChVector< Real > &ang)
 Set the quaternion from three angles (NASA angle set) heading, bank, and attitude.
 
ChVector< Real > Q_to_NasaAngles ()
 Convert the quaternion to three angles (NASA angle set) heading, bank and attitude.
 
void Qdt_from_Wabs (const ChVector< Real > &w, const ChQuaternion< Real > &q)
 Set the quaternion dq/dt. More...
 
void Qdt_from_Wrel (const ChVector< Real > &w, const ChQuaternion< Real > &q)
 Set the quaternion dq/dt. More...
 
void Qdt_to_Wabs (ChVector< Real > &w, const ChQuaternion< Real > &q)
 Compute the vector of angular speed 'w' specified in absolute coords, from the quaternion dq/dt and the rotation expressed as a quaternion q. More...
 
void Qdt_to_Wrel (ChVector< Real > &w, const ChQuaternion< Real > &q)
 Compute the vector of angular speed 'w' specified in relative coords, from the quaternion dq/dt and the rotation expressed as a quaternion q. More...
 
void Qdtdt_from_Aabs (const ChVector< Real > &a, const ChQuaternion< Real > &q, const ChQuaternion< Real > &q_dt)
 Set the quaternion ddq/dtdt. More...
 
void Qdtdt_from_Arel (const ChVector< Real > &a, const ChQuaternion< Real > &q, const ChQuaternion< Real > &q_dt)
 Set the quaternion ddq/dtdt. More...
 
void Qdt_from_AngAxis (const ChQuaternion< Real > &q, Real angle_dt, const ChVector< Real > &axis)
 Set the quaternion dq/dt. More...
 
void Qdtdt_from_AngAxis (const ChQuaternion< Real > &q, const ChQuaternion< Real > &q_dt, Real angle_dtdt, const ChVector< Real > &axis)
 Set the quaternion ddq/dtdt. More...
 
void ImmQ_complete (const ChVector< Real > &qimm)
 Given the imaginary (vectorial) {e1 e2 e3} part of a quaternion, tries to set the entire quaternion q = {e0, e1, e2, e3}. More...
 
void ImmQ_dt_complete (const ChQuaternion< Real > &q, const ChVector< Real > &qimm_dt)
 
void ImmQ_dtdt_complete (const ChQuaternion< Real > &q, const ChQuaternion< Real > &qdt, const ChVector< Real > &qimm_dtdt)
 
void ArchiveOUT (ChArchiveOut &marchive)
 Method to allow serialization of transient data in archives.
 
void ArchiveIN (ChArchiveIn &marchive)
 Method to allow de-serialization of transient data from archives.
 

Friends

template<typename RealB >
class ChQuaternion
 Declaration of friend classes.
 

Constructor & Destructor Documentation

template<class Real >
chrono::ChQuaternion< Real >::ChQuaternion ( )

Default constructor.

Note that this constructs a null quaternion {0,0,0,0}, not a {1,0,0,0} unit quaternion.

Member Function Documentation

template<class Real>
void chrono::ChQuaternion< Real >::Cross ( const ChQuaternion< Real > &  qa,
const ChQuaternion< Real > &  qb 
)

Set this quaternion to the quaternion product of the two quaternions A and B, following the classic Hamilton rule: this = AxB.

This is the true, typical quaternion product. It is NOT commutative.

template<class Real >
ChQuaternion< Real > chrono::ChQuaternion< Real >::GetNormalized ( ) const

Return a normalized copy of this quaternion, with euclidean length = 1.

Not to be confused with Normalize() which normalizes in place.

template<class Real >
ChVector< Real > chrono::ChQuaternion< Real >::GetXaxis ( ) const

Get the X axis of a coordsystem, given the quaternion which represents the alignment of the coordsystem.

Note that it is assumed that the quaternion is already normalized.

template<class Real >
ChVector< Real > chrono::ChQuaternion< Real >::GetYaxis ( ) const

Get the Y axis of a coordsystem, given the quaternion which represents the alignment of the coordsystem.

Note that it is assumed that the quaternion is already normalized.

template<class Real >
ChVector< Real > chrono::ChQuaternion< Real >::GetZaxis ( ) const

Get the Z axis of a coordsystem, given the quaternion which represents the alignment of the coordsystem.

Note that it is assumed that the quaternion is already normalized.

template<class Real>
void chrono::ChQuaternion< Real >::ImmQ_complete ( const ChVector< Real > &  qimm)

Given the imaginary (vectorial) {e1 e2 e3} part of a quaternion, tries to set the entire quaternion q = {e0, e1, e2, e3}.

Also for q_dt and q_dtdt. Note: singularities may happen!

template<class Real >
bool chrono::ChQuaternion< Real >::Normalize ( )

Normalize this quaternion in place, so that its euclidean length is 1.

Return false if the original quaternion had zero length (in which case the quaternion is set to [1,0,0,0]) and return true otherwise.

template<class Real >
ChQuaternion< Real > chrono::ChQuaternion< Real >::operator! ( ) const

Operator for making a conjugate quaternion (the original is not changed).

A conjugate quaternion has the vectorial part with changed sign.

template<class Real>
ChQuaternion< Real > chrono::ChQuaternion< Real >::operator% ( const ChQuaternion< Real > &  other) const

Operator for quaternion product: AB means the typical quaternion product AxB.

Note: DEPRECATED, use the * operator instead.

template<class Real>
ChQuaternion< Real > chrono::ChQuaternion< Real >::operator* ( const ChQuaternion< Real > &  other) const

Operator for quaternion product: A*B means the typical quaternion product.

Notes:

  • since unit quaternions can represent rotations, the product can represent a concatenation of rotations as: frame_rotation_2to0 = frame_rotation_1to0 * frame_rotation_2to1
  • pay attention to operator low precedence (see C++ precedence rules!)
  • quaternion product is not commutative.
template<class Real>
ChQuaternion< Real > & chrono::ChQuaternion< Real >::operator*= ( const ChQuaternion< Real > &  other)

Operator for quaternion product and assignment: A*=B means A'=A*B, with typical quaternion product.

Notes:

  • since unit quaternions can represent rotations, the product can represent a post-concatenation of a rotation in a kinematic chain.
  • quaternion product is not commutative.
template<class Real>
ChQuaternion< Real > chrono::ChQuaternion< Real >::operator/ ( const ChQuaternion< Real > &  other) const

Operator for element-wise division.

Note that this is NOT the quaternion division operation.

template<class Real>
ChQuaternion< Real > chrono::ChQuaternion< Real >::operator>> ( const ChQuaternion< Real > &  other) const

Operator for 'specular' quaternion product: A>>B = B*A.

Notes:

  • since unit quaternions can represent rotations, the product can represent a concatenation of rotations as: frame_rotation_2to0 = frame_rotation_2to1 >> frame_rotation_1to0
  • pay attention to operator low precedence (see C++ precedence rules!)
  • quaternion product is not commutative.
template<class Real>
ChQuaternion< Real > & chrono::ChQuaternion< Real >::operator>>= ( const ChQuaternion< Real > &  other)

Operator for quaternion 'specular' product and assignment: A>>=B means A'=A>>B, or A'=B*A with typical quaternion product.

Notes:

  • since unit quaternions can represent rotations, the product can represent a pre-concatenation of a rotation in a kinematic chain.
  • quaternion product is not commutative.
template<class Real>
Real chrono::ChQuaternion< Real >::operator^ ( const ChQuaternion< Real > &  other) const

Operator for dot product: A^B means the scalar dot-product A*B.

Note: pay attention to operator low precedence (see C++ precedence rules!)

template<class Real>
void chrono::ChQuaternion< Real >::Q_from_AngAxis ( Real  angle,
const ChVector< Real > &  axis 
)

Set the quaternion from an agle of rotation and an axis, defined in absolute coords.

The axis is supposed to be fixed, i.e. it is constant during rotation! NOTE, axis must be normalized! If you need directly the rotation vector=axis * angle, use Q_from_Rotv().

template<class Real>
void chrono::ChQuaternion< Real >::Q_from_Rotv ( const ChVector< Real > &  angle_axis)

Set the quaternion from a rotation vector (ie.

a 3D axis of rotation with length as agle of rotation) defined in absolute coords. If you need distinct axis and angle, use Q_from_AngAxis().

template<class Real>
void chrono::ChQuaternion< Real >::Q_to_AngAxis ( Real &  a_angle,
ChVector< Real > &  a_axis 
) const

Convert the quaternion to an agle of rotation and an axis, defined in absolute coords.

Resulting angle and axis must be passed as parameters. If you need directly the rotation vector=axis * angle, use Q_to_Rotv().

template<class Real >
ChVector< Real > chrono::ChQuaternion< Real >::Q_to_Rotv ( )

Get the rotation vector (ie.

a 3D axis of rotation with length as agle of rotation) from a quaternion. If you need distinct axis and angle, use rather Q_to_AngAxis().

template<class Real>
void chrono::ChQuaternion< Real >::Qdt_from_AngAxis ( const ChQuaternion< Real > &  q,
Real  angle_dt,
const ChVector< Real > &  axis 
)

Set the quaternion dq/dt.

Inputs: the axis of rotation 'axis' (assuming it is already normalized and expressed in absolute coords), the angular speed 'angle_dt' (scalar value), and the rotation expressed as a quaternion 'q'.

template<class Real>
void chrono::ChQuaternion< Real >::Qdt_from_Wabs ( const ChVector< Real > &  w,
const ChQuaternion< Real > &  q 
)

Set the quaternion dq/dt.

Inputs: the vector of angular speed w specified in absolute coords, and the rotation expressed as a quaternion q.

template<class Real>
void chrono::ChQuaternion< Real >::Qdt_from_Wrel ( const ChVector< Real > &  w,
const ChQuaternion< Real > &  q 
)

Set the quaternion dq/dt.

Inputs: the vector of angular speed w specified in relative coords, and the rotation expressed as a quaternion q.

template<class Real>
void chrono::ChQuaternion< Real >::Qdt_to_Wabs ( ChVector< Real > &  w,
const ChQuaternion< Real > &  q 
)

Compute the vector of angular speed 'w' specified in absolute coords, from the quaternion dq/dt and the rotation expressed as a quaternion q.

template<class Real>
void chrono::ChQuaternion< Real >::Qdt_to_Wrel ( ChVector< Real > &  w,
const ChQuaternion< Real > &  q 
)

Compute the vector of angular speed 'w' specified in relative coords, from the quaternion dq/dt and the rotation expressed as a quaternion q.

template<class Real>
void chrono::ChQuaternion< Real >::Qdtdt_from_Aabs ( const ChVector< Real > &  a,
const ChQuaternion< Real > &  q,
const ChQuaternion< Real > &  q_dt 
)

Set the quaternion ddq/dtdt.

Inputs: the vector of angular acceleration 'a' specified in absolute coords, the rotation expressed as a quaternion q, the rotation speed as a quaternion 'q_dt'.

template<class Real>
void chrono::ChQuaternion< Real >::Qdtdt_from_AngAxis ( const ChQuaternion< Real > &  q,
const ChQuaternion< Real > &  q_dt,
Real  angle_dtdt,
const ChVector< Real > &  axis 
)

Set the quaternion ddq/dtdt.

Inputs: the axis of ang. acceleration 'axis' (assuming it is already normalized and expressed in absolute coords), the angular acceleration 'angle_dtdt' (scalar value), the rotation expressed as a quaternion 'quat' and th rotation speed 'q_dt'.

template<class Real>
void chrono::ChQuaternion< Real >::Qdtdt_from_Arel ( const ChVector< Real > &  a,
const ChQuaternion< Real > &  q,
const ChQuaternion< Real > &  q_dt 
)

Set the quaternion ddq/dtdt.

Inputs: the vector of angular acceleration 'a' specified in relative coords, the rotation expressed as a quaternion q, the rotation speed as a quaternion 'q_dt'.

template<class Real>
ChVector< Real > chrono::ChQuaternion< Real >::Rotate ( const ChVector< Real > &  A) const

Rotate the vector A on the basis of this quaternion: res=p*[0,A]*p' (speed-optimized version).

Endomorphism assumes p is already normalized.

template<class Real>
ChVector< Real > chrono::ChQuaternion< Real >::RotateBack ( const ChVector< Real > &  A) const

Rotate the vector A on the basis of conjugate of this quaternion: res=p'*[0,A]*p (speed-optimized version).

Endomorphism assumes p is already normalized.