mrpro.data.Rotation

class mrpro.data.Rotation[source]

Bases: Module, Iterable[Rotation]

A container for Rotations.

A pytorch implementation of scipy.spatial.transform.Rotation. For more information see the scipy documentation: https://docs.scipy.org/doc/scipy/reference/generated/scipy.spatial.transform.Rotation.html

Differences compared to scipy.spatial.transform.Rotation:

  • torch.nn.Module based, the quaternions are a Parameter

  • not all features are implemented. Notably, mrp, davenport, and reduce are missing.

  • arbitrary number of batching dimensions

  • support for improper rotations (rotoinversion), i.e., rotations with an coordinate inversion or a reflection about a plane perpendicular to the rotation axis.

__init__(quaternions: Tensor | NestedSequence[float], normalize: bool = True, copy: bool = True, inversion: Tensor | NestedSequence[bool] | bool = False, reflection: Tensor | NestedSequence[bool] | bool = False) → None[source]

Initialize a new Rotation.

Instead of calling this method, also consider the different from_* class methods to construct a Rotation.

Parameters:

  • quaternions (Union[Tensor, NestedSequence[float]]) – Rotatation quaternions. If these requires_grad, the resulting Rotation will require gradients

  • normalize (bool, default: True) – If the quaternions should be normalized. Only disable if you are sure the quaternions are already normalized. Will keep a possible negative w to represent improper rotations.

  • copy (bool, default: True) – Always ensure that a copy of the quaternions is created. If both normalize and copy are False, the quaternions Parameter of this instance will be a view if the quaternions passed in.

  • inversion (Union[Tensor, NestedSequence[bool], bool], default: False) – If the rotation should contain an inversion of the coordinate system, i.e. a reflection of all three axes, resulting in a rotoinversion (improper rotation). If a boolean tensor is given, it should broadcast with the quaternions.

  • reflection (Union[Tensor, NestedSequence[bool], bool], default: False) – If the rotation should contain a reflection about a plane perpendicular to the rotation axis. This will result in a rotoflexion (improper rotation). If a boolean tensor is given, it should broadcast with the quaternions.

classmethod align_vectors(a: Tensor | Sequence[Tensor] | Sequence[float] | Sequence[Sequence[float]], b: Tensor | Sequence[Tensor] | Sequence[float] | Sequence[Sequence[float]], weights: Tensor | Sequence[float] | Sequence[Sequence[float]] | None = None, *, return_sensitivity: Literal[False] = False, allow_improper: bool = Ellipsis) → tuple[Rotation, float][source]
classmethod align_vectors(a: Tensor | Sequence[Tensor] | Sequence[float] | Sequence[Sequence[float]], b: Tensor | Sequence[Tensor] | Sequence[float] | Sequence[Sequence[float]], weights: Tensor | Sequence[float] | Sequence[Sequence[float]] | None = None, *, return_sensitivity: Literal[True], allow_improper: bool = Ellipsis) → tuple[Rotation, float, Tensor]

Estimate a rotation to optimally align two sets of vectors.

Find a rotation between frames A and B which best aligns a set of vectors a and b observed in these frames. The following loss function is minimized to solve for the rotation matrix \(R\):

\[L(R) = \frac{1}{2} \sum_{i = 1}^{n} w_i \| a_i - R b_i \|^2 ,\]

where \(w_i\)’s are the weights corresponding to each vector.

The rotation is estimated with Kabsch algorithm [KAB], and solves what is known as the “pointing problem”, or “Wahba’s problem” [WAH].

There are two special cases. The first is if a single vector is given for a and b, in which the shortest distance rotation that aligns b to a is returned. The second is when one of the weights is infinity. In this case, the shortest distance rotation between the primary infinite weight vectors is calculated as above. Then, the rotation about the aligned primary vectors is calculated such that the secondary vectors are optimally aligned per the above loss function. The result is the composition of these two rotations. The result via this process is the same as the Kabsch algorithm as the corresponding weight approaches infinity in the limit. For a single secondary vector this is known as the “align-constrain” algorithm [MAG2018].

