revision: v0.14
Quaternion Class Reference

This class contains the 4 components of a quaternion and the standard operators and functions needed for quaternion arithmetic. More...

#include <Quaternion.h>

Public Member Functions

 Quaternion ()
 Constructor; sets quaternion value to (1,0,0,0) More...
 
 Quaternion (Mdouble q0, Mdouble q1, Mdouble q2, Mdouble q3)
 Alternative constructor. Sets quaternion value to (q0,q1,q2,q3) More...
 
 Quaternion (Vec3D normal)
 
void setUnity ()
 Sets quaternion value to (1,0,0,0) More...
 
bool isUnity () const
 Checks if the quaternion value is (1,0,0,0) More...
 
Quaternion operator+ (const Quaternion &a) const
 Adds another quaternion and returns the result. More...
 
Quaternion operator- (const Quaternion &a) const
 Subtracts another quaternion and returns the result. More...
 
Quaternion operator* (Mdouble a) const
 Multiplies by a scalar. More...
 
Quaternion operator/ (Mdouble a) const
 Divides by a scalar. More...
 
Quaternionoperator+= (const Quaternion &a)
 Adds another quaternion. More...
 
Quaternionoperator-= (const Quaternion &a)
 Subtracts another quaternion. More...
 
Quaternionoperator*= (Mdouble a)
 Multiplies *this by a scalar. More...
 
Quaternionoperator/= (Mdouble a)
 Divides by a scalar. More...
 
void normalise ()
 Makes this Quaternion unit length |q|=1. More...
 
void setLength (Mdouble length)
 Make this Quaternion a certain length |q|=length. More...
 
Mdouble getLength () const
 Calculates the length of this Quaternion: \( \sqrt{a\cdot a} \). More...
 
Mdouble getLengthSquared () const
 Calculates the squared length of this Quaternion: \( a\cdot a \). More...
 
Mdouble getComponent (int index) const
 Returns the requested component of this Quaternion. More...
 
Quaternion angularVelocityBodyFixedFrameToAngularDisplacement (Vec3D v) const
 
Quaternion angularDisplacementTimeDerivative (Vec3D v) const
 Converts an angular momentum v=omega into a quaternion rate of change, q(t+dt)-q(t)/dt. More...
 
void updateAngularDisplacement (Vec3D angularVelocityDt)
 
Vec3D applyCInverse (Quaternion q) const
 Converts quaternion rate of change into an angular momentum omega. More...
 
void setComponent (int index, double val)
 Sets the requested component of this Quaternion to the requested value. More...
 
bool isEqualTo (const Quaternion &other, double tol) const
 Checks if the length this Quaternion is equal the length of other with a certain tolerance. More...
 
Vec3D getEuler () const
 Convert a quaternion to Euler angles. See Wikipedia for details. More...
 
void setEuler (const Vec3D &e)
 Convert Euler angles to a quaternion. See Wikipedia for details. More...
 
Mdouble getAngleZ () const
 Converts a quaternion to the rotation angle in the XY plane (for Mercury2D). See Wikipedia for details. More...
 
void setAngleZ (Mdouble psi)
 Converts the rotation angle in the XY plane into a quaternion (for Mercury2D). See Wikipedia for details. More...
 
MatrixSymmetric3D rotateInverseInertiaTensor (const MatrixSymmetric3D &invI) const
 Converts the inverse inertia tensor from the reference frame to the lab frame; see See QuaternionsWouter.pdf for details, where this operation is denoted by \(A*I^{-1}*A^T\). More...
 
void rotateTensor (SmallMatrix< 3, 3 > I) const
 
Vec3D getAxis () const
 Converts the quaternions into a normal vector by rotating the vector x=(1,0,0); see See Wiki for details. More...
 
void setOrientationViaNormal (Vec3D normal)
 
void getRotationMatrix (SmallMatrix< 3, 3 > &A) const
 
void rotate (Vec3D &position) const
 
void rotate (SmallVector< 3 > &position) const
 
void rotateBack (Vec3D &position) const
 
Mdouble getDistance (Vec3D p, Vec3D p0) const
 

Static Public Member Functions

static Mdouble getDistance (const Quaternion &a, const Quaternion &b)
 Calculates the distance between two Quaternion: \( \sqrt{\left(a-b\right) \cdot \left(a-b\right)} \). More...
 
static Mdouble getDistanceSquared (const Quaternion &a, const Quaternion &b)
 Calculates the squared distance between two Quaternion: \( \left(a-b\right) \cdot \left(a-b\right) \). More...
 
static Mdouble getLength (const Quaternion &a)
 Calculates the length of a Quaternion: \( \sqrt{a\cdot a} \). More...
 
static Mdouble getLengthSquared (const Quaternion &a)
 Calculates the squared length of a Quaternion: \( a\cdot a \). More...
 
static Quaternion getUnitQuaternion (const Quaternion &a)
 Returns a unit Quaternion based on a. More...
 

Public Attributes

Mdouble q0
 the zeroth component of the quaternion q = (q0,q1,q2,q3) More...
 
Mdouble q1
 the first component of the quaternion q = (q0,q1,q2,q3) More...
 
Mdouble q2
 the second component of the quaternion q = (q0,q1,q2,q3) More...
 
Mdouble q3
 the third component of the quaternion q = (q0,q1,q2,q3) More...
 

Friends

std::ostream & operator<< (std::ostream &os, const Quaternion &a)
 Adds elements to an output stream. More...
 
std::istream & operator>> (std::istream &is, Quaternion &a)
 Adds elements to an input stream. More...
 
