Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
Next revisionBoth sides next revision
doc:pycram:designator [2021/06/11 10:16] – [Designator] jdechdoc:pycram:designator [2021/06/18 09:08] – [Action Designator] 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.  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.  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. 
  
 The convention for naming descriptions is: the type of this description, followed by the type of designator it is meant for and lastly the word 'description'. The convention for naming descriptions is: the type of this description, followed by the type of designator it is meant for and lastly the word 'description'.
  
-Before the described movement of a designator can be executed all parameter have to be present. Because not all parameter have to be provided, missing ones have to be inferred. This is done by 'resolving' a designator, this calls the grounding method of the description which then interferes the missing parameter or inserts standard values.   +=== Perform a desigantor ===
 Motion and action designator both have a perform method which executes the behaviour the designator describes. The perform method can be simply called on every initialized designator like you can see in the following example.  Motion and action designator both have a perform method which executes the behaviour the designator describes. The perform method can be simply called on every initialized designator like you can see in the following example. 
 <code>MotionDesignator(MoveMotionDescription(target=[1,1,0], orientation=[0, 0, 0, 1])).perform()</code> <code>MotionDesignator(MoveMotionDescription(target=[1,1,0], orientation=[0, 0, 0, 1])).perform()</code>
 +
 +The perform method works different for every type of designator, for more information on how the respective method works please look at the other sections. 
 +
 +=== Resolving ===
 +
 +Before the described movement of a designator can be executed all properties have to be present. Because not all properties have to be provided, missing ones have to be inferred. This is done by 'resolving' a designator, this calls the grounding method of the description which then interferes the missing properties or inserts standard values.  
 +
 +This can be done by calling the 'reference' method of a designator. 
 +<code>
 +desig = MotionDesignator(MoveMotionDescription(target=[1,1,0]))
 +solution = desig.reference()</code>
 +
 +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. 
  
  
Line 34: Line 51:
 from pycram.process_module import with_real_robot from pycram.process_module import with_real_robot
  
-@with_simulated_robot+@with_real_robot
 def plan_a(): def plan_a():
     MotionDesignator(MoveMotionDescription(target=[1,1,0], orientation=[0, 0, 0, 1])).perform()     MotionDesignator(MoveMotionDescription(target=[1,1,0], orientation=[0, 0, 0, 1])).perform()
Line 74: Line 91:
     * WorldStateDetectingMotionDescription     * 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.  
 + 
 + 
 +=== Typing ===
  
 For every parameter in the description there is a type hint which allows to check the types of passed parameter. This check is done at the end of grounding the description by calling the '_check_properties' method. This method checks if there are missing properties and if the present properties have the right type. If on of these checks fail a ResolutionError is raised which shows the missing properties along with the ones which have the wrong type and the right type, according to the type hints in the description.  For every parameter in the description there is a type hint which allows to check the types of passed parameter. This check is done at the end of grounding the description by calling the '_check_properties' method. This method checks if there are missing properties and if the present properties have the right type. If on of these checks fail a ResolutionError is raised which shows the missing properties along with the ones which have the wrong type and the right type, according to the type hints in the description. 
 +
 +=== Perform ===
  
 Because motion designator are the lowest description of a movement the perform method of a motion designator calls the corresponding process module to perform the described motion. This works by calling a resolver method which checks the available process modules and returns the one that corresponds to the type of description. For more information on how process modules work please check [[process_modules]]. Because motion designator are the lowest description of a movement the perform method of a motion designator calls the corresponding process module to perform the described motion. This works by calling a resolver method which checks the available process modules and returns the one that corresponds to the type of description. For more information on how process modules work please check [[process_modules]].
Line 83: Line 105:
  
 ===== Action Designator ===== ===== 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.  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.