For both special cases (single vectors or an infinite weight), the sensitivity matrix does not have physical meaning and an error will be raised if it is requested. For an infinite weight, the primary vectors act as a constraint with perfect alignment, so their contribution to rssd will be forced to 0 even if they are of different lengths.

Parameters:

  • a (Tensor | Sequence[Tensor] | Sequence[float] | Sequence[Sequence[float]]) – Vector components observed in initial frame A. Each row of a denotes a vector.

  • b (Tensor | Sequence[Tensor] | Sequence[float] | Sequence[Sequence[float]]) – Vector components observed in another frame B. Each row of b denotes a vector.

  • weights (Tensor | Sequence[float] | Sequence[Sequence[float]] | None, default: None) – Weights describing the relative importance of the vector observations. If None, then all values in weights are assumed to be 1. One and only one weight may be infinity, and weights must be positive.

  • return_sensitivity (bool, default: False) – Whether to return the sensitivity matrix.

  • allow_improper (bool, default: False) – If True, allow improper rotations to be returned. If False, then the rotation is restricted to be proper.

Returns:

  • rotation – Best estimate of the rotation that transforms b to a.

  • rssd – Square root of the weighted sum of the squared distances between the given sets of vectors after alignment.

  • sensitivity_matrix – Sensitivity matrix of the estimated rotation estimate as explained in Notes.

References

[MAG2018]

Magner R (2018), Extending target tracking capabilities through trajectory and momentum setpoint optimization. Small Satellite Conference.

classmethod concatenate(rotations: Sequence[Rotation]) → Self[source]

Concatenate a sequence of Rotation objects into a single object.

Parameters:

rotations (Sequence[Rotation]) – The rotations to concatenate.

Returns:

concatenated – The concatenated rotations.

classmethod from_davenport(axes: Tensor, order: str, angles: Tensor, degrees: bool = False)[source]

Not implemented.

classmethod from_directions(*basis: Unpack, allow_improper: bool = True)[source]

Initialize from basis vectors as SpatialDimensions.

Parameters:

  • *basis (Unpack[tuple[SpatialDimension, SpatialDimension, SpatialDimension]]) – 3 Basis vectors of the new coordinate system, i.e. the columns of the rotation matrix

  • allow_improper (bool, default: True) – If true, the rotation is considered as improper if the determinant of the matrix is negative and the sign will be preserved. If false, a ValueError is raised if the determinant is negative.

Returns:

rotation – Object containing the rotations represented by the basis vectors.

classmethod from_euler(seq: str, angles: Tensor | NestedSequence[float] | float, degrees: bool = False, inversion: Tensor | NestedSequence[bool] | bool = False, reflection: Tensor | NestedSequence[bool] | bool = False) → Self[source]

Initialize from Euler angles.

Rotations in 3-D can be represented by a sequence of 3 rotations around a sequence of axes. In theory, any three axes spanning the 3-D Euclidean space are enough. In practice, the axes of rotation are chosen to be the basis vectors.

The three rotations can either be in a global frame of reference (extrinsic) or in a body centered frame of reference (intrinsic), which is attached to, and moves with, the object under rotation [EULa].

Parameters:

  • seq (str) – Specifies sequence of axes for rotations. Up to 3 characters belonging to the set {‘X’, ‘Y’, ‘Z’} for intrinsic rotations, or {‘x’, ‘y’, ‘z’} for extrinsic rotations. Extrinsic and intrinsic rotations cannot be mixed in one function call.

  • angles (Union[Tensor, NestedSequence[float], float]) – (…, [1 or 2 or 3]), matching the number of axes in seq. Euler angles specified in radians (degrees is False) or degrees (degrees is True).

  • degrees (bool, default: False) – If True, then the given angles are assumed to be in degrees. Otherwise they are assumed to be in radians

  • inversion (Union[Tensor, NestedSequence[bool], bool], default: False) – If True, the resulting transformation will contain an inversion of the coordinate system, resulting in a rotoinversion (improper rotation).

  • reflection (Union[Tensor, NestedSequence[bool], bool], default: False) – If True, the resulting transformation will contain a reflection about a plane perpendicular to the rotation axis, resulting in an improper rotation.