Quaternion operator+ (Mdouble a, const Quaternion &b)
 Adds a scalar to a quaternion. More...
 
Quaternion operator- (Mdouble a, const Quaternion &b)
 Subtracts the elements of a quaternion from a scalar. More...
 
Quaternion operator- (const Quaternion &a)
 Subtracts a quaternion. More...
 
Quaternion operator* (Mdouble a, const Quaternion &b)
 Multiplies all elements by a scalar. More...
 

Detailed Description

This class contains the 4 components of a quaternion and the standard operators and functions needed for quaternion arithmetic.

Implementation of a 3D quaternion (by Vitaliy). Modifications 21:9:2009 - Added the inclusion guards and some include objects

Todo:
Need to generalize this to n-dimensional quaternions of any type

A quaternion is a four-dimensional vector q = (q0,q1,q2,q3) that satisfies |q|^2=q0^2+q1^2+q2^2+q3^2=1. It can be used to describe the orientation of an object in space.

The properties (e.g. inertia tensor) of any interactable (particle or wall) in MercuryDPM are described in its reference frame. The quaternion is used to rotate the object into the lab frame (the system geometry). A few examples to help visualising quaternions can be found here .

The unit quaternion, q=(1,0,0,0) denotes the state where the lab frame and the reference frame is identical.

To see how to convert a quaternion to Euler angles or to compare it to a rotation of an object around a axis, see Wikipedia for details.

Constructor & Destructor Documentation

◆ Quaternion() [1/3]

Quaternion::Quaternion ( )

Constructor; sets quaternion value to (1,0,0,0)

Default constructor

31 {
32  setUnity();
33 }

References setUnity().

Referenced by angularDisplacementTimeDerivative(), angularVelocityBodyFixedFrameToAngularDisplacement(), getUnitQuaternion(), operator*(), operator+(), operator-(), operator/(), and setOrientationViaNormal().

◆ Quaternion() [2/3]

Quaternion::Quaternion ( Mdouble  q0,
Mdouble  q1,
Mdouble  q2,
Mdouble  q3 
)

Alternative constructor. Sets quaternion value to (q0,q1,q2,q3)

Alternative constructor, lets you define all four elements.

Parameters
[in]q0the q0-component
[in]q1the q1-component
[in]q2the q2-component
[in]q3the q3-component
43 {
44  this->q0 = q0;
45  this->q1 = q1;
46  this->q2 = q2;
47  this->q3 = q3;
48 }

References q0, q1, q2, and q3.

◆ Quaternion() [3/3]

Quaternion::Quaternion ( Vec3D  normal)
inline
Todo:
should be explicit as teh conversion is not unique
Parameters
normal
98  {
100  }

References setOrientationViaNormal().

Member Function Documentation

◆ angularDisplacementTimeDerivative()

Quaternion Quaternion::angularDisplacementTimeDerivative ( Vec3D  v) const

Converts an angular momentum v=omega into a quaternion rate of change, q(t+dt)-q(t)/dt.

Given v = \omega * dt, with omega the angular velocity, this computes the change in angular displacement to be added in the time integration. This is equivalent to applying the matrix \tilde{C}

423 {
424  return 0.5 * Quaternion(
425  -q1 * v.X - q2 * v.Y - q3 * v.Z,
426  q0 * v.X + q3 * v.Y - q2 * v.Z,
427  -q3 * v.X + q0 * v.Y + q1 * v.Z,
428  q2 * v.X - q1 * v.Y + q0 * v.Z);
429 }

References q0, q1, q2, q3, Quaternion(), Vec3D::X, Vec3D::Y, and Vec3D::Z.

Referenced by updateAngularDisplacement().

◆ angularVelocityBodyFixedFrameToAngularDisplacement()

Quaternion Quaternion::angularVelocityBodyFixedFrameToAngularDisplacement ( Vec3D  v) const
Todo:
should the arguments be passed by reference?
Todo:
rename to angularVelocityBodyFixedFrameToAngularDisplacement?
412 {
413  return Quaternion(
414  -q1 * v.X - q2 * v.Y - q3 * v.Z,
415  q0 * v.X - q3 * v.Y + q2 * v.Z,
416  q3 * v.X + q0 * v.Y - q1 * v.Z,
417  -q2 * v.X + q1 * v.Y + q0 * v.Z);
418 }

References q0, q1, q2, q3, Quaternion(), Vec3D::X, Vec3D::Y, and Vec3D::Z.

◆ applyCInverse()

Vec3D Quaternion::applyCInverse ( Quaternion  q) const

Converts quaternion rate of change into an angular momentum omega.

Todo:
rename to angularDisplacementToAngularVelocity?
442 {
443  return 2.0 * Vec3D(
444  -q1 * q.q0 + q0 * q.q1 - q3 * q.q2 + q2 * q.q3,
445  -q2 * q.q0 + q3 * q.q1 + q0 * q.q2 - q1 * q.q3,
446  -q3 * q.q0 - q2 * q.q1 + q1 * q.q2 + q0 * q.q3);
447 }

References q0, q1, q2, and q3.

◆ getAngleZ()

Mdouble Quaternion::getAngleZ ( ) const

Converts a quaternion to the rotation angle in the XY plane (for Mercury2D). See Wikipedia for details.

488 {
489  return -std::atan2(2 * (q0 * q3 + q1 * q2), 1 - 2 * (q2 * q2 + q3 * q3));
490 }

References q0, q1, q2, and q3.

Referenced by MarbleRun::actionsAfterTimeStep().

