Added docs and keyboard commands

docs/source/core_api.rst

@@ -7,7 +7,7 @@ Simulator Interface
 The most powerful way to interact with fluids is to create a ``fluids.FluidSim`` object. This object creates the environment, sets up all cars, and pedestrians, and controls background objects in the scene. The initialization arguments to this object control the parameters of the generated environment
 
 .. autoclass:: fluids.FluidSim
-   :members: get_control_keys, step
+   :members: get_control_keys, step, get_observations
 
 Action Types
 ^^^^^^^^^^^^
@@ -18,6 +18,14 @@ FLUIDS supports four action types. All action types are acceptable for ``FluidSi
 .. autoclass:: fluids.actions.VelocityAction
 .. autoclass:: fluids.actions.LastValidAction
 
+Observation Types
+^^^^^^^^^^^^^^^^^
+FLUIDS supports two observation types currently, a BirdsEye observation and a Grid observation.
+
+.. autoclass:: fluids.obs.FluidsObs
+   :members: get_array
+.. autoclass:: fluids.obs.GridObservation
+.. autoclass:: fluids.obs.BirdsEyeObservation
 
 Command Line Interface
 ^^^^^^^^^^^^^^^^^^^^^^
@@ -30,12 +38,22 @@ FLUIDS also provides a command line interface for visualizing the environment ru
 Run with -h flag to see arguments
 
 ::
-   
+
    >>> python3 -m fluids -h
+   usage: __main__.py [-h] [-b N] [-c N] [-p N] [-v N] [-o str] [--state file]
+
+   FLUIDS First Order Lightweight Urban Intersection Driving Simulator
+
    optional arguments:
-   -h, --help           show this help message and exit
-   -b N                 Number of background cars
-   -c N                 Number of controlled cars
-   -p N                 Number of background pedestrians
-   -v N                 Visualization level
-   --state layout file  Layout file for state generation
+   -h, --help    show this help message and exit
+   -b N          Number of background cars
+   -c N          Number of controlled cars
+   -p N          Number of background pedestrians
+   -v N          Visualization level
+   -o str        Observation type
+   --state file  Layout file for state generation
+
+   Keyboard commands for when visualizer is running:
+    .            Increases debug visualization
+    ,            Decreases debug visualization
+    o            Switches observation type

fluids/__main__.py

@@ -2,7 +2,16 @@
 from fluids.utils import fluids_print
 import argparse
 
-parser = argparse.ArgumentParser(description='FLUIDS First Order Lightweight Urban Intersection Driving Simulator')
+key_help = """
+Keyboard commands for when visualizer is running:
+   .            Increases debug visualization
+   ,            Decreases debug visualization
+   o            Switches observation type
+"""
+
+parser = argparse.ArgumentParser(description='FLUIDS First Order Lightweight Urban Intersection Driving Simulator',
+                                 formatter_class=argparse.RawDescriptionHelpFormatter,
+                                 epilog=key_help)
 parser.add_argument('-b', metavar='N', type=int, default=10, 
                     help='Number of background cars')
 parser.add_argument('-c', metavar='N', type=int, default=1, 

fluids/obs/birds_eye.py

@@ -8,6 +8,11 @@
 from fluids.utils import rotation_array
 
 class BirdsEyeObservation(FluidsObs):
+    """
+    Bird's-eye 2D top-down image centered on the vehicle, similar to what is visualized.
+    Minor difference is that drivable regions are colorless to differentiate from illegal drivable regions.
+    Array representation is (obs_dim, obs_dim, 3).
+    """
     def __init__(self, car, obs_dim=500):
         from fluids.assets import Car, Lane, Sidewalk, Terrain, TrafficLight, Waypoint, PedCrossing, Pedestrian
         state = car.state

fluids/obs/grid.py

@@ -7,6 +7,12 @@
 from fluids.utils import rotation_array
 
 class GridObservation(FluidsObs):
+    """
+    Grid observation type. 
+    Observation is an occupancy grid over the detection region. 
+    Observation has 6 dimensions: terrain, drivable regions, illegal drivable regions, cars, pedestrians, and traffic lights.
+    Array representation is (grid_size, grid_size, 6)
+    """
     def __init__(self, car, obs_dim=500):
         from fluids.assets import ALL_OBJS, TrafficLight, Lane, Terrain, Sidewalk, \
             PedCrossing, Street, Car, Waypoint, Pedestrian

fluids/obs/obs.py

@@ -1,5 +1,15 @@
 class FluidsObs(object):
+    """
+    The base FLUIDS observation interface
+    """
     def __init__(self):
         pass
     def get_array(self):
+        """
+        Returns a numpy array representation of the observation
+
+        Returns
+        -------
+        np.array
+        """
         raise NotImplementedError

fluids/sim.py

@@ -151,12 +151,10 @@ def step(self, actions={}):
             Keys in dict should correspond to controlled cars.
             Action can be of type KeyboardAction, SteeringAction, or VelocityAction
 
+
         Returns
         -------
-        dict of (key -> FluidsObs)
-            Dictionary mapping keys of controlled cars to FluidsObs object
-        int
-            Summed reward collected by all agents in this step
+        
         """
         for k, v in iteritems(actions):
             if type(v) == KeyboardAction:
@@ -184,6 +182,18 @@ def step(self, actions={}):
             self.render()
         return reward_step
     def get_observations(self, keys={}):
+        """
+        Get observatoins from controlled cars in the scene.
+
+        Parameters
+        ----------
+        keys: dict of keys
+            Keys should refer to cars in the scene
+        Returns
+        -------
+        dict of (key -> FluidsObs)
+            Dictionary mapping keys of controlled cars to FluidsObs object
+        """
         observations = {k:self.state.objects[k].make_observation(self.obs_space, **self.obs_args)
                         for k in keys}
         return observations