Package: carla-gym
Carla-gymCarla-gymis an interface to instantiate Reinforcement Learning (RL) environments on top of the CARLA Autonomous Driving simulator. It allows the training of agents (single or multi), the use of predefined or custom scenarios for reproducibility and benchmarking, and extensive control and customization over the virtual world. New environments and scenarios can be easily configured through XML documents (OPENScenario-like) or JSON configurations.InstallationPrerequisitesCARLA Autonomous Driving Simulator Serverinstalled locally. Otherwise, refer to theGuidesection below.CARLA_SERVERenvironment variable pointing to the CARLA executable.Requirementscarla==0.9.13 (use the same version as the local server installed)pettingzoopygamenetworkx==2.6.3opencv-pythonPython 3.7 and 3.8 are supported (the 'carla' package does not support higher versions). To install the package in the Python virtual environment of your choice, use the following command:pip install carla-gymUsageThe package allows you to interact with the CARLA simulator as a PettingZoo environment. You can instantiate an environment as follows:importcarla_gymenv=carla_gym.env(**args)# AEC APIenv=carla_gym.parallel_env(**args)# Parallel APIExamples of starter agents can be found in the examples folder. Any RL library that supports the standard multi-agent interface can be used to train the agents.The environment expects mandatory configuration for initialization. This can be provided as an .xml file or as a json dictionary, which overrides the .xml configurations. Standard configurations are provided within the package and can be imported as follows:importimportlibfromcarla_gym.core.constantsimportDEFAULT_MULTIENV_CONFIG# XMLwithimportlib.resources.open_text("carla_gym.scenarios","stop_sign_1b2c1p_town03.xml")asfile:env=carla_gym.env(xml_config_path=file.name)# JSONenv=carla_gym.env(configs=DEFAULT_MULTIENV_CONFIG)For additional information about the configuration, please refer toScenario configurationsection, or for information about the initialization settings, refer toArgumentssection.Functionalities:CARLA server self-hostingMulti-GPU supportConfiguration through XML OpenScenario-like or JSONScenario specification supports both single and multiple agentsAgents support automatic (autopilot) control, manual (keyboard) control, and default control as RL agentsSupported agents: Vehicles (4w/2w), Pedestrian (manual control TODO), and Traffic lightsAdditional World actors with automatic control and set origin-destinationRandom traffic of vehicles and pedestriansCamera rendering for multiple agents and spectator viewGuideCARLA setupEnvironment specificationsArgumentsAction spaceObservation spaceScenario configurationNaming ConventionContributingCARLA setupCARLA server supports Ubuntu (18.04/20.04/22.04 or later)/Debian/W10/W11. You can refer to theofficial CARLA docsfor the server installation process or follow the steps below:(for Ubuntu 18.04/20.04/22.04/+)Install the system requirements:Miniconda/Anaconda 3.x :wget -P ~ https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh; bash ~/Miniconda3-latest-Linux-x86_64.shcmake :sudo apt install cmakezlib :sudo apt install zlib1g-dev[optional] ffmpeg :sudo apt install ffmpegInstall CARLA (0.9.x):mkdir ~/software && cd ~/softwareDownload the 0.9.13 release version fromofficial repositoryExtract it into~/software/CARLA_0.9.13Set theCARLA_SERVERenvironment variable:echo "export CARLA_SERVER=${HOME}/software/CARLA_0.9.13/CarlaUE4.sh" >> ~/.bashrcNOTE: Currently Carla-gym supports CARLA 0.9.13NOTE: Independently from Carla-gym, installing the requiredcarladependency (PyPI package containing CARLA client API) ensures it matches the version number of your CARLA server.Environment specificationscarla_gym.env(configs:dict=None,xml_config_path:str=None,max_steps:int=500,render_mode:str=None,maps_path:str="/Game/Carla/Maps/",sync_server:bool=True,fixed_delta_seconds:float=0.05,render_width:int=800,render_height:int=600,actor_render_width:int=84,actor_render_height:int=84,discrete_action_space:bool=True,verbose:bool=False)Note that for a flexible customization the JSONconfigsspecifications override the ones parsed from the XML file specified inxml_config_path.For more information about sync/async mode of CARLA environment, refer to theCarla official docs.Argumentsconfigs: Scenarios configuration dictionary. Example provided incarla_gym.core.constants.DEFAULT_MULTIENV_CONFIG.xml_config_path: Filepath to a compatible XML file with scenarios configs. Example provided incarla_gym.scenarios.default_1c_town01.xml.max_steps: Maximum number of steps in the scenarios before the end of the episode.render_mode: Mode of rendering. Only 'human' is available.maps_path: Path where to find the external CARLA maps.sync_server: Whether the CARLA server should be in synchronous or asynchronous mode.fixed_delta_seconds: Fixes the time elapsed between two steps of the simulation to ensure reliable physics. Use 0.0 to work with a variable time-step.render_width: Spectator view rendering width.render_height: Spectator view rendering height.actor_render_width: Actor camera view rendering width.actor_render_height: Actor camera view rendering height.discrete_action_space: Whether the action space is discrete or continuous.verbose: Whether detailed logs should be given in output.Action spaceIn any given turn, an agent can choose from one of those 9 discrete actions:+-------------------+--------------------+-------------------+
| Action (Discrete) | Action (Continuous)|      Behavior     |
+-------------------+--------------------+-------------------+
|         0         |    [0.0, 0.0]      |    No operation   |
|         1         |    [0.0, -0.5]     |      Turn left    |
|         2         |    [0.0, 0.5]      |     Turn right    |
|         3         |    [1.0, 0.0]      |       Forward     |
|         4         |    [-0.5, 0.0]     |        Brake      |
|         5         |   [0.5, -0.05]     |    Forward left   |
|         6         |    [0.5, 0.05]     |   Forward right   |
|         7         |   [-0.5, -0.5]     |     Brake left    |
|         8         |    [-0.5, 0.5]     |     Brake right   |
+-------------------+--------------------+-------------------+otherwise, using continuous format:Box(high=np.array([1.0, 1.0]), low=np.array([-1.0, -1.0]), shape=(2,), dtype=np.float32)Observation spaceThe observation of each agent is composed of an image from the camera attached to it:Depth camera:Box(0.0, 255.0, shape=(actor_render_height, actor_render_width, 1 * framestack))RGB camera:Box(-1.0, 1.0, shape=(actor_render_height, actor_render_width, 3 * framestack))Optionally, additional information about the last navigation command, current speed, and distance to the goal can be included. Straightforward customization can be done by modifying the configuration provided at initialization (Seesectionbelow) or overriding themulti_env.MultiActorCarlaEnv._encode_obs()andmulti_env.MultiActorCarlaEnv._encode_obs()functions.Scenario configurationYou can customize the environment by providing an XML or JSON configuration. Details to create a custom XML configuration can be found indefault_1c_town01.xml.Naming ConventionFor the naming convention, we refer toMACAD-Gym. The currently provided scenarios were refactored from the same work to maintain consistency in line with the original effort in providing reproducibility and benchmarking scenarios. You can customize the configurations and eventually contribute with new configurations starting from provided XMLexamplesand respecting the current naming convention. Here is an example (reported from the officialrepo):ContributingYour effort is well appreciated. If you want to contribute to the development of Carla-gym:Fork & branchHappy coding timeCheck all is in order runningpre-commit run --all-filesMake sure all tests pass before submitting your contributionOpen a pull requestIf you have any questions, suggestions, or feedback, please feel free toopen an issue.