Core 1.0
Quaternion Class Reference

Quaternions. More...

#include <quaternion.h>

Public Member Functions

 Quaternion () noexcept
 Empty.
 Quaternion (const double &, const double &, const double &, const double &) noexcept
 Create a quaternion.
 Quaternion (const Vector &, const double &)
 Create a quaternion from an axis vector and a rotation angle.
 Quaternion (const Vector &, const Vector &)
 Create a unit quaternion representing the shortest rotation from vector a to vector b.
 Quaternion (const Matrix &)
 Create a quaternion from a rotation matrix.
Matrix RotationMatrix () const
 Transforms a quaternion into a rotation matrix.
void AngleAxis (double &, Vector &) const
 Transform a quaternion into an rotation defined by its axis and the angle of rotation angle.
double & operator[] (int) noexcept
 Overloaded.
constexpr double operator[] (int) const noexcept
 Returns the i-th coefficient of a quaternion.
Quaternion operator+ (const Quaternion &) const noexcept
 Overloaded.
Quaternion operator- (const Quaternion &) const noexcept
 Overloaded.
Quaternion operator* (const Quaternion &) const noexcept
 Multiplication of two quaternion.
Quaternion operator* (const double &) const noexcept
 Multiply a quaternion by a double value.
Quaternion operator- () const noexcept
 Overloaded.
Quaternion Inverse () const noexcept
 Compute the inverse of a quaternion.
Quaternion Conjugate () const noexcept
 Computes the conjugate of a quaternion.
Quaternion Exp () const
 Compute the exponential of a quaternion.
Quaternion Log () const
 Computes the logarithm of a quaternion.
Vector operator* (const Vector &) const noexcept
 Rotate a vector by this unit quaternion using the sandwich formula.

Static Public Member Functions

static Quaternion Slerp (const double &, const Quaternion &, const Quaternion &)
 Perform spherical linear interpolation (slerp) between two unit quaternions.
static Quaternion FromAngles (const double &, const double &, const double &)
 Create a quaternion from Euler rotation angles.

Static Public Attributes

static const Quaternion Null
 Null quaternion.
static const Quaternion Identity
 Identity.

Protected Attributes

double w = 1.0
 Quaternion components.

Static Protected Attributes

static const double Epsilon = 1e-03
 Cutoff value for sine function whenever the angle gets near zero.

Friends

Quaternion operator* (const double &c, const Quaternion &q)
 Left multiply a quaternion by a double value.
double SquaredNorm (const Quaternion &q)
 Squared length of a quaternion.
double Norm (const Quaternion &q)
 Euclidean length of a quaternion.
std::ostream & operator<< (std::ostream &s, const Quaternion &quaternion)
 Overloaded.

Detailed Description

Quaternions.

Constructor & Destructor Documentation

◆ Quaternion() [1/4]

Quaternion::Quaternion ( const double & w,
const double & x,
const double & y,
const double & z )
inlineexplicitnoexcept

Create a quaternion.

Parameters
wAngular parameter.
x,y,zAxis coordinates.

◆ Quaternion() [2/4]

Quaternion::Quaternion ( const Vector & axis,
const double & a )
explicit

Create a quaternion from an axis vector and a rotation angle.

Axis should be unit length.

Parameters
axisNormalized axis.
aAngle.

◆ Quaternion() [3/4]

Quaternion::Quaternion ( const Vector & a,
const Vector & b )
explicit

Create a unit quaternion representing the shortest rotation from vector a to vector b.

Both input vectors must be unit-length. The quaternion satisfies: \( q = \cos(\theta/2) + \sin(\theta/2)\,\hat{n} \) where \( \theta = \arccos(a \cdot b) \) and \( \hat{n} = (a \times b)/\|a \times b\| \).

Special cases:

  • a and b nearly parallel ( \(\theta \approx 0\)): returns the identity quaternion.
  • a and b nearly anti-parallel ( \(\theta \approx \pi\)): returns a 180° rotation around an arbitrary axis perpendicular to a.
Parameters
a,bUnit vectors.

◆ Quaternion() [4/4]

Quaternion::Quaternion ( const Matrix & R)
explicit

Create a quaternion from a rotation matrix.

The algorithm can be found in Ken Shoemake's article in 1987 Siggraph course notes Quaternion Calculus and Fast Animation. Coefficients are accessed with Matrix::operator()(int, int), i.e., R(i, j) is the coefficient at row i and column j, so that the quaternion of Matrix::Rotation(u, a) is the quaternion Quaternion(u, a), up to the sign.

