Getting Started

Along with our benchmark, we provide a range of tools each focusing on different aspects of motion planning for autonomous vehicles. To install all tools which are currently released on PyPi, please run:

pip install commonroad-all
To install the tools individually, please check out the tool pages on our PyPi Profile.

The following tools are currently not available on PyPi; please refer to the individual tool pages on this website for the installation instructions:
  • CommonRoad Scenario Designer
  • CommonRoad Reinforcement Learning
  • CommonRoad Search
Below, we provide minimal examples and entry-level tutorials to ease getting started with using the tools. For more advanced tutorials and further information about the tool, please have a look at the corresponding tool pages.

CommonRoad Input-Output

A comprehensive introduction to CommonRoad benchmarks can be found in our paper. In short, a benchmark consists of a scenario id, a cost function, and a vehicle model and vehicle type. The CommonRoad Input-Output package provides methods to read, write and visualize CommonRoad scenarios and planning problems. Furthermore, it can be used as a framework for implementing motion planning algorithms to solve CommonRoad Benchmarks and is the basis for other tools of the CommonRoad Framework. With CommonRoad Input-Output, solutions to benchmarks can be written as XML files for submitting them to our website.

pip install commonroad-io

A minimal example for using the package:

# import functions to read xml file and visualize commonroad objects
from commonroad.common.file_reader import CommonRoadFileReader
from commonroad.visualization.mp_renderer import MPRenderer

# generate path of the file to be opened
file_path = "ZAM_Tutorial-1_1_T-1.xml"

# read in the scenario and planning problem set
scenario, planning_problem_set = CommonRoadFileReader(file_path).open()

# plot the scenario
rnd = MPRenderer(figsize=(25, 10))
scenario.draw(rnd)
rnd.render(show=True)

CommonRoad Scenario Designer

Apart from our scenario database, we provide the CommonRoad Scenario Designer for creating new scenarios. This tool can convert maps from file formats such as OpenStreetMap and OpenDRIVE. Furthermore, it provides a graphical user interface to edit maps and scenarios manually and to populate the maps with traffic using the traffic simulator SUMO.

pip install commonroad-scenario-designer

CommonRoad-SUMO Interface & Interactive Scenarios

In interactive scenarios, other traffic participants react to the behavior of the ego vehicle. This is achieved by coupling CommonRoad with the traffic simulator SUMO. In addition to the CommonRoad-SUMO interface, we provide also interactive versions of CommonRoad scenarios.

pip install sumocr

A minimal example for using the package:

import os
from simulation.simulations import simulate_without_ego, simulate_with_solution, simulate_with_planner

path = os.path.abspath("")
# specify required arguments
name_scenario = 'DEU_Frankfurt-34_11_I-1'
folder_scenarios = os.path.join(path, 'interactive_scenarios')
path_scenario = os.path.join(folder_scenarios, name_scenario)
path_video = os.path.join(path, '../outputs/videos')
# run simulation. alternatively, use functions simulate_with_solution() and simulate_with_planner()
scenario_without_ego, pps = simulate_without_ego(interactive_scenario_path=path_scenario,
			output_folder_path=path_video,
			create_video=True)

CommonRoad Drivability Checker

In the drivability checker toolbox, we provide several tools that are commonly used in motion planning. These tools can be used to check the drivability of a trajectory, check for collisions, or to perform transformations into curvilinear coordinate systems.

pip install commonroad-drivability-checker

A minimal example for checking solutions and evaluating their costs:

from commonroad.common.file_reader import CommonRoadFileReader
from commonroad.common.solution import CommonRoadSolutionReader
from commonroad_dc.feasibility.solution_checker import obstacle_collision,
     boundary_collision, solution_feasible
from commonroad_dc.costs.evaluation import CostFunctionEvaluator

# load scenario and planning problem set
scenario, planning_problem_set = CommonRoadFileReader('Your_Scenario.xml').open()
# load solution (see commonroad-io Tutorial 2 for creating solutions)
solution = CommonRoadSolutionReader('Your_Solution.xml')

# check obstacle collisions
collision_result = obstacle_collision(scenario, planning_problem_set, solution)

# check road compliance
boundary_result = boundary_collision(scenario, planning_problem_set, solution)

# check kinematic feasibility
feasibility_result = solution_feasible(solution, scenario.dt, planning_problem_set)

# evaluate solution w.r.t. a cost function
ce = CostFunctionEvaluator.init_from_solution(solution)
cost_result = ce.evaluate_solution(scenario, planning_problem_set, solution)

CommonRoad Route Planner