◆ getAxis()

Vec3D Quaternion::getAxis ( ) const

Converts the quaternions into a normal vector by rotating the vector x=(1,0,0); see See Wiki for details.

502 {
503  //logger(ERROR,"o % d % d %",*this,Vec3D(1-2.0*q2*q2-2.0*q3*q3, 2.0*(q1*q2+q3*q0), 2.0*(q1*q3-q2*q0)),Vec3D(q0*q0+q1*q1-q2*q2-q3*q3, 2.0*(q1*q2+q3*q0), 2.0*(q1*q3-q2*q0)));
504  return Vec3D(q0 * q0 - q3 * q3 + q1 * q1 - q2 * q2, 2.0 * (q1 * q2 + q3 * q0), 2.0 * (q1 * q3 - q2 * q0));
505 }

References q0, q1, q2, and q3.

Referenced by HorizontalBaseScrew::convertLimits(), InfiniteWall::createVTK(), AxisymmetricIntersectionOfWalls::getDistanceAndNormal(), HorizontalBaseScrew::getDistanceAndNormal(), InfiniteWall::getDistanceAndNormal(), InfiniteWall::getDistanceNormalOverlapSuperquadric(), InfiniteWall::getNormal(), CGFields::OrientationField::setFields(), AngledPeriodicBoundary::shiftPosition(), and HorizontalBaseScrew::writeVTK().

◆ getComponent()

Mdouble Quaternion::getComponent ( int  index) const

Returns the requested component of this Quaternion.

returns the quaternion element belonging to the given index.

Parameters
[in]indexthe index of interest (should be 0, 1 or 2)
Returns
the value of the quaternion element belonging to the given index
233 {
234  switch (index)
235  {
236  case 0:
237  return q0;
238  case 1:
239  return q1;
240  case 2:
241  return q2;
242  case 3:
243  return q3;
244  default:
245  logger(ERROR,
246  "[Quaternion::getComponent] Index = %, which is too high for a 3D quaternion (should be 0-2).",
247  index);
248  return 0;
249  }
250 }

References ERROR, logger, q0, q1, q2, and q3.

Referenced by mathsFunc::isEqual().

◆ getDistance() [1/2]

Mdouble Quaternion::getDistance ( const Quaternion a,
const Quaternion b 
)
static

Calculates the distance between two Quaternion: \( \sqrt{\left(a-b\right) \cdot \left(a-b\right)} \).

Calculates the distance (i.e. the length of the difference) between two quaternions NB: this is a STATIC function!

Parameters
[in]athe first quaternion
[in]bthe second quaternion
Returns
the distance between the two arguments.
189 {
190  return std::sqrt(getDistanceSquared(a, b));
191 }

References getDistanceSquared().

Referenced by InfiniteWall::getDistance(), and isEqualTo().

◆ getDistance() [2/2]

Mdouble Quaternion::getDistance ( Vec3D  p,
Vec3D  p0 
) const

Calculates the distance from a wall through p0 whose normal is the vector (1,0,0). Used for the calculation of the distance in InfiniteWalls

616 {
617  return (q0 * q0 + q1 * q1 - q2 * q2 - q3 * q3) * (p0.X - p.X) +
618  2.0 * ((q1 * q2 + q0 * q3) * (p0.Y - p.Y) + (q1 * q3 - q0 * q2) * (p0.Z - p.Z));
619 }

References q0, q1, q2, q3, Vec3D::X, Vec3D::Y, and Vec3D::Z.

◆ getDistanceSquared()

Mdouble Quaternion::getDistanceSquared ( const Quaternion a,
const Quaternion b 
)
static

Calculates the squared distance between two Quaternion: \( \left(a-b\right) \cdot \left(a-b\right) \).

Calculates the square of the distance (i.e. the length of the difference) between two quaternions. NB: this is a STATIC function!

Parameters
[in]athe first quaternion
[in]bthe second quaternion
Returns
the square of the distance between the two arguments.
202 {
203  return ((a.q0 - b.q0) * (a.q0 - b.q0) + (a.q1 - b.q1) * (a.q1 - b.q1) + (a.q2 - b.q2) * (a.q2 - b.q2) +
204  (a.q3 - b.q3) * (a.q3 - b.q3));
205 }

References q0, q1, q2, and q3.

Referenced by getDistance().

◆ getEuler()

Vec3D Quaternion::getEuler ( ) const

Convert a quaternion to Euler angles. See Wikipedia for details.

Get the Euler angles of this quaternion. Example of visualising Euler angles can be found here

453 {
454  Mdouble sinp = 2 * (q0 * q2 - q3 * q1);
455  Mdouble pitch;
456  const Mdouble pi = 3.141592653589793238462643383279502884197169399375105820974944592307816406286208998628034825342117068;
457 
458  if ((std::abs(sinp) < 1))
459  {
460  pitch = std::asin(sinp);
461  }
462  else
463  {
464  pitch = copysign(pi/2., sinp);
465  }
466 
467  return Vec3D(
468  std::atan2(2 * (q0 * q1 + q2 * q3), 1 - 2 * (q1 * q1 + q2 * q2)),
469  pitch,
470  std::atan2(2 * (q0 * q3 + q1 * q2), 1 - 2 * (q2 * q2 + q3 * q3)));
471 }

References constants::pi, q0, q1, q2, and q3.

Referenced by EllipticalSuperQuadricCollision::setupInitialConditions(), test1(), and test2().

◆ getLength() [1/2]

Mdouble Quaternion::getLength ( ) const