Returns:

rotation – Object containing the rotation represented by the sequence of rotations around given axes with given angles.

References

classmethod from_matrix(matrix: Tensor | NestedSequence[float], allow_improper: bool = True) → Self[source]

Initialize from rotation matrix.

Rotations in 3 dimensions can be represented with 3 x 3 proper orthogonal matrices [ROTa]. If the input is not proper orthogonal, an approximation is created using the method described in [MAR2008]. If the input matrix has a negative determinant, the rotation is considered as improper, i.e. containing a reflection. The resulting rotation will include this reflection [ROTb].

Parameters:

  • matrix (Union[Tensor, NestedSequence[float]]) – A single matrix or a stack of matrices, shape (..., 3, 3)

  • allow_improper (bool, default: True) – If true, the rotation is considered as improper if the determinant of the matrix is negative. If false, an ValueError is raised if the determinant is negative.

Returns:

rotation – Object containing the rotations represented by the rotation matrices.

References

[MAR2008]

Landis Markley F (2008) Unit Quaternion from Rotation Matrix, Journal of guidance, control, and dynamics 31(2),440-442.

classmethod from_mrp(mrp: Tensor) → Self[source]

Not implemented.

classmethod from_quat(quaternions: Tensor | NestedSequence[float], inversion: Tensor | NestedSequence[bool] | bool = False, reflection: Tensor | NestedSequence[bool] | bool = False) → Self[source]

Initialize from quaternions.

3D rotations can be represented using unit-norm quaternions [QUAa]. As an extension to the standard, this class also supports improper rotations, i.e. rotations with reflection with respect to the plane perpendicular to the rotation axis or inversion of the coordinate system.

Note

If inversion != reflection, the rotation will be improper and saved as a rotation followed by an inversion inversion of the coordinate system.

Parameters:

  • quaternions (Union[Tensor, NestedSequence[float]]) – shape (..., 4) Each row is a (possibly non-unit norm) quaternion representing an active rotation, in scalar-last (x, y, z, w) format. Each quaternion will be normalized to unit norm.

  • inversion (Union[Tensor, NestedSequence[bool], bool], default: False) – if the rotation should contain an inversion of the coordinate system, i.e. a reflection of all three axes. If a boolean tensor is given, it should broadcast with the quaternions.

  • reflection (Union[Tensor, NestedSequence[bool], bool], default: False) – if the rotation should contain a reflection about a plane perpendicular to the rotation axis.

Returns:

rotation – Object containing the rotations represented by input quaternions.

References

classmethod from_rotvec(rotvec: Tensor | NestedSequence[float], degrees: bool = False, reflection: Tensor | NestedSequence[bool] | bool = False, inversion: Tensor | NestedSequence[bool] | bool = False) → Self[source]

Initialize from rotation vector.

A rotation vector is a 3 dimensional vector which is co-directional to the axis of rotation and whose norm gives the angle of rotation.

Parameters:

  • rotvec (Union[Tensor, NestedSequence[float]]) – shape (..., 3), the rotation vectors.

  • degrees (bool, default: False) – If True, then the given angles are assumed to be in degrees, otherwise radians.

  • reflection (Union[Tensor, NestedSequence[bool], bool], default: False) – If True, the resulting transformation will contain a reflection about a plane perpendicular to the rotation axis, resulting in a rotoflection (improper rotation).

  • inversion (Union[Tensor, NestedSequence[bool], bool], default: False) – If True, the resulting transformation will contain an inversion of the coordinate system, resulting in a rotoinversion (improper rotation).

Returns:

rotation – Object containing the rotations represented by the rotation vectors.

classmethod identity(shape: int | None | tuple[int, ...] = None) → Self[source]

Get identity rotation(s).

Composition with the identity rotation has no effect.

Parameters:

