Emrys::UnitQuaternion Struct Reference

An attitude: a unit quaternion of four coordinates whose differences are three-coordinate rotation vectors in the body frame. More...

#include <EmrysFilter/Spaces/UnitQuaternion.h>

Public Member Functions
Linear< 3 >	difference () const
template<typename Derived>
void	normalize (Eigen::MatrixBase< Derived > const &block) const
	Scales each column of block, a value (x, y, z, w) per column, to unit norm with \( w \ge 0 \), writing through the const reference as writable() does.
template<typename X, typename D, typename Out>
void	plus (Eigen::MatrixBase< X > const &x, Eigen::MatrixBase< D > const &d, Eigen::MatrixBase< Out > const &out) const
	Writes \( x \boxplus d = x \otimes \mathrm{Exp}(d) \) through out, column by column, normalized.
template<typename A, typename B, typename Out>
void	minus (Eigen::MatrixBase< A > const &a, Eigen::MatrixBase< B > const &b, Eigen::MatrixBase< Out > const &out) const
	Writes \( a \boxminus b = \mathrm{Log}(b^{-1} \otimes a) \) through out, column by column.
template<typename X, typename D, typename Out>
void	resetJacobian (Eigen::MatrixBase< X > const &, Eigen::MatrixBase< D > const &d, Eigen::MatrixBase< Out > const &out) const
	Writes the reset Jacobian at the step d through out: rightJacobian() of d, whatever the value.

Static Public Member Functions
static constexpr Eigen::Index	valueDimension ()
template<typename Derived>
static Eigen::Quaternion< typename Derived::Scalar >	exponential (Eigen::MatrixBase< Derived > const &d)
template<typename Derived>
static Eigen::Matrix< typename Derived::Scalar, 3, 1 >	logarithm (Eigen::QuaternionBase< Derived > const &q)
template<typename Derived>
static Eigen::Matrix< typename Derived::Scalar, 3, 3 >	rightJacobian (Eigen::MatrixBase< Derived > const &d)
template<typename Scalar = double>
static Eigen::Matrix< Scalar, 4, 1 >	identity ()
template<typename Derived>
static Eigen::Matrix< typename Derived::Scalar, 4, 1 >	coefficientsOf (Eigen::QuaternionBase< Derived > const &q)
template<typename Block>
static auto	map (Block &&block)

Static Public Attributes
static constexpr int	FixedValueDimension = 4
	four coordinates, (x, y, z, w)
static constexpr int	ValueDimensionStep = 0
	not resizable
static constexpr int	MaxValueDimension = 4
	the value dimension, as for any fixed space

Friends
bool	operator== (UnitQuaternion const &, UnitQuaternion const &)=default
	Spaces compare equal: a UnitQuaternion has no parameters.

Detailed Description

An attitude: a unit quaternion of four coordinates whose differences are three-coordinate rotation vectors in the body frame.

Values are stored as (x, y, z, w), the order of Eigen::Quaternion::coeffs(), so a state's attitude block is exactly what an Eigen::Quaternion stores and map() views it as one; the product is Eigen's, Hamilton's. normalize() scales a value to unit norm with \( w \ge 0 \), choosing one of the two quaternions of each rotation. Differences are rotation vectors in Linear<3>, applied on the right, in the body frame:

\[ q \boxplus \delta = q \otimes \mathrm{Exp}(\delta), \qquad q \boxminus p = \mathrm{Log}(p^{-1} \otimes q), \]

the right \( \oplus \) and \( \ominus \) of Solà, Deray, and Atchuthan (2018) on SO(3), the group's \( \boxplus \) and \( \boxminus \) in the sense of Hertzberg, Wagner, Frese, and Schröder (2013). The logarithm takes the short way round, so a difference has norm at most \( \pi \). The reset Jacobian is the right Jacobian of SO(3) in closed form (rightJacobian()), so a covariance is carried to a moved mean without automatic differentiation (decisions.md [covariance-reset]).

Name the block with a tag, struct Attitude : UnitQuaternion {};, and view it in model code with UnitQuaternion::map(block<Attitude>(space, x)). Use Repeated for several.

Member Function Documentation

coefficientsOf()

template<typename Derived>

Eigen::Matrix< typename Derived::Scalar, 4, 1 > Emrys::UnitQuaternion::coefficientsOf ( Eigen::QuaternionBase< Derived > const & q )