Calculates the length of this Quaternion: \( \sqrt{a\cdot a} \).

Calculates the length of this quaternion

Returns
the (scalar) length of this quaternion
300 {
301  return std::sqrt(getLengthSquared());
302 }

References getLengthSquared().

Referenced by setLength().

◆ getLength() [2/2]

Mdouble Quaternion::getLength ( const Quaternion a)
static

Calculates the length of a Quaternion: \( \sqrt{a\cdot a} \).

Calculates the length of a given quaternion NB: this is a STATIC function!

Parameters
[in]aquaternion to be measured.
Returns
length of the argument.
311 {
312  return a.getLength();
313 }

References getLength().

Referenced by getLength().

◆ getLengthSquared() [1/2]

Mdouble Quaternion::getLengthSquared ( ) const

Calculates the squared length of this Quaternion: \( a\cdot a \).

Calculates the square of the length of itself

Returns
the square of the length of this quaternion
223 {
224  return (q0 * q0 + q1 * q1 + q2 * q2 + q3 * q3);
225 }

References q0, q1, q2, and q3.

Referenced by getLength(), and normalise().

◆ getLengthSquared() [2/2]

Mdouble Quaternion::getLengthSquared ( const Quaternion a)
static

Calculates the squared length of a Quaternion: \( a\cdot a \).

Calculates the square of the length of a given quaternion. NB: this is a STATIC function!

Parameters
[in]athe quaternion.
Returns
the square of the length of the argument.
214 {
215  return (a.q0 * a.q0 + a.q1 * a.q1 + a.q2 * a.q2 + a.q3 * a.q3);
216 }

References q0, q1, q2, and q3.

Referenced by getUnitQuaternion().

◆ getRotationMatrix()

void Quaternion::getRotationMatrix ( SmallMatrix< 3, 3 > &  A) const

Retrieves the rotation matrix

Parameters
[out]AThe rotation matrix
509 {
510 
511  Mdouble q00 = q0 * q0;
512  Mdouble q01 = 2 * q0 * q1;
513  Mdouble q02 = 2 * q0 * q2;
514  Mdouble q03 = 2 * q0 * q3;
515  Mdouble q11 = q1 * q1;
516  Mdouble q12 = 2 * q1 * q2;
517  Mdouble q13 = 2 * q1 * q3;
518  Mdouble q22 = q2 * q2;
519  Mdouble q23 = 2 * q2 * q3;
520  Mdouble q33 = q3 * q3;
521  A(0, 0) = q00 + q11 - q22 - q33;
522  A(1, 0) = q12 + q03;
523  A(2, 0) = q13 - q02;
524  A(0, 1) = q12 - q03;
525  A(1, 1) = q00 - q11 + q22 - q33;
526  A(2, 1) = q23 + q01;
527  A(0, 2) = q13 + q02;
528  A(1, 2) = q23 - q01;
529  A(2, 2) = q00 - q11 - q22 + q33;
530 }

References A, q0, q1, q2, and q3.

Referenced by SuperQuadricParticle::computeHessianLabFixed(), rotate(), rotateTensor(), ShapeGradientHessianTester::testCushion(), ShapeGradientHessianTester::testEllipsoid(), and ShapeGradientHessianTester::testRoundedBeam().

◆ getUnitQuaternion()

Quaternion Quaternion::getUnitQuaternion ( const Quaternion a)
static

Returns a unit Quaternion based on a.

Calculates the unit quaternion of a given quaternion (unless it is a quaternion with zero length; in that case it returns a 3D quaternion with each element equal to zero). NB: this is a STATIC function!

Parameters
[in]athe quaternion of interest
Returns
unit quaternion in the direction of the argument (unless the argument has length zero; in that case a zero-quaternion).
325 {
326  Mdouble Length2 = a.getLengthSquared();
327  if (Length2 != 0.0)
328  return a / std::sqrt(Length2);
329  else
330  return Quaternion(1, 0, 0, 0);
331 }

References getLengthSquared(), and Quaternion().

◆ isEqualTo()

bool Quaternion::isEqualTo ( const Quaternion other,
double  tol 
) const

Checks if the length this Quaternion is equal the length of other with a certain tolerance.

Checks if the length of the quaternion is equal to the one given in the first argument (other), with a tolerance given in the second argument (tol).

Parameters
[in]otherthe 3D quaternion to check against
[in]tolthe tolerance
Returns
returns TRUE if the difference between the lengths of this quaternion and that given in the first argument (other) is smaller than the given tolerance.
291 {
292  return (getDistance(*this, other) <= tol * tol);
293 }

References getDistance().

◆ isUnity()

bool Quaternion::isUnity ( ) const
inline

Checks if the quaternion value is (1,0,0,0)

Checks if ALL elements are zero

Returns
TRUE if q0 equals one and ALL other elements are zero
Bug:
use isEqual instead of ==
114  {
115  return q0 == 1.0 && q1 == 0.0 && q2 == 0.0 && q3 == 0.0;
116  };

References q0, q1, q2, and q3.

◆ normalise()

void Quaternion::normalise ( )

Makes this Quaternion unit length |q|=1.

Normalises the quaternion, i.e. divides all elements by the quaternions length (resulting in a quaternion in the same direction, but with unit length).

162 {
163  const Mdouble length2 = getLengthSquared();
164  if (length2 == 0)
165  {
166  logger(ERROR, "Normalizing a quaternion of length 0");
167  }
168  *this /= sqrt(length2);
169 }

References ERROR, getLengthSquared(), and logger.