shape (int | None | tuple[int, ...], default: None) – Number of identity rotations to generate. If None, then a single rotation is generated.

Returns:

identity – The identity rotation.

classmethod random(num: int | Sequence[int] | None = None, random_state: int | RandomState | Generator | None = None, improper: bool | Literal['random'] = False)[source]

Generate uniformly distributed rotations.

Parameters:

  • num (int | Sequence[int] | None, default: None) – Number of random rotations to generate. If None, then a single rotation is generated.

  • random_state (int | RandomState | Generator | None, default: None) – If random_state is None, the RandomState singleton is used. If random_state is an int, a new RandomState instance is used, seeded with random_state. If random_state is already a Generator or RandomState instance then that instance is used.

  • improper (Union[bool, Literal['random']], default: False) – if True, only improper rotations are generated. If False, only proper rotations are generated. if “random”, then a random mix of proper and improper rotations are generated.

Returns:

random_rotation – Contains a single rotation if num is None. Otherwise contains a stack of num rotations.

classmethod random_vmf(num: int | None = None, mean_axis: Tensor | None = None, kappa: float = 0.0, sigma: float = math.inf)[source]

Randomly sample rotations from a von Mises-Fisher distribution.

Generate rotations from a von Mises-Fisher distribution with a given mean axis and concentration parameter and a 2pi-wrapped Gaussian distribution for the rotation angle.

Parameters:

  • mean_axis (Tensor | None, default: None) – shape (..., 3,), the mean axis of the von Mises-Fisher distribution.

  • kappa (float, default: 0.0) – The concentration parameter of the von Mises-Fisher distribution. small kappa results in a uniform distribution, large kappa results in a peak around the mean axis. similar to the inverse of the variance of a Gaussian distribution.

  • sigma (float, default: math.inf) – Standard deviation (radians) of the 2pi-wrapped Gaussian distribution used to sample the rotation angle. Use math.inf if a uniform distribution is desired.

  • num (int | None, default: None) – number of samples to generate. If None, a single rotation is generated.

Returns:

random_rotation – a stack of (num, ...) rotations.

property det: Tensor[source]

Returns the determinant of the rotation matrix.

Will be 1. for proper rotations and -1. for improper rotations.

property is_improper: Tensor[source]

Returns a true boolean tensor if the rotation is improper.

property quaternion_w: Tensor[source]

Get w component of the quaternion.

property quaternion_x: Tensor[source]

Get x component of the quaternion.

property quaternion_y: Tensor[source]

Get y component of the quaternion.

property quaternion_z: Tensor[source]

Get z component of the quaternion.

property shape: Size[source]

Return the batch shape of the Rotation.

property single: bool[source]

Returns true if this a single rotation.

__call__(vectors: NestedSequence[float] | Tensor, inverse: bool = False) → Tensor[source]
__call__(vectors: SpatialDimension[Tensor] | SpatialDimension[float], inverse: bool = False) → SpatialDimension[Tensor]

Apply this rotation to a set of vectors.

forward(vectors: NestedSequence[float] | Tensor | SpatialDimension[Tensor] | SpatialDimension[float], inverse: bool = False) → Tensor | SpatialDimension[Tensor][source]

Apply this rotation to a set of vectors.

If the original frame rotates to the final frame by this rotation, then its application to a vector can be seen in two ways:

  • As a projection of vector components expressed in the final frame to the original frame.

  • As the physical rotation of a vector being glued to the original frame as it rotates. In this case the vector components are expressed in the original frame before and after the rotation.

In terms of rotation matrices, this application is the same as self.as_matrix() @ vectors.

Parameters:

  • vectors (Union[NestedSequence[float], Tensor, SpatialDimension[Tensor], SpatialDimension[float]]) – Shape(…, 3). Each vectors[i] represents a vector in 3D space. A single vector can either be specified with shape (3, ) or (1, 3). The number of rotations and number of vectors given must follow standard pytorch broadcasting rules.

  • inverse (bool, default: False) – If True then the inverse of the rotation(s) is applied to the input vectors.

