Differences

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

Link to this comparison view

Next revision		Previous revision
doc:package:cram_designators [2013/12/12 14:57] – created gkazhoyadoc:package:cram_designators [2021/05/02 20:57] (current) – gkazhoya
Line 1: Line 1:
-<<PackageHeader(cram_designators)>> +**Disclaimer: this page is outdated, so some code might not run. See the Tutorials page for more up to date code.** 
-<<TOC(4)>>+ 
 +====== cram_designators ======
  
 == Introduction == == Introduction ==
Line 38: Line 39:
  * ''reference designator &optional role'' tries to dereference the designator and return its data object or throws an error if it is not an effective designator, i.e. one that can be dereferenced. By specifying a role parameter, different resolution algorithms can be selected.  * ''reference designator &optional role'' tries to dereference the designator and return its data object or throws an error if it is not an effective designator, i.e. one that can be dereferenced. By specifying a role parameter, different resolution algorithms can be selected.
  
- * ''next-solution designator'' returns another solution for the effective designator ''designator'' or NIL if none exists. The next solution is newly constructed designator with identical that is equated to ''designator'' since it describes the same entity.+ * ''next-solution designator'' returns another solution for the effective designator ''designator'' or NIL if none exists. The next solution is newly constructed designator with identical properties that is equated to ''designator'' since it describes the same entity.
  
  * ''designator-solutions-equal solution-1 solution-2'' compares two designator solutions and returns T if they are equal.  * ''designator-solutions-equal solution-1 solution-2'' compares two designator solutions and returns T if they are equal.
Line 60: Line 61:
 Object designators are a direct interface between CRAM plans and the perception subsystem used on a robot. The key-value-pairs of in the designator's properties describe the object that is to be perceived. Finding the right object based on them is a perception subsystem's task so the system does not provide any sophisticated mechanism for resolving an object designator. There is only one constraint on object designators: effective designators must bind the data object to an instance of ''object-designator-data'' or a class derived from it. Essentially, the following steps have to be implemented by the perception subsystem: Object designators are a direct interface between CRAM plans and the perception subsystem used on a robot. The key-value-pairs of in the designator's properties describe the object that is to be perceived. Finding the right object based on them is a perception subsystem's task so the system does not provide any sophisticated mechanism for resolving an object designator. There is only one constraint on object designators: effective designators must bind the data object to an instance of ''object-designator-data'' or a class derived from it. Essentially, the following steps have to be implemented by the perception subsystem:
  
-  1. Parse the designator's properties for a description of the object to be found. +  - Parse the designator's properties for a description of the object to be found. 
- +  - Find the described object. 
-  2. Find the described object. +  - Create a new effective designator with the data object bound to an instance of ''object-designator-data'' containing all relevant information about the object. 
- +  - Equate the new effective designator with the original designator.
-  3. Create a new effective designator with the data object bound to an instance of ''object-designator-data'' containing all relevant information about the object. +
- +
-  4. Equate the new effective designator with the original designator.+
  
 === Action Designators === === Action Designators ===
Line 79: Line 77:
                      (make-3d-vector 1.0 0.0 0.0)                       (make-3d-vector 1.0 0.0 0.0) 
                      (make-identity-rotation)))))))                      (make-identity-rotation)))))))
-  (make-designator 'action '((type navigation) (goal ,goal-location)))+  (make-designator 'action `((type navigation) (goal ,goal-location)))
 </code> </code>
  
Line 95: Line 93:
 The most complex designator resolution mechanism currently is the implementation of location designators. It is that complex because it requires great flexibility to implement the computation of poses such as "a location to stand for opening a drawer". Essentially, the resolution of location designators is done in two steps: The most complex designator resolution mechanism currently is the implementation of location designators. It is that complex because it requires great flexibility to implement the computation of poses such as "a location to stand for opening a drawer". Essentially, the resolution of location designators is done in two steps:
  
- 1. Generation of a lazy list of pose candidates. +  - Generation of a lazy list of pose candidates. 
- +  - Verification if a generated pose candidate is actually a solution.
- 2. Verification if a generated pose candidate is actually a solution.+
  
 That way, generation can be kept very general and filters can be applied to remove invalid solutions. When the ''reference'' method is called on a location designator, the system first executes so-called generator functions to generate the sequence of pose candidates. Generator functions are priorized, i.e. they are ordered and some must be executed before others. Each generator function must be a function that gets a location designator as input and returns the (lazy) list of possible solutions for this designator. The system then appends all lists and tries to validate one solution after the other until either a solution is valid or a maximal number of solutions has been tried. In that case, the designator cannot be resolved and an error is thrown. Validation functions are functions with two parameters, the designator that is to be resolved and the pose candidate to validate. Depending on their result a solution can either be accepted, immediately rejected or rejected if no other validation function accepts it. That way, generation can be kept very general and filters can be applied to remove invalid solutions. When the ''reference'' method is called on a location designator, the system first executes so-called generator functions to generate the sequence of pose candidates. Generator functions are priorized, i.e. they are ordered and some must be executed before others. Each generator function must be a function that gets a location designator as input and returns the (lazy) list of possible solutions for this designator. The system then appends all lists and tries to validate one solution after the other until either a solution is valid or a maximal number of solutions has been tried. In that case, the designator cannot be resolved and an error is thrown. Validation functions are functions with two parameters, the designator that is to be resolved and the pose candidate to validate. Depending on their result a solution can either be accepted, immediately rejected or rejected if no other validation function accepts it.