Referenced by setOrientationViaNormal(), and updateAngularDisplacement().

◆ operator*()

Quaternion Quaternion::operator* ( Mdouble  a) const

Multiplies by a scalar.

Multiplies each element with a scalar

Parameters
[in]athe scalar to be multiplied with
Returns
the resulting quaternion
87 {
88  return Quaternion(q0 * a, q1 * a, q2 * a, q3 * a);
89 }

References q0, q1, q2, q3, and Quaternion().

◆ operator*=()

Quaternion & Quaternion::operator*= ( Mdouble  a)

Multiplies *this by a scalar.

Multiplies each element by a scalar

Parameters
[in]ascalar to be multiplied by
Returns
(reference to) itself, i.e. resulting quaternion
135 {
136  q0 *= a;
137  q1 *= a;
138  q2 *= a;
139  q3 *= a;
140  return *this;
141 }

References q0, q1, q2, and q3.

◆ operator+()

Quaternion Quaternion::operator+ ( const Quaternion a) const

Adds another quaternion and returns the result.

Adds quaternion to itself

Parameters
[in]aquaternion to be added
Returns
resulting 3D quaternion
67 {
68  return Quaternion(q0 + a.q0, q1 + a.q1, q2 + a.q2, q3 + a.q3);
69 }

References q0, q1, q2, q3, and Quaternion().

◆ operator+=()

Quaternion & Quaternion::operator+= ( const Quaternion a)

Adds another quaternion.

Adds a quaternion to itself

Parameters
[in]aquaternion to be added
Returns
(reference to) itself, i.e. resulting quaternion
107 {
108  q0 += a.q0;
109  q1 += a.q1;
110  q2 += a.q2;
111  q3 += a.q3;
112  return *this;
113 }

References q0, q1, q2, and q3.

◆ operator-()

Quaternion Quaternion::operator- ( const Quaternion a) const

Subtracts another quaternion and returns the result.

Subtracts quaternion from itself

Parameters
[in]aquaternion to be subtracted
Returns
resulting quaternion
77 {
78  return Quaternion(q0 - a.q0, q1 - a.q1, q2 - a.q2, q3 - a.q3);
79 }

References q0, q1, q2, q3, and Quaternion().

◆ operator-=()

Quaternion & Quaternion::operator-= ( const Quaternion a)

Subtracts another quaternion.

Subtracts a quaternion from itself

Parameters
[in]aquaternion to be subtracted
Returns
(reference to) itself, i.e. resulting quaternion
121 {
122  q0 -= a.q0;
123  q1 -= a.q1;
124  q2 -= a.q2;
125  q3 -= a.q3;
126  return *this;
127 }

References q0, q1, q2, and q3.

◆ operator/()

Quaternion Quaternion::operator/ ( Mdouble  a) const

Divides by a scalar.

Divides each element by a scalar

Parameters
[in]athe scalar to be divided by
Returns
resulting quaternion
97 {
98  return Quaternion(q0 / a, q1 / a, q2 / a, q3 / a);
99 }

References q0, q1, q2, q3, and Quaternion().

◆ operator/=()

Quaternion & Quaternion::operator/= ( Mdouble  a)

Divides by a scalar.

Divides each element by a scalar

Parameters
[in]ascalar to be divided by
Returns
(reference to) itself, i.e. resulting quaternion
149 {
150  q0 /= a;
151  q1 /= a;
152  q2 /= a;
153  q3 /= a;
154  return *this;
155 }

References q0, q1, q2, and q3.

◆ rotate() [1/2]

void Quaternion::rotate ( SmallVector< 3 > &  position) const

Applies the rotation to a position

Rotate the given vector from the body-fixed angles to the lab-fixed angles. This is the same as multiplying with the rotation matrix, A.

584 {
587  position = A * position;
588 }

References A, and getRotationMatrix().

◆ rotate() [2/2]

void Quaternion::rotate ( Vec3D position) const

◆ rotateBack()

void Quaternion::rotateBack ( Vec3D position) const

Applies the inverse rotation to a position

Rotate the given vector from the lab-fixed angles to the body-fixed angles. This is the same as multiplying with the inverse/transpose of the rotation matrix, A^T = A^{-1}.

593 {
594  Mdouble q00 = q0 * q0;
595  Mdouble q01 = 2 * q0 * q1;
596  Mdouble q02 = 2 * q0 * q2;
597  Mdouble q03 = 2 * q0 * q3;
598  Mdouble q11 = q1 * q1;
599  Mdouble q12 = 2 * q1 * q2;
600  Mdouble q13 = 2 * q1 * q3;
601  Mdouble q22 = q2 * q2;
602  Mdouble q23 = 2 * q2 * q3;
603  Mdouble q33 = q3 * q3;
604  position = Matrix3D(
605  q00 + q11 - q22 - q33, q12 + q03, q13 - q02,
606  q12 - q03, q00 - q11 + q22 - q33, q23 + q01,
607  q13 + q02, q23 - q01, q00 - q11 - q22 + q33) * position;
608 }

References q0, q1, q2, and q3.

Referenced by SuperQuadricParticle::computeHessianLabFixed(), SuperQuadricParticle::computeShape(), SuperQuadricParticle::computeShapeGradientLabFixed(), AxisymmetricIntersectionOfWalls::convertLimits(), ScrewsymmetricIntersectionOfWalls::convertLimits(), NurbsWall::getDistanceAndNormal(), Screw::getDistanceAndNormal(), BasicIntersectionOfWalls::getDistanceAndNormal(), BasicUnionOfWalls::getDistanceAndNormal(), IntersectionOfWalls::getDistanceAndNormal(), LevelSetWall::getDistanceAndNormal(), InfiniteWall::getDistanceNormalOverlapSuperquadric(), BaseWall::getInteractionWith(), ShapeGradientHessianTester::testCushion(), ShapeGradientHessianTester::testEllipsoid(), and ShapeGradientHessianTester::testRoundedBeam().

