py3dframe.FrameTransform#

class FrameTransform(*, input_frame=None, output_frame=None, dynamic=True, convention=0)[source]#

Class to represent a transformation between two frames of reference.

Lets consider two orthonormal reference frames \(E\) and \(F\) of \(\mathbb{R}^3\) (see py3dframe.Frame). The transformation from the frame E (input frame) to the frame F (output frame) can be stored in a FrameTransform object.

Lets consider a point \(X\) whose coordinates in the frame E are \(\mathbf{X}_i\) and in the frame F are \(\mathbf{X}_o\). There exist 8 principal conventions to express the transformation between the frame E and the frame F.

The 8 conventions are summarized as follows:

Index

Formula

0

\(\mathbf{X}_E = \mathbf{R} \mathbf{X}_F + \mathbf{T}\)

1

\(\mathbf{X}_E = \mathbf{R} \mathbf{X}_F - \mathbf{T}\)

2

\(\mathbf{X}_E = \mathbf{R} (\mathbf{X}_F + \mathbf{T})\)

3

\(\mathbf{X}_E = \mathbf{R} (\mathbf{X}_F - \mathbf{T})\)

4

\(\mathbf{X}_F = \mathbf{R} \mathbf{X}_E + \mathbf{T}\)

5

\(\mathbf{X}_F = \mathbf{R} \mathbf{X}_E - \mathbf{T}\)

6

\(\mathbf{X}_F = \mathbf{R} (\mathbf{X}_E + \mathbf{T})\)

7

\(\mathbf{X}_F = \mathbf{R} (\mathbf{X}_E - \mathbf{T})\)

Because the frames are orthonormal, the matrix \(\mathbf{R}\) is an orthogonal matrix, i.e. \(\mathbf{R}^T = \mathbf{R}^{-1}\).

Parameters:

  • input_frame (Optional[Frame], optional) – The input frame of the transformation. Default is None - the global frame.

  • output_frame (Optional[Frame], optional) – The output frame of the transformation. Default is None - the global frame.

  • dynamic (bool, optional) – If True, the transformation will be affected by the changes in the input frame or the output frame. Default is True.

  • convention (int, optional) – Integer in [0, 7] selecting the convention to express the transformation. Default is 0.

Raises:

  • TypeError – If the input_frame or the output_frame is not a Frame object (or None). If the dynamic is not a boolean. If the convention is not an integer or a string.

  • ValueError – If the convention is not between 0 and 7.

Set the input and output frames#

The input and output frames of the transformation can be set and accessed via the corresponding properties. To freeze the transformation with respect to changes in the input and output frames, set the dynamic attribute to False.

FrameTransform.input_frame

The input frame of the transformation.

FrameTransform.output_frame

The output frame of the transformation.

FrameTransform.dynamic

The dynamic attribute controls whether the transformation is affected by changes in the input or output frame.

FrameTransform.convention

The convention to express the transformation between the input frame and the output frame.

FrameTransform.get_active_input_frame()

Get a copy of the active input frame of the transformation.

FrameTransform.get_active_output_frame()

Get a copy of the active output frame of the transformation.

Access the parameters of the transformation#

FrameTransform.get_translation(*[, convention])

Get the translation vector between the input frame and the output frame in a specified convention.

FrameTransform.translation

Getter for the translation vector between the input frame and the output frame in the convention of the transformation.

FrameTransform.get_rotation(*[, convention])

Get the rotation between the input frame and the output frame in a specified convention.

FrameTransform.rotation

Getter for the rotation between the input frame and the output frame in the convention of the transformation.

FrameTransform.get_rotation_matrix(*[, ...])

Get the rotation matrix representation of the rotation between the input frame and the output frame in a specified convention.

FrameTransform.rotation_matrix

Getter for the rotation matrix representation of the rotation between the input frame and the output frame in the convention of the transformation.

FrameTransform.get_quaternion(*[, ...])

Get the quaternion representation of the rotation between the input frame and the output frame in a specified convention.

FrameTransform.quaternion

Getter for the quaternion representation of the rotation between the input frame and the output frame in the convention of the transformation.

FrameTransform.get_euler_angles(*[, ...])

Get the Euler angles representation of the rotation between the input frame and the output frame in a specified convention.

FrameTransform.euler_angles

Getter for the Euler angles representation of the rotation between the input frame and the output frame in the convention of the transformation.

FrameTransform.get_rotation_vector(*[, ...])

Get the rotation vector representation of the rotation between the input frame and the output frame in a specified convention.

FrameTransform.rotation_vector

Getter for the rotation vector representation of the rotation between the input frame and the output frame in the convention of the transformation.

Perform the transformation from input to output and vice versa#

To transform points or vectors from the input frame to the output frame, use the transform method. To transform points or vectors from the output frame to the input frame, use the inverse_transform method.

FrameTransform.transform(*[, point, vector])

Transform a point or a vector from the input frame to the output frame.

FrameTransform.inverse_transform(*[, point, ...])

Transform a point or a vector from the output frame to the input frame.

Manipulate the transformation#

Some operations can be performed on FrameTransform objects.

FrameTransform.inverse()

Get the inverse transformation by swapping the input frame and the output frame.

Examples of Usage#

To create a FrameTransform object, the user must provide two Frame objects.

from py3dframe import Frame, FrameTransform

frame_E = Frame.canonical() # Global frame
frame_F = Frame.from_axes(origin=[1, 2, 3], x_axis=[1, 0, 0], y_axis=[0, 1, 0], z_axis=[0, 0, 1]) # Local frame
transform = FrameTransform(input_frame=frame_E, output_frame=frame_F, dynamic=True, convention=0)

  • If the dynamic parameter is set to True, the FrameTransform object will be affected by the changes in the input frame or the output frame.

  • If the dynamic parameter is set to False, the FrameTransform object will correspond to the transformation between the input frame and the output frame at the time of the creation of the FrameTransform object.

  • If the dynamic parameter is set to True and then changed to False, the FrameTransform object will correspond to the transformation between the input frame and the output frame at the time of the change of the dynamic parameter.

The user can access the rotation matrix and the translation vector of the transformation as follows:

R = transform.get_rotation_matrix(convention=0) # Rotation matrix in convention 0
T = transform.get_translation(convention=0) # Translation vector in convention 0

The user can also access the input frame and the output frame of the transformation as follows:

frame_E = transform.get_active_input_frame()
frame_F = transform.get_active_output_frame()

To update the input frame or the output frame of the transformation, the user can use the corresponding properties.

frame_G = Frame.from_axes(origin=[3, 2, 1], x_axis=[0, 1, 0], y_axis=[0, 0, 1], z_axis=[1, 0, 0]) # Another local frame
transform.input_frame = frame_G # Update the input frame of the transformation
transform.output_frame = frame_F # Update the output frame of the transformation

Note

If the dynamic parameter is set to False, the FrameTransform object will not be affected by the changes in the input frame or the output frame. Set dynamic to True to reactivate the dynamic mode (you can then reset it to False again if needed).

The FrameTransform object can be used to transform points or vectors from the input frame to the output frame and vice versa.

import numpy

X_i = numpy.array([1, 2, 3]).reshape((3, 1)) # Point in input frame
X_o = transform.transform(point=X_i)
X_i = transform.inverse_transform(point=X_o)

For vectors, the translation vector is not taken into account.

X_i = numpy.array([1, 2, 3]).reshape((3, 1)) # Point in input frame
X_o = transform.transform(point=X_i) # X_i = R X_o + T
V_i = numpy.array([1, 2, 3]).reshape((3, 1)) # Vector in input frame
V_o = transform.transform(vector=V_i) # V_i = R V_o