Returns:

rotated_vectors – Result of applying rotation on input vectors. Shape depends on the following cases:

  • If object contains a single rotation (as opposed to a stack with a single rotation) and a single vector is specified with shape (3,), then rotated_vectors has shape (3,).

  • In all other cases, rotated_vectors has shape (..., 3), where is determined by broadcasting.

apply(fn: NestedSequence[float] | Tensor, inverse: bool) → Tensor[source]
apply(fn: SpatialDimension[Tensor] | SpatialDimension[float], inverse: bool) → SpatialDimension[Tensor]
apply(fn: Callable[[Module], None]) → Self

Either apply a function to the Rotation module or apply the rotation to a vector.

This is a hybrid method that matches the signature of both torch.nn.Module.apply and scipy.spatial.transform.Rotation.apply. If a callable is passed, it is assumed to be a function that will be applied to the Rotation module. For applying the rotation to a vector, consider using rotation(vector) instead of rotation.apply(vector).

approx_equal(other: Rotation, atol: float = 1e-6, degrees: bool = False) → Tensor[source]

Determine if another rotation is approximately equal to this one.

Equality is measured by calculating the smallest angle between the rotations, and checking to see if it is smaller than atol.

Parameters:

  • other (Rotation) – Object containing the rotations to measure against this one.

  • atol (float, default: 1e-6) – The absolute angular tolerance, below which the rotations are considered equal.

  • degrees (bool, default: False) – If True and atol is given, then atol is measured in degrees. If False, then atol is measured in radians.

Returns:

approx_equal – Whether the rotations are approximately equal, bool if object contains a single rotation and Tensor if object contains multiple rotations.

as_davenport(axes: Tensor, order: str, degrees: bool = False) → Tensor[source]

Not implemented.

as_directions() → tuple[SpatialDimension[Tensor], SpatialDimension[Tensor], SpatialDimension[Tensor]][source]

Represent as the basis vectors of the new coordinate system as SpatialDimensions.

Returns the three basis vectors of the new coordinate system after rotation, i.e. the columns of the rotation matrix, as SpatialDimensions.

Returns:

basis – The basis vectors of the new coordinate system.

as_euler(seq: str, degrees: bool = Ellipsis, *, improper: Literal['ignore', 'warn'] = 'warn') → Tensor[source]
as_euler(seq: str, degrees: bool = Ellipsis, *, improper: Literal['reflection', 'inversion']) → tuple[Tensor, Tensor]

Represent as Euler angles.

Any orientation can be expressed as a composition of 3 elementary rotations. Once the axis sequence has been chosen, Euler angles define the angle of rotation around each respective axis [EULb].

The algorithm from [BER2022] has been used to calculate Euler angles for the rotation about a given sequence of axes.

Euler angles suffer from the problem of gimbal lock [GIM], where the representation loses a degree of freedom and it is not possible to determine the first and third angles uniquely. In this case, a warning is raised, and the third angle is set to zero. Note however that the returned angles still represent the correct rotation.

Parameters:

  • seq (str) – 3 characters belonging to the set {‘X’, ‘Y’, ‘Z’} for intrinsic rotations, or {‘x’, ‘y’, ‘z’} for extrinsic rotations [EULb]. Adjacent axes cannot be the same. Extrinsic and intrinsic rotations cannot be mixed in one function call.

  • degrees (bool, default: False) – Returned angles are in degrees if this flag is True, else they are in radians

  • improper (Union[Literal['reflection'], Literal['inversion'], Literal['ignore'], Literal['warn']], default: 'warn') – How to handle improper rotations. If ‘warn’, a warning is raised if the rotation is improper. If ‘ignore’, the reflection information is discarded. If ‘reflection’ or ‘inversion’, additional information is returned in the form of a boolean tensor indicating if the rotation is improper. If ‘reflection’, the boolean tensor indicates if the rotation contains a reflection about a plane perpendicular to the rotation axis. If ‘inversion’, the boolean tensor indicates if the rotation contains an inversion of the coordinate system. The quaternion is adjusted to represent the rotation to be performed before the reflection or inversion.

