Create a list of tutorials and add the first one

doc/source/example/tutorials/asv_homing_grid.py

+import matplotlib.pyplot as plt
+import pandas as pd
+import numpy as np
+import pkg_resources
+from navipy.database import DataBaseLoad
+from navipy.processing.pcode import apcv
+from navipy.moving.agent import GridAgent
+from navipy.sensors import Senses
+
+# 1) Connect to the database
+mydb_filename = pkg_resources.resource_filename(
+    'navipy', 'resources/database.db')
+mydb = DataBaseLoad(mydb_filename)
+mysenses = Senses(renderer=mydb)
+# 2) Define the position-orinetation at which
+# we want the image
+posorient = mydb.posorients.loc[12, :]
+mysenses.update(posorient)
+memory = apcv(mysenses.vision.scene,
+              mysenses.vision.viewing_directions)
+
+
+# Create a grid agent
+my_agent = GridAgent(mydb_filename)
+
+# init position
+rowid = 1
+initpos = mydb.posorients.loc[rowid]
+my_agent.posorient = initpos
+
+# Mode of motion
+mode_of_motion = dict()
+mode_of_motion['mode'] = 'on_cubic_grid'
+mode_of_motion['param'] = dict()
+mode_of_motion['param']['grid_spacing'] = 1
+my_agent.mode_of_motion = mode_of_motion
+
+# Define a motion function
+
+
+def asv_homing(posorient_vel, senses, memory):
+    asv = apcv(senses.vision.scene,
+               senses.vision.viewing_directions)
+    homing_vector = memory - asv
+    homing_vector = np.squeeze(homing_vector[..., 0, :])
+    velocity = pd.Series(data=0,
+                         index=['dx', 'dy', 'dz',
+                                'dalpha_0', 'dalpha_1', 'dalpha_2'])
+    velocity[['dx', 'dy', 'dz']] = homing_vector
+    return velocity
+
+
+my_agent.motion = asv_homing
+my_agent.motion_param = {'memory': memory}
+# Run
+max_nstep = 100
+trajectory = my_agent.fly(max_nstep, return_tra=True)
+
+# Plot
+f, axarr = plt.subplots(2, 1, figsize=(15, 4))
+trajectory.loc[:, ['x', 'y', 'z']].plot(ax=axarr[0])
+trajectory.loc[:, ['dx', 'dy', 'dz']].plot(ax=axarr[1])
+f.show()

doc/source/tutorials.rst

+Tutorials
+=========
+
+Average skyline vector homing
+-----------------------------
+Homing with an average skyline vector consist of deriving the skyline \
+or an approximation of it from the visual information. For example, \
+ultra violet light is mostly present in the sky, and thus by summing \
+ultra violet light along the elevation one may obtain the skyline. \
+This approximation was inspired by the visual system of insect and has \
+been succesffuly applied to model of homing (Basten and mallott), and robots (Thomas Stone). \
+
+Once the skyline have been optained, the center of mass of it is calcualted. \
+The center of mass of the skyline is a vector lying in the equatorial \
+plane of the visual system (due to the sumation along the elevation). \
+The center of mass of the skyline was succeffully applied in simulation \
+and robots (Hafner, Mangan).
+
+The center of mass of the skyline, also refered as average skyline \
+vector, at the goal and current location are compared by simple difference. \
+The difference gives the homing vector, i.e. a vector proportional to \
+the velocity of the agent.
+
+On a grid
+~~~~~~~~~
+By restricting the agent motion on a grid, we can used a database containing \
+images rendered at pre defined location (the grid nodes).
+
+.. literalinclude:: example/tutorials/asv_homing_grid.py
+   :lines: 13
+
+And initialise the senses of our virtual agent
+
+.. literalinclude:: example/tutorials/asv_homing_grid.py
+   :lines: 14
+
+The agent should calculate the average skyline location at its home location \
+i.e. the goal location during the homing task.
+
+.. literalinclude:: example/tutorials/asv_homing_grid.py
+   :lines: 17-19
+
+Our agent should have a method to calculate its velocity from the \
+current sensory information to reach its home location. The ASV homing \
+model is the method, and can be defined as follow:
+
+.. literalinclude:: example/tutorials/asv_homing_grid.py
+   :lines: 41-50
+
+Now we have to initialise an agent moving on a grid (i.e. a GridAgent)
+
+.. literalinclude:: example/tutorials/asv_homing_grid.py
+   :lines: 24
+
+at an initial position
+
+.. literalinclude:: example/tutorials/asv_homing_grid.py
+   :lines: 27-29
+
+a mode of motion corresponding to the grid used in the database
+
+.. literalinclude:: example/tutorials/asv_homing_grid.py
+   :lines: 32-36
+
+and the function to calculate the velocity, i.e. the motion of the agent
+
+.. literalinclude:: example/tutorials/asv_homing_grid.py
+   :lines: 53-54
+
+Note that the position orientation and derivative (posorient_vel) is not \
+used by the function, but is required by the GridAgent.
+
+Finally our agent is ready to fly for number of step or until its velocity is null.
+
+.. literalinclude:: example/tutorials/asv_homing_grid.py
+   :lines: 56-57
+
+In close loop
+~~~~~~~~~~~~~
+
+Catchment area of ASV
+---------------------
+
+Comparing modalities
+--------------------
+
+Comparing models
+----------------