R3::basic_rotation

namespace nin::R3 {
    template <std::floating_point T>
    class basic_rotation;
}

A 3D rotation stored as an axis-angle pair. Unlike basic_orientation_qty, a rotation can span multiple full turns.

The rotation matrix factors are cached and recomputed lazily when the axis or angle changes.

The invariant requires the axis vector to be non-zero; it is normalised internally before use.

Nested types

Type Definition

value_type

T

orientation

basic_orientation_qty<T>

quaternion

basic_quaternion<T>

Member functions

(Constructor)

constructs a 3D rotation

basic_rotation()

(1)

basic_rotation(basic_rotation<T1> const& other)

(2)

basic_rotation(TM const& matrix, matrix_ordering order, int revs = 0)

(3)

basic_rotation(TA const& axis, units::angle_v<T> angle)

(4)

basic_rotation(orientation const& reference, orientation const& measure, int revolutions = 0)

(5)

  • (1) Default constructor. Identity rotation about X axis.

  • (2) Explicit converting constructor from a different floating-point type.

  • (3) Constructs from a rotation matrix with optional revolution count.

  • (4) Constructs from an axis (3-element container) and an angle. Throws std::domain_error if the axis is zero and the angle is non-zero.

  • (5) Constructs the rotation that maps reference to measure, plus revolutions full turns.

invert

negates the rotation angle in place

void invert()

(1)

axis

rotation axis accessor

nin::vector<T,3> const& axis() const

(1)

Returns the rotation axis. The mutable overload is disabled to protect the non-zero invariant; use set_axis() instead.

set_axis

replaces the rotation axis

void set_axis(TM const& new_axis)

(1)

Sets a new axis while preserving the current angle. Throws std::domain_error if the axis is zero and the angle is non-zero.

angle

rotation angle accessor

units::angle_v<T> const& angle() const

(1)

units::angle_v<T>& angle()

(2)

  • (1) Returns the current angle.

  • (2) Returns a mutable reference. Modifying it invalidates the cache.

operator()

applies the rotation

TM operator()(TM const& vec) const

(1)

orientation operator()(orientation const& orient = {}) const

(2)

basic_position_qty<T> operator()(basic_position_qty<T> const& point) const

(3)

  • (1) Rotates a 3-element container of raw scalars.

  • (2) Rotates an orientation quantity.

  • (3) Rotates a position quantity.

Non-member functions

inv

returns an inverted rotation

basic_rotation<T> inv(basic_rotation<T> R)

(1)

compose

composes two rotations

basic_rotation<T> compose(basic_rotation<T> const& left, basic_rotation<T> const& right, int revolutions = 0)

(1)

The left rotation evaluates after the right rotation. An optional revolutions parameter adds full turns to the result.