SUMO (Simulation of Urban MObility) is "an open source, highly portable, microscopic and continuous multi-modal traffic simulation package designed to handle large networks" (https://www.eclipse.org/sumo/).
CARLA is an "Open-source simulator for autonomous driving research". (https://carla.org/)
This project is about the effect that Augmented Reality Head Up Displays (AR-HUDs) have on the driving performance of drivers in an urban environment. Using SUMO, it is possible to simulate how driving behavior changes in response to different AR-HUDs, for example by influencing the awareness of the surrounding vehicles or reaction times to events happening nearby. If an AR-HUD has a high distraction level, it has an negative influence to the reaction time of the driver, while an AR-HUD with a low distraction level but high relevance of informations can improve the reaction time. Those changes can be observed in a 3D environment using CARLA, which makes it easier to observe situations and evaluate them. We always tried to make factors (calculations, values, etc) impacting the driving performance as reasonable and factual as possible using scientific resources whenever possible or making educated guesses.
- Sumo (Version 1.21 or higher)
- traci (python package)
- sumolib (python package)
- CARLA (Version 0.9.15)
- carla (python package)
- Python 3 (Version 3.10)
- tkinter (for GUI)
- numpy, cv2 (for live feed overlays)
- cElementTree, minidom (for xml operations)
- PIL (for picture integration)
- XML, CSV (file formats)
Generally, we try to use the latest version of each package und Framework to improve speed and accuracy. However, the carla python package is only available for python 3.10 or older, limiting the python version. Using older libraries should be compatible.
- Python 3.10
- Sumo 1.21
- Carla 0.9.15 - both the Server and Client
- Ensure all requirements are installed and the PATH variable is correctly set.
- Clone this repository to a location of your choice.
- Install python packages using pip.
pip install -r .\requirements.txt
- Open "config.py" and setup your carla base path up to the folder "\WindowsNoEditor".
- Copy content of setup_files into the Carla folder (copy the WindowsNoEditor folder over the one from carla, merge/ overwrite if promted)
- For the simulation to work, you need to update the .rou.xml files in your CarlaBaseDir/Co-Simulation/Sumo/examples/rou folder.
- You can use the files provided with this project or create your files using
randomTrips.py. - You can find the method in the /tools folder in your SUMO installation.
python randomTrips.py -n "CarlaBaseDir/Co-Simulation/Sumo/examples/net/TownXX.net.xml" -e 7200 --route-file "CarlaBaseDir/Co-Simulation/Sumo/examples/rou/Townxx.rou.xml" --period 6 --validate
- Using this command, you will get the appropriate .rou file for the simulation.
- You can change the duration of your simulation by setting the -e to a different value.
- Please make sure to also set --period (default 1) to your prefered value. Note: Setting a period too low will cause the simulation to become overflooded, which prevents it from running correctly. You can avoid this by choosing a higher --period value.
- Run main.py to access the GUI ("python main.py")
- In the GUI, select which components u want to run.
- Choose a map for the simulation from the list
- Select whether you want the co-simulation with CARLA, run the first-person spectator client, and decide whether you want a vehicle without a HUD (a baseline vehicle). If you select the first-person spectator client without the CARLA option, a silent CARLA server will start in the background.
- Add or remove HUD configurations until you have the desired number.
- configure and adjust the probability and name of all HUD configurations
- If you want to run the spectator client at a later point, make sure you have selected the co-simulation with Carla option and run spectator.py
- Click
Start Simulation. SUMO and other selected components will open for a visual simulation. Simultaneously, TRaCI will run the simulation in the background and collect all data. - The simulation results will be saved to the folder Simulation_data
You can start the next simulation without having to restart the project. Simply close all running SUMO and CARLA processes before starting a new simulation. Sometimes, a CARLA thread does not close properly and idles in the background, which causes problems when trying to start a new simulation. If you have issues starting a new simulation, check the task manager and close all running CARLA threads.
- q = Quit: Terminate the Spectator Client.
- n = Next: Switch to the next vehicle
- o = Overlay: Toggle the overlay that shows the name of the HUD and car (does not toggle the configured HUD!).
After opening the GUI, you can navigate to the settings tab. Her,e you can select which simulation data you want to save in your .csv file.
Note that by default, all the data is selected. Whenever you restart the GUI you have the manually deselect options you don't want to save.
These are the options:
- map: the map that was being used for the simulation
- vehicle_id: unique vehicle id
- hud_id: unique hud_id in the form of: individualIdentifier_HUDname
- simulation_time: the simulation step when the data was being collected
- vehicle_type: the vehicle_type the car is using
- position_x: x position of the vehicle
- position_y: y position of the vehicle
- current_speed: current speed of the vehicle
- current_gap: current gap of the vehicle to the leading vehicle
- current_acceleration: current acceleration of the vehicle, negative values mean the vehicle is braking
- distance_traveled: total distance the vehicle has traveled during the simulation
- time_loss: total time the car is behind its schedule
- maxSpeed: calculated maximal speed the car will drive
- speedAdherenceFactor: calculated factor to which the car follows the speed limit
- reactionTime: calculated reaction time for the HUD
- fatiguenessLevel: calculated fatigueness level for the HUD
- awarenessLevel: calculated awareness level for the HUD
- acceleration: calculated maximal acceleration for the HUD
- minGapFactor: calculated factor to which the driver obeys the legal minimal gap
- distractionLevel: calculated distraction level for the HUD
- brightness: brightness option that was selected for the HUD
- information_frequency: information frequency that was selected for the HUD
- information_relevance: information relevance that was selected for the HUD
- FoV: FoV option that was selected for the HUD
Note that you are not able to deselect the hud_id.
Apse-Extension-for-Carla-and-Sumo
|---analysis : Folder that contains R code for basic descriptive and inferential analysis of the log data
|---icons : Folder that contains the Icons used as HUD elements in the spectator client
| |---12 icon image files
|---sample_data : Folder that contains sample data logs of a simulation with 5 HUDs in Town01
|---screenshots : Folder that contains screenshots from the components for use in the docs and help page
| |---13 screenshots
|---setup_files : Folder that contains the path and the files that need to be updated within Carla for the program to run
| |---root_folder_of_carla
| |---WindowsNoEditor
| |---Co-Simulation
| |---Sumo
| |---examples
| |---rou
| |---Town01.rou.xml : Route file for map Town01, required for vehicles to be simulated in Carla
| |---Town04.rou.xml : Route file for map Town04, required for vehicles to be simulated in Carla
| |---Town05.rou.xml : Route file for map Town05, required for vehicles to be simulated in Carla
|---Simulation_data : Folder that contains all generated simulation data, empty by default.
|---calculations.py : File that contains all simulation formulas.
|---config.py : Configuration file that contains the path to the Carla folder.
|---hudconfig.xml : File that contains the HUD config of the last simulation, used to transfer HUD settings from the main client to the spectator client.
|---main.py : File that contains the main client, used to start all other components and configure all HUDs.
|---README.md : Readme that contains a overview over all files and instructions to run the program.
|---requirements.txt : File that contains the python packages that are used and are not included in the default python installation.
|---spectator.py : File that contains the spectator client, used to spectate Cars from a driver perspective and show an example HUD based on the HUD configuration.
There are several limitations to this project:
- Options used to simulate the AR HUDs are very limited. To allow a more accurate simulation, it would be necessary to differentiate more, maybe even allow the customisation of the different HUD elements.
- The created formulae, base values and weights used to simulate the driving performance using AR HUDs are based on data from the linked research. However, the accuracy of the simulation results can be decreased if the data is imprecise or scarce regarding certain factors. We tried to use as much data as possible, but some calculations are educated guesses.
- The number of HUDs simulated simultaneously is limited to the number of available vehicle types (
vTypes) in CARLA since the different HUDs are mapped to the vTypes. Currently, we are enabling the simultaneous simulation of eleven HUDs. - CARLA has rather large requirements for self-compiling, which makes it not feasible for us to modify CARLA directly. Therefore, we were forced to use a pre-compiled version of CARLA that works well but imposes restrictions on the overall project.
- The SUMO integration into CARLA is usable to show the state of vehicles in a 3D environment, but using the plethora of sensors and tools that CARLA can provide was impossible. The vehicle data is transferred so that SUMO provides the location of every vehicle at every given time to CARLA, meaning the sensors only see the vehicle projection with no access to the simulation data itself.
- The spectator client is limited in the information that it receives because the CARLA sensors don't work properly. Therefore, the visualization is much less dynamic than it could have been. The spectator client is limited to the vehicle speed as a dynamic item in the HUD.
- While SUMO and CARLA synchronize the vehicles pretty well, there are consistency and synchronization errors between SUMO and CARLA regarding the world. For example, traffic lights are not in sync, and roadsigns do not necessarily match.
- There is no proper way to export maps from SUMO to CARLA, as CARLA maps require extensive 3D modeling of the complete map. This limited us to the maps that CARLA provides.
Currently (December 2024), Carla 0.10.0 is released but does not yet support co-simulation with SUMO. We plan to support this in the future.