Rotations

This module is for alternative 3D rotation formalisms besides the Quaternion, Matrix, and Euler representations provided by the mathutils library. They must implement the to_quaternion method, which returns a mathutils.Quaternion instance, in order to be compatible with the rest of this library. A from_other classmethod may also be useful, in order to convert from a mathutils representation to the alternative representation.

class starfish.rotations.Spherical(theta, phi, roll)

An alternative 3-value representation of a rotation based on spherical coordinates.

Imagine a unit sphere centered about an object. Two spherical coordinates (an azimuthal angle, henceforth theta, and a polar angle, henceforth phi) define a point on the surface of the sphere, and a corresponding unit vector from the center of the sphere (the object) to the point on the surface of the sphere.

First, the +Z axis of the object is rotated to this unit vector, while the XY plane of the object is aligned such that the +X axis points in the +phi direction and the +Y axis points in the +theta direction. It may be helpful to visualize this rotation as such: imagine that the +Z axis of the object is a metal rod attached rigidly to the object, extending out through the surface of the sphere. Now grab the rod and use it to rotate the object such that the rod is passing through the point on the sphere defined by theta and phi. Finally, twist the rod such that the original “right” direction of the object (its +X axis) is pointing towards the south pole of the sphere, along the longitude line defined by theta. Correspondingly, this should mean that the original “up” direction of the object (its +Y axis) is pointing eastward along the latitude line defined by phi.

Next, perform a right-hand rotation of the object about the same unit vector by a third angle (henceforth called the roll angle). In the previous analogy, this is equivalent to then twisting the metal rod counter-clockwise by the roll angle. This configuration is the final result of the rotation.

Note: the particular alignment of the XY plane (+X is +phi and +Y is +theta) was chosen so that “zero rotation” (aka the identity quaternion, or (0, 0, 0) Euler angles) corresponds to (theta, phi, roll) = (0, 0, 0).

Also note that this representation only uses 3 values, and thus it has singularities at the poles where theta and the roll angle are redundant (only their sum matters).

Attributes:

  • theta: The azimuthal angle, in radians

  • phi: The polar angle, in radians (0 at the north pole, pi at the south pole)

  • roll: The roll angle, in radians

classmethod from_other(obj)

Constructs a Spherical object from a Quaternion, Euler, or Matrix rotation object from the mathutils library.

to_quaternion()

Returns a mathutils.Quaternion representation of the rotation.