update docs

doc/source/processing.rst

@@ -2,32 +2,3 @@ Processing a scene
 ==================
 
 .. automodule:: navipy.processing
-
-Place code
-----------
-		  
-Skyline
-~~~~~~~
-.. autofunction:: navipy.processing.pcode.skyline
-
-Michelson-contrast
-~~~~~~~~~~~~~~~~~~
-.. autofunction:: navipy.processing.pcode.michelson_contrast
-
-Contrast-weighted-nearness
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-.. autofunction:: navipy.processing.pcode.contrast_weighted_nearness
-
-Place-code vectors
-~~~~~~~~~~~~~~~~~~
-.. autofunction:: navipy.processing.pcode.pcv
-
-Average place-code vector
-~~~~~~~~~~~~~~~~~~~~~~~~~
-.. autofunction:: navipy.processing.pcode.apcv
-
-Motion code
------------
-Optic flow
-~~~~~~~~~~
-.. autofunction:: navipy.processing.mcode.optic_flow

navipy/processing/__init__.py

 """
-The scene processing part of the toolbox defines methodes
-to transform an image into a place code in the sense
-of Basten and Mallot (2010).
-
-The scene is either
-
-* a 4d numpy array, used when the image is a equirectangular \
-projection, i.e. a panoramic image.
-* a 3d numpy array, used when the viewing direction can not \
-be mapped/projected on a regular image (e.g. insect eye).
-
-We thus define the following for a scene:
+An agent comes equipped with a battery of sensors, such as a camera \
+depth estimation sensors, compass, and odometer. Here, we focus on the \
+the processing of retino-topic information provided by a camera and a \
+depth estimation sensor. This retino-topic information is refer as a scene.
 
 image based scene (IBS)
   A classical image. Each pixel is viewed in a direction
@@ -24,6 +16,11 @@ Omatidium based scene (OBS)
   In that case the scene is a 3d numpy array
   [ommatidia-index, channel-index,1].
 
+Place code
+----------
+Processing a scene yield to a certain encoding of information at the location \
+where the scene was acquired, rendered, seen by the agent.
+
 By extension a place-code is either image based or ommatidium based.
 The number of dimension of an ib-place-code is always 4, and of an
 ob-place-code always 3.
@@ -43,4 +40,31 @@ Omatidium based place-code (OBPC)
 
 Abusing the terminology of a place-code, a scene can be a place-code.
 Therefore ibs and obs have 4 and 3 dimension, respectively.
+
+Skyline
+~~~~~~~
+.. autofunction:: navipy.processing.pcode.skyline
+
+Michelson-contrast
+~~~~~~~~~~~~~~~~~~
+.. autofunction:: navipy.processing.pcode.michelson_contrast
+
+Contrast-weighted-nearness
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. autofunction:: navipy.processing.pcode.contrast_weighted_nearness
+
+Place-code vectors
+~~~~~~~~~~~~~~~~~~
+.. autofunction:: navipy.processing.pcode.pcv
+
+Average place-code vector
+~~~~~~~~~~~~~~~~~~~~~~~~~
+.. autofunction:: navipy.processing.pcode.apcv
+
+Motion code
+-----------
+Optic flow
+~~~~~~~~~~
+.. autofunction:: navipy.processing.mcode.optic_flow
+
 """

navipy/processing/pcode.py

@@ -15,12 +15,13 @@ from .tools import check_viewing_direction
 
 def skyline(scene):
     """Return the average along the elevation of a scene
+
     :param scene: the scenery at a given location (a 4d numpy array)
     :returns: the skyline [1,azimuth,channel,1]
     :rtype: np.ndarray
 
     .. literalinclude:: example/processing/skyline.py
-       :lines: 12-14
+       :lines: 16
 
     .. plot:: example/processing/skyline.py
 
@@ -49,7 +50,7 @@ and minimum of the local image intensity
     :rtype: np.ndarray
 
     .. literalinclude:: example/processing/michelson_contrast.py
-       :lines: 12-14
+       :lines: 16
 
     .. plot:: example/processing/michelson_contrast.py
 
@@ -88,7 +89,7 @@ and minimum of the local image intensity in the michelson-contrast.
     :param distance_channel: the index of the distance-channel.
 
     .. literalinclude:: example/processing/contrast_weighted_nearness.py
-       :lines: 13-15
+       :lines: 17-18
 
     .. plot:: example/processing/contrast_weighted_nearness.py
 
@@ -121,7 +122,7 @@ def pcv(place_code, viewing_directions):
     :rtype: (np.ndarray)
 
     .. literalinclude:: example/processing/pcv.py
-       :lines: 13-15
+       :lines: 16-17
 
     .. plot:: example/processing/pcv.py
 
@@ -171,7 +172,7 @@ def apcv(place_code, viewing_directions):
     :rtype: (np.ndarray)
 
     .. literalinclude:: example/processing/apcv.py
-       :lines: 13-15
+       :lines: 16-17
 
     .. plot:: example/processing/apcv.py