Class inertialsim::geometry::RotationBase

template <typename Derived>

ClassList > inertialsim > geometry > RotationBase

CRTP base 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 Matrix of algebra elements (rows = axes, cols = samples).
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 Composition operator on the matrix group. Supports broadcasting: if either lhs or rhs has size 1, it will be broadcast against all elements of the other operand. Derived classes may implement more efficient methods.
Derived	operator[] (int index) const Get a single element by index.
const std::optional< Timestamps > &	time () const Time array (or nullopt if not set).
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
Vector3D	ApplyImpl (const Vector3D & vectors) const Apply rotation to vectors.
AlgebraArray	AsAlgebraImpl () const Return algebra representation.
GroupArray	AsGroupImpl () const Return as group elements (for CRTP interface).
Derived	InverseImpl () const Return the inverse rotation.
	RotationBase () Default constructor.
	RotationBase (const RotationMatrixArray & matrices, const std::optional< Timestamps > & time=std::nullopt) Construct from rotation matrices.
int	num_elements_impl () const Number of rotations stored.

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.
Derived	CubicHermiteInterpolate (const Timestamps & time) const Cubic Hermite spline interpolation.
Derived	LinearInterpolate (const Timestamps & time) const Linear interpolation implementation.
	MatrixLieGroup (const std::optional< Timestamps > & time=std::nullopt) Constructor.
Derived &	derived () CRTP helper to access derived class.
const Derived &	derived () const
int	num_times () const

Protected Static Functions

Type	Name
GroupElement	ExpImpl (const AlgebraElement & rotation_vector) Exponential map: rotation vector to rotation matrix.
Derived	FromAlgebraImpl (const AlgebraArray & rotation_vectors, const std::optional< Timestamps > & time=std::nullopt) Construct from algebra elements (for CRTP interface).
Derived	FromGroupImpl (const GroupArray & elements, const std::optional< Timestamps > & time) Construct from group elements (for CRTP interface).
Derived	FromIdentityImpl (int num_elements) Construct identity rotations.
Derived	FromRandomImpl (int num_rotations, std::optional< uint64_t > seed=std::nullopt) Construct uniformly distributed random rotations.
JacobianMatrixArray	JacobianImpl (const AlgebraArray & rotation_vectors, const std::string & side, bool inverse) Jacobian of SO(3) exponential map.
AlgebraElement	LogImpl (const GroupElement & matrix) Logarithm map: rotation matrix to rotation vector.

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 given algebra elements.
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:

Tuple of axes (3xN) and angles (N).

---

function AsEuler

Return the Euler angle representation.

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

** **

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.

** **

sequence = sequence.lower()
scipy.spatial.transform.Rotation.as_euler(sequence)

Parameters:

• sequence Euler angle rotation sequence. 3 letters representing the axes of rotation "X", "Y", and "Z".

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.

** **

scipy.spatial.transform.Rotation.as_matrix()

Returns:

Vector of 3x3 rotation matrices.

---

function AsQuaternion

Return the quaternion representation.

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

See FromQuaternion() for documentation regarding quaternion conventions.

** **

quaternion = scipy.spatial.transform.Rotation.as_quat()
quaternion = quaternion[:,[3,0,1,2]]  // Convert to scalar first

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.

** **

scipy.spatial.transform.Rotation.as_rotvec()

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:

Vector of 3x3 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.

** **

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.

** **

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.

** **

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.

** **

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]

** **

sequence = sequence.lower()
scipy.spatial.transform.Rotation.from_euler(sequence, euler)

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.

** **

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}]

** **

scipy.spatial.transform.Rotation.from_matrix(matrix)

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.

** **

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.

** **

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.

** **

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

** **

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

** **

quaternion = quaternion[:,[1,2,3,0]]
scipy.spatial.transform.Rotation.from_quat(quaternion)

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.

** **

To avoid modulo \(2\pi\) ambiguities, the magnitude of the rotation vectors will be adjusted such that: \(0 < \|rotation\_vector\| \leq 2\pi\)

** **

scipy.spatial.transform.Rotation.from_rotvec(rv).as_rotvec()

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:

Vector of 3x3 integral factor matrices.

---

Protected Functions Documentation

function ApplyImpl

Apply rotation to vectors.

inline Vector3D inertialsim::geometry::RotationBase::ApplyImpl (
    const Vector3D & vectors
) const

Parameters:

• vectors Vectors to rotate (3xN matrix).

Returns:

Rotated vectors.

---

function AsAlgebraImpl

Return algebra representation.

inline AlgebraArray inertialsim::geometry::RotationBase::AsAlgebraImpl () const

Returns:

Rotation vectors (3xN matrix).

---

function AsGroupImpl

Return as group elements (for CRTP interface).

inline GroupArray inertialsim::geometry::RotationBase::AsGroupImpl () const

Returns:

Vector of group elements.

---

function InverseImpl

Return the inverse rotation.

inline Derived inertialsim::geometry::RotationBase::InverseImpl () const

Returns:

Derived with transposed matrices.

---

function RotationBase [½]

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.

---

function num_elements_impl

Number of rotations stored.

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

---

Protected Static Functions Documentation

function ExpImpl

Exponential map: rotation vector to rotation matrix.

static inline GroupElement inertialsim::geometry::RotationBase::ExpImpl (
    const AlgebraElement & rotation_vector
) 

Uses the from_rotation_vector conversion.

Parameters:

• vector Rotation vector (algebra element).

Returns:

Rotation matrix (group element).

---

function FromAlgebraImpl

Construct from algebra elements (for CRTP interface).

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

Parameters:

• rotation_vectors Rotation vectors (3xN matrix).
• time Optional time array.

Returns:

Derived instance.

---

function FromGroupImpl

Construct from group elements (for CRTP interface).

static inline Derived inertialsim::geometry::RotationBase::FromGroupImpl (
    const GroupArray & elements,
    const std::optional< Timestamps > & time
) 

Parameters:

• elements Array of group elements.
• time Optional time array.

Returns:

Derived instance.

---

function FromIdentityImpl

Construct identity rotations.

static inline Derived inertialsim::geometry::RotationBase::FromIdentityImpl (
    int num_elements
) 

Parameters:

• num_elements Number of identity rotations.

Returns:

Derived instance with identity matrices.

---

function FromRandomImpl

Construct uniformly distributed random rotations.

static inline Derived inertialsim::geometry::RotationBase::FromRandomImpl (
    int num_rotations,
    std::optional< uint64_t > seed=std::nullopt
) 

Rotations are uniformly distributed on the unit sphere (SO(3)).

Parameters:

• num_rotations Number of random rotations to create.
• seed Optional random seed for reproducibility.

Returns:

Derived instance with random rotation matrices.

---

function JacobianImpl

Jacobian of SO(3) exponential map.

static inline JacobianMatrixArray inertialsim::geometry::RotationBase::JacobianImpl (
    const AlgebraArray & rotation_vectors,
    const std::string & side,
    bool inverse
) 

Returns the first derivative of the exponential map with respect to the elements of the Lie algebra when composed on the side specified.

Parameters:

• rotation_vectors Rotation vectors (3xN).
• side "left" or "right" to specify which Jacobian.
• inverse If true, return inverse Jacobian.

Returns:

Vector of 3x3 Jacobian matrices.

---

function LogImpl

Logarithm map: rotation matrix to rotation vector.

static inline AlgebraElement inertialsim::geometry::RotationBase::LogImpl (
    const GroupElement & matrix
) 

Uses the as_rotation_vector conversion.

Parameters:

• element Rotation matrix (group element).

Returns:

Rotation vector (algebra element).

---

---

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