py3dframe.FrameTree#

class FrameTree(root_frame=None)[source]#

A class to manage a tree/system of Frame objects better than using individual Frame objects with parent/child relationships.

Warning

All the connected frames are stored in a tree structure must have parent=None because the FrameTree manages the relationships. Avoid modifying the parent attribute of the Frame objects connected to a FrameTree to prevent inconsistencies.

By default, the root frame is considered the canonical frame of \(\mathcal{R}^3\) and is associated with the name ‘root’.

Root_Frame (Canonical Frame)
├── Child_Frame_1
│   ├── Grandchild_Frame_1
│   └── Grandchild_Frame_2
└── Child_Frame_2
    └── Grandchild_Frame_3
Parameters:

root_frame (Optional[Frame], optional) – The root Frame of the FrameTree. If None, the canonical Frame of \(\mathcal{R}^3\) is used. Default is None.

Update the tree connections#

The connections between frames in the tree can be set using the connect_frame() method.

FrameTree.connect_frame(name, frame[, ...])

Add a Frame to the FrameTree.

FrameTree.disconnect_frame(name[, recursive])

Remove a Frame from the FrameTree.

FrameTree.list_frames()

List all frame names in the FrameTree.

FrameTree.get_child_names(name)

Get the names of the child frames of a specified frame in the FrameTree.

FrameTree.get_frame(name)

Get a Frame from the FrameTree by its name.

FrameTree.get_parent_name(name)

Get the name of the parent frame of a specified frame in the FrameTree.

FrameTree.move_frame(name[, new_parent_name])

Move a Frame to a new parent frame in the FrameTree.

FrameTree.rename_frame(old_name, new_name)

Rename a Frame in the FrameTree.

FrameTree.replace_frame(name, frame)

Replace a Frame in the FrameTree with another Frame.

FrameTree.set_root_frame(frame)

Set the root Frame of the FrameTree.

Transformations between frames in the tree#

FrameTree.get_transform([input_frame, ...])

Get the FrameTransform between two frames in the FrameTree.

FrameTree.transform([input_frame, ...])

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

Save and load FrameTree objects#

FrameTree.to_dict()

Serialize the FrameTree to a dictionary.

FrameTree.from_dict(data)

Deserialize a FrameTree from a dictionary.

FrameTree.to_json(filename)

Save the FrameTree object to a JSON file.

FrameTree.from_json(filename)

Load a FrameTree object from a JSON file.

Additional methods#

FrameTree.__repr__()

Return repr(self).

FrameTree.__str__()

Return str(self).

FrameTree.__len__()

FrameTree.__contains__(name)

FrameTree.__getitem__(name)

FrameTree.__bool__()

FrameTree.print_tree()

Print the FrameTree structure.

Usage example#

Create some frames and build a FrameTree

import numpy as np
from py3dframe import Frame, FrameTree, Rotation

# Create some frames
rotation = Rotation.from_euler('xyz', [0, 0, 0], degrees=True)
translation = np.array([0, 0, 0]).reshape(3, 1)

root_frame = Frame.from_rotation(translation=translation, rotation=rotation, convention=0)

rotation = Rotation.from_euler('xyz', [0, 0, 0], degrees=True)
translation = np.array([1, 0, 0]).reshape(3, 1)

child_frame_1 = Frame.from_rotation(translation=translation, rotation=rotation, convention=0)

rotation = Rotation.from_euler('xyz', [0, 0, 0], degrees=True)
translation = np.array([0, 1, 0]).reshape(3, 1)

child_frame_2 = Frame.from_rotation(translation=translation, rotation=rotation, convention=0)

# Build a FrameTree
frame_tree = FrameTree()
frame_tree.connect_frame(name="Root_Frame", frame=root_frame)
frame_tree.connect_frame(name="Child_Frame_1", frame=child_frame_1, parent_name="Root_Frame")
frame_tree.connect_frame(name="Child_Frame_2", frame=child_frame_2, parent_name="Root_Frame")

# Print the FrameTree
frame_tree.print_tree()