some docstrings

invertedai/api_resources.py

@@ -26,12 +26,12 @@ def available_locations(*args: str):
 
     Parameters
     ----------
-    *args: str
+    *args : str
         Variable length argument list of keywords.
 
     Returns
     -------
-    out : List[str]
+    response : List[str]
         A list of "available locations" to your account (api-key)
 
     See Also
@@ -72,7 +72,7 @@ def get_map(
 
     Parameters
     ----------
-    location: str
+    location : str
         Name of the location.
 
     include_map_source: bool
@@ -81,26 +81,50 @@ def get_map(
     Returns
     -------
     response : Dict
+        A dictionary of the json payload from the server
         <rendered_map> : List[int]
             Rendered image of the amp encoded in jpeg format.
             use cv2.imdecode(response["rendered_map"], cv2.IMREAD_COLOR)
             to decode the image
-        <lanelet_map_source>
-        <static_actors>
-
+        <lanelet_map_source> : str
+            Serialized XML file of the OSM map.
+            save the map by write(response["lanelet_map_source"])
+        <static_actors> : List[Dict]
+            A list of static actors of the location, i.e, traffic signs and lights
+                <track_id> : int
+                     A unique ID of the actor, used to track and change state of the actor
+                <agent_type> : str
+                    Type of the agent, either "traffic-light", or "stop-sign"
+                <x> : float
+                    The x coordinate of the agent on the map
+                <y> : float
+                    The y coordinate of the agent on the map
+                <psi_rad> : float
+                    The orientation of the agent
+                <length> : float
+                    The lenght of the actor
+                <width> : float
+                    The width of the actor
 
     See Also
     --------
-    invertedai.get_map
+    invertedai.available_locations
 
     Notes
     -----
-    Providing more than three keywords is uncessary
 
     Examples
     --------
-    >>> iai.available_maps("carla", "roundabout")
-    ["CARLA:Town03:Roundabout"]
+    >>> response = iai.get_map(location=args.location)
+    >>> if response["lanelet_map_source"] is not None:
+    >>>     file_path = "map.osm"
+    >>>     with open(file_path, "w") as f:
+    >>>         f.write(response["lanelet_map_source"])
+    >>> if response["rendered_map"] is not None:
+    >>>     file_path = "map.jpg"
+    >>>     rendered_map = np.array(response["rendered_map"], dtype=np.uint8)
+    >>>     image = cv2.imdecode(rendered_map, cv2.IMREAD_COLOR)
+    >>>     cv2.imwrite(file_path, image)
     """
 
     start = time.time()
@@ -124,6 +148,65 @@ def initialize(
     min_speed=None,
     max_speed=None,
 ) -> dict:
+    """
+    Parameters
+    ----------
+    location : str
+        Name of the location.
+
+    agent_count : int
+        Number of cars to spawn on the map
+
+    batch_size : int
+        Batch size
+
+    min_speed : Optional[int]
+        Not available yet, (for setting the minimum speed of spawned cars)
+
+    max_speed : Optional[int]
+        Not available yet, (for setting the minimum speed of spawned cars)
+
+    Returns
+    -------
+    Response: Dict
+        A dictionary of the json payload from the server
+        <states> : List[List[List[Tuple[(float,) * 4]]]] (BxAxTx4)
+            List of positions and speeds of agents.
+            List of B (batch size) lists,
+            each element is of size A (number of agents) lists,
+            eeach element is of T (number of time steps) list,
+            each elemnt is a list of 4 floats (x,y,speed, orientation)
+
+        <recurrent_states> : List[List[Tuple[(Tuple[(float,) * 64],) * 2]]]
+            Internal state of simulation, which must be fedback to continue simulation
+
+        <attributes> : List[List[Tuple[(float,) * 3]]]  (BxAx3)
+            List of agent attributes
+            List of B (batch size) lists,
+            each element is of size A (number of agents) lists,
+            each elemnt is a list of x floats (width, lenght, lr)
+
+        <traffic_light_state>: Dict[str, str]
+            Dictionary of traffic light states.
+            Keys are the traffic-light ids and
+            values are light state: 'red', 'green', 'yellow' and 'red'
+
+        <traffic_state_id>: str
+            The id of the current stat of the traffic light,
+            which must be fedback to get the next state of the traffic light
+
+    See Also
+    --------
+    invertedai.drive
+
+    Notes
+    -----
+
+    Examples
+    --------
+    >>> response = iai.initialize(location="CARLA:Town03:Roundabout", agent_count=10)
+    """
+
     start = time.time()
     timeout = TIMEOUT
 
@@ -161,8 +244,8 @@ def initialize(
 
 def drive(
     location: str = "CARLA:Town03:Roundabout",
-    states: dict = {},
-    agent_attributes: dict = {},
+    states: list = [],
+    agent_attributes: list = [],
     recurrent_states: Optional[List] = None,
     get_birdviews: bool = False,
     steps: int = 1,
@@ -171,6 +254,80 @@ def drive(
     exclude_ego_agent: bool = True,
     present_mask: Optional[List] = None,
 ) -> dict:
+    """
+        Parameters
+        ----------
+        location : str
+            Name of the location.
+
+        states : List[List[List[Tuple[(float,) * 4]]]] (BxAxTx4)
+            List of positions and speeds of agents.
+            List of B (batch size) lists,
+            each element is of size A (number of agents) lists,
+            eeach element is of T (number of time steps) list,
+            each elemnt is a list of 4 floats (x,y,speed, orientation)
+
+        agent_attributes : List[List[Tuple[(float,) * 3]]]  (BxAx3)
+            List of agent attributes
+            List of B (batch size) lists,
+            each element is of size A (number of agents) lists,
+            each elemnt is a list of x floats (width, lenght, lr)
+
+        recurrent_states : List[List[Tuple[(Tuple[(float,) * 64],) * 2]]]
+            Internal state of simulation, which must be fedback to continue simulation
+            This should have been obtained either from iai.drive or iai.initialize.
+
+        get_birdviews: bool
+            If True returns bird's-eye render of the map with agents
+
+        steps: int = 1,
+        get_infractions: bool = False,
+        traffic_states_id: str = "000:0",
+        exclude_ego_agent: bool = True,
+        present_mask: Optional[List] = None,
+    )
+
+        Returns
+        -------
+        Response: Dict
+            A dictionary of the json payload from the server
+            <states> : List[List[List[Tuple[(float,) * 4]]]] (BxAxTx4)
+                List of positions and speeds of agents.
+                List of B (batch size) lists,
+                each element is of size A (number of agents) lists,
+                eeach element is of T (number of time steps) list,
+                each elemnt is a list of 4 floats (x,y,speed, orientation)
+
+            <recurrent_states> : List[List[Tuple[(Tuple[(float,) * 64],) * 2]]]
+                Internal state of simulation, which must be fedback to continue simulation
+
+            <attributes> : List[List[Tuple[(float,) * 3]]]  (BxAx3)
+                List of agent attributes
+                List of B (batch size) lists,
+                each element is of size A (number of agents) lists,
+                each elemnt is a list of x floats (width, lenght, lr)
+
+            <traffic_light_state>: Dict[str, str]
+                Dictionary of traffic light states.
+                Keys are the traffic-light ids and
+                values are light state: 'red', 'green', 'yellow' and 'red'
+
+            <traffic_state_id>: str
+                The id of the current stat of the traffic light,
+                which must be fedback to get the next state of the traffic light
+
+        See Also
+        --------
+        invertedai.drive
+
+        Notes
+        -----
+
+        Examples
+        --------
+        >>> response = iai.initialize(location="CARLA:Town03:Roundabout", agent_count=10)
+    """
+
     def _tolist(input_data: List):
         if not isinstance(input_data, list):
             return input_data.tolist()