Regina 7.4 Calculation Engine
regina::Rotation3D< Real > Class Template Reference

Represents a rotation about the origin in real three-dimensional space. More...

#include <maths/3d.h>

Public Member Functions

 Rotation3D ()=default
 Creates the identity rotation.
 
constexpr Rotation3D (const Rotation3D &)=default
 Creates a new copy of the given rotation.
 
constexpr Rotation3D (Real a, Real b, Real c, Real d)
 Creates a new rotation from the given quaternion coordinates.
 
Rotation3Doperator= (const Rotation3D &)=default
 Sets this to be a copy of the given rotation.
 
constexpr Real operator[] (int index) const
 Returns the given quaternion coordinate for this rotation.
 
constexpr bool operator== (const Rotation3D &other) const
 Determines if this and the given rotation have the same quaternion coordinates.
 
void normalise ()
 Rescales all four quaternion coordinates by the same positive constant so that the quaternion coordinates become normalised.
 
constexpr Rotation3D operator* (const Rotation3D &rhs) const
 Returns the composition of this and the given rotation.
 
Rotation3Doperator*= (const Rotation3D &rhs)
 Composes this with the given rotation, which is to be applied first.
 
constexpr Vector3D< Real > operator* (const Vector3D< Real > &vector) const
 Returns the image of the given vector under this rotation.
 
constexpr Rotation3D inverse () const
 Returns the inverse to this rotation.
 
constexpr Matrix3D< Real > matrix () const
 Returns the 3-dimensional transformation matrix for this rotation.
 

Detailed Description

template<typename Real = double>
class regina::Rotation3D< Real >

Represents a rotation about the origin in real three-dimensional space.

Regina stores a rotation using a quaternion, which consists of four real numbers. We refer to these four numbers as the quaternion coordinates.

Specifically, suppose we rotate by an angle of θ around the axis pointing from the origin to the unit vector (x,y,z), and this rotation follows a right-hand rule (the thumb of the right hand points from the origin out towards (x,y,z), and the fingers follow the direction of the rotation). Then the four real numbers that make up the quaternion are (cos θ/2, x sin θ/2, y sin θ/2, z sin θ/2).

Some notes about the uniqueness of quaternions:

  • A non-zero rotation can be described in two ways (by simultaneously negating both the axis vector and the angle of rotation). Both descriptions yield identical quaternion coordinates.
  • A zero rotation (i.e., the identity operation) can be described using any axis of rotation. Again, regardless of the choice of axis, we obtain identical quaternion coordinates (specifically, (1,0,0,0)).

Regarding normalisation:

  • In theory, a quaternion that describes a rotation must be normalised; that is, its four real quaternion coordinates must form a unit vector in 4-D. This follows immediately from the discussion above, using the fact that the axis vector (x,y,z) is a unit vector in 3-D.
  • In this class, however, we do not require the quaternion coordinates to be normalised, since this may allow quaternions to be constructed more easily. Instead we allow the quaternion coordinates (λa, λb, λc, λd) to represent the same rotation as (a,b,c,d) for any positive λ (and, if we ignore the direction of rotation and just consider its endpoint, then for any negative λ also).
  • If you wish (though this is not actually necessary), you can normalise the coordinates yourself by calling normalise().

See Regina's notes on 3-D geometry for important information, including the inexact floating-point nature of the Vector3D class, and the right-handedness of Regina's coordinate system.

These objects are small enough to pass by value and swap with std::swap(), with no need for any specialised move operations or swap functions.

Python
The template parameter Real is double.
Template Parameters
Realthe floating-point type to use for all storage and computation.

Constructor & Destructor Documentation

◆ Rotation3D() [1/3]

template<typename Real = double>
regina::Rotation3D< Real >::Rotation3D ( )
default

Creates the identity rotation.

This is the operation that does not rotate at all.

◆ Rotation3D() [2/3]

template<typename Real = double>
regina::Rotation3D< Real >::Rotation3D ( const Rotation3D< Real > & )
constexprdefault

Creates a new copy of the given rotation.

◆ Rotation3D() [3/3]

template<typename Real = double>
regina::Rotation3D< Real >::Rotation3D ( Real a,
Real b,
Real c,
Real d )
inlineconstexpr

Creates a new rotation from the given quaternion coordinates.

As described in the class notes, these coordinates do not need to be normalised.

Precondition
The given coordinates are not all zero.
Parameters
athe first quaternion coordinate; that is, the coordinate corresponding to cos θ/2 from the discussion in the class notes.
bthe second quaternion coordinate; that is, the coordinate corresponding to x sin θ/2 from the discussion in the class notes.
cthe third quaternion coordinate; that is, the coordinate corresponding to y sin θ/2 from the discussion in the class notes.
dthe fourth quaternion coordinate; that is, the coordinate corresponding to z sin θ/2 from the discussion in the class notes.

