Restructure doc as overview, tutorials, references

doc/source/brain.rst

-Brain
-=====
-
-.. automodule:: navipy

doc/source/comparing.rst

-Comparing
-=========
-
-.. automodule:: navipy.comparing
-
-Place code
-----------
-		  
-Image diff
-~~~~~~~~~~
-.. autofunction:: navipy.comparing.simple_imagediff
-
-Euclidian image diff
-~~~~~~~~~~~~~~~~~~~~
-.. autofunction:: navipy.comparing.imagediff
-
-Rotational image difference function
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.. autofunction:: navipy.comparing.rot_imagediff
-
-Differential optic flow
-~~~~~~~~~~~~~~~~~~~~~~~
-.. autofunction:: navipy.comparing.diff_optic_flow
-
-
-Memory in networks
-------------------

doc/source/example/moving/multi_agent.py

-"""
-An example of how to use Multi agent
-"""

doc/source/index.rst

@@ -23,13 +23,9 @@ Content
    :maxdepth: 1
 	      
    gettingstarted
-   brain
-   rendering
-   processing
-   comparing
-   moving
-   database
-   tutorials
+   overview/index
+   tutorials/index
+   references/index
 
 
 Indices and tables

doc/source/moving.rst

-Moving
-######
-
-Overview
-********
-.. automodule:: navipy.moving
-
-Close-loop agent
-****************
-
-Online rendering
-================
-.. autoclass:: navipy.moving.agent.CyberBeeAgent
-    :members:
-
-Pre-rendered
-============
-.. autoclass:: navipy.moving.agent.GridAgent
-    :members:
-
-Graph agent
-***********
-.. autoclass:: navipy.moving.agent.GraphAgent
-    :members:
-
-Summary
-*******
-.. automodule:: navipy.moving.agent

doc/source/overview/brain.rst

+Brain
+=====
+
+Every agent comes with a brain processing the about of \
+senses or sensors for biological or technical agent, respectively.
+
+The senses of agents in navipy are limited
+to:
+
+* 4d vision (brighness + depth)
+
+The 4d vision sense is controlled by rendering module, either an \
+online rendering or loaded from a database containing pre-rendered images.
+
+For example to use pre-rendered images from a database:
+
+.. literalinclude:: examples/apcv.py
+   :lines: 10-11
+
+Then the brain can be updated at a new position orientation:
+
+.. literalinclude:: examples/apcv.py
+   :lines: 15
+
+Building your own brain
+-----------------------
+
+The Brain class is an abstract Brain, such that it can not control an agent. \
+To control, an agent, the Brain should have a function called velocity.
+
+For example, an stationary agent should always return a null velocity.
+
+.. literalinclude:: examples/static_brain.py
+   :lines: 3,9-17
+
+An agent using an average skyline homing vector, could be build as follow
+
+.. literalinclude:: examples/asv_brain.py
+   :lines: 4-5,11-36
+
+

doc/source/overview/comparing.rst

+Comparing
+=========
+
+
+Rotational image difference function
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    .. literalinclude:: examples/ridf.py
+       :lines: 4,20
+
+    .. plot:: overview/examples/ridf.py

doc/source/overview/database.rst

+Database
+========
+
+Database are generated by the rendering module, and contains all \
+images and there corresponding position-orientations.
+
+* position_orientation: containing all position and orientation of where \
+images were rendered. The position-orientation is described by \
+['x','y','z','alpha_0','alpha_1','alpha_2']
+* image: containing all images ever rendered. Each channel of each image \
+are normalised, so to use the full coding range.
+* normalisation: the normalisation constantes
+
+
+How to load a database
+----------------------
+
+.. literalinclude:: examples/get_posorients.py
+      :lines: 8
+
+How to load all position-orientation
+------------------------------------
+
+The database contains all position-orientation \
+at which an image as been rendered. In certain \
+situation, it may be usefull to know all \
+position-orientation in the database. More technically \
+speaking, loading the full table of position-orientaiton.
+
+.. literalinclude:: examples/get_posorients.py
+      :lines: 9-10
+
+.. plot:: overview/examples/get_posorients.py
+
+How to load an image
+--------------------
+
+The database contains images which can be processed differently \
+depending on the navigation strategy beeing used.
+
+Images are at given position-orientations. To load an image \
+the position-orientation can be given. The DataBaseLoader will \
+look if this position-orientation has been rendered. If it is \
+the case, the image will be returned.
+
+.. literalinclude:: examples/load_image_posorient.py
+      :lines: 14-23
+
+.. plot:: overview/examples/load_image_posorient.py
+
+However, looking in the database if an image has already been \
+rendered at a given position-orientation can cost time. To speed up \
+certain calculation, image can instead be access by row number. \
+Indeed each position-orientation can be identified by a unique row \
+number. This number is consistant through the entire database. Thus, \
+an image can be loaded by providing the row number.
+
+.. literalinclude:: examples/load_image_rowid.py
+      :lines: 13-15
+
+.. plot:: overview/examples/load_image_rowid.py
+
+
+.. todo: channels as part of database

doc/source/example/processing/apcv.py → doc/source/overview/examples/apcv.py

 import matplotlib.pyplot as plt
 from navipy.database import DataBaseLoad
-import navipy.processing as processing
+from navipy.processing import pcode
+from navipy.processing import tools
+from navipy.processing import constants
 from navipy import Brain
 import pkg_resources
 
@@ -13,17 +15,17 @@ mybrain = Brain(renderer=mydb)
 # we want the image
 posorient = mydb.posorients.loc[12, :]
 mybrain.update(posorient)
-my_apcv = processing.pcode.apcv(mybrain.vision.scene,
-                                mybrain.vision.viewing_directions)
+my_apcv = pcode.apcv(mybrain.vision.scene,
+                     mybrain.vision.viewing_directions)
 
-my_apcv_sph = processing.tools.cartesian_to_spherical(x=my_apcv[..., 0],
-                                                      y=my_apcv[..., 1],
-                                                      z=my_apcv[..., 2])
+my_apcv_sph = tools.cartesian_to_spherical(x=my_apcv[..., 0],
+                                           y=my_apcv[..., 1],
+                                           z=my_apcv[..., 2])
 elevation = mydb.viewing_directions[...,
-                                    processing.constants.__spherical_indeces__[
+                                    constants.__spherical_indeces__[
                                         'elevation']]
 azimuth = mydb.viewing_directions[...,
-                                  processing.constants.__spherical_indeces__[
+                                  constants.__spherical_indeces__[
                                       'azimuth']]
 
 

doc/source/example/processing/pcv.py → doc/source/overview/examples/pcv.py

 # import matplotlib.pyplot as plt
 from navipy.database import DataBaseLoad
-import navipy.processing as processing
+from navipy.processing import pcode
 from navipy import Brain
 import pkg_resources
 
@@ -13,5 +13,5 @@ mybrain = Brain(renderer=mydb)
 # we want the image
 posorient = mydb.posorients.loc[12, :]
 mybrain.update(posorient)
-my_pcv = processing.pcode.pcv(mybrain.vision.scene,
-                              mybrain.vision.viewing_directions)
+my_pcv = pcode.pcv(mybrain.vision.scene,
+                   mybrain.vision.viewing_directions)