updated documenatation

.gitignore

+pathConfig.py
+scenarios/*
+
+## Core latex/pdflatex auxiliary files:
+*.aux
+*.lof
+*.log
+*.lot
+*.fls
+*.out
+*.toc
+*.fmt
+*.fot
+*.cb
+*.cb2
+
+## Intermediate documents:
+*.dvi
+*-converted-to.*
+# these rules might exclude image files for figures etc.
+*.ps
+# *.eps
+# *.pdf
+
+## Generated if empty string is given at "Please type another file name for output:"
+.pdf
+
+## Bibliography auxiliary files (bibtex/biblatex/biber):
+*.bbl
+*.bcf
+*.blg
+*-blx.aux
+*-blx.bib
+*.brf
+*.run.xml
+
+## Build tool auxiliary files:
+*.fdb_latexmk
+*.synctex
+*.synctex(busy)
+*.synctex.gz
+*.synctex.gz(busy)
+*.pdfsync
+
+## Auxiliary and intermediate files from other packages:
+# algorithms
+*.alg
+*.loa
+
+# achemso
+acs-*.bib
+
+# amsthm
+*.thm
+
+# beamer
+*.nav
+*.snm
+*.vrb
+
+# cprotect
+*.cpt
+
+# fixme
+*.lox
+
+# feynmf/feynmp
+*.mf
+*.mp
+*.t[1-9]
+*.t[1-9][0-9]
+*.tfm
+*.[1-9]
+*.[1-9][0-9]
+
+#(r)(e)ledmac/(r)(e)ledpar
+*.end
+*.?end
+*.[1-9]
+*.[1-9][0-9]
+*.[1-9][0-9][0-9]
+*.[1-9]R
+*.[1-9][0-9]R
+*.[1-9][0-9][0-9]R
+*.eledsec[1-9]
+*.eledsec[1-9]R
+*.eledsec[1-9][0-9]
+*.eledsec[1-9][0-9]R
+*.eledsec[1-9][0-9][0-9]
+*.eledsec[1-9][0-9][0-9]R
+
+# glossaries
+*.acn
+*.acr
+*.glg
+*.glo
+*.gls
+*.glsdefs
+
+# gnuplottex
+*-gnuplottex-*
+
+# gregoriotex
+*.gaux
+*.gtex
+
+# hyperref
+*.brf
+
+# knitr
+*-concordance.tex
+# TODO Comment the next line if you want to keep your tikz graphics files
+*.tikz
+*-tikzDictionary
+
+# listings
+*.lol
+
+# makeidx
+*.idx
+*.ilg
+*.ind
+*.ist
+
+# minitoc
+*.maf
+*.mlf
+*.mlt
+*.mtc
+*.mtc[0-9]
+*.mtc[1-9][0-9]
+
+# minted
+_minted*
+*.pyg
+
+# morewrites
+*.mw
+
+# mylatexformat
+*.fmt
+
+# nomencl
+*.nlo
+
+# sagetex
+*.sagetex.sage
+*.sagetex.py
+*.sagetex.scmd
+
+# scrwfile
+*.wrt
+
+# sympy
+*.sout
+*.sympy
+sympy-plots-for-*.tex/
+
+# pdfcomment
+*.upa
+*.upb
+
+# pythontex
+*.pytxcode
+pythontex-files-*/
+
+# thmtools
+*.loe
+
+# TikZ & PGF
+*.dpth
+*.md5
+*.auxlock
+
+# todonotes
+*.tdo
+
+# easy-todo
+*.lod
+
+# xindy
+*.xdy
+
+# xypic precompiled matrices
+*.xyc
+
+# endfloat
+*.ttt
+*.fff
+
+# Latexian
+TSWLatexianTemp*
+
+## Editors:
+# WinEdt
+*.bak
+*.sav
+
+# Texpad
+.texpadtmp
+
+# Kile
+*.backup
+
+# KBibTeX
+*~[0-9]*
+
+# build files doc
+tools/Python/commonroad/doc/build/*
+
+# auto folder when using emacs and auctex 
+/auto/*
+
+# python
+*__pycache__/
+*.cache
+*pytest_cache/
+*.egg-info
+

README.md

 # SUMO - CommonRoad Interface
 
-This interface couples the framework for motion planning of automated vehicles based on [CommonRoad_io](https://pypi.org/project/commonroad-io/) and the traffic simulator [SUMO](https://sumo.dlr.de).
+This package implements the interface between the framework for motion planning of automated vehicles [CommonRoad_io](https://pypi.org/project/commonroad-io/) and the traffic simulator [SUMO](https://sumo.dlr.de). The interface is presented in detail in our [paper](https://mediatum.ub.tum.de/doc/1486856/344641.pdf) [1] and a documentation of the API can be found [here]( https://commonroad.in.tum.de/static/docs/commonroad-sumo-interface/index.html).
 
 # Prerequisites
 The package is written in Python 3.6 and tested on Linux.
@@ -17,6 +17,7 @@ And add the absolute path of `commonroad-sumo-interface` to your Python interpre
 
 Clone a customized version of SUMO for smooth lane changes from https://github.com/octavdragoi/sumo and check out branch `smooth-lane-change`.
 For installation we recommend building with:
+
 ```
 sudo apt-get install cmake python g++ libxerces-c-dev libfox-1.6-dev libgdal-dev libproj-dev libgl2ps-dev swig
 cd sumo
@@ -25,6 +26,7 @@ mkdir build && cd build
 cmake ..
 make -j8
 ```
+
 More options on the installation can be found here: https://sumo.dlr.de/wiki/Installing/Linux_Build .
 
 ## Configure SUMO and local environment
@@ -82,5 +84,8 @@ for t in range(conf.simulation_steps):
 
     sumo_sim.simulate_step()
 
+sumo_sim.stop()
 create_video(sumo_sim, conf.video_start, conf.video_end, output_folder)
 ```
+
+[1] Moritz Klischat, Octav Dragoi, Mostafa Eissa, and Matthias Althoff, Coupling SUMO with a Motion Planning Framework for Automated Vehicles, SUMO 2019: Simulating Connected Urban Mobility

example_scripts/create_scenario_files.py

-"""
-Converts net.xml to Commonroad xml files and creates rou files for simulation.
-"""
-
-import matplotlib.pyplot as plt
-from typing import List
-from commonroad.visualization.draw_dispatch_cr import draw_object
-from sumo2cr.maps.sumo_scenario import ScenarioWrapper
-from commonroad.common.util import Interval
-from commonroad.scenario.trajectory import State
-import os
-
-__author__ = "Moritz Klischat"
-__copyright__ = "TUM Cyber-Physical Systems Group"
-__credits__ = ["ZIM Projekt ZF4086007BZ8"]
-__version__ = "1.0.0"
-__maintainer__ = "Moritz Klischat"
-__email__ = "commonroad-i06@in.tum.de"
-__status__ = "Released"
-
-scenario_folder = os.path.join(os.path.dirname(__file__),'../scenarios')
-
-net_file = os.path.join(scenario_folder, 'a9/a9.net.xml')
-sumo_cfg_file = os.path.join(scenario_folder, 'a9/a9.sumo.cfg')
-
-# parameters
-dt = 0.1
-convert_map = True
-n_vehicles_max:int = 30
-veh_per_second = 50
-n_ego_vehicles:int = 1
-ego_ids:List[int] = []
-initial_states:List[State] = []
-ego_start_time:int=10
-departure_time_ego = 3
-departure_interval_vehicles = Interval(0,20)
-
-if convert_map:
-    # generate commonroad map + rou file + cfg file
-    scenario = ScenarioWrapper.full_conversion_from_net(net_file, dt, n_vehicles_max, n_ego_vehicles, ego_ids, ego_start_time, departure_time_ego, departure_interval_vehicles,veh_per_second)
-else:
-    # generate rou file
-    scenario = ScenarioWrapper.recreate_route_file(sumo_cfg_file, dt, n_vehicles_max, n_ego_vehicles, ego_ids, ego_start_time, departure_time_ego, departure_interval_vehicles,veh_per_second)
-
-plt.figure(figsize=(25, 25))
-draw_object(scenario.lanelet_network)
-
-plt.autoscale()
-plt.axis('equal')
-plt.xlim([290,380])
-plt.ylim([195,250])
+"""
+Converts net.xml to Commonroad xml files and creates rou files for simulation.
+"""
+
+import matplotlib.pyplot as plt
+from typing import List
+from commonroad.visualization.draw_dispatch_cr import draw_object
+from sumo2cr.maps.sumo_scenario import ScenarioWrapper
+from commonroad.common.util import Interval
+from commonroad.scenario.trajectory import State
+import os
+
+__author__ = "Moritz Klischat"
+__copyright__ = "TUM Cyber-Physical Systems Group"
+__credits__ = ["ZIM Projekt ZF4086007BZ8"]
+__version__ = "1.0.0"
+__maintainer__ = "Moritz Klischat"
+__email__ = "commonroad-i06@in.tum.de"
+__status__ = "Released"
+
+scenario_folder = os.path.join(os.path.dirname(__file__),'../scenarios')
+
+net_file = os.path.join(scenario_folder, 'a9/a9.net.xml')
+sumo_cfg_file = os.path.join(scenario_folder, 'a9/a9.sumo.cfg')
+
+# parameters
+dt = 0.1
+convert_map = True
+n_vehicles_max:int = 30
+veh_per_second = 50
+n_ego_vehicles:int = 1
+ego_ids:List[int] = []
+initial_states:List[State] = []
+ego_start_time:int=10
+departure_time_ego = 3
+departure_interval_vehicles = Interval(0,20)
+
+if convert_map:
+    # generate commonroad map + rou file + cfg file
+    scenario = ScenarioWrapper.full_conversion_from_net(net_file, dt, n_vehicles_max, n_ego_vehicles, ego_ids, ego_start_time, departure_time_ego, departure_interval_vehicles,veh_per_second)
+else:
+    # generate rou file
+    scenario = ScenarioWrapper.recreate_route_file(sumo_cfg_file, dt, n_vehicles_max, n_ego_vehicles, ego_ids, ego_start_time, departure_time_ego, departure_interval_vehicles,veh_per_second)
+
+plt.figure(figsize=(25, 25))
+draw_object(scenario.lanelet_network)
+
+plt.autoscale()
+plt.axis('equal')
+plt.xlim([290,380])
+plt.ylim([195,250])
 plt.show()
\ No newline at end of file

example_scripts/minimal_example.py

@@ -30,5 +30,7 @@ for t in range(conf.simulation_steps):
 
     sumo_sim.simulate_step()
 
+sumo_sim.stop()
+
 create_video(sumo_sim, conf.video_start, conf.video_end, output_folder)
 

pathConfig_DEFAULT.py

-'''
- Copy this file and rename to path_config.py, afterwards set paths according to your local configuration
-'''
-
-# set installation locations
-SUMO_GUI_BINARY = '/usr/bin/sumo-gui'
-# path to binary of adapted sumo repository (see readme)
-SUMO_BINARY = '/home/user/sumo/bin/sumo'
-
-# by default port 8873 is used, you can modify the port number
-TRACI_PORT = 8873
-
-# default files (no adaption required)
+'''
+ Copy this file and rename to path_config.py, afterwards set paths according to your local configuration
+'''
+
+# set installation locations
+SUMO_GUI_BINARY = '/usr/bin/sumo-gui'
+# path to binary of adapted sumo repository (see readme)
+SUMO_BINARY = '/home/user/sumo/bin/sumo'
+
+# by default port 8873 is used, you can modify the port number
+TRACI_PORT = 8873
+
+# default files (no adaption required)
 DEFAULT_CFG_FILE = 'sumo_config/.sumo.cfg'
\ No newline at end of file

sumo2cr/interface/ego_vehicle.py

@@ -3,7 +3,7 @@ from typing import Dict, List, Union
 import numpy as np
 import copy
 from commonroad.geometry.shape import Rectangle
-from commonroad.planning.planning_problem import PlanningProblem
+from commonroad.planning.planning_problem import PlanningProblem, GoalRegion
 from commonroad.prediction.prediction import TrajectoryPrediction
 from commonroad.scenario.obstacle import DynamicObstacle, ObstacleType
 from commonroad.scenario.trajectory import State, Trajectory
@@ -40,10 +40,10 @@ class EgoVehicle:
 
     def set_planned_trajectory(self, planned_state_list:List[State]) -> None:
         """
-        Set planned trajectory beginning with current time step.
-        :param planned_state_list:
-        :param initial_time_step. If None, add at current time step
-        :return:
+        Sets planned trajectory beginning with current time step.
+
+        :param planned_state_list: the planned trajectory
+
         """
 
         assert len(planned_state_list) >= self.delta_steps,\
@@ -57,15 +57,16 @@ class EgoVehicle:
 
     @property
     def get_planned_trajectory(self) -> List[State]:
-        """Get planned trajectory from current time step"""
+        """Gets planned trajectory according to the current time step"""
         return self._planned_trajectories[self.current_time_step]
 
     def get_dynamic_obstacle(self,time_step: Union[int,None]=None) -> DynamicObstacle:
         """
-        If time step is false, add complete driven trajectory.
-        If time step is int: start from given step and add planned trajectory
+        If time step is false, adds complete driven trajectory and returns the dynamic obstacles.
+        If time step is int: starts from given step and adds planned trajectory and returns the dynamic obstacles.
+
         :param time_step: initial time step of vehicle
-        :return: DynamicObstacle
+        :return: DynamicObstacle object of the ego vehicle.
         """
         if time_step is False:
             return DynamicObstacle(self.id,obstacle_type=ObstacleType.CAR,
@@ -86,6 +87,12 @@ class EgoVehicle:
             raise ValueError('time needs to be None or integer')
 
     def get_planned_state(self, delta_step: int=0):
+        """
+        Returns the planned state.
+
+        :param delta_step: get plannedd state after delta steps
+        
+        """
         planned_state:State = copy.deepcopy(self._planned_trajectories[self.current_time_step][0])
         if self.delta_steps > 1:
             # linear interpolation
@@ -98,12 +105,20 @@ class EgoVehicle:
 
     @property
     def current_state(self) -> State:
+        """
+        Returns the current state.
+        """
         if self.current_time_step == self.initial_state.time_step:
             return self.initial_state
         else:
             return self._state_dict[self.current_time_step]
 
-    def get_state_at_timestep(self,time_step: int):
+    def get_state_at_timestep(self,time_step: int) -> State:
+        """
+        Returns the state according to the given time step.
+
+        :param time_step: the state is returned according to this time step.
+        """
         if time_step == self.initial_state.time_step:
             return self.initial_state
         else:
@@ -116,7 +131,10 @@ class EgoVehicle:
         raise PermissionError('current_state cannot be set manually, use set_planned_trajectory()')
 
     @property
-    def current_time_step(self):
+    def current_time_step(self) -> int:
+        """
+        Returns current time step.
+        """
         return self._current_time_step
 
     @current_time_step.setter
@@ -124,17 +142,26 @@ class EgoVehicle:
         raise PermissionError('current_state cannot be set manually, use set_planned_trajectory()')
 
     @property
-    def goal(self):
+    def goal(self) -> GoalRegion:
+        """
+        Returns the goal of the planning problem.
+        """
         return self.planning_problem.goal
 
-    def add_state(self,state):
+    def add_state(self, state: State) -> None:
+        """
+        Adds a state to the current state dictionary.
+
+        :param state: the state to be added
+
+        """
         self._state_dict[self._current_time_step+1] = state
 
     @property
     def driven_trajectory(self) -> TrajectoryPrediction:
         """
         Returns trajectory prediction object for driven trajectory (mainly for plotting)
-        :return:
+
         """
         state_dict_tmp ={}
         for t, state in self._state_dict.items():
@@ -152,7 +179,10 @@ class EgoVehicle:
             return
 
     @property
-    def width(self):
+    def width(self) -> float:
+        """
+        Returns the width of the ego vehicle.
+        """
         return self._width
 
     @width.setter
@@ -162,7 +192,10 @@ class EgoVehicle:
             return
 
     @property
-    def length(self):
+    def length(self) -> float:
+        """
+        Returns the length of the ego vehicle.
+        """
         return self._length
 
     @length.setter
@@ -172,7 +205,10 @@ class EgoVehicle:
             return
 
     @property
-    def initial_state(self):
+    def initial_state(self) -> State:
+        """
+        Returns the initial state of the ego vehicle.
+        """
         return self._initial_state
 
     @initial_state.setter

sumo2cr/interface/sumo_simulation.py

+import sys, os
+
+if 'SUMO_HOME' in os.environ:
+    tools = os.path.join(os.environ['SUMO_HOME'], 'tools')
+    sys.path.append(tools)
+else:
+    sys.exit("please declare environment variable 'SUMO_HOME'")
+
+
 from collections import defaultdict
 import logging
 import math
-import sys, os
 import sumo_config.default
 import traci
 import numpy as np
@@ -18,7 +26,7 @@ from pathConfig import *
 from sumo_config.plot_params import *
 from sumo_config.default import SumoCommonRoadConfig
 from sumo2cr.interface.util import initialize_id_dicts
-from typing import Dict, List, Union, Type
+from typing import Dict, List, Union, Type, Tuple
 
 __author__ = "Moritz Klischat, Mostafa Eissa"
 __copyright__ = "TUM Cyber-Physical Systems Group"
@@ -39,7 +47,7 @@ logging.basicConfig(stream=sys.stderr, level=logging.CRITICAL)
 
 class SumoSimulation:
     """
-    Class for interfacing between of SUMO simulation and CommonRoad.
+    Class for interfacing between the SUMO simulation and CommonRoad.
     """
     def __init__(self):
         """Init empty object"""
@@ -66,9 +74,10 @@ class SumoSimulation:
 
     def initialize(self, conf: Type[SumoCommonRoadConfig] = None) -> None:
         """
-        Read scenario files, start traci simulation, initialize vehicles, conduct pre-simulation.
+        Reads scenario files, starts traci simulation, initializes vehicles, conducts pre-simulation.
+
         :param conf: configuration object. If None, use default configuration.
-        :return:
+        
         """
 
         if conf is not None:
@@ -95,7 +104,13 @@ class SumoSimulation:
                 warnings.warn('<SumoSimulation/init_ego_vehicles> Ego vehicles are defined through .rou file and planning problem. Is that intended?')
             self.init_ego_vehicles_from_planning_problem(self.planning_problem_set)
 
-    def init_ego_vehicles_from_planning_problem(self, planning_problem_set: PlanningProblemSet):
+    def init_ego_vehicles_from_planning_problem(self, planning_problem_set: PlanningProblemSet) -> None:
+        """
+        Initializes the ego vehicles according to planning problem set.
+
+        :param planning_problem_set: The planning problem set which defines the ego vehicles. 
+        """
+
         # retrieve arbitrary route id for initialization (will not be used by interface)
         generic_route_id = self.routedomain.getIDList()[0]
 
@@ -116,21 +131,35 @@ class SumoSimulation:
                     EgoVehicle(cr_id, planning_problem.initial_state, self.conf.delta_steps, width, length, planning_problem))
 
     def _add_ego_vehicle(self, ego_vehicle: EgoVehicle):
+        """
+        Adds a ego vehicle to the current ego vehicle set.
+
+        :param ego_vehicle: the ego vehicle to be added.
+        """
         self._ego_vehicles[ego_vehicle.id] = ego_vehicle
 
     @property
     def ego_vehicles(self) -> Dict[int, EgoVehicle]:
+        """
+        Returns the ego vehicles of the current simulation.
+
+        """
         return self._ego_vehicles
 
     @ego_vehicles.setter
     def ego_vehicles(self, ego_vehicles: Dict[int, EgoVehicle]):
+        """
+        Sets the ego vehicles of the current simulation.
+
+        :param ego_behicles: ego vehicles used to set up the current simulation.
+        """
         if hasattr(self, '_ego_vehicles'):
             raise ValueError('Cannot set ego_vehicles, use SumoSimlation.forward_ego_vehicles() or ._add_ego_vehicle()')
         else:
             self._ego_vehicles = ego_vehicles
 
     @property
-    def current_time_step(self):
+    def current_time_step(self) -> int:
         """
         :return: current time step of interface
         """
@@ -138,22 +167,43 @@ class SumoSimulation:
 
     @current_time_step.setter
     def current_time_step(self,current_time_step):
+        """
+        Time step should not be set manually.
+        """
         raise(ValueError('Time step should not be set manually'))
 
     def print_lanelet_net(self, with_lane_id=True, with_succ_pred=False, with_adj=False, with_speed=False):
-        """ Plot commonroad road network without vehicles or obstacles."""
+        """ 
+        Plots commonroad road network without vehicles or obstacles.
+
+        :param with_lane_id: if set to true, the lane id will also be printed.
+        :param with_succ_pred: if set to true, the successor and predecessor lanelets will be printed.
+        :param with_adj: if set to true, adjacant lanelets will be printed.
+        :param with_speed: if set to true, the speed limit will be printed.
+        """
         self.scenarios.print_lanelet_net(with_lane_id