◆ rotateInverseInertiaTensor()

MatrixSymmetric3D Quaternion::rotateInverseInertiaTensor ( const MatrixSymmetric3D invI) const

Converts the inverse inertia tensor from the reference frame to the lab frame; see See QuaternionsWouter.pdf for details, where this operation is denoted by \(A*I^{-1}*A^T\).

Todo:
move link to where it belongs http://stackoverflow.com/questions/1171849/finding-quaternion-representing-the-rotation-from-one-vector-to-another This is the same as rotateTensor, but than for MatrixSymmetric3D instead of SmallMatrix<3,3>.
627 {
628  Mdouble a = 1 - 2 * q2 * q2 - 2 * q3 * q3;
629  Mdouble b = 2 * q1 * q2 - 2 * q0 * q3;
630  Mdouble c = 2 * q1 * q3 + 2 * q0 * q2;
631  Mdouble d = 2 * q1 * q2 + 2 * q0 * q3;
632  Mdouble e = 1 - 2 * q1 * q1 - 2 * q3 * q3;
633  Mdouble f = 2 * q2 * q3 - 2 * q0 * q1;
634  Mdouble g = 2 * q1 * q3 - 2 * q0 * q2;
635  Mdouble h = 2 * q2 * q3 + 2 * q0 * q1;
636  Mdouble i = 1 - 2 * q1 * q1 - 2 * q2 * q2;
638  invI.XX * a * a + 2 * invI.XY * a * b + 2 * invI.XZ * a * c + invI.YY * b * b + 2 * invI.YZ * b * c +
639  invI.ZZ * c * c,
640  d * (invI.XX * a + invI.XY * b + invI.XZ * c) + e * (invI.XY * a + invI.YY * b + invI.YZ * c) +
641  f * (invI.XZ * a + invI.YZ * b + invI.ZZ * c),
642  g * (invI.XX * a + invI.XY * b + invI.XZ * c) + h * (invI.XY * a + invI.YY * b + invI.YZ * c) +
643  i * (invI.XZ * a + invI.YZ * b + invI.ZZ * c),
644  invI.XX * d * d + 2 * invI.XY * d * e + 2 * invI.XZ * d * f + invI.YY * e * e + 2 * invI.YZ * e * f +
645  invI.ZZ * f * f,
646  g * (invI.XX * d + invI.XY * e + invI.XZ * f) + h * (invI.XY * d + invI.YY * e + invI.YZ * f) +
647  i * (invI.XZ * d + invI.YZ * e + invI.ZZ * f),
648  invI.XX * g * g + 2 * invI.XY * g * h + 2 * invI.XZ * g * i + invI.YY * h * h + 2 * invI.YZ * h * i +
649  invI.ZZ * i * i
650  );
651  return ans;
652 }

References constants::i, q0, q1, q2, q3, MatrixSymmetric3D::XX, MatrixSymmetric3D::XY, MatrixSymmetric3D::XZ, MatrixSymmetric3D::YY, MatrixSymmetric3D::YZ, and MatrixSymmetric3D::ZZ.

Referenced by test1(), and test2().

◆ rotateTensor()

void Quaternion::rotateTensor ( SmallMatrix< 3, 3 >  I) const
655 {
658  I = A * I * A.transpose();
659 }

References A, and getRotationMatrix().

◆ setAngleZ()

void Quaternion::setAngleZ ( Mdouble  psi)

Converts the rotation angle in the XY plane into a quaternion (for Mercury2D). See Wikipedia for details.

493 {
494  //assuming theta=phi=0
495  q0 = std::cos(-0.5 * psi);
496  q1 = 0;
497  q2 = 0;
498  q3 = std::sin(-0.5 * psi);
499 }

References mathsFunc::cos(), q0, q1, q2, q3, and mathsFunc::sin().

Referenced by DPMBase::readNextDataFile().

◆ setComponent()

void Quaternion::setComponent ( int  index,
double  val 
)

Sets the requested component of this Quaternion to the requested value.

Sets the element of the quaternion belonging to the first argument (index) to the value given in the second argument (val).

Parameters
[in]indexindex of element of interest,
[in]valvalue to be set
259 {
260  switch (index)
261  {
262  case 0:
263  q0 = val;
264  break;
265  case 1:
266  q1 = val;
267  break;
268  case 2:
269  q2 = val;
270  break;
271  case 3:
272  q3 = val;
273  break;
274  default:
275  logger(ERROR,
276  "[Quaternion::setComponent] Index = %, which is too high for a 3D quaternion (should be 0-2).",
277  index);
278  }
279 }

References ERROR, logger, q0, q1, q2, and q3.

◆ setEuler()

void Quaternion::setEuler ( const Vec3D e)

Convert Euler angles to a quaternion. See Wikipedia for details.

474 {
475  Mdouble cp = std::cos(0.5 * e.Y);
476  Mdouble sp = std::sin(0.5 * e.Y);
477  Mdouble cr = std::cos(0.5 * e.X);
478  Mdouble sr = std::sin(0.5 * e.X);
479  Mdouble cy = std::cos(0.5 * e.Z);
480  Mdouble sy = std::sin(0.5 * e.Z);
481  q0 = cr * cp * cy + sr * sp * sy;
482  q1 = sr * cp * cy - cr * sp * sy;
483  q2 = cr * sp * cy + sr * cp * sy;
484  q3 = cr * cp * sy - sr * sp * cy;
485 }

