Hands On with the Time Space Map

From OpenCog
Jump to: navigation, search

About

Time Space Map allows efficiently representing objects in a spatial map and some number of past spatial maps, so that opencog can access and process such data with a good compute performance. This kind of storage is a kind of probabilistic point cloud information over a period of time. We use octomap library and add a time buffer with relationship and access query functions exposed for programmers to store and process such data. this hans on assumes you have basic understanding of how to use cogserver from command line and are familiar with some basics of opencog along familiarity with scheme (guile) [Note: Working demo can be seen in ros-behavior-scripting git repository in file "src/time-map.scm"]

Hands On

Enter the 'build' directory.. (note that the build directory might be in ~/opencog/opencog/ - this depends on the directory structure of your install)

1. Start the cogserver with telnet port 17001:

build$ ./opencog/cogserver/server/cogserver

2. telnet to cogserver from command line:

build$ rlwrap telnet localhost 17001

Note: rlwrap allows you to use arrow keys and for history to be maintained

3. To enter scheme (the guile shell) on the opencog> prompt type "scm" to get into guile shell

opencog> scm

4. on guile prompt type:

   (use-modules (opencog) (opencog atom-types)(opencog ato pointmem))

5. we now first create a map with name "faces" - This creates an opencog space-time map, for storing locations of faces. This map will be udates every 66 millisdeconds (about 15 Hz), and will buffer 150 frames (about 10 seconds), and work with a one centimeter resolution (the native coords of the map are meters).

  (create-map "faces" 0.01 66 150)

this should return true #t

6. we can now either step time units automatically or manually. For this hands on we will do it manually, but automatic time stepping is possible too For automatic time step Do Not run the command '(auto-step-time-on "faces")' for this hands on tutorial

  ; Run the map in a new thread. This will automtically create a new time-slice every 66 milliseconds.
  ;(auto-step-time-on "faces")

Manual time step is done by typing:

  (step-time-unit "faces")

Manual time step has to be done each time we need to create a map for a new discrete time unit

7. We now add an atom at a point in map by:

  (map-ato "faces" (NumberNode 10) 1.0 1.0 1.0)
  ;function map-ato takes map name, atom, x,y,z

this should return true #t

8. To query the atom we have several functions like

  (get-locs-ato "faces" (NumberNode 10))

The output of the above command should be:

(SetLink
   (AtLocationLink
      (ObjectNode "faces")
      (ListLink
         (NumberNode "10.000000")
         (ListLink
            (NumberNode "1.005000")
            (NumberNode "1.005000")
            (NumberNode "1.005000")
         )
      )
   )
)

or try this command:

   (get-elapse-list-ato "faces" (NumberNode 10))

The output of the above command should be:

(SetLink
   (AtTimeLink
      (TimeNode "2017-02-01 16:08:19 352")
      (NumberNode "10.000000")
   )
)

Of course the time node will not have the same datetime as specified above

9. To add an observation after the first time slot of 66 milliseconds elapses, we time step again. [We chose manual time step so that we can observe how the system works under auto time step for each time step]. First we time step the map: [This should not be done when auto time step is on]

   (step-time-unit "faces") 

Then we add a new observation like:

   (map-ato "faces" (NumberNode 10) 2.0 1.0 1.0)

this should return true #t

Now we observe the location of current atom

   (get-locs-ato "faces" (NumberNode 10))

The output of the above command should be:

(SetLink
   (AtLocationLink
      (ObjectNode "faces")
      (ListLink
         (NumberNode "10.000000")
         (ListLink
            (NumberNode "2.005000")
            (NumberNode "1.005000")
            (NumberNode "1.005000")
         )
      )
   )
)

To Observe previous slot, function get-past-locs-ato takes map-name, match-atom, milli-seconds of past from current unit.

   (get-past-locs-ato "faces" (NumberNode 10) 10)

The output of the above command should be:

(SetLink
   (AtLocationLink
      (ObjectNode "faces")
      (ListLink
         (NumberNode "10.000000")
         (ListLink
            (NumberNode "1.005000")
            (NumberNode "1.005000")
            (NumberNode "1.005000")
         )
      )
   )
)

10. To do spacial query, we add observer point (NumberNode 1) and reference point (NumberNode 5)

    (map-ato "faces" (NumberNode 1) 0.1 0 0)
    (map-ato "faces" (NumberNode 5) 0.2 -1.0 -0.1)

both these commands should return true #t Now we query (distance b/w observer and reference of current observation time get-dist-ato takes map-name,atom1,atom2,past time from current unit in milli-seconds)

    (get-dist-ato "faces" (Number 1) (Number 5) 0)

The output of the above command should be:

1.0109896142725172

Query angular nearness (get-angular-nearness observer,target,reference,time in past in milli-seconds)

    (get-angular-nearness-ato "faces" (Number 1) (Number 10) (Number 5) 0)

Output:

2

The return values mean: 2 = far, 1 = near, 0 = touching

Query right-left of

    (get-right-left-of-ato "faces" (Number 1) (Number 10) (Number 5) 0)
2

The return values mean: 2 = right, 1 = left, 0 = aligned


11. To remove an atom we have the following atom at a past location

   (get-past-locs-ato "faces" (NumberNode 10) 10)

Output:

(SetLink
   (AtLocationLink
      (ObjectNode "faces")
      (ListLink
         (NumberNode "10.000000")
         (ListLink
            (NumberNode "1.005000")
            (NumberNode "1.005000")
            (NumberNode "1.005000")
         )
      )
   )
)

We remove it by

    (remove-past-ato "faces" (Number 10) 10)

Now checking again

    (get-past-locs-ato "faces" (NumberNode 10) 10)
(SetLink
)

For removing atom in current time slot:

    (remove-curr-ato "faces" (Number 10))

To exit:

  • If at the guile prompt, then type dot '.' and [enter]
  • At the cogserver (prompt: opencog>) type at the telnet client:
 shutdown


Note: there are a lot more functions that are not covered here. They can be found in the file (path depends on your installation):

 ~/opencog/opencog/opencog/timeoctomap/pointmemory/PointMemorySCM.cc 

The documentation for each function will exist here: Visual Perception Buffer Scheme Functions.
These are the functions (as of 2017-02-06):

create-map, get-time-res, get-space-res, get-time-units, step-time-unit, auto-step-time-on, auto-step-time-off, is-auto-step-on, map-ato, get-first-ato, get-last-ato, get-first-locs-ato, get-last-locs-ato, get-at-loc-ato, get-past-loc-ato, get-locs-ato, et-past-locs-ato, get-elapse-list-at-loc-ato, get-elapse-list-ato, remove-location-ato, remove-past-location-ato, remove-curr-ato, remove-past-ato, remove-all-ato

spatial query functions:

get-dist-ato, get-angular-nearness-ato, get-right-left-of-ato, get-above-below-of-ato

Info

Project Owner: Mandeep

Priority: High

For some reason I needed a reinstall of opencog (with removal of old files) to get telnet to work

Tested by Adam Ford Adam (talk) 06:16, 6 February 2017 (UTC)