Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
doc:pycram:designator [2021/06/10 10:52] – jdech | doc:pycram:designator [2021/07/30 12:01] (current) – jdech | ||
---|---|---|---|
Line 2: | Line 2: | ||
Designators are CRAMs and PyCRAMs way of representing actions, motions, objects and locations. However at the moment only action and motion designator are implemented in PyCRAM. | Designators are CRAMs and PyCRAMs way of representing actions, motions, objects and locations. However at the moment only action and motion designator are implemented in PyCRAM. | ||
- | Designators, | + | Designators, |
- | < | + | < |
+ | from pycram.motion_designator import MotionDesignator, | ||
+ | |||
+ | MotionDesignator(MoveMotionDescription(target=[1, | ||
This motion desigantor holds a description of type MoveMotionDescription meaning it describes moving the robot around. The parameter or properties are ' | This motion desigantor holds a description of type MoveMotionDescription meaning it describes moving the robot around. The parameter or properties are ' | ||
The convention for naming descriptions is: the type of this description, | The convention for naming descriptions is: the type of this 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 ' | + | === Perform |
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. | ||
< | < | ||
+ | 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 ' | ||
+ | |||
+ | This can be done by calling the ' | ||
+ | < | ||
+ | desig = MotionDesignator(MoveMotionDescription(target=[1, | ||
+ | solution = desig.reference()</ | ||
+ | |||
+ | 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. | ||
+ | < | ||
+ | MotionDesignar.resolver[' | ||
+ | </ | ||
+ | In this case the resolver is called ' | ||
+ | |||
+ | ==== Real and Simulated robot ==== | ||
+ | Because the target of a designator can be either a real or a simulated robot, there needs to be a way to differentiate between the two targets. | ||
+ | This can be done in two ways which will be both explained in the following paragraphs. | ||
+ | |||
+ | === Decorator === | ||
+ | The first one is to use a decorator, decorator are python syntax to annotate functions to execute code before and after the function is executed. In this case the decorator manages the ' | ||
+ | The decorator can be imported from the process_module.py file. There are two available decorator ' | ||
+ | < | ||
+ | from pycram.process_module import with_simulated_robot | ||
+ | |||
+ | @with_simulated_robot | ||
+ | def plan_a(): | ||
+ | MotionDesignator(MoveMotionDescription(target=[1, | ||
+ | </ | ||
+ | This will execute the motion designator on a simulated robot in the Bullet World. | ||
+ | |||
+ | < | ||
+ | from pycram.process_module import with_real_robot | ||
+ | |||
+ | @with_real_robot | ||
+ | def plan_a(): | ||
+ | MotionDesignator(MoveMotionDescription(target=[1, | ||
+ | </ | ||
+ | This will execute the motion designator on the real robot. | ||
+ | |||
+ | |||
+ | === With Statement === | ||
+ | The second way is using the python ' | ||
+ | The statement can be imported, like the decorator, from the process_module file. | ||
+ | An example on how to use this method can be seen below. | ||
+ | < | ||
+ | from pycram.process_module import simulated_robot | ||
+ | |||
+ | with simulated_robot: | ||
+ | MotionDesignator(MoveMotionDescription(target=[1, | ||
+ | </ | ||
+ | This will execute the motion designator on the simulated robot. | ||
+ | |||
+ | < | ||
+ | from pycram.process_module import real_robot | ||
+ | |||
+ | with real_robot: | ||
+ | MotionDesignator(MoveMotionDescription(target=[1, | ||
+ | </ | ||
+ | This will execute the designator on the real robot. | ||
===== Motion Designator ===== | ===== Motion Designator ===== | ||
Line 29: | Line 98: | ||
* 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 ' | 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 ' | ||
+ | |||
+ | === 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 38: | Line 112: | ||
===== Action Designator ===== | ===== Action Designator ===== | ||
- | Action designator are a high level representation of movements which compose different motion designator. | + | Action designator are a high level representation of movements which compose different motion designator. |
+ | |||
+ | The currently available action designator descriptions are: | ||
+ | * MoveTorsoActionDescription | ||
+ | * SetGripperActionDescription | ||
+ | * ReleaseActionDescription | ||
+ | * GripActionDescription | ||
+ | * MoveArmsIntoConfigurationDescription | ||
+ | * MoveArmsInSequenceDescription | ||
+ | * ParkArmsDescription | ||
+ | * PickUpDescription | ||
+ | * PlaceDescription | ||
+ | * NavigateDescription | ||
+ | * TransportObjectDescription | ||
+ | * LookAtDescription | ||
+ | * DetectActionDescription | ||
+ | * OpenActionDescription | ||
+ | * CloseActionDescription | ||
- | Action designator work much like motion designator | + | === Perform === |
+ | Like motion designator, action | ||
- | 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 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. | ||
+ | < | ||
+ | from pycram.action_designator import ActionDesignator, | ||
+ | |||
+ | ActionDesignator(MoveTorsoActionDesignator(position=[1, | ||
+ | |||
+ | 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. | ||
+ | |||
+ | < | ||
+ | from pycram.action_designator import ActionDesignator, | ||
+ | |||
+ | MoveTorsoActoinDescription(position=[1, | ||
+ | |||
+ | 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. |