Class inertialsim::geometry::RotationBase

template <typename Derived>

ClassList > inertialsim > geometry > RotationBase

Base class for 3-dimensional rotation types. More...

• #include <rotation_base.h>

Inherits the following classes: inertialsim::geometry::MatrixLieGroup

Public Types

Type	Name
typedef MatrixLieGroup< Derived, 3, 3 >	Base

Public Types inherited from inertialsim::geometry::MatrixLieGroup

See inertialsim::geometry::MatrixLieGroup

Type	Name
typedef Eigen::Matrix< Scalar, AlgebraDimension, Eigen::Dynamic >	AlgebraArray Array of algebra elements.
typedef Eigen::Matrix< Scalar, AlgebraDimension, 1 >	AlgebraElement Algebra element type (vector).
typedef std::vector< GroupElement >	GroupArray Array of group elements.
typedef Eigen::Matrix< Scalar, GroupDimension, GroupDimension >	GroupElement Group element type (square matrix).
typedef Eigen::Matrix< Scalar, AlgebraDimension, AlgebraDimension >	JacobianMatrix Jacobian matrix (algebra to algebra).
typedef std::vector< JacobianMatrix >	JacobianMatrixArray Array of Jacobian matrices.

Public Functions

Type	Name
AxisAngle	AsAxisAngle () const Return axis and angle representation.
EulerAngles	AsEuler (const std::string & sequence) const Return the Euler angle representation.
const RotationMatrixArray &	AsMatrix () const Return the rotation matrix representation.
Quaternion	AsQuaternion () const Return the quaternion representation.
RotationVector	AsRotationVector () const Return the rotation vector representation.
RotationVector	Error (const RotationBase< OtherDerived > & reference) const Calculate error compared to a reference rotation.
int	num_rotations () const Number of rotations stored.

Public Functions inherited from inertialsim::geometry::MatrixLieGroup

See inertialsim::geometry::MatrixLieGroup

Type	Name
Vector3D	Apply (const Vector3D & vectors) const Apply the group action to an array of vectors.
Derived	Interpolate (const Timestamps & interp_time, Interpolator method=Interpolator::LINEAR) const Interpolate at given times.
Derived	Inverse () const Invert an instance.
Derived	Slice (int start, int end) const Get a slice of elements.
AlgebraArray	TimeDerivative (int order=1, int accuracy=4, const std::string & side="right") const Compute time derivative using finite differences.
int	num_elements () const Number of elements stored in the instance.
Derived	operator* (const Derived & rhs) const Compose elements of the group.
Derived	operator[] (int index) const Get a single element by index.
const std::optional< Timestamps > &	time () const Time array corresponding to each element.
virtual	~MatrixLieGroup () = default

Public Static Functions

Type	Name
RotationMatrixArray	DoubleIntegralFactor (const RotationVector & rotation_vectors) Double integral factor.
Derived	FromAxisAngle (const Vector3D & axis, const Scalar1D & angle, const std::optional< Timestamps > & time=std::nullopt) Construct a Rotation from an axis and angle.
Derived	FromEuler (const EulerAngles & euler, const std::string & sequence, const std::optional< Timestamps > & time=std::nullopt) Construct a Rotation from a sequence of Euler angles.
Derived	FromMatrix (const RotationMatrixArray & matrices, const std::optional< Timestamps > & time=std::nullopt, bool orthonormalize=false) Construct a Rotation from rotation matrices.
Derived	FromQuaternion (const Quaternion & quaternions, const std::optional< Timestamps > & time=std::nullopt, bool scalar_last=false) Construct a Rotation from quaternions.
Derived	FromRotationVector (const RotationVector & rotation_vectors, const std::optional< Timestamps > & time=std::nullopt) Construct a Rotation from rotation vectors.
RotationMatrixArray	IntegralFactor (const RotationVector & rotation_vectors) First integral factor.

Public Static Functions inherited from inertialsim::geometry::MatrixLieGroup