Member Function Documentation

◆ inverse()

template<typename Real = double>
Rotation3D regina::Rotation3D< Real >::inverse ( ) const
inlineconstexpr

Returns the inverse to this rotation.

This rotates around the same axis by negative the original angle.

This function does not require the quaternion coordinates to be normalised. If this rotation has its coordinates scaled by λ, then the resulting rotation will have its coordinates scaled by λ also.

Returns
the inverse rotation.

◆ matrix()

template<typename Real = double>
Matrix3D< Real > regina::Rotation3D< Real >::matrix ( ) const
inlineconstexpr

Returns the 3-dimensional transformation matrix for this rotation.

The result will be a 3-by-3 matrix M, which can be used to rotate column vectors by matrix multiplication. Specifically, this rotation transforms the column vector v into the vector M * v.

This function does not require the quaternion coordinates to be normalised. The result will be the same as though normalise() had been called beforehand.

Returns
the corresponding 3-dimensional rotation matrix.

◆ normalise()

template<typename Real = double>
void regina::Rotation3D< Real >::normalise ( )
inline

Rescales all four quaternion coordinates by the same positive constant so that the quaternion coordinates become normalised.

Specifically, after this operation:

  • each quaternion coordinate will have the same sign as it did before this operation;
  • the four quaternion coordinates (a,b,c,d) will satisfy a^2 + b^2 + c^2 + d^2 = 1.

◆ operator*() [1/2]

template<typename Real = double>
Rotation3D regina::Rotation3D< Real >::operator* ( const Rotation3D< Real > & rhs) const
inlineconstexpr

Returns the composition of this and the given rotation.

Composition of 3-D rotations is not commutative. Here we follow the same convention as used elsewhere in Regina (e.g., by Regina's permutation classes): the product q * r indicates that we should apply rotation r first, followed by rotation q. This is also consistent with the matrix() function, which produces matrices that act on column vectors (matrix * vector), and which therefore compose using the same convention.

This function does not require the quaternion coordinates of either this or rhs to be normalised. If the two rotations have coordinates scaled by λ and μ respectively, then the resulting composition will have its coordinates scaled by λμ.

Parameters
rhsthe rotation to apply before this.
Returns
the composition of this and the given rotation.

◆ operator*() [2/2]

template<typename Real = double>
Vector3D< Real > regina::Rotation3D< Real >::operator* ( const Vector3D< Real > & vector) const
inlineconstexpr

Returns the image of the given vector under this rotation.

Warning
This operator is only recommended for occasional ad-hoc calculations. If you need to transform a large number of points using the same rotation matrix, it is faster to call matrix() once and then multiply each vector by the resulting matrix in turn. (The implementation of this operator does exactly this, but does not allow for caching the transformation matrix.)
Parameters
vectorthe 3-D vector to rotate.
Returns
the result of applying this rotation to the given vector.

◆ operator*=()

template<typename Real = double>
Rotation3D & regina::Rotation3D< Real >::operator*= ( const Rotation3D< Real > & rhs)
inline

Composes this with the given rotation, which is to be applied first.

This rotation will be changed directly.

Composition of 3-D rotations is not commutative. Here we follow the same convention as used elsewhere in Regina (e.g., by Regina's permutation classes): writing q *= r indicates that we should apply rotation r first, followed by rotation q, and then change q to store the resulting composition. This is also consistent with the matrix() function, which produces matrices that act on column vectors (matrix * vector), and which therefore compose using the same convention.

This function does not require the quaternion coordinates of either this or rhs to be normalised. If the two original rotations have coordinates scaled by λ and μ respectively, then the resulting composition will have its coordinates scaled by λμ.

Parameters
rhsthe rotation to apply before this.
Returns
a reference to this rotation.

◆ operator=()

template<typename Real = double>
Rotation3D & regina::Rotation3D< Real >::operator= ( const Rotation3D< Real > & )
default

Sets this to be a copy of the given rotation.

Returns
a reference to this rotation.

◆ operator==()

template<typename Real = double>
bool regina::Rotation3D< Real >::operator== ( const Rotation3D< Real > & other) const
inlineconstexpr

Determines if this and the given rotation have the same quaternion coordinates.

Warning
Equality and inequailty testing, while supported, is extremely fragile, since it relies on floating-point comparisons.
Parameters
otherthe rotation to compare with this.
Returns
true if and only if the two rotations have the same quaternion coordinates.

◆ operator[]()

template<typename Real = double>
Real regina::Rotation3D< Real >::operator[] ( int index) const
inlineconstexpr

Returns the given quaternion coordinate for this rotation.

Parameters
indexindicates which coordinate to return; this must be between 0 and 3 inclusive.
Returns
the corresponding quaternion coordinate.

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