py3dframe.Frame.to_dict#

Frame.to_dict(method=['quaternion', 'rotation_vector', 'rotation_matrix'])[source]#

Save the Frame object to a dictionary.

The dictionary has the following structure:

{
    "package": "py3dframe",
    "class": "Frame",
    "version": __version__,
    "translation": [float, float, float],
    "quaternion": [float, float, float, float],
    "rotation_vector": [float, float, float],
    "rotation_matrix": [[float, float, float], [float, float, float], [float, float, float]],
    "euler_angles": [float, float, float],
    "convention": int
}

  • The quaternion is given in WXYZ format (scalar first).

  • The rotation vector is given in radians.

  • The Euler angles are given in radians and the axes are “xyz”.

  • The rotation is given in the convention of the frame.

  • The translation vector is given in the convention of the frame.

See also

  • method from_dict() to load the Frame object from a dictionary.

  • class FrameTree to save/load a system of frames.

Note

For the reader, only one of the rotation keys is needed to reconstruct the frame. The other keys are provided for convenience and user experience. The reader chooses the key to use in the following order of preference if several are given:

  • quaternion

  • rotation_vector

  • rotation_matrix

  • euler_angles

Warning

euler_angles can raise a this warning :

  • UserWarning: Gimbal lock detected. Setting third angle to zero since it is not possible to uniquely determine all angles.

I recommand to not use it.

Warning

  • parent frame is not saved (only local frame is saved), so the loaded frame must be reattached to the parent frame if needed. (See also FrameTree to save/load a system of frames).

Note

For retrocompatibility, the default method “quaternion” must be used.

Parameters:

method (Union[str, Sequence[str]], optional) – The method to use to save the rotation. It can be one of the following : “quaternion”, “rotation_vector”, “rotation_matrix” or “euler_angles”. Several methods can be used at the same time. Default is [“quaternion”, “rotation_vector”, “rotation_matrix”].

Returns:

The dictionary containing the Frame object.

Return type:

Dict[str, Any]

Examples

Create a Frame object and save it to a dictionary using the default method (quaternion, rotation_vector, rotation_matrix):

from py3dframe import Frame
frame = Frame.from_axes(origin=[1, 2, 3], x_axis=[1, 0, 0], y_axis=[0, 1, 0], z_axis=[0, 0, 1], convention=0)
frame_dict = frame.to_dict()

# Reload the Frame object from the dictionary:

loaded_frame = Frame.from_dict(frame_dict)

Warning, the method no longer saves the parent frame. To save/load a system of frames, consider using the FrameTree class.

from py3dframe import Frame

parent = Frame.from_axes(origin=[0, 0, 0], x_axis=[1, 0, 0], y_axis=[0, 1, 0], z_axis=[0, 0, 1], convention=0)
child = Frame.from_axes(origin=[1, 0, 0], x_axis=[1, 0, 0], y_axis=[0, 1, 0], z_axis=[0, 0, 1], convention=0, parent=parent)

child_dict = child.to_dict(method=["quaternion", "rotation_vector"])
parent_dict = parent.to_dict(method=["quaternion", "rotation_vector"])

# Reload the frames from the dictionaries
loaded_parent = Frame.from_dict(parent_dict)
loaded_child = Frame.from_dict(child_dict)
loaded_child.parent = loaded_parent # IMPORTANT
On this page

This Page