Differences

This shows you the differences between two versions of the page.

--- doc:pycram:designator [2021/06/18 08:54] – [Designator] jdech
+++ doc:pycram:designator [2021/07/30 12:01] (current) – jdech
@@ Line 4: / Line 4: @@
 Designators, in PyCRAM, consist of an instance of the respective class which holds a description with all parameter necessary as instance attributes. In the following we will reefer to the parameter as properties of the respective description. Below you can see a few examples which should help understand the usage of designators.
-<code>MotionDesignator(MoveMotionDescription(target=[1,1,0], orientation=[0, 0, 0, 1]))</code>
+<code>
+from pycram.motion_designator import MotionDesignator, MoveMotionDesignator
+MotionDesignator(MoveMotionDescription(target=[1,1,0], orientation=[0, 0, 0, 1]))</code>
 This motion desigantor holds a description of type MoveMotionDescription meaning it describes moving the robot around. The parameter or properties are 'target' which represents the coordinates in world frame of where the robot should move and 'orientation' which is the orientation the robot should have after moving.
@@ Line 26: / Line 29: @@
 In this case solution is a dictionary of the resolved designator. This dictionary also contains a orientation because this is needed to move the robot around. The value for the orientation would be the orientation of the robot in the Bullet World or the identity orientation if no simulation is running.
+For resolving a designator it is important to remark that, similar to performing, the return value varies dependent on the designator type. For motion designator this is a dictionary and for action designator this is a new action designator.
+=== Different Resolver ===
+The resolver is the method used in the reference method of a Designator. There can be different resolver registered for a designator, to register a new resolver method you add it to the dictionary in the respective designator class. How to register a new resolver method can be seen below.
+<code>
+MotionDesignar.resolver['grounding'] = call_grounding_function
+</code>
+In this case the resolver is called 'grounding' and the method called when using this resolver is 'call_grounding_function'. So if you have a designator which should be resolved using the grounding resolver the call_ground_function is called and passed the designator to be resolved. The call_ground_function then checks the type of the designator description and chooses the right method to ground the attributes of the description.
 ==== Real and Simulated robot ====
@@ Line 46: / Line 58: @@
 from pycram.process_module import with_real_robot
-@with_simulated_robot
+@with_real_robot
 def plan_a():
     MotionDesignator(MoveMotionDescription(target=[1,1,0], orientation=[0, 0, 0, 1])).perform()
@@ Line 86: / Line 98: @@
     * WorldStateDetectingMotionDescription
-All descriptions take different parameters depending on the described movement. Some of these parameters are optional, meaning there are multiple parameter which provide the information. For example, in the case of the MoveArmJointsMotionDescription where the used can provide either positions for the left or right arm, both of these parameters are optional. Another case may be that the missing parameter can be inferred or that a standard value can be used. In the case of the MoveMotionDescription if no orientation is provided the current orientation of the robot in the Bullet World is used. In other cases where an arm has to be named and the user does not specify which arm to use, the left is used as a standard value.
+All descriptions take different parameters depending on the described movement. Some of these parameters are optional, meaning there are multiple parameter which provide the information. For example, in the case of the MoveArmJointsMotionDescription where the user can provide either positions for the left or right arm, both of these parameters are optional. Another case may be that the missing parameter can be inferred or that a standard value can be used. In the case of the MoveMotionDescription if no orientation is provided the current orientation of the robot in the Bullet World is used. In other cases where an arm has to be named and the user does not specify which arm to use, the left is used as a standard value.
@@ Line 100: / Line 112: @@
 ===== Action Designator =====
-Action designator are a high level representation of movements which compose different motion designator. For example the is the transport action designator which transports an object from one position to another. This includes going to the location of the object, detecting the object, picking it up, moving to the target location and placing the object.
+Action designator are a high level representation of movements which compose different motion designator. One example for this is the transport action designator which transports an object from one position to another. This includes going to the location of the object, detecting the object, picking it up, moving to the target location and placing the object.
-Action designator work much like motion designator in that both hold a description which has all properties needed for execution. Action designator descriptions also have a grounding method which interferes missing properties.
-The main difference between action and motion designator is that action designator do not call a process module if they are performed, instead they call a function which is set while the designator is grounded. This function is the plan that composes the motions needed for executing the described movement.
 The currently available action designator descriptions are:
@@ Line 122: / Line 130: @@
     * OpenActionDescription
     * CloseActionDescription
+=== Perform ===
+Like motion designator, action designator also have a perform method which executes the behaviour described in the designator.
+The main difference between action and motion designator is that action designator do not call a process module if they are performed, instead they call a function which is set while the designator is grounded. This function is the plan that composes the motions needed for executing the described movement.
+An example on how to perform an action designator can be seen below.
+<code>
+from pycram.action_designator import ActionDesignator, MoveTorsoActionDescription
+ActionDesignator(MoveTorsoActionDesignator(position=[1, 1, 0])).perform() </code>
+The perform method will firstly call the ground method of the description to ensure that all necessary properties are present and then execute the function set while grounding the designator.
+=== Grounding ===
+Grounding is similar to the resolving of motion designator, both inference missing properties or insert standard values. The difference is that the grounding returns another action designator instead of a dictionary and that while inferencing the properties the grounding method assigns a function which is executed when the designator is performed.
+You can see an example of how to ground an action designator below.
+<code>
+from pycram.action_designator import ActionDesignator, MoveTorsoActionDescription
+MoveTorsoActoinDescription(position=[1, 1, 0]).ground()</code>
+As you can see, the grounding method is part of the description.
+The grounding method will also be called when performing an action designator before executing the actual behaviour of the designator.