Merge pull request #11 from jerryz123/docs

Filled in docs for state, env, and objects

docs/source/conf.py

@@ -35,7 +35,8 @@
               'sphinx.ext.mathjax',
               'sphinx.ext.viewcode',
               'sphinx.ext.githubpages',
-              'sphinx.ext.autodoc']
+              'sphinx.ext.autodoc',
+              'sphinx.ext.napoleon']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

docs/source/environment.rst

@@ -1,5 +1,10 @@
 Environments
 ============
 
+The UrbanDrivingEnvironment Class
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autoclass:: gym_urbandriving.UrbanDrivingEnv
+   :members: _step, _reset, _render
+
 Ray Integration
 ^^^^^^^^^^^^^^^

docs/source/examples.rst

@@ -65,7 +65,41 @@ in the scene. For every other object, it queries its internal list of agents as
 
 Designing a State
 ^^^^^^^^^^^^^^^^^
+Designing a state is very simple in UDS. To design a custom state, simply inherit from ``PositionState`` and implement your own array of ``static_objects`` and define your own ``randomize()`` function.
 
+::
+
+   class CustomState(PositionState):
+      static_objects = [Terrain(175, 175, 350, 350),
+                        Terrain(825, 175, 350, 350),
+                        Terrain(175, 825, 350, 350),
+                        Terrain(825, 825, 350, 350),
+                        Lane(200, 450, 400, 100, angle=-180),
+                        Lane(200, 550, 400, 100),
+                        Lane(800, 450, 400, 100, angle=-180),
+                        Lane(800, 550, 400, 100),
+                        Lane(450, 200, 400, 100, angle=-90),
+                        Lane(550, 200, 400, 100, angle=90),
+                        Lane(450, 800, 400, 100, angle=-90),
+                        Lane(550, 800, 400, 100, angle=90),
+                        Street(500, 500, 200, 200),
+                        Sidewalk(200, 375, 400, 50),
+                        Sidewalk(200, 625, 400, 50),
+                        Sidewalk(800, 375, 400, 50),
+                        Sidewalk(800, 625, 400, 50),
+                        Sidewalk(375, 175, 50, 350),
+                        Sidewalk(625, 175, 50, 350),
+                        Sidewalk(375, 825, 50, 350),
+                        Sidewalk(625, 825, 50, 350),]
+
+You should place the dynamic objects in the ``randomize()`` function
+
+
+::
+   
+      def randomize(self):
+         self.dynamic_objects = []
+         self.dynamic_objects.append(Car(500, 200))
 
 Imitation Learning
 ^^^^^^^^^^^^^^^^^^

docs/source/index.rst

@@ -15,3 +15,5 @@ This is Berkeley AUTOLAB's Urban Driving Simulator.
    environment.rst
    state.rst
    objects.rst
+
+

docs/source/objects.rst

@@ -3,18 +3,33 @@ Objects
 
 Cars
 ^^^^
+.. autoclass:: gym_urbandriving.assets.Car
+   :members: step, can_collide
+
 
 Pedestrians
 ^^^^^^^^^^^
-
+.. autoclass:: gym_urbandriving.assets.Pedestrian
+   :members: step, can_collide
+
 Terrain
 ^^^^^^^
+.. autoclass:: gym_urbandriving.assets.Terrain
 
 Lanes
 ^^^^^
+.. autoclass:: gym_urbandriving.assets.Lane
+   :members: generate_car
+
 
 Sidewalks
 ^^^^^^^^^
+.. autoclass:: gym_urbandriving.assets.Sidewalk
+   :members: generate_man
+
+
 
 Streets
 ^^^^^^^
+.. autoclass:: gym_urbandriving.assets.Street
+

docs/source/state.rst

@@ -1,2 +1,12 @@
 States
 ======