References mathsFunc::cos(), q0, q1, q2, q3, mathsFunc::sin(), Vec3D::X, Vec3D::Y, and Vec3D::Z.

Referenced by BaseParticle::oldRead(), DPMBase::readNextDataFile(), and BaseInteractable::setOrientationViaEuler().

◆ setLength()

void Quaternion::setLength ( Mdouble  length)

Make this Quaternion a certain length |q|=length.

Sets the length of the quaternion to a given scalar (while maintaining the direction).

Parameters
[in]lengththe length to be set
177 {
178  *this /= this->getLength() * length;
179 }

References getLength().

◆ setOrientationViaNormal()

void Quaternion::setOrientationViaNormal ( Vec3D  normal)

Used to the the normal of an InfiniteWall that has a normal into the x-direction by default. This can be changed by resetting the wall orientation; thus the normal is the vector (1,0,0) rotated by this quaternion.

Defines one possible orientation that rotates the x-axis into the direction given by normal

Parameters
[in]normalthe vector that the x-axis is rotated into.
537 {
538  //if the normal vector cannot be read properly
539 // if (normal.getLengthSquared() < 1e-20)
540 // {
541 // setUnity();
542 // return;
543 // }
544 
545  normal.normalise();
546 
547  if (normal.X <= -1 + 1e-14)
548  {
549  *this = Quaternion(0, 0, 1, 0);
550  return;
551  }
552 
553  Vec3D half = Vec3D(1, 0, 0) + normal;
554  q0 = half.X;
555  q1 = 0;
556  q2 = -half.Z;
557  q3 = half.Y;
558  normalise();
559  //note, it can technically happen that normalising a normalised vector slightly changes the result.
560 }

References normalise(), Vec3D::normalise(), q0, q1, q2, q3, Quaternion(), Vec3D::X, Vec3D::Y, and Vec3D::Z.

Referenced by Quaternion(), and BaseInteractable::setOrientationViaNormal().

◆ setUnity()

void Quaternion::setUnity ( )

Sets quaternion value to (1,0,0,0)

Sets q0 to 1, and all other elements to zero.

54 {
55  q0 = 1.0;
56  q1 = 0.0;
57  q2 = 0.0;
58  q3 = 0.0;
59 }

References q0, q1, q2, and q3.

Referenced by BaseInteractable::BaseInteractable(), and Quaternion().

◆ updateAngularDisplacement()

void Quaternion::updateAngularDisplacement ( Vec3D  angularVelocityDt)
432 {
433  *this += angularDisplacementTimeDerivative(angularVelocityDt);
434  //const Quaternion q = *this;
435  normalise();
436  //logger(INFO,"%|%",q,*this);
437 }

References angularDisplacementTimeDerivative(), and normalise().

Referenced by BaseInteractable::rotate().

Friends And Related Function Documentation

◆ operator*

Quaternion operator* ( Mdouble  a,
const Quaternion b 
)
friend

Multiplies all elements by a scalar.

Multiplies each element of a given quaternion (b) by a given scalar (a). NB: this is a global function and a friend of the Quaternion class. Gets called when a scalar multiplication of the form (Mdouble) * (Quaternion) is performed.

Parameters
[in]athe scalar
[in]bthe quaternion
Returns
the resulting quaternion
406 {
407  return Quaternion(b.q0 * a, b.q1 * a, b.q2 * a, b.q3 * a);
408 }

◆ operator+

Quaternion operator+ ( Mdouble  a,
const Quaternion b 
)
friend

Adds a scalar to a quaternion.

Adds a scalar to the elements of given quaternion NB this is a global function and a friend of the Quaternion class. Gets called when addition operation of the form (Mdouble) + (Quaternion) is performed.

Parameters
[in]athe scalar to be added
[in]bthe quaternion the scalar gets added to.
Returns
the resulting quaternion.
368 {
369  return Quaternion(b.q0 + a, b.q1 + a, b.q2 + a, b.q3 + a);
370 }

◆ operator- [1/2]

Quaternion operator- ( const Quaternion a)
friend

Subtracts a quaternion.

Returns the negative of a given quaternion. NB: this is a global function and a friend of the Quaternion class. Gets called when a negation operation of the form - (Quaternion) is performed.

Parameters
[in]athe quaternion to be negated
Returns
the negated quaternion
393 {
394  return Quaternion(-a.q0, -a.q1, -a.q2, -a.q3);
395 }

◆ operator- [2/2]

Quaternion operator- ( Mdouble  a,
const Quaternion b 
)
friend

Subtracts the elements of a quaternion from a scalar.

Subtracts each element of a given quaternion from a scalar NB this is a global function and a friend of the Quaternion class. Gets called when subtraction operation of the form (Mdouble) - (Quaternion) is performed.

Parameters
[in]athe scalar
[in]bthe quaternion to be subtracted the scalar gets subtracted from.
Returns
the resulting quaternion.
381 {
382  return Quaternion(a - b.q0, a - b.q1, a - b.q2, a - b.q3);
383 }

◆ operator<<

std::ostream& operator<< ( std::ostream &  os,
const Quaternion a 
)
friend

Adds elements to an output stream.

Adds all elements of the quaternion to an output stream. NB: this is a global function and a friend of the Quaternion class!

