py3dframe.Transform#

class py3dframe.Transform(*, input_frame: Frame | None = None, output_frame: Frame | None = None, dynamic: bool = True, convention: int = 0)[source]#

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 Transform 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}\).

See also

function py3dframe.switch_RT_convention() to convert the transformation between the frames E and F from one convention to another.

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 (Union[int, str], optional) – The convention to express the transformation. It can be an integer between 0 and 7 or a string corresponding to the conventions. Default is 0.

Raises:

TypeError – If the input_frame or the output_frame is not a Frame object (or None). If the rotation_matrix is not an array_like object (or None). If the translation is not an array_like object (or None). If the dynamic is not a boolean. If the convention is not an integer or a string.
ValueError – If the rotation_matrix is not a 3x3 matrix. If the translation_vector is not a 3-element vector. If the convention is not between 0 and 7 or a valid string. If the user provides both the rotation_matrix and the translation_vector and the input_frame and the output_frame.

Examples

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

from py3dframe import Frame, Transform

frame_E = Frame() # Global frame
frame_F = Frame(origin=[1, 2, 3], x=[1, 0, 0], y=[0, 1, 0], z=[0, 0, 1]) # Local frame
transform = Transform(input_frame=frame_E, output_frame=frame_F, dynamic=True, convention=0)

If the dynamic parameter is set to True, the Transform object will be affected by the changes in the input frame or the output frame.
If the dynamic parameter is set to False, the Transform object will correspond to the transformation between the input frame and the output frame at the time of the creation of the Transform object.
If the dynamic parameter is set to True and then changed to False, the Transform 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.rotation_matrix
T = transform.translation

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

frame_E = transform.input_frame
frame_F = transform.output_frame

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

X_i = [1, 2, 3]
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 = [1, 2, 3]
X_o = transform.transform(point=X_i) # X_i = R X_o + T
V_i = [1, 2, 3]
V_o = transform.transform(vector=V_i) # V_i = R V_o

`py3dframe.Transform.input_frame`	Getter and setter for the input_frame attribute.
`py3dframe.Transform.output_frame`	Getter and setter for the output_frame attribute.
`py3dframe.Transform.dynamic`	Getter and setter for the dynamic attribute.
`py3dframe.Transform.convention`	Getter and setter for the convention parameter.
`py3dframe.Transform.get_translation`(*[, ...])	Get the translation vector between the input frame and the output frame in the given convention.
`py3dframe.Transform.translation`	Getter for the translation vector between the input frame and the output frame in the convention of the frame.
`py3dframe.Transform.get_rotation`(*[, convention])	Get the rotation between the input frame and the output frame in the given convention.
`py3dframe.Transform.rotation`	Getter for the rotation between the input frame and the output frame in the convention of the frame.
`py3dframe.Transform.get_rotation_matrix`(*[, ...])	Get the rotation matrix between the input frame and the output frame in the given convention.
`py3dframe.Transform.rotation_matrix`	Getter for the rotation matrix between the input frame and the output frame in the convention of the frame.
`py3dframe.Transform.get_quaternion`(*[, ...])	Get the quaternion between the input frame and the output frame in the given convention.
`py3dframe.Transform.quaternion`	Getter for the quaternion between the input frame and the output frame in the convention of the frame.
`py3dframe.Transform.get_euler_angles`(*[, ...])	Get the Euler angles between the input frame and the output frame in the given convention.
`py3dframe.Transform.euler_angles`	Getter for the Euler angles between the input frame and the output frame in the convention of the frame.
`py3dframe.Transform.get_rotation_vector`(*[, ...])	Get the rotation vector between the input frame and the output frame in the given convention.
`py3dframe.Transform.rotation_vector`	Getter for the rotation vector between the input frame and the output frame in the convention of the frame.
`py3dframe.Transform.transform`(*[, point, vector])	Transform a point or a vector from the input frame to the output frame.
`py3dframe.Transform.inverse_transform`(*[, ...])	Transform a point or a vector from the output frame to the input frame.

py3dframe.Transform#

This Page