From f082fb772bb66ab651e29a96233e57e0db4b21d0 Mon Sep 17 00:00:00 2001 From: Christian Petersmeier Date: Fri, 11 Feb 2022 04:15:18 -0800 Subject: [PATCH] Add property tutorial, restructure tutorial files --- core/doc/howtoguides.rst | 2 +- core/doc/tut_cartesian.rst | 4 ++ core/doc/tut_first-steps.rst | 6 ++ core/doc/tut_pick-and-place.rst | 7 +++ core/doc/tut_properties.rst | 100 ++++++++++++++++++++++++++++++++ core/doc/tutorials.rst | 26 +++------ 6 files changed, 125 insertions(+), 20 deletions(-) create mode 100644 core/doc/tut_cartesian.rst create mode 100644 core/doc/tut_first-steps.rst create mode 100644 core/doc/tut_pick-and-place.rst create mode 100644 core/doc/tut_properties.rst diff --git a/core/doc/howtoguides.rst b/core/doc/howtoguides.rst index d32fc664..7cb20940 100644 --- a/core/doc/howtoguides.rst +++ b/core/doc/howtoguides.rst @@ -206,7 +206,7 @@ property to be derived from the monitored stage as shown in the example. Download the full example code here: :download:`Source <./../../demo/scripts/compute_ik.py>` -.. literalinclude:: ./../../../demo/scripts/compute_ik.py +.. literalinclude:: ./../../demo/scripts/compute_ik.py :language: python :lines: 35-45 diff --git a/core/doc/tut_cartesian.rst b/core/doc/tut_cartesian.rst new file mode 100644 index 00000000..efa8d809 --- /dev/null +++ b/core/doc/tut_cartesian.rst @@ -0,0 +1,4 @@ +.. _subsec-tut-cartesian: + +Cartesian +--------- diff --git a/core/doc/tut_first-steps.rst b/core/doc/tut_first-steps.rst new file mode 100644 index 00000000..eadf7b9a --- /dev/null +++ b/core/doc/tut_first-steps.rst @@ -0,0 +1,6 @@ +.. _subsec-tut-firststeps: + +First Steps +----------- + +Here go the first steps. diff --git a/core/doc/tut_pick-and-place.rst b/core/doc/tut_pick-and-place.rst new file mode 100644 index 00000000..9b24f05f --- /dev/null +++ b/core/doc/tut_pick-and-place.rst @@ -0,0 +1,7 @@ +.. _subsec-tut-pick-place: + +Pick and Place +-------------- + +.. literalinclude:: ./../../demo/scripts/pickplace.py + :language: python diff --git a/core/doc/tut_properties.rst b/core/doc/tut_properties.rst new file mode 100644 index 00000000..15a695c4 --- /dev/null +++ b/core/doc/tut_properties.rst @@ -0,0 +1,100 @@ +.. _subsec-tut-properties: + +Properties +---------- + +Properties are named attributes of a stage. +They can be used to configure the stages behaviour +and control further substages. Lets take a closer +look at how to work with properties. + +Basic Operations with Properties +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Lets define a property and assign a description, as well as +a value to it. + +.. literalinclude:: ./../../demo/scripts/properties.py + :language: python + :lines: 18-25 + +Notice that a property always has two values: the current value +and the default value. Before we use the property, we might want to +check if the current value defined. + +.. literalinclude:: ./../../demo/scripts/properties.py + :language: python + :lines: 27-28 + +Now we are ready to safely retrieve the values of the proprty! + +.. literalinclude:: ./../../demo/scripts/properties.py + :language: python + :lines: 30-37 + +The Property Map +^^^^^^^^^^^^^^^^ + +Usually a stage comprises multiple properties. A stage +contains a single PropertyMap that acts as a container for +all properties associated to that stage. + +Lets first create a PropertyMap in isolation and initialize +some properties using a dict. As you can see, properties can be +of arbitrary type. + +.. literalinclude:: ./../../demo/scripts/properties.py + :language: python + :lines: 39-47 + +Properties can also be initialized using a more pythonic way. + +.. literalinclude:: ./../../demo/scripts/properties.py + :language: python + :lines: 49-50 + +There are two ways to retrieve properties back from the property map. +We might only be interested in in the value of the property: + +.. literalinclude:: ./../../demo/scripts/properties.py + :language: python + :lines: 52-53 + +Or we can obtain a refernece to the whole property object. + +.. literalinclude:: ./../../demo/scripts/properties.py + :language: python + :lines: 55-56 + +The PropertyMap class additionally provides an iterator that can be used in loops. + +.. literalinclude:: ./../../demo/scripts/properties.py + :language: python + :lines: 58-62 + +Remember that wer initialized our PropertyMap by using a dict. In fact, you +can also use an existing PropertMap to copy over some properties. + +.. literalinclude:: ./../../demo/scripts/properties.py + :language: python + :lines: 64-67 + +Accessing Properties of a Stage +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You can obtain a reference to the the PropertyMap of a stage like so + +.. literalinclude:: ./../../demo/scripts/properties.py + :language: python + :lines: 15-16, 74-75 + +As mentioned, each stage contains a PropertyMap. +Stages communicate to each other via their interfaces. +If you want to forward properties through these interfaces, +you can use the reference of a stages' property object. + +.. literalinclude:: ./../../demo/scripts/compute_ik.py + :language: python + :lines: 27-28, 35-36, 40-42 + +Take a look at the :ref:`How-To-Guides ` +for a full example of this. diff --git a/core/doc/tutorials.rst b/core/doc/tutorials.rst index f3600a57..107d00c4 100644 --- a/core/doc/tutorials.rst +++ b/core/doc/tutorials.rst @@ -3,25 +3,13 @@ Tutorials ========= +The following tutorials take you step by step through the implementation of fundamental examples +of the moveit task constructor. + .. toctree:: :caption: Tutorials -.. _subsec-tut-firststeps: - -First Steps ------------ - -Here go the first steps. - -.. _subsec-tut-cartesian: - -Cartesian ---------- - -.. _subsec-tut-pick-place - -Pick and Place --------------- - -.. literalinclude:: ./../../demo/scripts/pickplace.py - :language: python + First Steps + Cartesian + Properties + Pick and Place