Parameters
[in]osthe output stream,
[in]aThe quaternion of interest
Returns
the output stream with quaternion elements added
341 {
342  os << a.q0 << ' ' << a.q1 << ' ' << a.q2 << ' ' << a.q3;
343  return os;
344 }

◆ operator>>

std::istream& operator>> ( std::istream &  is,
Quaternion a 
)
friend

Adds elements to an input stream.

Reads all elements of a given quaternion from an input stream. NB: this is a global function and a friend of the Quaternion class!

Parameters
[in,out]isthe input stream
[in,out]athe quaternion to be read in
Returns
the input stream from which the quaternion elements were read
354 {
355  is >> a.q0 >> a.q1 >> a.q2 >> a.q3;
356  return is;
357 }

Member Data Documentation

◆ q0

◆ q1

◆ q2

◆ q3


The documentation for this class was generated from the following files:
Quaternion::angularDisplacementTimeDerivative
Quaternion angularDisplacementTimeDerivative(Vec3D v) const
Converts an angular momentum v=omega into a quaternion rate of change, q(t+dt)-q(t)/dt.
Definition: Quaternion.cc:422
Vec3D::normalise
void normalise()
Makes this Vec3D unit length.
Definition: Vector.cc:123
constants::pi
const Mdouble pi
Definition: ExtendedMath.h:45
logger
Logger< MERCURY_LOGLEVEL > logger("MercuryKernel")
Definition of different loggers with certain modules. A user can define its own custom logger here.
Quaternion::q1
Mdouble q1
the first component of the quaternion q = (q0,q1,q2,q3)
Definition: Quaternion.h:73
Vec3D::X
Mdouble X
the vector components
Definition: Vector.h:65
Quaternion::q0
Mdouble q0
the zeroth component of the quaternion q = (q0,q1,q2,q3)
Definition: Quaternion.h:69
Quaternion::setUnity
void setUnity()
Sets quaternion value to (1,0,0,0)
Definition: Quaternion.cc:53
Vec3D
Definition: Vector.h:50
A
@ A
Definition: StatisticsVector.h:42
Mdouble
double Mdouble
Definition: GeneralDefine.h:34
Matrix3D
Implementation of a 3D matrix.
Definition: Matrix.h:38
SmallMatrix
Data type for small dense matrix.
Definition: SmallMatrix.h:68
Quaternion::getLengthSquared
Mdouble getLengthSquared() const
Calculates the squared length of this Quaternion: .
Definition: Quaternion.cc:222
ERROR
LL< Log::ERROR > ERROR
Error log level.
Definition: Logger.cc:53
mathsFunc::sin
Mdouble sin(Mdouble x)
Definition: ExtendedMath.cc:44
Quaternion::Quaternion
Quaternion()
Constructor; sets quaternion value to (1,0,0,0)
Definition: Quaternion.cc:30
MatrixSymmetric3D::XZ
Mdouble XZ
Definition: MatrixSymmetric.h:42
Quaternion::q2
Mdouble q2
the second component of the quaternion q = (q0,q1,q2,q3)
Definition: Quaternion.h:77
MatrixSymmetric3D::ZZ
Mdouble ZZ
Definition: MatrixSymmetric.h:42
MatrixSymmetric3D::XY
Mdouble XY
Definition: MatrixSymmetric.h:42
Quaternion::normalise
void normalise()
Makes this Quaternion unit length |q|=1.
Definition: Quaternion.cc:161
Vec3D::Y
Mdouble Y
Definition: Vector.h:65
constants::i
const std::complex< Mdouble > i
Definition: ExtendedMath.h:51
MatrixSymmetric3D::XX
Mdouble XX
The six distinctive matrix elements.
Definition: MatrixSymmetric.h:42
Quaternion::getRotationMatrix
void getRotationMatrix(SmallMatrix< 3, 3 > &A) const
Definition: Quaternion.cc:508
Quaternion::getDistanceSquared
static Mdouble getDistanceSquared(const Quaternion &a, const Quaternion &b)
Calculates the squared distance between two Quaternion: .
Definition: Quaternion.cc:201
Quaternion::q3
Mdouble q3
the third component of the quaternion q = (q0,q1,q2,q3)
Definition: Quaternion.h:81
Quaternion::getLength
Mdouble getLength() const
Calculates the length of this Quaternion: .
Definition: Quaternion.cc:299
MatrixSymmetric3D::YZ
Mdouble YZ
Definition: MatrixSymmetric.h:42
Quaternion::getDistance
static Mdouble getDistance(const Quaternion &a, const Quaternion &b)
Calculates the distance between two Quaternion: .
Definition: Quaternion.cc:188
MatrixSymmetric3D
Implementation of a 3D symmetric matrix.
Definition: MatrixSymmetric.h:37
Vec3D::Z
Mdouble Z
Definition: Vector.h:65
Quaternion::getLengthSquared
static Mdouble getLengthSquared(const Quaternion &a)
Calculates the squared length of a Quaternion: .
Definition: Quaternion.cc:213
Quaternion::setOrientationViaNormal
void setOrientationViaNormal(Vec3D normal)
Definition: Quaternion.cc:536
Quaternion::getLength
static Mdouble getLength(const Quaternion &a)
Calculates the length of a Quaternion: .
Definition: Quaternion.cc:310
MatrixSymmetric3D::YY
Mdouble YY
Definition: MatrixSymmetric.h:42
mathsFunc::cos
Mdouble cos(Mdouble x)
Definition: ExtendedMath.cc:64