+
+The Abstract PositionState
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autoclass:: gym_urbandriving.state.PositionState
+   :members: get_collisions, collides_any, min_dist_to_coll
+
+The Simple Intersection
+^^^^^^^^^^^^^^^^^^^^^^^
+.. autoclass:: gym_urbandriving.state.SimpleIntersectionState
+   :members: randomize

gym_urbandriving/assets/car.py

@@ -45,6 +45,14 @@ def __init__(self, x, y, xdim=80, ydim=40, angle=0.0, vel=0.0,
         self.l_f = self.l_r = self.ydim / 2.0
 
     def step(self, action):
+        """
+        Updates this object given this action input
+
+        Parameters
+        ----------
+        action :
+            The action to take
+        """
         if self.dynamics_model == "kinematic":
             self.kinematic_model_step(action)
         else:
@@ -53,7 +61,7 @@ def step(self, action):
     def point_model_step(self, action, info_dict=None):
         """
         Updates the car for one timestep based on point model
-        
+
         Parameters
         ----------
         action: 1x2 array,
@@ -80,7 +88,7 @@ def point_model_step(self, action, info_dict=None):
         self.y += dy
         self.vel += acc
         self.vel = max(min(self.vel, self.max_vel), -self.max_vel)
-        
+
     def kinematic_model_step(self, action):
         """
         Updates the car for one timestep.
@@ -118,7 +126,7 @@ def integrator(self, state, t, acc, delta_f):
         equation variables for dynamics.
         SciPy ODE integrator calls this function.
 
-        Args:
+        :
             state: 1x6 array, contains x, y, dx_body, dy_body, rad_angle, rad_dangle
                 of car.
             t: float, timestep.
@@ -152,6 +160,16 @@ def get_state(self):
     def can_collide(self, other):
         """
         Specifies whether this object can collide with another object
+
+        Parameters
+        ----------
+        other : 
+            Object to test collision against
+
+        Returns
+        -------
+        bool 
+           True if this object can collide with other
         """
         from gym_urbandriving.assets.lane import Lane
         if type(other) in {Terrain, Sidewalk, Car, Pedestrian}:

gym_urbandriving/assets/lane.py

@@ -5,10 +5,42 @@
 
 
 class Lane(Street):
+    """
+    Represents a lane of road. Lanes have directionality, so cars should drive in the
+    right direction.
+
+    Parameters
+    ----------
+    x : float
+       Upper left x coordinate of the lane block
+    y : float
+       Upper left y coordinate of the lane block
+    xdim : float
+       Width of the lane block
+    ydim : float
+       Height of the lane block
+    angle ; float
+       In degrees, the rotation of the lane block.
+    """
     def __init__(self, x, y, xdim, ydim, angle=0.0):
         Rectangle.__init__(self, x, y, xdim, ydim, angle=angle, sprite="lane.png", static=True);
 
     def generate_car(self, car_type="kinematic", randomize=True):
+        """
+        Generates a car on the lane, facing the right direction.
+
+        Parameters
+        ----------
+        car_type : "kinematic" or "point"
+            Specifies dynamics model for the car
+        randomize : bool
+            Specifies if the car's position is randomized
+
+        Returns
+        -------
+        Car
+            Generated Car object
+        """
         if randomize:
             car = Car(0, 0, angle=self.angle+np.random.uniform(-10, 10),
                       dynamics_model=car_type)
@@ -36,4 +68,3 @@ def generate_car(self, car_type="kinematic", randomize=True):
             x, y = x+self.x, y+self.y
             car.x, car.y = x, y
             return car
-

gym_urbandriving/assets/pedestrian.py

@@ -3,6 +3,26 @@
 from gym_urbandriving.assets.terrain import Terrain
 
 class Pedestrian(Circle):
+    """
+    Represents a pedestrian as a circle
+    
+    Parameters
+    ----------
+    x : float
+        Center x coordinate
+    y : float
+        Center y coordinate
+    radius : float
+        Size of the pedestrian
+    angle : float
+        Initial orientation, in degrees
+    vel : float
+        Initial velocity
+    max_vel : float
+        Maximum velocity
+    mass : float
+        Mass of pedestrian
+    """
     def __init__(self, x, y, radius=17, angle=0.0, vel=0.0, acc=0.0, max_vel=2.0, mass=100.0):
         Circle.__init__(self, x, y, radius, angle, sprite="person.png")
         self.vel = vel
@@ -13,10 +33,14 @@ def __init__(self, x, y, radius=17, angle=0.0, vel=0.0, acc=0.0, max_vel=2.0, ma
 
     def step(self, action, info_dict=None):
         """
-        Updates the car for one timestep.
-        Args:
-            action: 1x2 array, steering / acceleration action.
-            info_dict: dict, contains information about the environment.
+        Updates the pedestrian for one timestep.
+
+        Parameters
+        ----------
+        action : 1x2 array
+           Steering / acceleration action.
+        info_dict : dict
+           Contains information about the environment.
         """
         self.shapely_obj = None
         if action is None:

gym_urbandriving/assets/sidewalk.py

@@ -3,10 +3,32 @@
 from gym_urbandriving.assets.pedestrian import Pedestrian
 
 class Sidewalk(Rectangle):
+    """
+    Represents a block of sidewalk. Passable for pedestrians, not for cars
+
+    Parameters
+    ----------
+    x : float
+       Upper left x coordinate of the sidewalk block
+    y : float
+       Upper left y coordinate of the sidewalk block
+    xdim : float
+       Width of the sidewalk block
+    ydim : float
+       Height of the sidewalk block
+    """
     def __init__(self, x, y, xdim, ydim):
-        Rectangle.__init__(self, x, y, xdim, ydim, sprite="gray.png", static=True);
+        Rectangle.__init__(self, x, y, xdim, ydim, sprite="gray.png", static=True)
 
     def generate_man(self, man_type=Pedestrian):
+        """
+        Generates a man on the sidewalk
+
+        Returns
+        -------
+        Pedestrian
+            Generated Pedestrian object
+        """
         man = man_type(0, 0, angle=self.angle)
         angle = np.radians(-self.angle)
         rotation_mat = np.array([[np.cos(angle), -np.sin(angle)],

gym_urbandriving/assets/street.py

@@ -1,6 +1,22 @@
 from gym_urbandriving.assets.primitives.rectangle import Rectangle
 
 class Street(Rectangle):
-    def __init__(self, x, y, xdim, ydim, angle=0.0, sprite="black.png"):
-        Rectangle.__init__(self, x, y, xdim, ydim, angle=0.0, sprite=sprite, static=True);
+    """
+    Represents a block of street. Passable for cars and pedestrians.
+    Does not have directionality associated with it, so use this for
+    the middle of an intersection
+
+    Parameters
+    ----------
+    x : float
+       Upper left x coordinate of the street block
+    y : float
+       Upper left y coordinate of the street block
+    xdim : float
+       Width of the street block
+    ydim : float
+       Height of the street block
+    """
+    def __init__(self, x, y, xdim, ydim):
+        Rectangle.__init__(self, x, y, xdim, ydim, angle=0.0, sprite="black.png", static=True);
 

gym_urbandriving/assets/terrain.py

@@ -2,6 +2,20 @@
 from gym_urbandriving.assets.primitives.rectangle import Rectangle
 
 class Terrain(Rectangle):
+    """
+    Represents a square of impassable terrain
+    
+    Parameters
+    ----------
+    x : float
+       Upper left x coordinate of the terrain block
+    y : float
+       Upper left y coordinate of the terrain block
+    xdim : float
+       Width of the terrain block
+    ydim : float
+       Height of the terrain block
+    """
     def __init__(self, x, y, xdim, ydim):
         sprite = ["block1.png", "block2.png", "block3.png", "block4.png"][np.random.randint(0, 3)]
         Rectangle.__init__(self, x, y, xdim, ydim, sprite="grass.jpg", static=True);