From 090816f857578c5c6dbe37c71ef28251a2d674c2 Mon Sep 17 00:00:00 2001
From: "Olivier J.N. Bertrand" <olivier.bertrand@uni-bielefeld.de>
Date: Sat, 13 Jan 2018 23:27:50 +0100
Subject: [PATCH] Update the doc for moving agent
---
doc/source/moving.rst | 16 +++++++-
navipy/moving/__init__.py | 75 +++++++++++++++++++++++++++++++++++
navipy/moving/agent.py | 83 +++++++++++++--------------------------
3 files changed, 118 insertions(+), 56 deletions(-)
diff --git a/doc/source/moving.rst b/doc/source/moving.rst
index 1163efd..cb96de9 100644
--- a/doc/source/moving.rst
+++ b/doc/source/moving.rst
@@ -1,13 +1,27 @@
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
diff --git a/navipy/moving/__init__.py b/navipy/moving/__init__.py
index e69de29..02abd04 100644
--- a/navipy/moving/__init__.py
+++ b/navipy/moving/__init__.py
@@ -0,0 +1,75 @@
+"""
+Close-loop agent
+~~~~~~~~~~~~~~~~
+A standard method to move an agent is to update:
+
+1. update the sensory information at the current agent location :math:`x`
+2. deduce the agent motion :math:`vdt` from this information
+3. displace the agent by motion ( :math:`x \rightarrow x + vdt`)
+
+The use of a close loop model including visual rendering is \
+sometimes too slow to efficiently test several models or tune the \
+parameters of a given models. The GridAgent solves this problem by \
+restricting the agent motion on locations with rendered scene. The \
+agent moves thus on a grid, and its next position is always \
+snapped to the closest grid location. The finer the grid is, the \
+larger the database storing all sceneries and grid location is; \
+but also the more accurate the agent motion is. The grid size \
+depend on the storage space, the time you can wait for the \
+database creation, and how sensitive to exact location your model is.
+
+This iterative method can be used with a wide range of models. \
+In :navipy: differents classes of agents exist. \
+They differ by the method use to update the sensory information:
+
++----------------+----------------------------------------------------+
+|Agent class |Sensory update |
++================+====================================================+
+|:CyberBeeAgent: |:Cyberbee: update within blender. |
++----------------+----------------------------------------------------+
+|:GridAgent: |:DataBaseLoad: update from a pre-rendered database. |
++----------------+----------------------------------------------------+
+
+To deduce the agent motion from the current state of the agent \
+(e.g. position, orientation, sensory information, memories, ...) all \
+classes of agents use callback function, which is a custom function \
+defined by the user. This function takes as input argument, the \
+agent position-orientation and its velocities, and the currently \
+seen scene. The function should return a the agent motion. \
+
+Once the agent sensory method and motion method have been configured, \
+the agent can:
+
+1. move (perform a one step motion), or
+2. fly (move until its velocity is null, or until n-steps).
+
+Agent on a graph
+~~~~~~~~~~~~~~~~
+As mentioned above, in every model of navigation the agent motion \
+is derived from its current external state, its position \
+orientation as well as the derivatives, and its internal state. \
+However, when the agent motion is only derived from its current \
+position orientation, and what is seen from this location, the \
+simulation of an agent can be drastically simplified. Indeed, \
+not only the scene at relevant location can be pre-rendered, but \
+the motion of the agent from those locations as well.
+
+The agent being restricted to move from relevant locations to \
+relevant locations, a graph of interconnected locations can be built.\
+The nodes of the graph are the relevant locations, and the directed \
+edges the motion of the agent from one location to the next. \
+:GraphAgent: can build such graph by simply using a database of \
+pre-rendered scenery at relevant locations, and a function \
+giving the motion of the agent from a scene and the agent \
+position orientation. Once the graph has been generated, \
+attractors can be found, the number of locations converging to \
+those (i.e. the catchment area or volume), if two locations are \
+connected, etc.
+
+To speed up certain calculations, additional values can stored \
+at each graph node and access from the callback function. It is \
+worth mentioning a warning here. The size of the graph can be \
+incredibly large. Thus, not too much information can be stored \
+at each node. To assess the memory size of the graph before \
+creating it, one can use the tool agent.tools.assess_graphmemsize.
+"""
diff --git a/navipy/moving/agent.py b/navipy/moving/agent.py
index 6b0225e..2d217c6 100644
--- a/navipy/moving/agent.py
+++ b/navipy/moving/agent.py
@@ -1,5 +1,13 @@
"""
-
++----------------+--------------+-------------+
+|Agent class |Type of agent | Rendering +
++================+==============+=============+
+|:CyberBeeAgent: |Close loop |Online |
++----------------+ |-------------+
+|:GraphAgent: | |Pre-rendered |
++----------------+--------------+ |
+|:GridAgent: +Open loop | |
++----------------+--------------+-------------+
"""
import numpy as np
import pandas as pd
@@ -100,19 +108,11 @@ class AbstractAgent():
class CyberBeeAgent(AbstractAgent):
"""
- A common method to make an agent moves is to update the sensory \
- information at the current agent location, then process this \
- information such to deduce the agent motion, and finally displaced\
- the agent at its new location. This iterative method can be used \
- with a wide range of models.
- In navipy the update of the sensory information is done by the \
- Cyberbee a class interfacing blender with the navipy, such that \
- visual information can be rendered at the agent location.
- To use the CyberBeeAgent you first need to create a function with \
- input the scene and the position orientation of the agent, and \
- with output the agent motion. The CyberBeeAgent can then be moved \
- for a single step, or fly until a given number of movement has \
- been effectuated or the agent stopped.
+ A CyberBeeAgent uses the rendering method of cyberbee. \
+CyberBeeAgent is a close loop agent and need to be run within blender \
+(see :doc:`rendering`).
+
+ bla
"""
def __init__(self, cyberbee):
@@ -133,22 +133,15 @@ class CyberBeeAgent(AbstractAgent):
class GridAgent(AbstractAgent, Process):
"""
- The use of a close loop model including visual rendering is \
- sometimes too slow to efficiently test several models or tune the \
- parameters of a given models. The GridAgent solves this problem by \
- restricting the agent motion on locations with rendered scene. The \
- agent moves thus on a grid, and its next position is always \
- snapped to the closest grid location. The finer the grid is, the \
- larger the database storing all sceneries and grid location is; \
- but also the more accurate the agent motion is. The grid size \
- depend on the storage space, the time you can wait for the \
- database creation, and how sensitive to exact location your model is.
- Similar to the CyberBeeAgent, your navigational model should be \
- contained in a function with input the scene and the position \
- orientation of the agent, and with output the agent motion. The \
- agent can be move a single step, or fly until a given number of \
- movement has been effectuated or the agent stopped. It is here \
- worth mentioning that the GridAgent inherit from the Process \
+ A GridAgent fetches the scene from a pre-rendered database. \
+(see :doc:`database`)
+GridAgent is a close loop agent here its position is snap to a grid.
+
+ Single process
+ Here come example of how to use it
+
+ Multi process
+ GridAgent inherit from the Process \
class of the multiprocessing module of the standard python \
library. Thus, several GridAgents can safely be run in parallel.
"""
@@ -257,31 +250,11 @@ class GridAgent(AbstractAgent, Process):
class GraphAgent():
"""
- As mentioned above, in every model of navigation the agent motion \
- is derived from its current external state, its position \
- orientation as well as the derivatives, and its internal state. \
- However, when the agent motion is only derived from its current \
- position orientation, and what is seen from this location, the \
- simulation of an agent can be drastically simplified. Indeed, \
- not only the scene at relevant location can be pre-rendered, but \
- the motion of the agent from those locations as well. The agent \
- being restricted to move from relevant locations to relevant \
- locations, a graph of interconnected locations can be built. The \
- nodes of the graph are the relevant locations, and the directed \
- edges the motion of the agent from one location to the next. \
- GraphAgent can build such graph by simply using a database of \
- pre-rendered scenery at relevant locations, and a function \
- giving the motion of the agent from a scene and the agent \
- position orientation. Once the graph has been generated, \
- attractors can be found, the number of locations converging to \
- those (i.e. the catchment area or volume), if two locations are \
- connected, etc.
- To speed up certain calculations, additional values can stored \
- at each graph node and access from the callback function. It is \
- worth mentioning a warning here. The size of the graph can be \
- incredibly large. Thus, not too much information can be stored \
- at each node. To assess the memory size of the graph before \
- creating it, one can use the tool agent.tools.assess_graphmemsize.
+ A GraphAgent uses, to build a graph,
+
+1. pre-rendered scene from a database to derive \
+the agent motion, or
+2. pre-computed agent-motion
"""
def __init__(self, database_filename):
--
GitLab