See inertialsim::geometry::MatrixLieGroup

Type	Name
Derived	Compose (const std::vector< Derived > & instances) Compose a sequence of instances (first to last).
Derived	FromIdentity (int num_elements=1) Create identity elements.
Derived	FromRandom (int num_elements=1, std::optional< Eigen::numext::uint64_t > seed=std::nullopt) Create random elements.

Protected Functions

Type	Name
	RotationBase () Default constructor.
	RotationBase (const RotationMatrixArray & matrices, const std::optional< Timestamps > & time=std::nullopt) Construct from rotation matrices.

Protected Functions inherited from inertialsim::geometry::MatrixLieGroup

See inertialsim::geometry::MatrixLieGroup

Type	Name
AlgebraArray	AsAlgebra () const Get the algebra elements.
GroupArray	AsGroup () const Get the group elements.
	MatrixLieGroup (const std::optional< Timestamps > & time=std::nullopt) Constructor.
int	num_times () const

Protected Static Functions inherited from inertialsim::geometry::MatrixLieGroup

See inertialsim::geometry::MatrixLieGroup

Type	Name
GroupElement	Exp (const AlgebraElement & vector) Exponential map from algebra to group.
Derived	FromAlgebra (const AlgebraArray & elements, const std::optional< Timestamps > & time) Create instance from algebra elements.
Derived	FromGroup (const GroupArray & elements, const std::optional< Timestamps > & time) Create instance from group elements.
JacobianMatrixArray	Jacobian (const AlgebraArray & algebra, const std::string & side="left", bool inverse=false) Calculate the Jacobian of the exponential map.
AlgebraElement	Log (const GroupElement & element) Logarithm map from group to algebra.

Detailed Description

Template parameters:

• Derived The derived class (Rotation or CoordinateRotation).

Public Types Documentation

typedef Base

using inertialsim::geometry::RotationBase< Derived >::Base =  MatrixLieGroup<Derived, 3, 3>;

---

Public Functions Documentation

function AsAxisAngle

Return axis and angle representation.

inline AxisAngle inertialsim::geometry::RotationBase::AsAxisAngle () const

Returns:

Pair containing:

• Axes (3xN)
• Angles (N)

---

function AsEuler

Return the Euler angle representation.

inline EulerAngles inertialsim::geometry::RotationBase::AsEuler (
    const std::string & sequence
) const

Singularities

The first and third Euler angles cannot be uniquely determined in the following scenarios:

• For symmetric sequences: euler[1] == 0 or pi
• For asymmetric sequences: euler[1] == -pi/2 or pi/2

This is sometimes referred to as "gimbal lock". The third angle is arbitrarily set to zero in this case, as per the convention in Reference [02] and Reference [04]. Note that the output still represents a correct, valid rotation but independent tracking of the first and third angles is lost.

See FromEuler() for additional documentation regarding Euler angle conventions.

Parameters:

• sequence Euler angle rotation sequence. 3 letters representing the axes of rotation (e.g., "XYZ").

Returns:

Euler angles (3xN matrix). The first element represents the angle around the first axis in the sequence.

---

function AsMatrix

Return the rotation matrix representation.

inline const  RotationMatrixArray & inertialsim::geometry::RotationBase::AsMatrix () const

See FromMatrix() for documentation regarding rotation matrix conventions.

Returns:

Rotation matrices.

---

function AsQuaternion

Return the quaternion representation.

inline Quaternion inertialsim::geometry::RotationBase::AsQuaternion () const

See FromQuaternion() for documentation regarding quaternion conventions.

Returns:

Quaternions (N x 4 matrix), with scalar element first.

---

function AsRotationVector

Return the rotation vector representation.

inline RotationVector inertialsim::geometry::RotationBase::AsRotationVector () const

See FromRotationVector() for documentation regarding rotation vector conventions.

Returns:

Rotation vectors (3xN matrix).

---

function Error

