ReferenceFrame API Reference#

The ReferenceFrame Type#

The ReferenceFrame type allows for a reference frame definition within a single object. The ReferenceFrame type also provides rotation methods similar to the rotate_from(), rotate_to(), and rotate_between() functions.

The ReferenceFrame type holds an internal rotation matrix that is easily updatable via updating the rotation angles. This means the ReferenceFrame type is ideal for handling many rotations as the type easily persists, updates, and applies the rotation matrix for you.

class pyevspace.ReferenceFrame(order: RotationOrder, angles: EulerAngles, *, intrinsic: bool = True, offset: Vector | None = None)#

Holds the definition of a reference frame and assists in rotating vectors to and from, and even between other ReferenceFrame objects.

The ReferenceFrame type should be thought of just like reference frames discussed in the rotation API. The special function of this type is to provide the arguments to the constructor once, and simply manage any angle adjustments using the set_angles() method and efficiently apply the rotations with the various rotate_*() methods provided.

Changed in version 0.16.0: ReferenceFrame is now subclassable, and is no longer an immutable type, meaning class members can be directly modified or added.

Parameters:

  • order – the Euler order of the rotation of the reference frame

  • angles – the Euler angles of the rotation of the reference frame

  • intrinsic – True (default) for an intrinsic rotation, False for extrinsic

  • offset – optionally define an offset of the origin relative to an inertial frame (default = None)

Raises:

TypeError – if any of the parameters do not have their specified type

Other Constructors#

ReferenceFrame.__new__(cls: type) → Self#

Create a new, uninitialized type object if type is a subclass of ReferenceFrame.

Changed in version 0.16.0: type can be a subtype of ReferenceFrame, and an object of that type will be created and returned.

Changed in version 0.16.0: The returned value is no longer initialized, and ReferenceFrame.__init__() should be used to initialize it. The default order is XYZ, the angles are defaulted to zero and offset is set to None.

ReferenceFrame.__init__(self, order: RotationOrder, angles: EulerAngles, *, intrinsic: bool = True, offset: Vector | None = None)#

Initializes a ReferenceFrame to the argument values. This method and arguments behave identically to the ReferenceFrame constructor.

Parameters:

  • order – the Euler order of the rotation of the reference frame

  • angles – the Euler angles of the rotation of the reference frame

  • intrinsic – True (default) for an intrinsic rotation, False for extrinsic

  • offset – optionally define an offset of the origin relative to an inertial frame (default = None)

Raises:

TypeError – if any of the parameters do not have their specified type

Added in version 0.16.0.

Subclassing ReferenceFrame#

As of version 0.16.0 the ReferenceFrame class supports subclassing. As the ReferenceFrame class is implemented as a C struct, it has a specific memory layout, and as a consequence of that it is a @distjoint-base. This means ReferenceFrame cannot be combined with any other types whose layout is defined as a C struct when inheriting, which most Python built-in types such as list or tuple are. For example combining ReferenceFrame and list as base classes will raise a TypeError:

>>> class Foo(ReferenceFrame, list):
...     pass
...
TypeError: multiple bases have instance lay-out conflict

This limitation does not apply when combining a @distjoin-base with a pure python class, and of course is not an issue if ReferenceFrame is the only base class for a derived type.

Other types that interact with ReferenceFrame may also be subclasses, for example Vector or Matrix. Because the base types of this module do not know how to initialize any derived types, these base types are always returned by ReferenceFrame methods. For example if MyType inherits from Vector, calling ReferenceFrame.rotate_to() with a MyType instance will always return a Vector. For different behavior you will need to create a subclass of ReferenceFrame and overload the functions so that they use the return value of the parent function to create instances of MyType as desired.

Instance Members#

Properties#

property ReferenceFrame.intrinsic#

The intrinsic value provided to the constructor.

Type:

bool

Readonly:

this value cannot be changed

property ReferenceFrame.offset#

The offset of the origin of the reference frame.

Type:

this must be a Vector or None`

property ReferenceFrame.order#

The Euler rotation order of the reference frame.

Type:

RotationOrder

Readonly:

this value cannot be changed

Methods#

ReferenceFrame.get_angles() → EulerAngles#

Returns a copy of the current values of the internal rotation angles.

Note

The returned value is only a copy. Changing the values on the returned object will not affect the ReferenceFrame instance. See ReferenceFrame.set_angles() for changing the ReferenceFrame angle values.

Returns:

a copy of the internal angle state as an EulerAngles object

ReferenceFrame.set_angles(angles: EulerAngles) → None#
ReferenceFrame.set_angles(*, alpha: SupportsFloat | None = None, beta: SupportsFloat | None = None, gamma: SupportsFloat | None) → None

Updates the angles of the rotation. The angles can be updated from an EulerAngles instance, or individually from alpha, beta, or gamma values. The second form accepts keyword only arguments, and only non-None values will be updated. Each time an angle is updated, the internal rotation matrix is also updated. It is therefore most efficient to provide all angles at once, as the matrix is only updated a single time.

The individual angle version of this method is more efficient as the angles don’t need to be copied from an EulerAngles instance, but the first form is provided for convenience.

Parameters:

  • angles – an EulerAngles instance to update the rotation angles to

  • alpha – the first angle of the rotation to update (default is None)

  • beta – the second angle of the rotation to update (default is None)

  • gamma – the third angle of the rotation to update (default is None)

Returns:

None

Raises:

  • TypeError – if angles is not an EulerAngles instance

  • TypeError – if any keyword values cannot be converted to a float

ReferenceFrame.get_matrix() → Matrix:#

Returns a copy of the current state of the internal rotation matrix. This is mostly meant for introspective/validation purposes, however it can be used like any other matrix, but keep in mind it is merely a copy, and any modification will not be reflected on the internal state of the ReferenceFrame object it was retrieved from.

Returns:

a copy of the internal rotation matrix

ReferenceFrame.rotate_to(vector: Vector) → Vector#
ReferenceFrame.rotate_to(frame: ReferenceFrame, vector: Vector) → Vector

Rotates a vector from the inertial reference frame that self is currently defined against, to this reference frame. If frame is provided, the method behaves like rotate_between(), rotating from frame to self.

Note

The suffix applies to the calling object i.e. self, so this method always rotates a vector to self.

ReferenceFrame.rotate_from(vector: Vector) → Vector#
ReferenceFrame.rotate_from(frame: ReferenceFrame, vector: Vector) → Vector

Rotates a vector from this reference frame to the inertial reference frame that self is currently defined against. If frame is provided, the method behaves like rotate_between(), rotating to frame from self.

Note

The suffix applies to the calling object i.e. self, so this method always rotates a vector from self.