.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "../../docs/source/_gallery/tree_of_frame.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_.._.._docs_source__gallery_tree_of_frame.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_.._.._docs_source__gallery_tree_of_frame.py:


.. _example_tree_of_frames:

Deals with numerous frames (Tree of frames)
===============================================================

In this example, we will see how to define a tree of frames, where each frame is defined with respect to another frame.

When managing a large number of frames, it is often useful to organize them in a tree structure better than defining the architecture manually.

.. GENERATED FROM PYTHON SOURCE LINES 14-20

Create a tree of frames
---------------------------------------------------

By default the ``"root"`` frame is the canonical frame, but it can be defined as any frame using :meth:`py3dframe.FrameTree.set_root_frame`.

Then the frames can be connected to the tree using :meth:`py3dframe.FrameTree.connect_frame`, where the name of the parent frame must be specified and ``"root"`` refers to the root frame.

.. GENERATED FROM PYTHON SOURCE LINES 20-56

.. code-block:: Python


    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, 15, 45], 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', [12, 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)

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

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

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

    # Print the FrameTree
    frame_tree.print_tree()






.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    root
    ├── Child_Frame_1
    │   ├── Child_Frame_3
    ├── Child_Frame_2




.. GENERATED FROM PYTHON SOURCE LINES 57-65

Perform transformations between frames in the tree
---------------------------------------------------

The transformations between the frames in the tree can be performed using 
the method ``transform`` of the class :class:`py3dframe.FrameTree`.

The points and vectors must be :math:`(3, N)` numpy arrays, where :math:`N` is the number of points or vectors to transform.


.. GENERATED FROM PYTHON SOURCE LINES 65-84

.. code-block:: Python


    point_child1 = np.array([1, 2, 3]).reshape(3, 1)
    point_child2 = frame_tree.transform(
        "Child_Frame_1", 
        "Child_Frame_2", 
        point=point_child1
    )
    print(f"Point in Child_Frame_1: {point_child1.flatten()}")
    print(f"Point in Child_Frame_2: {point_child2.flatten()}")

    vector_child1 = np.array([1, 0, 0]).reshape(3, 1)
    vector_child2 = frame_tree.transform(
        "Child_Frame_1", 
        "Child_Frame_2", 
        vector=vector_child1
    )
    print(f"Vector in Child_Frame_1: {vector_child1.flatten()}")
    print(f"Vector in Child_Frame_2: {vector_child2.flatten()}")





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Point in Child_Frame_1: [1 2 3]
    Point in Child_Frame_2: [0.81783725 2.15895985 2.23901325]
    Vector in Child_Frame_1: [1 0 0]
    Vector in Child_Frame_2: [ 0.6830127   0.61427573 -0.39516955]




.. GENERATED FROM PYTHON SOURCE LINES 85-90

Save and load the FrameTree (JSON format)
---------------------------------------------------

The FrameTree can be saved and loaded in JSON format using the methods 
``to_json`` and ``from_json`` of the class :class:`py3dframe.FrameTree`.

.. GENERATED FROM PYTHON SOURCE LINES 90-96

.. code-block:: Python


    json_file = "frame_tree.json"
    frame_tree.to_json(json_file)
    loaded_frame_tree = FrameTree.from_json(json_file)
    loaded_frame_tree.print_tree()





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    root
    ├── Child_Frame_1
    │   ├── Child_Frame_3
    ├── Child_Frame_2





.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 0.014 seconds)


.. _sphx_glr_download_.._.._docs_source__gallery_tree_of_frame.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: tree_of_frame.ipynb <tree_of_frame.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: tree_of_frame.py <tree_of_frame.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: tree_of_frame.zip <tree_of_frame.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_