{"id":19130064,"url":"https://github.com/mathworks/deep-traffic-lab","last_synced_at":"2025-05-06T00:53:29.866Z","repository":{"id":92436029,"uuid":"407625339","full_name":"mathworks/deep-traffic-lab","owner":"mathworks","description":null,"archived":false,"fork":false,"pushed_at":"2024-01-22T14:59:41.000Z","size":24952,"stargazers_count":22,"open_issues_count":1,"forks_count":10,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-05-06T00:53:22.662Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"MATLAB","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mathworks.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"license.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-09-17T17:23:25.000Z","updated_at":"2024-09-26T02:13:21.000Z","dependencies_parsed_at":"2025-04-19T06:48:44.120Z","dependency_job_id":null,"html_url":"https://github.com/mathworks/deep-traffic-lab","commit_stats":{"total_commits":2,"total_committers":2,"mean_commits":1.0,"dds":0.5,"last_synced_commit":"d341dc1a44d7dcc7b8b8aff83262f02d60ac6e6e"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mathworks%2Fdeep-traffic-lab","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mathworks%2Fdeep-traffic-lab/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mathworks%2Fdeep-traffic-lab/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mathworks%2Fdeep-traffic-lab/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mathworks","download_url":"https://codeload.github.com/mathworks/deep-traffic-lab/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252601681,"owners_count":21774659,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-09T06:09:26.040Z","updated_at":"2025-05-06T00:53:29.571Z","avatar_url":"https://github.com/mathworks.png","language":"MATLAB","funding_links":[],"categories":[],"sub_categories":[],"readme":" \n# **Deep Traffic Lab** \n\nDeep Traffic Lab (DTL) is an end-to-end learning platform for traffic navigation based on MATLAB\u0026reg;. DTL uses the Automated Driving Toolbox\u0026trade; from MATLAB, in conjunction with several other toolboxes, to provide a platform using a cuboid world that is suitable to test learning algorithms for Autonomous Driving. Additionally, DTL uses SUMO traffic simulator to model and define road traffic actors on the simulator so the user can focus on providing a solution for the Ego Vehicle.\n\nAdditionally, DTL simulator provides an out-of-the-box environment compatible with the Reinforcement Learning Toolbox\u0026trade; from MATLAB that allows the user to easily train a \"ego vehicle\" agent on how to navigate traffic. Similarly, DTL allows the user to define his own controller algorithms for autonomous driving in any traffic situation by letting the user create their own road topologies, and define traffic interactions. \n\nDTL defines \"ego vehicles\" within MATLAB and updates the ego vehicles' states on SUMO to simulate traffic interations. Similarly,  DTL syncronizes vehicles defined within SUMO ecosystems with MATLAB driving scenario actors to define and control road traffic actors. \n\nIn order to provide custom topologies interactively, Deep Traffic Lab uses **Driving Scenario Designer Application** to provide a driving scenario and a road topology that is later converted to a SUMO .net file using an OpenDRIVE\u0026reg; export file and SUMO's [netconvert](https://sumo.dlr.de/docs/netconvert.html). For more information refer to  the documentation  [here](https://www.mathworks.com/help/driving/ref/drivingscenariodesigner-app.html).\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"./figures/AppleHill.gif\" alt=\"logo\"  width = \"1000\"/\u003e\n\u003c/p\u003e\n\n## MATLAB\u0026reg; Toolbox Dependencies\nRequires MATLAB release R2021a or newer with the following toolboxes:\n- [Automated Driving Toolbox\u0026trade;](https://www.mathworks.com/products/automated-driving.html)\n- [Navigation Toolbox\u0026trade;](https://www.mathworks.com/products/navigation.html#:~:text=Navigation%20Toolbox%E2%84%A2)\n- [Robotics Systems Toolbox\u0026trade;](https://www.mathworks.com/products/robotics.html)\n- [Image Processing Toolbox\u0026trade;](https://www.mathworks.com/products/image.html)\n- [Computer Vision Toolbox\u0026trade;](https://www.mathworks.com/products/computer-vision.html)\n- [Sensor Fusion and Tracking Toolbox\u0026trade;](https://www.mathworks.com/products/sensor-fusion-and-tracking.html)\n- [Reinforcement Learning Toolbox\u0026trade;](https://www.mathworks.com/products/reinforcement-learning.html)\n- [Deep Learning Toolbox\u0026trade;](https://www.mathworks.com/products/deep-learning.html)\n\n## Third Party Products:\nDeep Traffic Lab uses the following external dependencies \n- [SUMO](https://eclipse.dev/sumo/) (1.9.2 or newer)\n- [TraCI4Matlab](https://www.mathworks.com/matlabcentral/fileexchange/44805-traci4matlab)\n- [INPOLY](https://github.com/dengwirda/inpoly)\n\n**NOTE:** Currently Deep Traffic Lab supports Windows 10 only. Support for macOS and Linux will come in the future.\n\n## Setup \nTo install:\n1. Install SUMO 1.9.2 or newer ([instructions](https://sumo.dlr.de/docs/Installing/index.html)) \n2. Configure SUMO_HOME as an environment variable ([instructions](https://sumo.dlr.de/docs/Basics/Basic_Computer_Skills.html#windows))\n3. Clone Git repository\n```\ngit clone \u003c[URL to Git repo]\u003e\n```\n4. Initialize submodules by running\n```\ngit submodule update --init\n```\n5. Open MATLAB\n6. Navigate to Open Traffic Lab repository\n7. Run ./scripts/install.m\n\n**Note:** Step 7 needs to be run every time that the MATLAB path resets\n\n## Getting Started \n\nDeep traffic lab follows the workflow as shown below:\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"./figures/Workflow.PNG\" alt=\"workflow\"  /\u003e\n\u003c/p\u003e\n\n\n### *Reinforcement Learning:*\nIn order to run a reinforcement learning training, the user can refer to the [example](./Example/StraightHighwayDiscreteMetaAction/main.m) that comes with this repository. \n\nTo be able to run a reinforcement learning training, the user needs to define a MATLAB compatible environment. This can be done by modifying the template environment that comes with this repository ([DiscreteHighwayEnvironment.m](Example/StraightHighwayDiscreteMetaAction/DiscreteHighwayEnvironment.m)) and  can be used as template to modify and use custom applications as needed by user.\n\nThe provided example comes with a default .json configuration for Ego Vehicles and for traffic vehicles. However, if needed the user can modify the configuration files by modifying the provided templates to define [EgoVehicles](Example\\StraightHighwayDiscreteMetaAction\\SingleEgoMinimalSensorsConfigTemplate.m) and to define [TrafficVehicles](Example/StraightHighwayDiscreteMetaAction/TrafficConfigTemplate.m). \n\nAdditionally, inside the EgoConfig.json file, the user needs to properly define the sensors to be used by the Ego Vehicle. For a list of available sensors, refer to the [EgoTemplate](ConfigurationTemplates/TwoEgoSensorsConfigTemplate.m) file, where an array of Cameras, Lidars, and Radars are defined. These sensors will be used as part of the observation space for the reinforcement learning environment.\n\nFor more details on how to generate a neural netrwork for your RL agent, please see [here](https://www.mathworks.com/help/reinforcement-learning/ug/create-agent-using-deep-network-designer-and-train-using-image-observations.html)\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"./Example/StraightHighwayDiscreteMetaAction/result/result_media/result.gif\" alt=\"RL Training\"  /\u003e\n\u003c/p\u003e\n\n***Note:*** Despite the ability to define more than just one ego vehicle, Deep Traffic Lab does not support multi-agent reinforcement learning training at the moment since current support for multi-agent environment training is done using Simulink\u0026reg;. Official support from Deep Traffic Lab for multi-agent may come in the future\n### *Discrete/Continuous Control:*\nDeep Traffic Lab can be used with a control mechanism instead of a learning mechanism. In [this](TestScripts\\TestContinuousModelStanley\\TestModelStanleyController.m) example, a stanley controller is used on the ego vehicle. The controlled vehicle uses a discrete bicycle model to follow a set of waypoints on a straight road.\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"./figures/Stanley/stanleyGif.gif\" alt=\"Stanley Controller\"  /\u003e\n\u003c/p\u003e\n\n### *Defining Custom Networks:*\nDeep Traffic Lab uses [Driving Scenario Designer App](https://www.mathworks.com/help/driving/ref/drivingscenariodesigner-app.html) to define roads interactively. To define custom scenarios follow the instructions depicted below\n\n1. Create the road topology as described [here](https://www.mathworks.com/videos/driving-scenario-designer-1529302116471.html)\n2. If a straight road is defined, it is a good practice to split the roads into more than one segments to be able to define routes laters\n3. Export scenario into MATLAB function \n4. Export road topology to OpenDRIVE\n\u003cp align=\"center\"\u003e  \n\u003cimg src=\"./figures/CustomTopologyInstructions/1.PNG\" width = \"1200\"\u003e\n\u003c/p\u003e\n\n4. Open [scripts/GenerateEnvrionmentFiles.m](scripts/GenerateEnvironmentFiles.m) \n5. Specify paths to generated .xodr files and target folders to generate network files\n\n\u003cp align=\"center\"\u003e  \n\u003cimg src=\"./figures/CustomTopologyInstructions/2.PNG\" width = \"1200\"\u003e\n\u003c/p\u003e\n\n6. First, a SUMO .net.xml file will be created using SUMO's [netconvert](https://sumo.dlr.de/docs/netconvert.html) tool. After the conversion, SUMO's [Netedit](https://sumo.dlr.de/docs/Netedit/index.html#changing_connections]) will pop up.\n7. Define traffic rules such as speed limits, and allowed vehicles on each road as shown below\n\n\u003cp align=\"center\"\u003e  \n\u003cimg src=\"./figures/CustomTopologyInstructions/3.PNG\" width = \"1200\"\u003e\n\u003c/p\u003e\n\n\n8. Go to Demand tab inside of NETEDIT\n9. Select Route icon \n10. Define available routes by selecting edges\n\n\u003cp align=\"center\"\u003e  \n\u003cimg src=\"./figures/CustomTopologyInstructions/4.PNG\" width = \"1200\"\u003e\n\u003c/p\u003e\n\n10.  If a route should be exclusively defined for ego vehicles, define the route ID as \"ego_route\". Deep Traffic Lab will only spawn ego_vehicles within this route\n10. Save network and route file as \"network.net.xml\" and \"Routes.rou.xml\" respectively\n11. In order to be able to use the newly created environment, a SUMO configuration file needs to be created. The user can modigy the [.sumocfg](highwayConfiguration.sumocfg) file that comes with this repository. For more information on how to create a .sumocfg file please refer to SUMO documentation.\n\n### *Defining Configuration Files:*\n\nDeep Traffic Lab uses a SUMO configuration file to call the corresponding SUMO network and route files (see SUMO documentation for more information). However, in order to specify the details and configurations for the Ego Vehicles and Traffic Vehicles, DTL uses .json files as a standard. In order to create the JSON configuration files, a template script is provided for the Ego Vehicles and Traffic Vehicles respectively. For more information on how to use them, please go to [ConfigurationTemplates](ConfigurationTemplates) folder.\n\nThe overall structure of each configuration file is shown as follows:\n\n\u003cp align=\"center\"\u003e  \n\u003cimg src=\"./figures/trafficJson.PNG\" width = \"1200\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e  \n\u003cimg src=\"./figures/egoJson.PNG\" width = \"1200\"\u003e\n\u003c/p\u003e\n\nAn example of two ego configuration files is shown as follows:\n\n\u003cp align=\"center\"\u003e  \n\u003cimg src=\"./figures/egoJsonEg.PNG\" width = \"1200\"\u003e\n\u003c/p\u003e\n\n### *Defining Traffic Environment:*\nIn order to be able to run Deep Traffic Lab, the simulator requires a set of configuration files in addition to the simulation StopTime, SampleTime, and a boolean indicating if SUMO gui should be invoqued as shown on the code snippet below. \n```\nscenario = highwayStraight();\nSampleTime = 0.1; %[sec]\nStopTime = SampleTime*1000; %[sec]\n```\n```\nhighwayEnv = TrafficEnvironment(scenario, ...\n    sumoConfigFile, ...\n    egoConfigFile,...\n    trafficConfigFile,...\n    StopTime,...\n    'SampleTime', SampleTime,...\n    'SumoVisualization', true);\n```\n\nThe variable \"scenario\" corresponds to the road topology defined programmatically or using Driving Scenario Designer App and describes the same road topology that is used by SUMO. Make sure that the .sumocfg file routes and network correspond to the same network.\n\nAfter *\"TrafficEnvrionment\"* has been defined, the user can call a visualization of the environment by choosing a vehicle randomly \n\n```\nhighwayEnv.create_random_visualization;\n```\nor by calling the name of an specific vehicle \n\n```\nhighwayEnv.create_chase_visualization('ego01');\n```\n\n\u003cp align=\"center\"\u003e  \n\u003cimg src=\"./figures/visualizationEgo.png\"\u003e\n\u003c/p\u003e\n\nIn order to deploy traffic, the following member method can be called\n\n```\n[hasBeenCreated, numberOfTrafficActors, egos] = highwayEnv.deploy_traffic();\n```\n\n*\"deploy_traffic\"* method, as it names suggests, deploys traffic on the scenario. Additionally, it returns the following parameters: \n\n- *hasBeenCreated:* boolean that specifies wether the creation of the environment has been successfull\n- *numberOfTrafficActors:* Integer describing how many actors were created\n- *egos:* a cell list that contains a handle to the ego vehicles. Using this handle, the user can monitor the ego states, current status, and call the step function for the ego, which takes a control input as its parameters\n\nAdditionally, when *\"deploy_traffic\"* method is called, the current traffic is despawned, so this method also works as a reset function.\n\n## Examples\nTo learn how to use this in testing workflows, see [Examples](/examples/) or [TestScripts](TestScripts/). \n\n## Architecture\nDeep Traffic Lab uses three main classes that define the architecture of the environment without taking into account the RLEnv class which serves as template for the users to define an environment according to their needs. The functionality of each class is described below.\n\n- **TrafficEnvironment:** This class is the one in charge to define the connection between the environment in MATLAB and SUMO respectively. Additionally, it uses the configuration files, specified by the user, to create and deploy traffic according to the specifications from the user. This class is also in charge of creating chase plot visualizations within the driving scenario in MATLAB. *TraffiicEnvironment* allows the user to define the lane changing model within SUMO, this can be a sublane model, or a prespecified fixed time lane changing time window. For more details refer to [SUMO Documentations](https://sumo.dlr.de/docs/Simulation/SublaneModel.html) and the [Class Documentation](lib/@TrafficEnvironment/TrafficEnvironment.m) on the constructor method.\n- **TrafficVehicle:** This class represent each of the vehicles in the simulation. Thus, it is in charge of defining the physical properties of the vehicle in the simulation and synchronize it between SUMO and MATLAB. Due to the architecture from Driving Scenario World in MATLAB, actors in MATLAB that have finished their route in SUMO, are placed in a location far away from the scenario. *TrafficVehicle* class recycles \"despawned\" vehicles when a new instance of a vehicle is created inside SUMO.\n- **EgoVehicle:** This class inherits from *TrafficVehicle* class and uses the same methods as the parent class. However, this class is also in charge of defining the vehicle model (SUMO, Bicycle) used to control the \"Ego Vehicles\" using the defined action space (DiscreteMeta-Action, Discrete, Continuous) specified by the user on the configuration files. Additionally, this class is in charge of defining the sensors and observations that the ego vehicle will use during the simulation (ideal, lidar, radar, camera, occupancy grid).\n\nA diagram with the public methods that each class uses is shown below\n\n\u003cp align=\"center\"\u003e  \n\u003cimg src=\"./figures/class.PNG\" width=\"1500\"\u003e\n\u003c/p\u003e\n\nSimilarly, the initialization architecture for Deep Traffic Lab is described on the diagram below\n\n\u003cp align=\"center\"\u003e  \n\u003cimg src=\"./figures/initializationArch.PNG\" width=\"1500\"\u003e\n\u003c/p\u003e\n\nwhere the available options are as follows\n\u003cp align=\"center\"\u003e  \n\u003cimg src=\"./figures/initializationArchOptions.PNG\" width=\"1500\"\u003e\n\u003c/p\u003e\n\nOnce the environment has been fully specified, the runtime synchronization is described on the diagram below\n\u003cp align=\"center\"\u003e  \n\u003cimg src=\"./figures/RuntimeArch.PNG\" width=\"1500\"\u003e\n\u003c/p\u003e\n\n\n\n## Current Limitations\n- RL training only supports single agent environments\n- Parallel training of RL Agents is not currently supported \n- The specified number of traffic actors withing trafficConfig.json file, may differ from the actual number of spawned vehicles due to space limitations inside of road\n- SUMO road topologies might differ from MATLAB road topologies due to issues when exporting Driving Scenario Designer topology to OpenDRIVE's .xodr file. For more information see [here](https://www.mathworks.com/help/driving/ref/drivingscenario.export.html#mw_fea198e6-827f-49bd-a1f5-4c953b2139b1).\n- SUMO induction loops, or flows are not supported\n- Lidar point clouds might throw an error due a bug. This bug has been fixed for future releases (MATLAB r2021b)\n- When defining a continuous model for the ego vehicle, there exist a two step delay on the Ego Vehices due to synchronization architecture between SUMO and DSD. Thus, it is advised to use a small time step\n\n\n\n## License\nThe license for Deep Traffic Lab is available in the [LICENSE.TXT](LICENSE.TXT) file in this GitHub repository.\n\n## Community Support\n[MATLAB Central](https://www.mathworks.com/matlabcentral)\n\nCopyright 2021 The MathWorks, Inc.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmathworks%2Fdeep-traffic-lab","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmathworks%2Fdeep-traffic-lab","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmathworks%2Fdeep-traffic-lab/lists"}