Calculate error compared to a reference rotation.

template<typename  OtherDerived>
inline RotationVector inertialsim::geometry::RotationBase::Error (
    const  RotationBase < OtherDerived > & reference
) const

Parameters:

• reference Reference rotation.

Returns:

Error as a rotation vector from the reference rotation.

---

function num_rotations

Number of rotations stored.

inline int inertialsim::geometry::RotationBase::num_rotations () const

---

Public Static Functions Documentation

function DoubleIntegralFactor

Double integral factor.

static inline RotationMatrixArray inertialsim::geometry::RotationBase::DoubleIntegralFactor (
    const  RotationVector & rotation_vectors
) 

Returns the matrix factor F2 for double integration.

Parameters:

• rotation_vectors Rotation vectors (3xN).

Returns:

Integral factor matrices.

---

function FromAxisAngle

Construct a Rotation from an axis and angle.

static inline Derived inertialsim::geometry::RotationBase::FromAxisAngle (
    const  Vector3D & axis,
    const  Scalar1D & angle,
    const std::optional< Timestamps > & time=std::nullopt
) 

Euler's rotation theorem states that any rotation of a rigid body can be represented by an axis of rotation and an angle of rotation about that axis.

The input axes and angles must be consistent in dimension. The input axes must be unit norm.

Range and sign conventions

A rotation of $ \theta $ degrees around a given axis is equivalent to a rotation of $ 2\pi - \theta $ about the opposite (negative) axis. To standardize, input angles and axes will be adjusted such that: $ 0 \leq angle \leq \pi $

Parameters:

• axis Array of unit axes of rotation (3xN matrix).
• angle Array of angles (N vector). Each angle corresponds to each axis input.
• time Optional time array of unique, strictly increasing times.

Returns:

Derived instance.

---

function FromEuler

Construct a Rotation from a sequence of Euler angles.

static inline Derived inertialsim::geometry::RotationBase::FromEuler (
    const  EulerAngles & euler,
    const std::string & sequence,
    const std::optional< Timestamps > & time=std::nullopt
) 

Euler angles are a sequence of three rotations applied around the axes of a coordinate system.

Sequence conventions

Euler angles act as a sequence of three independent rotations. The order of these rotations matter. Sequences are specified with a string, e.g. "XYZ" or "YZY". The first letter is the first rotation applied (rightmost position in the equivalent matrix multiplication). Two consecutive letters cannot be the same. When the first and third rotations are around the same axis (e.g. "ZYZ") the sequence is referred to as symmetric. When the first and third rotations are around different axes (e.g. "YZX") the sequence is referred to as asymmetric. See Reference [02] for further details.

Rotation axis conventions

Because %Euler angle rotations are applied consecutively, the second and third rotations can be conceived as rotating around the set of original (or fixed) coordinate axes (extrinsic convention); or rotating around a moving set of coordinate axes (intrinsic convention). InertialSim uses the extrinsic convention. See Reference [02] for further details.

Angle range conventions

%Euler angle values are not unique. To standardize, the angles will be adjusted such that:

• $ -\pi < euler[0] \leq \pi $
• $ -\pi < euler[2] \leq \pi $
• For symmetric sequences: $ 0 \leq euler[1] \leq \pi $
• For asymmetric sequences: $ -\pi/2 \leq euler[1] \leq \pi/2 $

Parameters:

• euler Array of Euler angles (3xN matrix). The first element represents the angle around the first axis in the sequence.
• sequence Euler angle rotation sequence. 3 letters representing the axes of rotation "X", "Y", and "Z". The first letter is the first rotation applied.
• time Optional time array of unique, strictly increasing times.

Returns:

Derived instance.

---

function FromMatrix

Construct a Rotation from rotation matrices.

static inline Derived inertialsim::geometry::RotationBase::FromMatrix (
    const  RotationMatrixArray & matrices,
    const std::optional< Timestamps > & time=std::nullopt,
    bool orthonormalize=false
) 