Parameters
RRotation matrix.

Member Function Documentation

◆ AngleAxis()

void Quaternion::AngleAxis ( double & angle,
Vector & axis ) const

Transform a quaternion into an rotation defined by its axis and the angle of rotation angle.

The quaternion representing the rotation is : q=cos(a/2)+sin(a/2)*(x*i+y*j+z*k).

Parameters
angleThe angle.
axisVector axis.

◆ Exp()

Quaternion Quaternion::Exp ( ) const

Compute the exponential of a quaternion.

If q=a*(x,y,z) where (x,y,z) is unit length, then exp(q)=cos(a)+sin(a)*(x,y,z). If sin(a) is near zero, use exp(a)=cos(a)+a*(x,y,z).

◆ FromAngles()

Quaternion Quaternion::FromAngles ( const double & a,
const double & b,
const double & c )
static

Create a quaternion from Euler rotation angles.

Using this function is simpler than calling the constructor from a rotation matrix.

Parameters
a,b,cRotation angles around x, y and z axes (should be in radian).

◆ Inverse()

Quaternion Quaternion::Inverse ( ) const
noexcept

Compute the inverse of a quaternion.

This should be applied to non-zero quaternions only. If quaternion happens to be null, then the function return also null wich is an invalid result that flags the error.

◆ Log()

Quaternion Quaternion::Log ( ) const

Computes the logarithm of a quaternion.

If quaternion is of unit length, then q=cos(a)+sin(a).v, then log(q)=a.v.

◆ operator*() [1/3]

Quaternion Quaternion::operator* ( const double & c) const
inlinenoexcept

Multiply a quaternion by a double value.

Parameters
cReal.

◆ operator*() [2/3]

Quaternion Quaternion::operator* ( const Quaternion & q) const
noexcept

Multiplication of two quaternion.

Note that multiplication is not generally commutative.

◆ operator*() [3/3]

Vector Quaternion::operator* ( const Vector & p) const
noexcept

Rotate a vector by this unit quaternion using the sandwich formula.

Uses the direct formula \( p' = p + 2w\,(q \times p) + 2\,(q \times (q \times p)) \) where \( q = (x,y,z) \) is the vector part and \( w \) is the scalar part. This avoids constructing the full 3×3 rotation matrix (which would cost 9 multiplications and 9 additions via RotationMatrix(), plus a matrix–vector multiply), and instead uses two cross-products and two scalar–vector multiplications — roughly half the floating-point operations.

Parameters
pVector to rotate.
Returns
Rotated vector.

◆ operator[]()

double Quaternion::operator[] ( int i) const
inlineconstexprnoexcept

Returns the i-th coefficient of a quaternion.

Terms are x, y, and z if index is in [0,2], and w otherwise.

◆ RotationMatrix()

Matrix Quaternion::RotationMatrix ( ) const

Transforms a quaternion into a rotation matrix.

Coefficients are given column by column, as expected by the constructor of Matrix, so that the matrix is the same as the one created by Matrix::Rotation(), and that q.RotationMatrix() * p is equal to q * p.

◆ Slerp()

Quaternion Quaternion::Slerp ( const double & t,
const Quaternion & p,
const Quaternion & q )
static

Perform spherical linear interpolation (slerp) between two unit quaternions.

Interpolates along the shortest arc on the unit quaternion sphere. Negates q when the dot product is negative to always take the shorter arc. When the rotations are very close, the normalized linear interpolation is used, which avoids the division by the sine of the angle and differs from the spherical interpolation by a term of the order of the cube of the angle.

Parameters
tInterpolating value in [0,1]: 0 returns p, 1 returns q.
p,qUnit quaternions to interpolate.

◆ Norm

double Norm ( const Quaternion & q)
friend

Euclidean length of a quaternion.

Parameters
qQuaternion.

◆ operator*

Quaternion operator* ( const double & c,
const Quaternion & q )
friend

Left multiply a quaternion by a double value.

Parameters
cReal.
qQuaternion.

◆ operator<<

std::ostream & operator<< ( std::ostream & s,
const Quaternion & quaternion )
friend

Overloaded.

Parameters
sStream.
quaternionThe quaternion.

◆ SquaredNorm

double SquaredNorm ( const Quaternion & q)
friend

Squared length of a quaternion.

Parameters
qQuaternion.