Tactics2D: A Reinforcement Learning Environment Library for Driving Decision-making
EN | CN
About
[!note] This is the official codebase for Course AU7043 in Shanghai Jiao Tong University under branch
AU7043.
tactics2d is an open-source Python library that provides diverse and challenging traffic scenarios for the development and evaluation of reinforcement learning-based decision-making models in autonomous driving. tactics2d stands out with the following key features:
- Compatibility
- 📦 Trajectory dataset -- Enables seamless importation of various real-world trajectory datasets, including Argoverse, Dragon Lake Parking (DLP), INTERACTION, LevelX Series (HighD, InD, RounD, ExiD), NuPlan, and Waymo Open Motion Dataset (WOMD), encompassing both trajectory parsing and map information.
- 📄 Map format -- Enables parsing and conversion of commonly used open map formats like OpenDRIVE, Lanelet2-style OpenStreetMap (OSM), and SUMO roadnet.
- Customizability
- 🚗 Traffic participants -- Supports the creation of new traffic participant classes with customizable physical attributes, physics dynamics/kinematics models, and behavior models.
- 🚧 Road elements -- Support the definition of new road elements, with a focus on regulatory aspects.
- Diversity
- 🛣️ Traffic scenarios -- Features an extensive range of built-in Gym-style traffic scenarios, including highway, lane-merging, unsignalized/signalized intersection, roundabout, parking, and racing.
- 🚲 Traffic participants -- Features a variety of built-in traffic participants with realistic physics parameters, detailed further here.
- 📷 Sensors -- Provides bird's-eye-view (BEV) semantic segmentation RGB image and single-line LiDAR point cloud for model input.
- Visualization -- Offers a user-friendly visualization tool for real-time rendering of traffic scenarios and participants, along with the capability to record and replay traffic scenarios.
- Reliability -- Over 85% code is covered by unit tests and integration tests.
For further information on tactics2d, please refer to our comprehensive documentation, and a detailed comparison with other similar libraries is available here.
Community
We have a Discord Community for support. Feel free to ask questions. Posting in Github Issues and PRs are also welcome.
Installation
0. System Requirements
We have conducted testing for the execution and construction of tactics2d on the following platforms:
Note: The matrix below reflects versions covered by the
test_modulesCI workflow.
| System | 3.8 | 3.9 | 3.10 | 3.11 | 3.12 | 3.13 |
|---|---|---|---|---|---|---|
| Ubuntu 18.04 | :white_check_mark: | - | - | - | - | - |
| Ubuntu 20.04 | :white_check_mark: | :white_check_mark: | - | - | - | - |
| Ubuntu 22.04 | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| Ubuntu 24.04 | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| Windows | - | - | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| macOS | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
1. Installation
We strongly recommend using conda to manage the Python environment. If you don't have conda installed, you can download it from here.
# create a new conda environment
conda create -n tactics2d python=3.9
conda activate tactics2d
1.1 Install from PyPI
You can simply install tactics2d from PyPI with the following command.
pip install tactics2d
1.2 Install from Github
You can also install tactics2d from its source on GitHub. This way is recommended if you want to run the sample code or contribute to the development of tactics2d. Please note that you should have GCC installed on your operating system before installing tactics2d.
# clone the repository with submodules but ignore the large files (mainly the NuPlan's map data)
# please download NuPlan's map data from its official website and put it in the `tactics2d/data/map/NuPlan` directory
git clone --recurse-submodules git@github.com:WoodOxen/tactics2d.git
cd tactics2d
pip install -v .
If no errors occur, you should have installed tactics2d successfully.
2. Dataset Preparation
According to the licenses of the trajectory datasets, we cannot distribute the original datasets with tactics2d. You need to download the datasets from their official websites. Currently, tactics2d supports the following datasets:
- Argoverse 2
- Dragon Lake Parking (DLP)
- HighD
- InD
- RounD
- ExiD
- INTERACTION
- NuPlan
- Waymo Open Motion Dataset v1.2 (WOMD)
You can put the downloaded files at whatever location you like. In the parser, you can specify the path to the dataset.
3. Run the Tutorial
After the installation, you can run the tutorial jupyter notebooks to get started with tactics2d.
To run train_parking_demo.ipynb, which is a simplified version of our work in this paper, you need to pull an extra module rllib:
git submodule update --init --recursive
4. For More Samples
We have built a complete CI pipeline for tactics2d. The samples under tests are good samples for you to get familiar with the interfaces. To run the samples, you can use the following command:
pip install pytest
pytest tests/[test_file_name]::[test_function_name]
Demo
tactics2d supports the parsing of various real-world trajectory datasets, including Argoverse, Dragon Lake Parking (DLP), INTERACTION, LevelX Series (highD, inD, rounD, ExiD), NuPlan, and Waymo Open Motion Dataset (WOMD). For more demos, please refer to the documentation.
Highway cases
| HighD (Location 3) | ExiD (Location 6) |
|---|---|
Intersection cases
| InD (Location 4) | Argoverse |
|---|---|
| INTERACTION | WOMD |
|---|---|
Roundabout cases
| RounD (Location 0) | INTERACTION |
|---|---|
Parking cases
| DLP | Self-generated |
|---|---|
|
Coming soon |
Racing cases (Self-generated)
Citation
If you find tactics2d useful, please cite this in your publication.
@article{li2024tactics2d,
title={Tactics2D: A Highly Modular and Extensible Simulator for Driving Decision-Making},
author={Li, Yueyuan and Zhang, Songan and Jiang, Mingyang and Chen, Xingyuan and Yang, Jing and Qian, Yeqiang and Wang, Chunxiang and Yang, Ming},
journal={IEEE Transactions on Intelligent Vehicles},
year={2024},
publisher={IEEE}
}
Works Based on Tactics2D
You are welcome to raise pull request and update your publication based on Tactics2D.
Jiang, Mingyang*, Li, Yueyuan*, Zhang, Songan, et al. "HOPE: A Reinforcement Learning-based Hybrid Policy Path Planner for Diverse Parking Scenarios." IEEE Transactions on Intelligent Transportation Systems (2025). (*Co-first author) | Code | Demo