A rotation matrix is an orthonormal 3x3 matrix that represents a rigid body rotation.

Active vs passive rotation matrices

See the class documentation regarding passive and active conventions. Passive rotation matrices are also commonly known as coordinate transform matrices, or direction cosine matrices. An active rotation matrix is the transpose of the equivalent passive coordinate transform matrix: $ R_{i \rightarrow b} = C_{i}^{bT} = C_{b}^{i} $

Parameters:

• matrices Vector of 3x3 rotation matrices.
• time Optional time array of unique, strictly increasing times corresponding to each matrix input.
• orthonormalize If true, enforce orthonormality of the matrix input.

Returns:

Derived instance.

---

function FromQuaternion

Construct a Rotation from quaternions.

static inline Derived inertialsim::geometry::RotationBase::FromQuaternion (
    const  Quaternion & quaternions,
    const std::optional< Timestamps > & time=std::nullopt,
    bool scalar_last=false
) 

Quaternions are 4-parameter arrays, a subset of which can represent rotation. They are the minimum dimension representation that is free from singularities. Quaternions of rotation are also known as Euler-Rodrigues symmetric parameters.

The input quaternions must be normalized.

%Quaternion conventions

There are two conventions for ordering the elements of a quaternion: scalar element first or scalar element last (fourth). InertialSim uses the scalar first convention. The alternative is supported by setting scalar\_last = true.

Sign conventions

The physical rotation represented by a quaternion and its negative are the same: q == -q. To standardize, the input quaternion will be adjusted such that the scalar element is always positive.

Composition conventions

There are multiple conventions for composing quaternions. InertialSim uses the traditional Hamilton convention. See Reference [02] and Reference [05] for further details.

Naming conventions

The four quaternion elements have multiple naming conventions:

• q[0] = a = w (scalar)
• q[1] = b = x
• q[2] = c = y
• q[3] = d = z

Parameters:

• quaternions Array of quaternions (N x 4 matrix).
• time Optional time array of unique, strictly increasing times.
• scalar_last If true, the scalar element is in the last position.

Returns:

Derived instance.

---

function FromRotationVector

Construct a Rotation from rotation vectors.

static inline Derived inertialsim::geometry::RotationBase::FromRotationVector (
    const  RotationVector & rotation_vectors,
    const std::optional< Timestamps > & time=std::nullopt
) 

The rotation vector is a vector whose magnitude is the angle of rotation and whose direction is the axis of rotation (in the right-handed sense). It is closely related to the axis-angle representation.

The input rotation vectors must be non-zero.

Angle range conventions

To avoid modulo $ 2\pi $ ambiguities, the magnitude of the rotation vectors will be adjusted such that: $ 0 < \lVert rotation\_vector \rVert \leq 2\pi $

Parameters:

• rotation_vectors Array of rotation vectors (3xN matrix).
• time Optional time array of unique, strictly increasing times.

Returns:

Derived instance.

---

function IntegralFactor

First integral factor.

static inline RotationMatrixArray inertialsim::geometry::RotationBase::IntegralFactor (
    const  RotationVector & rotation_vectors
) 

Returns the matrix factor F1 that converts the integral of a vector v that is constant in a rotating frame to the integral in a fixed frame.

Parameters:

• rotation_vectors Rotation vectors (3xN).

Returns:

Integral factor matrices.

---

Protected Functions Documentation

function RotationBase [1/2]

Default constructor.

inline inertialsim::geometry::RotationBase::RotationBase () 

---

function RotationBase [2/2]

Construct from rotation matrices.

inline explicit inertialsim::geometry::RotationBase::RotationBase (
    const  RotationMatrixArray & matrices,
    const std::optional< Timestamps > & time=std::nullopt
) 

Parameters:

• matrices Vector of 3x3 rotation matrices.
• time Optional time array.

---

---

The documentation for this class was generated from the following file cpp/include/inertialsim/geometry/rotation_base.h