Getting Started

This manual introduces the main functionality by means of some examples. Exact class descriptions can be found in the module descriptions.

CommonRoad XML-files consist of a Scenario and a PlanningProblemSet. A Scenario represents the environment including a LaneletNetwork and a set of DynamicObstacle and StaticObstacle. A LaneletNetwork is built from lane segments (Lanelet), that can be connected arbitrarily. A PlanningProblemSet contains one PlanningProblem for every ego vehicle in the Scenario, consisting of an initial State and a GoalRegion that has to be reached.

For detailed information, see XML CommonRoad Documentation.

Reading Files

Description: commonroad.common.file_reader.

The CommonRoadFileReader reads the Scenario and the PlanningProblemSet from a CommonRoad XML-file:

import os
import matplotlib.pyplot as plt

from commonroad.common.file_reader import CommonRoadFileReader
from commonroad.visualization.draw_dispatch_cr import draw_object

file_path = os.path.join(os.getcwd(), 'scenarios/NGSIM/Lankershim/USA_Lanker-1_1_T-1.xml')

scenario, planning_problem_set = CommonRoadFileReader(file_path).open()

plt.figure(figsize=(25, 10))

An intersection scenario USA_Lanker-1_1_T-1 from CommonRoad

Per default, the first time step of the scenario is plotted. Please note that within all modules of CommonRoad the time is discretized and only discrete time steps are used. To plot the scenario at another time index, draw parameters can be defined:

draw_parameters = {'time_begin': 10}

plt.figure(figsize=(25, 10))
draw_object(scenario, draw_params=draw_parameters)

For more details on plotting options see Visualization Manual.


Description: commonroad.scenario.scenario.

Reading a CommonRoad XML-file with the CommonRoadFileReader returns an instance of class Scenario. This instance contains all information about the road network and surrounding obstacles.

Additionally, the scenario can be modified or new scenarios can be created.

E.g. scenarios can be translated and rotated:

import numpy as np

translation = np.array([0.0, 0.0])
angle = np.pi/2

scenario.translate_rotate(translation, angle)
planning_problem_set.translate_rotate(translation, angle)

plt.figure(figsize=(25, 10))

scenario rotated 90 deg counter-clockwise

Note that all other objects (obstacles, lanelets, planning problems, goal regions, occupancies, trajectories, …) can be translated and rotated as well.

Other useful methods for trajectory planning are:

Lanelet Network

Description: commonroad.scenario.lanelet.

Each Lanelet stores its left and right boundary and its center by a polyline (a list of vertices). If a lanelet A is the successor of another lanelet B, the first (center/left/right) point of A coincides with the last (center/left/right) point of B. More necessary conditions on lanelets can be found in the XML CommonRoad Documentation.

Useful methods for trajectory planning are:


Description: commonroad.scenario.obstacle

Obstacles in CommonRoad have an unique ID, an ObstacleRole (static or dynamic), an ObstacleType (e.g. car, pedestrian, parked vehicle, construction zone, …), a Shape (e.g. rectangle, polygon, …), and an initial State.

While a StaticObstacle is only described by those attributes, a DynamicObstacle has additionally a prediction that defines its predicted dynamic behavior.

Useful methods for trajectory planning are:

Dynamic Obstacle Prediction

Description: commonroad.prediction.prediction.

Every DynamicObstacle has a TrajectoryPrediction or a SetBasedPrediction. Each prediction contains an Occupancy set that represents the two-dimensional occupancy of the obstacle over time.

Each of the given XML scenarios provides exactly one type of prediction for all dynamic obstacles.

Trajectory Prediction

Description: TrajectoryPrediction.

This prediction corresponds to the most likely trajectory of the obstacle. The Trajectory consists of a list of State and an initial time step. The occupancy is calculated by forwarding the shape of the Obstacle along the Trajectory.

Set Based Prediction

Description: SetBasedPrediction.

This prediction stores the occupied area of the obstacle over time as bounded sets.

Planning Problems

Description: PlanningProblem.

To solve a scenario, one has to find solutions to all problems in the PlanningProblemSet. Every PlanningProblem corresponds to one ego vehicle. It consists of an initial state for the ego vehicle and a GoalRegion which the ego vehicle has to reach. A GoalRegion is a collection of different goal states (e.g. position region in form of an arbitrary Shape or a list of Lanelet objects, velocity interval, time interval, orientation interval,…).

Checking if a GoalRegion is reached works as follows:

from commonroad.planning.goal import GoalRegion
from commonroad.common.util import Interval, AngleInterval
from commonroad.scenario.trajectory import State

# define example goal region
goal_state_1 = State(time_step=Interval(3, 5), orientation=AngleInterval(0.1, 1), velocity=Interval(20, 30.5))
goal_state_2 = State(time_step=Interval(3, 6), orientation=AngleInterval(0.1, 1), velocity=Interval(15, 25.5))

goal_region = GoalRegion([goal_state_1, goal_state_2])

# state of the ego vehicle
state = State(time_step=3, orientation=0.5, velocity=25)

# check if the state is inside of the goal region

Other useful methods:

Writing Files

Description: commonroad.common.file_writer.

The CommonRoadFileWriter writes a Scenario and a PlanningProblemSet to a CommonRoad XML-file:

from commonroad.common.file_writer import CommonRoadFileWriter
from commonroad.common.file_writer import OverwriteExistingFile

fw = CommonRoadFileWriter(scenario, planning_problem_set, "author", "affiliation", "source", "tags")

filename = "filename.xml"

fw.write_to_file(filename, OverwriteExistingFile.ALWAYS)

Solution Writer

Description: commonroad.common.solution_writer.

To upload a solution to one can either submit data in form of a Trajectory or as a list of control inputs. The CommonRoadSolutionWriter creates an XML file according to the given XML schema definition including an attribute with the correct benchmark ID. In order to do so, the scenario ID, the VehicleType, the VehicleModel, and the CostFunction have to be given.

A solution (trajectory or control input vector) can be written as XML file in the following way:

import os

from commonroad.common.solution_writer import CommonRoadSolutionWriter, VehicleModel, VehicleType, CostFunction
from commonroad.scenario.trajectory import Trajectory, State

# prepare trajectory
pm_state_list = list()
for i in range(10):
    pm_state_list.append(State(**{'position': np.array([i, -i]), 'velocity': i*.2, 'velocity_y': i*0.001, 'time_step': i}))
trajectory_pm = Trajectory(0, pm_state_list)

# prepare control input vector (list of [x_acceleration, y_acceleration, time])
pm_input_list = np.array([[1.0, 3.5, 0.0], [2.0, 2.5, 0.1], [3.0, 1.5, 0.2]])

# write solution to a xml file
csw = CommonRoadSolutionWriter(output_dir=os.getcwd(), scenario_id='test_scenario', step_size=0.1,
                               vehicle_type=VehicleType.BMW_320i, vehicle_model=VehicleModel.PM,
# add trajectory solution
csw.add_solution_trajectory(trajectory_pm, planning_problem_id=5)

# or add control vector solution
csw.add_solution_input_vector(pm_input_list, planning_problem_id=8)