inlinestaticnodiscard

Returns

the coordinates of q in this space's order, (x, y, z, w): its coeffs(), for writing an Eigen::Quaternion into a mean without counting where w goes.

difference()

Linear< 3 > Emrys::UnitQuaternion::difference ( ) const

inlinenodiscard

Returns

the difference space: rotation vectors, three plain coordinates

exponential()

template<typename Derived>

Eigen::Quaternion< typename Derived::Scalar > Emrys::UnitQuaternion::exponential ( Eigen::MatrixBase< Derived > const & d )

inlinestaticnodiscard

Returns

the unit quaternion of the rotation vector d, the exponential map of SO(3): \( \mathrm{Exp}(\delta) = (\hat\delta \sin\tfrac\theta2, \cos\tfrac\theta2) \) with \( \theta = |\delta| \), and its series below a small angle, where it stays differentiable. A process model that integrates a body rate \( \omega \) over \( \Delta t \) writes auto q = map(block<Attitude>(out, y)); q = q * exponential(omega * dt);.

identity()

template<typename Scalar = double>

Eigen::Matrix< Scalar, 4, 1 > Emrys::UnitQuaternion::identity ( )

inlinestaticnodiscard

Returns

the coordinates of the identity rotation, (0, 0, 0, 1) in this space's (x, y, z, w) order, where mean << 1, 0, 0, 0 would be a half turn about x.

logarithm()

template<typename Derived>

Eigen::Matrix< typename Derived::Scalar, 3, 1 > Emrys::UnitQuaternion::logarithm ( Eigen::QuaternionBase< Derived > const & q )

inlinestaticnodiscard

Returns

the rotation vector of the unit quaternion q, the logarithm map of SO(3), the short way round: q and \( -q \) give the same vector, of norm at most \( \pi \).

map()

template<typename Block>

auto Emrys::UnitQuaternion::map ( Block && block )

inlinestaticnodiscard

Returns

block, four coordinates (x, y, z, w) in one column, as an Eigen::Map of an Eigen::Quaternion over the same memory: writable where block is, otherwise a map of a const quaternion. Nothing is copied, so the map must not outlive the storage, and a non-unit quaternion written through it is canonicalized where the library takes values from outside, by normalizeValues(). Copy it with Eigen::Quaterniond q = map(block);. The attitude block of a whole state is UnitQuaternion::map(block<Attitude>(space, x)), and that of vehicle k in a Repeated block UnitQuaternion::map(block<Fleet>(space, x, k)) (TagPath.h).

block must have direct access with unit inner stride, such as a column, a segment, or a whole vector; an unevaluated expression does not compile, and is to be evaluated first. A plain matrix passed as a temporary does not compile either, since the map would dangle; a temporary Block, Map, or Ref views storage that outlives it and is accepted.

resetJacobian()

template<typename X, typename D, typename Out>

void Emrys::UnitQuaternion::resetJacobian ( Eigen::MatrixBase< X > const & , Eigen::MatrixBase< D > const & d, Eigen::MatrixBase< Out > const & out ) const

inline

Writes the reset Jacobian at the step d through out: rightJacobian() of d, whatever the value.

See resetJacobian(space, x, d) for what it is and its sources.

rightJacobian()

template<typename Derived>

Eigen::Matrix< typename Derived::Scalar, 3, 3 > Emrys::UnitQuaternion::rightJacobian ( Eigen::MatrixBase< Derived > const & d )

inlinestaticnodiscard

Returns

the right Jacobian of SO(3) at the rotation vector d,

\[ J_r(\delta) = I - \frac{1 - \cos\theta}{\theta^2} [\delta]_\times + \frac{\theta - \sin\theta}{\theta^3} [\delta]_\times^2, \qquad \theta = |\delta|, \]

from Solà, Deray, and Atchuthan (2018), eq. (143), with its series \( I - \tfrac12 [\delta]_\times + \tfrac16 [\delta]_\times^2 \) below a small angle. It takes a change of the step to the change of \( q \boxplus \delta \) seen from there, so it is both this space's reset Jacobian and the Jacobian of plus() in its step.

valueDimension()

constexpr Eigen::Index Emrys::UnitQuaternion::valueDimension ( )

inlinestaticnodiscardconstexpr

Returns

4, the number of coordinates of a value

---

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

• EmrysFilter/Spaces/UnitQuaternion.h