Returns:

angles – shape (3,) or (..., 3), depending on shape of inputs used to initialize object. The returned angles are in the range:

  • First angle belongs to [-180, 180] degrees (both inclusive)

  • Third angle belongs to [-180, 180] degrees (both inclusive)

  • Second angle belongs to:

  • [-90, 90] degrees if all axes are different (like xyz)

  • [0, 180] degrees if first and third axes are the same (like zxz)

References

[BER2022]

Bernardes E, Viollet S (2022) Quaternion to Euler angles conversion: A direct, general and computationally efficient method. PLoS ONE 17(11) https://doi.org/10.1371/journal.pone.0276302

as_matrix() → Tensor[source]

Represent as rotation matrix.

3D rotations can be represented using rotation matrices, which are 3 x 3 real orthogonal matrices with determinant equal to +1 [ROT] for proper rotations and -1 for improper rotations.

Returns:

matrix – shape (..., 3, 3), depends on shape of inputs used for initialization.

References

as_mrp() → Tensor[source]

Not implemented.

as_quat(canonical: bool = Ellipsis, *, improper: Literal['warn', 'ignore'] = 'warn') → Tensor[source]
as_quat(canonical: bool = Ellipsis, *, improper: Literal['reflection', 'inversion']) → tuple[Tensor, Tensor]

Represent as quaternions.

Active rotations in 3 dimensions can be represented using unit norm quaternions [QUAb]. The mapping from quaternions to rotations is two-to-one, i.e. quaternions q and -q, where -q simply reverses the sign of each component, represent the same spatial rotation. The returned value is in scalar-last (x, y, z, w) format.

Parameters:

  • canonical (bool, default: False) – Whether to map the redundant double cover of rotation space to a unique “canonical” single cover. If True, then the quaternion is chosen from {q, -q} such that the w term is positive. If the w term is 0, then the quaternion is chosen such that the first nonzero term of the x, y, and z terms is positive.

  • improper (Union[Literal['reflection'], Literal['inversion'], Literal['ignore'], Literal['warn']], default: 'warn') – How to handle improper rotations. If ‘warn’, a warning is raised if the rotation is improper. If ‘ignore’, the reflection information is discarded. If ‘reflection’ or ‘inversion’, additional information is returned in the form of a boolean tensor indicating if the rotation is improper. If ‘reflection’, the boolean tensor indicates if the rotation contains a reflection about a plane perpendicular to the rotation axis. Note that this required additional computation. If ‘inversion’, the boolean tensor indicates if the rotation contains an inversion of the coordinate system. The quaternion is adjusted to represent the rotation to be performed before the reflection or inversion.

Returns:

  • quaternions – shape (..., 4,), depends on shape of inputs used for initialization.

  • (optional) reflection (if improper is ‘reflection’) or inversion (if improper is ‘inversion’) – boolean tensor of shape (...,), indicating if the rotation is improper and if a reflection or inversion should be performed after the rotation.

References

as_rotvec(degrees: bool = Ellipsis, *, improper: Literal['ignore', 'warn'] = 'warn') → Tensor[source]
as_rotvec(degrees: bool = Ellipsis, *, improper: Literal['reflection', 'inversion']) → tuple[Tensor, Tensor]

Represent as rotation vectors.

A rotation vector is a 3 dimensional vector which is co-directional to the axis of rotation and whose norm gives the angle of rotation [ROTc].

Parameters:

  • degrees (bool, default: False) – Returned magnitudes are in degrees if this flag is True, else they are in radians

  • improper (Union[Literal['reflection'], Literal['inversion'], Literal['ignore'], Literal['warn']], default: 'warn') – How to handle improper rotations. If ‘warn’, a warning is raised if the rotation is improper. If ‘ignore’, the reflection information is discarded. If ‘reflection’ or ‘inversion’, additional information is returned in the form of a boolean tensor indicating if the rotation is improper. If ‘reflection’, the boolean tensor indicates if the rotation contains a reflection about a plane perpendicular to the rotation axis. If ‘inversion’, the boolean tensor indicates if the rotation contains an inversion of the coordinate system. The quaternion is adjusted to represent the rotation to be performed before the reflection or inversion.

