Differences

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

--- doc:beginner:designators [2014/10/30 12:10] – Tutorial code now placed in several files, for clarity. mpomarlan
+++ doc:beginner:designators [2015/05/11 17:00] (current) – removed gkazhoya
@@ Line 1: / Line 1: @@
-====== Creating action designators for the turtlesim ======
-**Description:** In this tutorial you will learn what designators are, and in particular, work with action designators: you will learn how to define one, and how to use it.
-**Previous Tutorial:** [[doc:beginner:simple_plans|Implementing simple plans to move a turtle]]\\
-**Next Tutorial:** [[doc:beginner:process_modules|Creating process modules]]
-===== Designators: an overview =====
-From a user's point of view, a designator is a Common Lisp object that contains a sequence of key-value pairs representing a high-level, symbolic description of some aspect of a robot's activity. The concept's power and usefulness comes from the ability to infer concrete parameters when needed, based on user-specified rules, from the context in which the robot operates and the symbolic description in the designator. This is known as 'resolving' or '[de]referencing' a designator, and it returns an object containing the newly resolved values that can then be used by the robot to specify some task.
-Currently there are three types of designators defined in CRAM:
-  * location designators: describe locations taking various constraints into account (for example, reachability, visibility etc)
-  * object designators: describe objects on a symbolic level (what they are, what they may be used for etc)
-  * action designators: describe an action that a robot should take and serve as input to process modules (covered in the [[doc:beginner:process_modules|next tutorial]])
-These types should cover most use cases in robotics, however, if needed, new designator types can be defined as subclasses of the designator class.
-As a simple example of a designator creation, suppose we want to create a designator for a location from which some object (for which we already have a designator) can be seen. We would then write
-<code lisp>
-(defparameter spy-location (make-designator 'location `((to see) (obj ,prime-minister))))
-</code>
-(do not add this code to your tutorial files, it is meant simply for illustration here.)
-This line of code creates a location designator (spy-location) which 'knows' of the given object (prime-minister, which we assume is an already defined object designator), and knows that its purpose is to see the object. We do not actually specify a location in terms of coordinates at this moment. When we do want to find a suitable set of coordinates for this location, we would call
-<code lisp>
-(reference spy-location)
-</code>
-and, assuming we have set up rules to take into account knowledge of the associated object, the environment, and the vision capabilities of the robot, we would have a process which can enumerate possible coordinates for the location that would satisfy its purpose and return these as coordinate vectors.
-For the rest of this tutorial, we will work with action designators and show a few basics of their creation and use. For a more detailed look at designators, it is recommended that you also read the [[doc:package:cram_designators|cram_designators]] page.
-===== Using action designators =====
-First, you will need to add a few more dependencies to the tutorial package files you created previously. To package.xml, add build and run dependencies on cram_reasoning and cram_designators:
-<code>
-  <build_depend>cram_reasoning</build_depend>
-  <build_depend>cram_designators</build_depend>
-  <run_depend>cram_reasoning</run_depend>
-  <run_depend>cram_designators</run_depend>
-</code>
-In your cram-beginner-tutorial.asd file, on the :depends-on line, add dependencies to designators and cram-reasoning. Let's also create a new source file for the code in this tutorial, call it action-designators.lisp, and add it to your :components of :module ''src'' in your cram-beginner-tutorial.asd file which should now look something like this:
-<code lisp>
-(defsystem cram-beginner-tutorial
-  :depends-on (roslisp cram-language turtlesim-msg cl-transforms geometry_msgs-msg designators cram-reasoning)
-  :components
-  ((:module "src"
-            :components
-            ((:file "package")
-             (:file "control-turtlesim" :depends-on  ("package"))
-             (:file "simple-plans" :depends-on  ("package" "control-turtlesim"))
-             (:file "action-designators" :depends-on  ("package"))))))
-</code>
-Finally, package.lisp needs to undergo some more drastic changes:
-<code lisp>
-(desig-props:def-desig-package cram-beginner-tutorial
-  (:nicknames :tut)
-  (:use #:cpl
-        #:roslisp
-        #:cl-transforms
-        #:cram-designators
-)
-(:desig-properties
-;;;action properties
-    #:shape
-    #:radius
-    #:triangle
-    #:square
-    #:pentagon
-    #:hexagon
-))
-</code>
-The first lines look familiar enough, but we added the cram-designators namespace to the use list, for convenience. Also, we replaced the defpackage macro on the first line with desig-properties:def-desig-package in order to prevent potential namespace conflicts between designator users. Then we defined a list of symbols that can appear as designator properties.
-Now, reload the tutorial in roslisp_repl (which also loads the newly added dependencies).
-==== Creating an action designator ====
-Let's try to create an action designator in the repl command line:
-<code lisp>
-TUT> (defparameter mydesig (make-designator 'action `((type shape) (shape triangle) (radius 3))))
-MYDESIG
-TUT> (desig-prop-value mydesig 'radius)
-</code>
-As we can see, the make-designator function simply returns a designator object with the properties we specify. We can also read those already specified property values with the desig-prop-value function. So far, so good, but the interesting thing about designators is their resolution. Let's try that in the repl command line:
-<code lisp>
-TUT> (reference mydesig)
-WARNING:
-   Trying to prove goal (ACTION-DESIG
-                         #<ACTION-DESIGNATOR
-                           ((TYPE SHAPE) (SHAPE TRIANGLE) (RADIUS 3))
-                           {100A0907B3}>
-                         ?ACT) with undefined functor ACTION-DESIG.
-; Evaluation aborted on #<CRAM-DESIGNATORS:DESIGNATOR-ERROR "Cannot resolve action designator ~a." {1007447C53}>.
-</code>
-This rather obscure error message is roslisp_repl's way of telling you there are no rules in place to resolve this designator, so let's try to provide a few such rules.
-==== Defining inference rules for designators ====
-Append the following to your action-designators.lisp file:
-<code lisp>
-(in-package :tut)
-(defstruct turtle-shape
-  "represents an object in continuous space matching a symbolic description"
-  radius
-  edges)
-  (cram-reasoning:def-fact-group shape-actions (action-desig)
-  ;; for each kind of shape, call make-turtle-shape with the right number of edges
-  ;; triangle
-  (cram-reasoning:<- (action-desig ?desig (shape ?action))
-    (desig-prop ?desig (type shape))
-    (desig-prop ?desig (shape triangle))
-    (desig-prop ?desig (radius ?radius))
-    (cram-reasoning:lisp-fun make-turtle-shape :radius ?radius :edges 3  ?action))
-  ;; square
-  (cram-reasoning:<- (action-desig ?desig (shape ?action))
-    (desig-prop ?desig (type shape))
-    (desig-prop ?desig (shape square))
-    (desig-prop ?desig (radius ?radius))
-    (cram-reasoning:lisp-fun make-turtle-shape :radius ?radius :edges 4  ?action))
-  ;; pentagon
-  (cram-reasoning:<- (action-desig ?desig (shape ?action))
-    (desig-prop ?desig (type shape))
-    (desig-prop ?desig (shape pentagon))
-    (desig-prop ?desig (radius ?radius))
-    (cram-reasoning:lisp-fun make-turtle-shape :radius ?radius :edges 5  ?action))
-  ;; hexagon
-  (cram-reasoning:<- (action-desig ?desig (shape ?action))
-    (desig-prop ?desig (type shape))
-    (desig-prop ?desig (shape hexagon))
-    (desig-prop ?desig (radius ?radius))
-    (cram-reasoning:lisp-fun make-turtle-shape :radius ?radius :edges 6  ?action)))
-</code>
-Let's see what this code does. The defstruct declares a struct type to hold values resulting from the inference. It's an instantiation of our action in a space of (possibly) continuous parameters, which we deduce from a symbolic description of the designator via rules given in the def-fact-group.
-As for the inference rules themselves, these are PROLOG code embedded in Lisp, for it is PROLOG that powers the inference behind designator resolution. The def-fact-group is a collection of several rules, each of similar structure, so it helps to look at one of them in more detail:
-<code lisp>
-  (cram-reasoning:<- (action-desig ?desig (shape ?action))
-    (desig-prop ?desig (type shape))
-    (desig-prop ?desig (shape pentagon))
-    (desig-prop ?desig (radius ?radius))
-    (cram-reasoning:lisp-fun make-turtle-shape :radius ?radius :edges 5  ?action))
-</code>
-The first parameter to cram-reasoning:<- is the "rule head"
-<code lisp>
-(action-desig ?desig (shape ?action))
-</code>
-while all other parameters comprise the "rule body"
-<code lisp>
-    (desig-prop ?desig (type shape))
-    (desig-prop ?desig (shape pentagon))
-    (desig-prop ?desig (radius ?radius))
-    (cram-reasoning:lisp-fun make-turtle-shape :radius ?radius :edges 5  ?action)
-</code>
-PROLOG's inference semantics is, in a nutshell, 'IF there is some assignment to variables such that all elements of the body are true, THEN use that assignment of variables to execute the head'. Note, for a symbol to be considered a variable, its name must begin with a '?'.
-For this example rule we've selected, PROLOG looks at the designator and asks "does it contain a key-value pair that is (type shape)?" (so no variables here except the designator itself). Assuming this is true, it then asks "does it contain a key-value pair that is (shape pentagon)?" If still true, it asks "does it contain a key-value pair that is (radius <some variable value>)?" This last question has the effect of extracting the value of the radius parameter that we created the designator with and making it available to PROLOG. Finally, it "asks" Lisp to create a turtle-shape structure with the ?radius value just discovered, and the number of edges selected via the shape parameter, and store this in ?action.
-If all of the above body rules are true (or can be executed sucessfully) then the head is itself run, and what it does is glue the newly created ?action, the object containing the concrete values, to the designator ?desig. Or in more concrete terms, it defines what the value of the action-desig predicate is if applied to ?desig, and that value is a list containing the name 'shape' and the values of ?action.
-For this tutorial, the inference is very simple: in fact, it is just a conditional switch based on the shape parameter which translates a name like 'triangle' or 'pentagon' into the corresponding number of edges.
-Reload the tutorial package in roslisp_repl. This will also load the newly defined inference rules.
-Let's try to create, then reference a designator in the repl command line again:
-<code lisp>
-TUT> (defparameter mydesig2 (make-designator 'action `((type shape) (shape triangle) (radius 5))))
-MYDESIG
-TUT> (reference mydesig2)
-(SHAPE #S(TURTLE-SHAPE :RADIUS 5 :EDGES 3))
-</code>
-No more resolution errors this time, as we have specified inference rules which allow us to have a shape object returned, which we could then pass as a parameter to a process module that will actually move the turtle along this shape.
-== Next ==
-Now that we know how to handle designators, we need to have the robot act on them in some way. CRAM process modules allow us to do just that ...
-[[doc:beginner:process_modules|Creating process modules]]