The CommonRoad route planner plans high-level routes and their respective reference paths on the lanelet network of a CommonRoad scenarios. The routes and reference paths can be used motion planners (e.g. Commonroad ReactivePlanner), especially when planning in Frenet-Frame.

pip install commonroad-route-planner

A minimal code example:

# commonrad
from commonroad.common.file_reader import CommonRoadFileReader

# Own Code base
import commonroad_route_planner.fast_api.fast_api as fast_api

def main(path_to_xml: str, save_imgs: bool = False, save_path: str = ""):
    # Load the CommonRoad Scenario Object
    scenario, planning_problem_set = CommonRoadFileReader(
        f"{path_to_xml}"
    ).open()

    # retrieve the first planning problem in the problem set
    planning_problem = list(planning_problem_set.planning_problem_dict.values())[0]


    # get reference path
    reference_path = fast_api.generate_reference_path_from_lanelet_network_and_planning_problem(
               lanelet_network=scenario.lanelet_network,
               planning_problem=planning_problem
     )



if __name__ == "__main__":
    path_to_xml: str = "absolute/path/to/cr/xml.xml"
    save_path: str = "absolute/path/to/saving/dir"
    main(save_imgs=True, path_to_xml=path_to_xml)

CommonRoad Velocity Planner

The commonroad velocity planner implements several velocity profile planners for generating global reference trajectories (mission planning) used for guiding local planners, such as the commonroad-reative-planner. It uses a reference path, for example generated by the commonroad-route-planner, and assigns each point a reference trajectory. If provided, the planner also aims at keeping the speed limit of each lanelet. We provide both a planner based on convex optimization as well as one based on the race line generation based on bang-bang-control. Documentation at https://commonroad-velocity-planner-cps-commonroad-94e36f831ce3972d112f.pages.gitlab.lrz.de/

pip install commonroad-velocity-planner
from commonroad.common.file_reader import CommonRoadFileReader
from commonroad_route_planner.route_planner import RoutePlanner
from commonroad_route_planner.route import Route
from commonroad_velocity_planner.velocity_planner_interface import IVelocityPlanner
from commonroad_velocity_planner.configuration.configuration_builder import ConfigurationBuilder
from commonroad_velocity_planner.velocity_planning_problem import VppBuilder

# cr-io
scenario, planning_problem_set = CommonRoadFileReader("path/to/commonroad/xml").open()
planning_problem = list(planning_problem_set.planning_problem_dict.values())[0]

# route planner
route: Route = RoutePlanner(
    lanelet_network=scenario.lanelet_network, planning_problem=planning_problem
).plan_routes().retrieve_shortest_route()

# Velocity Planner
global_trajectory = IVelocityPlanner().plan_velocity(
    route=route,
    planner_config=ConfigurationBuilder().get_predefined_configuration(),
    velocity_planning_problem=VppBuilder().build_vpp(
        route=route, 
        planning_problem=planning_problem, 
        default_goal_velocity=planning_problem.initial_state.velocity
    )
)

CommonRoad Raceline Planner

The CommonRoad Raceline Planner combines several algorithms for raceline global trajectory planning for autonomous racing on closed tracks. Our work is based on code of the Indy Racing Team at TU Munich, namely the groups from Prof. Betz (AVS) and Prof. Lienkamp (FTM).

pip install commonroad-raceline-planner

You can find the .ini and vehicle constraint files here

from commonroad.common.file_reader import CommonRoadFileReader
from commonroad_raceline_planner.raceline import RaceLine
from commonroad_raceline_planner.raceline_fast_api import generate_ftm_minimum_curvature_raceline_from_cr

scenario, planning_problem_set = CommonRoadFileReader("PATH/TO/YOUR/SCENARIO").open()
planning_problem = list(planning_problem_set.planning_problem_dict.values())[0]

raceline: RaceLine = generate_ftm_minimum_curvature_raceline_from_cr(
                    cr_scenario=scenario,
                    planning_problem=planning_problem,
                    ini_path="PATH/TO/.ini",
                    ggv_file="PATH/TO/ggv",
                    ax_max_machines_file="PATH/TO/ENGINECONSTRAINTS",
                    show_plot=True
                )

CommonRoad Reactive-Planner

This project generates solutions to trajectory planning problems given in the CommonRoad scenario format. The trajectories are generated following the sampling-based approach in \[1\]. This approach plans motions by sampling a discrete set of trajectories, represented as quintic polynomials in a curvilinear (Frenét) coordinate frame. The sampled trajectories are checked for kinematic feasibility and collision with static/dynamic obstacles before selecting an optimal trajectory according to a given cost function. \[1\] Werling, M., et al. "Optimal trajectory generation for dynamic street scenarios in a Frenét frame." Proc. of the IEEE Int. Conf. on Robotics and Automation, 2010, pp. 987-993.