Returns:

  • rotvec – Shape (..., 3), depends on shape of inputs used for initialization.

  • (optional) reflection (if improper is ‘reflection’) or inversion (if improper is ‘inversion’) – boolean tensor of shape (...,), indicating if the rotation is improper and if a reflection or inversion should be performed after the rotation.

References

inv() → Self[source]

Invert this rotation.

Composition of a rotation with its inverse results in an identity transformation.

Returns:

inverse – Object containing inverse of the rotations in the current instance.

invert_axes() → Self[source]

Invert the axes of the coordinate system.

Converts a proper rotation to an improper one, or vice versa by inversion of the coordinate system.

Note

This is not the same as the inverse of the rotation. See inv an inverse.

Returns:

inverted_axes – Object containing the rotation with inverted axes.

magnitude() → Tensor[source]

Get the magnitude(s) of the rotation(s).

Returns:

magnitude – Angles in radians. The magnitude will always be in the range [0, pi].

mean(weights: Tensor | NestedSequence[float] | None = None, dim: None | int | Sequence[int] = None, keepdim: bool = False) → Self[source]

Get the mean of the rotations.

The mean used is the chordal L2 mean (also called the projected or induced arithmetic mean) [HAR2013]. If A is a set of rotation matrices, then the mean M is the rotation matrix that minimizes the following loss function: \(L(M) = \sum_{i = 1}^{n} w_i \| A_i - M \|^2\),

where \(w_i\)’s are the weights corresponding to each matrix.

Optionally, if A is a set of Rotation matrices with multiple batch dimensions, the dimensions to reduce over can be specified.

If the rotations contains improper, the mean will be computed without considering the improper and the result will contain a reflection if the weighted majority of the rotations over which the mean is taken have improper.

Parameters:

  • weights (Union[Tensor, NestedSequence[float], None], default: None) – Weights describing the relative importance of the rotations. If None, then all values in weights are assumed to be equal.

  • dim (None | int | Sequence[int], default: None) – Batch Dimensions to reduce over. None will always return a single Rotation.

  • keepdim (bool, default: False) – Keep reduction dimensions as length-1 dimensions.

Returns:

mean – Object containing the mean of the rotations in the current instance.

References

[HAR2013]

Hartley R, Li H (2013) Rotation Averaging. International Journal of Computer Vision (103) https://link.springer.com/article/10.1007/s11263-012-0601-0

reflect() → Self[source]

Reflect this rotation.

Converts a proper rotation to an improper one, or vice versa by reflecting the rotation about a plane perpendicular to the rotation axis.

Returns:

reflected – Object containing the reflected rotations.

reshape(*shape: int | Sequence[int]) → Self[source]

Reshape the Rotation object in the batch dimensions.

Parameters:

shape (int | Sequence[int]) – The new shape of the Rotation object.

Returns:

reshaped – The reshaped Rotation object.

__matmul__(other: Rotation) → Self[source]

Compose this rotation with the other.

If p and q are two rotations, then the composition of ‘q followed by p’ is equivalent to p @ q. In terms of rotation matrices, the composition can be expressed as p.as_matrix() @ q.as_matrix().

Parameters:

other (Rotation) – Object containing the rotations to be composed with this one. Note that rotation compositions are not commutative, so p @ q is generally different from q @ p.

Returns:

composition – This function supports composition of multiple rotations at a time. The following cases are possible:

  • Either p or q contains a single rotation. In this case composition contains the result of composing each rotation in the other object with the single rotation.

  • Both p and q contain N rotations. In this case each rotation p[i] is composed with the corresponding rotation q[i] and output contains N rotations.

__mul__(other: Rotation) → Self[source]

For compatibility with sp.spatial.transform.Rotation.