pip install commonroad-reactive-planner

A minimal example for using the package:

from commonroad_rp.reactive_planner import ReactivePlanner
from commonroad_rp.utility.config import ReactivePlannerConfiguration
from commonroad_route_planner.route_planner import RoutePlanner

# scenario filename
filename = "ZAM_Over-1_1.xml"

# Build planner configuration object (includes loading scenario)
config = ReactivePlannerConfiguration.load(f"tutorial_config_{filename[:-4]}.yaml", filename)
config.update()

# run route planner to compute route
route_planner = RoutePlanner(config.scenario, config.planning_problem)
route = route_planner.plan_routes().retrieve_first_route()

# initialize reactive planner
planner = ReactivePlanner(config)

# set reference path and desired velocity (here we just keep the current speed)
planner.set_reference_path(route.reference_path)
planner.set_desired_velocity(current_speed=planner.x_0.velocity)

# call plan function
optimal_result = planner.plan()

CommonRoad-Reach

CommonRoad-Reach is a toolbox that integrates different methods for computing reachable sets and extracting driving corridors for automated vehicles in dynamic traffic scenarios.

pip install commonroad-reach

A minimal example for using the package:

from commonroad_reach.data_structure.configuration_builder import ConfigurationBuilder
from commonroad_reach.data_structure.reach.reach_interface import ReachableSetInterface
from commonroad_reach.utility import visualization as util_visual


# build configuration
# make sure that the "scenarios" directory in your current directory contains the ARG_Carcarana-1_1_T-1 scenario
config = ConfigurationBuilder().build_configuration("ARG_Carcarana-1_1_T-1")
config.update()

# compute reachable sets using reachability interface
reach_interface = ReachableSetInterface(config)
reach_interface.compute_reachable_sets()

# plot computation results
util_visual.plot_scenario_with_reachable_sets(reach_interface)

CommonRoad-RL

This project offers a software package to solve motion planning problems on CommonRoad using reinforcement learning methods, currently based on Stable Baselines.

A minimal example for using the package:

import gym
import commonroad_rl.gym_commonroad

# kwargs overwrites configs defined in commonroad_rl/gym_commonroad/configs.yaml
env = gym.make("commonroad-v1",
		# if installed via pip add the paths to the data folders and uncomment the following two lines 
		# meta_scenario_path=meta_scenario_path, #path to meta scenario specification 
		# train_reset_config_path= training_data_path, #path to training pickels
               action_configs={"action_type": "continuous"},
               goal_configs={"observe_distance_goal_long": True, "observe_distance_goal_lat": True},
               surrounding_configs={"observe_lane_circ_surrounding": False,
               		     "fast_distance_calculation": False,
                                    "observe_lidar_circle_surrounding": True,
                                    "lidar_circle_num_beams": 20},
               reward_type="sparse_reward",
               reward_configs={"sparse_reward":{"reward_goal_reached": 50.,
                                      "reward_collision": -100.,
                                      "reward_off_road": -50.,
      					"reward_time_out": -10.,
					"reward_friction_violation": 0.}})

observation = env.reset()
for _ in range(500):
    # env.render() # rendered images with be saved under ./img
    action = env.action_space.sample() # your agent here (this takes random actions)
    observation, reward, done, info = env.step(action)

    if done:
        observation = env.reset()
env.close()

CommonRoad-CARLA Interface

This interface couples the 3D driving simulator CARLA and the CommonRoad software framework.

pip install commonroad-carla-interface

A minimal example for using the package:

from commonroad.common.file_reader import CommonRoadFileReader
from carlacr.carla_interface import CarlaInterface
from carlacr.helper.config import CarlaParams, CustomVis

# Specify CommonRoad scenario
scenario, pps = CommonRoadFileReader(cr_scenario_path := "scenarios/DEU_Test-1_1_T-2.xml").open()

# Configure simulation and scenario settings
param = CarlaParams()
param.map = cr_scenario_path
param.vis_type = CustomVis.EGO

# Execute simulation for replaying CommonRoad scenario
CarlaInterface(param).replay(scenario, ego_id=6)

CommonRoad-CriMe

CommonRoad-CriMe is a toolbox that provides a framework in Python with unified notations, vehicle models, and coordinate systems for criticality measures of autonomous vehicles.

pip install commonroad-crime

A minimal example of using the package:

from commonroad_crime.data_structure.configuration import CriMeConfiguration
from commonroad_crime.data_structure.crime_interface import CriMeInterface
from commonroad_crime.measure import (TTC, TTCStar, TTB, TTS, TTK, TTR, THW, WTTC, BTN, PF, HW,
                                      ALongReq, ALatReq, STN, P_MC, LongJ, LatJ, DeltaV)

# ==== specify scenario ID
scenario_id = "DEU_Gar-1_1_T-1"

# ==== build configuration
config = CriMeConfiguration.load(f"../config_files/{scenario_id}.yaml", scenario_id)
# or use the default one with: config = CriMeConfiguration()
config.update()
config.print_configuration_summary()

# ==== compute the criticality using CriMe interface
crime_interface = CriMeInterface(config)
crime_interface.evaluate_scenario([HW, THW, TTC, WTTC, TTCStar, TTS, TTK, TTB, TTR, ALongReq,
                                   ALatReq, LongJ, LatJ, DeltaV, BTN, STN, P_MC, PF], )  # and more ...

# ==== visualize the results for debugging and showcasing
crime_interface.visualize()

CommonRoad-Geometric

Our Python framework for graph-based autonomous driving research provides a user-friendly and fully customizable data processing pipeline for extracting PyTorch-based graph datasets from traffic scenarios. The spatiotemporal heterogeneous graph representations provided by CommonRoad-Geometric explicitly models current and historic vehicle interactions in a map-aware manner. Being based on the well-established PyTorch-Geometric framework for graph-based deep learning, our framework allows researchers to leverage cutting-edge graph neural networks to model the complex interaction effects among a varying number of traffic participants and the underlying road infrastructure, which can then be used for various downstream learning tasks such as traffic prediction and motion planning.

pip install git+https://github.com/CommonRoad/crgeo.git

Motivating example:

simulation = SumoSimulation(
    "data/osm_crawled/DEU_Munich_1-100.xml"
)
traffic_extractor = TrafficExtractor(
    simulation=simulation,
    options=TrafficExtractorOptions(
        edge_drawer=VoronoiEdgeDrawer(dist_threshold=30.0),
        #feature_computers=...
    )
)

with simulation:
    for time_step, scenario in simulation(to_time_step=200):
        data = traffic_extractor.extract(TrafficExtractionParams(
            index=time_step,
        ))
        print(data)
        print(data.vehicle.velocity)

>> CommonRoadData(scenario_id=ZAM_TMP-0_0, t=0, dt=0.04)
>>  - VirtualAttributesNodeStorage('vehicle')
>>        x: Tensor (torch.Size([1, 19]), torch.float32)
>>                  velocity: idx (0, 2)
>>                  acceleration: idx (2, 4)
>>                  ...
>>        ...
>>  - VirtualAttributesEdgeStorage(('vehicle', 'to', 'vehicle'))
>>       edge_index: Tensor (torch.Size([2, 0]), torch.int64)
>>       edge_attr: Tensor (torch.Size([0, 10]), torch.float32)
>>                  same_lanelet: idx (0, 1) 
>>                  distance: idx (1, 2)
>>                  ...
>>       ...
>>  - VirtualAttributesNodeStorage('lanelet')
>>  ...

>> tensor([[6.21., 0.], [5.12, 0.], [7.45, 0.], ...])

CommonRoad-OpenSCENARIO-Converter

Automatic Traffic Scenario Conversion between OpenSCENARIO and CommonRoad. Currently, we support the conversion direction from OpenSCENARIO to CommonROAD.

pip install commonroad-openscenario-converter

A minimal example of using the converter:

from osc_cr_converter.converter.osc2cr import Osc2CrConverter
from osc_cr_converter.utility.configuration import ConverterParams
from osc_cr_converter.utility.visualization import visualize_scenario

# scenario path and name
openscenario = 'Path_to_Your_OpenSCENARIO.xosc'

# build configuration
config = ConverterParams()

# convert OpenSCENARIO to CommonRoad
converter = Osc2CrConverter(config)
scenario = converter.run_conversion(openscenario)

# visualize the converted CommonRoad scenario
visualize_scenario(scenario, config)

CommonRoad-Autoware-Interface

Our software CR2AW builds an interface between CommonRoad and [Autoware.Universe](https://autoware.org/), to date the most popular open-source driving stack. This enables to use various motion planners using the CommonRoad format within the Autoware software stack and rapidly transfer new algorithms from simulation to a real vehicle. CR2AW is implemented as a ROS2 node which can be launched as a complete planning module within Autoware. We are currently using CR2AW to develop planning algorithms for our TUM research vehicle [EDGAR](https://arxiv.org/pdf/2309.15492). For setup and usage instructions, please refer to the README of the [repository](https://github.com/CommonRoad/commonroad-autoware-interface).