8.12 Road abstraction classes

8.12.1 Class definitions

8.12.2 Actor map

A map is the top-level actor that contains the description of the abstract road network.

Basic information

Table 184. Basic information of actor map
Parents	osc_actor
Used by	OpenSCENARIO

Parameters

Table 185. Actor map
Parameter	Type	Mandatory	Description
map_file	string	no	Name of the external map file
routes	list of route	yes	The list of routes that are part of the abstract road network
junctions	list of junction	yes	The list of junctions that are part of the abstract road network
driving_rule	driving_rule	yes	Specify on which side of the road the vehicles drive
traffic_light_groups	list of traffic_light_group	no	All the traffic lights in the map
traffic_light_control	list of traffic_light_cycle	no	The traffic light cycle for traffic light groups. It does not necessarily contain control plans for all elements in traffic light groups and may also be empty.

8.12.2.1 Methods

8.12.2.1.1 Method odr_to_route_point()

Takes a position in ASAM OpenDRIVE coordinates and returns the corresponding ASAM OpenSCENARIO route-coordinates for the point. The method returns an error if the point is not on a route.

Prototype

extend map:
    def odr_to_route_point(road_id: string, lane_id: string, s: length, t: length) -> route_point

Return value

Returns a route_point.

Parameters

Table 186. Parameters for method odr_to_route_point()
Parameter	Type	Description
road_id	string	ASAM OpenDRIVE roadId
lane_id	string	Optional. ASAM OpenDRIVE laneId. If omitted, the t-coordinate is measured from the ASAM OpenDRIVE road reference line. If included, the t-coordinate is measured from the ASAM OpenDRIVE lane centerline of the lane.
s	length	The s-coordinate in ASAM OpenDRIVE coordinates
t	length	The t-coordinate in ASAM OpenDRIVE coordinates

8.12.2.1.2 Method xyz_to_route_point()

Takes a position in world coordinates and returns the corresponding ASAM OpenSCENARIO route-coordinates for the point. If the point is not on a route, returns with an error.

Prototype

extend map:
    def xyz_to_route_point(x: length, y: length, z: length) -> route_point

Return value

Returns a route_point.

Parameters

Table 187. Parameters for method xyz_to_route_point()
Parameter	Type	Description
x	length	The x-coordinate in the world-coordinate system.
y	length	The y-coordinate in the world-coordinate system.
z	length	The z-coordinate in the world-coordinate system.

8.12.2.1.3 Method route_point_to_xyz()

Converts the coordinates specified in route-coordinates into the corresponding world-coordinates. Returns a route point in Cartesian (x, y, z) coordinates.

Prototype

extend map:
    def route_point_to_xyz(route_point: route_point) -> xyz_point

Return value

Returns an xyz_point.

Parameters

Table 188. Parameters for method route_point_to_xyz()
Parameter	Type	Description
route_point	route_point	ASAM OpenSCENARIO route_point to be converted.

8.12.2.1.4 Method outer_side()

Farther from opposing traffic.

Prototype

extend map:
    def outer_side() -> side_left_right

Return value

Returns right if map.driving_rule is right_hand_traffic, left otherwise.

8.12.2.1.5 Method inner_side()

Closer to opposing traffic.

Prototype

extend map:
    def inner_side() -> side_left_right

Return value

Returns left if map.driving_rule is right_hand_traffic, right otherwise.

8.12.2.1.6 Method create_route()

Creates a compound_route that contains all the provided route instances, in the same sequential order as the input list. Routable point types are connected according to the connect_points_by argument. If the connect_points_by field is empty, this method defaults to the option waypoint.

Prototype

extend map:
    def create_route(routes: list of route, connect_points_by: connect_route_points, legal_route: bool) -> compound_route

Return value

Returns a compound_route that contains all the specified routes.

Parameters

Table 189. Parameters for method create_route()
Parameter	Type	Description
routes	list of route	The route instances to be combined to form the new compound_route.
connect_points_by	connect_route_points	Defines how to connect the points in the list of route. Default: waypoint.
legal_route	bool	The compound route only contains legal route elements. Default: true.

When actors are placed on lanes with no inherent traffic flow direction, like a sidewalk, the initial orientation of the actor within this lane might be ambiguous. In this case, it is suggested to use two instances of route_point to disambiguate the preferred initial orientation of the actor. The example below demonstrates a pedestrian walking across sidewalk_1 (in the positive t-direction) before taking the crosswalk towards sidewalk_2.

Syntax

Code 74. Syntax example

map: map
my_cross: crossing
sidewalk_1, sidewalk_2: lane
map.crossing_connects(my_cross, sidewalk_1, sidewalk_2, start_s_coord: 5.0m)

sw_pt_1: route_point with:
        keep(it.route == sidewalk_1)
        keep( it.s ==  5.0m)
        keep( it.t == -1.0m)

sw_pt_2: route_point with:
        keep(it.route == sidewalk_1)
        keep( it.s == 5.0m) # same s-coordinate as sw_pt_1
        keep( it.t == 0.5m)  # t-coordinate to the left of sw_pt_1

create_route([sw_pt_1, sw_pt_2, my_cross, sidewalk_2])

The below example demonstrates a pedestrian walking along sidewalk_1 in negative s-direction before taking the crosswalk towards sidewalk_2.

Code 75. Syntax example

map: map
my_cross: crossing
sidewalk_1, sidewalk_2: lane
map.crossing_connects(my_cross, sidewalk_1, sidewalk_2, start_s_coord: 5.0m)

sw_pt_1: route_point with:
    keep(it.route == sidewalk_1)
    keep(it.s == 10.0m)
    keep(it.t == 0.0m)

sw_pt_2: route_point with:
    keep(it.route == sidewalk_1)
    keep(it.s == 5.0m) # s-coordinate smaller than sw_pt_1
    keep(it.t == 0.0m) # same t-coordinate as sw_pt_1

create_route([sw_pt_1, sw_pt_2, my_cross, sidewalk_2])

8.12.2.1.7 Method create_route_point()

Creates a route_point.

Prototype

extend map:
    def create_route_point(route: route, s: length, t: length) -> route_point

Return value

Returns a route_point.

Parameters

Table 190. Parameters for method create_route_point()
Parameter	Type	Description
route	route	The route where the point resides
s	length	s-coordinate in the route
t	length	t-coordinate in the route

8.12.2.1.8 Method create_xyz_point()

Creates an xyz_point.

Prototype

extend map:
    def create_xyz_point(x: length, y: length, z: length) -> xyz_point

Return value

Returns an xyz_point.

Parameters

Table 191. Parameters for method create_xyz_point()
Parameter	Type	Description
x	length	x-coordinate in world-coordinate system
y	length	y-coordinate in world-coordinate system
z	length	z-coordinate in world-coordinate system

8.12.2.1.9 Method create_odr_point()

Creates an odr_point.

Prototype

extend map:
    def create_odr_point(road_id: string, lane_id: string, s: length, t: length) -> odr_point

Return value

Returns an odr_point.

Parameters

Table 192. Parameters for method create_odr_point()
Parameter	Type	Description
road_id	string	ASAM OpenDRIVE roadId
lane_id	string	Optional. ASAM OpenDRIVE laneId. If omitted, the t-coordinate is measured from the ASAM OpenDRIVE road reference line. If included, the t-coordinate is measured from the respective ASAM OpenDRIVE lane centerline.
s	length	s-coordinate in ASAM OpenDRIVE coordinates
t	length	t-coordinate in ASAM OpenDRIVE coordinates

8.12.2.1.10 Method create_path()

Creates a path in world x-y-z-coordinates from a list of pose_3d points.

Prototype

extend map:
    def create_path(points: list of pose_3d, interpolation: path_interpolation) -> path

Return value

Returns a path in world x-y-z-coordinates.

Parameters

Table 193. Parameters for method create_path()
Parameter	Type	Description
points	list of pose_3d	List of points in world x-y-z-coordinates.
interpolation	path_interpolation	Choose how to join the points of the path.

Syntax

Code 76. Syntax example for create_path()

pose1, pose2, pose3: pose_3d
keep(pose1.position.x == 23.423)
keep(pose1.position.y == 3.43)
# Repeat for pose2 and pose3

my_path: path = create_path([pose1, pose2, pose3], smooth)

8.12.2.1.11 Method create_path_odr_points()

Creates a path in world x-y-z-coordinates from a list of odr_point points.

Prototype

extend map:
    def create_path_odr_points(points: list of odr_point, interpolation: path_interpolation, on_road_network: bool) -> path

Return value

Returns a path in world x-y-z-coordinates.

Parameters

Table 194. Parameters for method create_path_odr_points()
Parameter	Type	Description
points	list of odr_point	Sequence of `odr_point` that will be converted to world x-y-z-coordinates to create a `path`.
interpolation	path_interpolation	Choose how to join the points of the path.
on_road_network	bool	If set to true, the points of the path must be joined while keeping the whole path on the road network.

Syntax

Code 77. Syntax example for create_path_odr_points()

pt1: odr_point = create_odr_point(road_id: 12, lane_id: 1, s: 10m, t: 0.2m)
pt2: odr_point = create_odr_point(road_id: 12, lane_id: 2, s: 25m, t: 0.0m)
pt3: odr_point = create_odr_point(road_id: 13, lane_id: 1, s: 30m, t: 0.0m)

my_path: path = create_path_odr_points([pt1, pt2, pt3], smooth, true)

8.12.2.1.12 Method create_path_route_points()

Creates a path in world x-y-z-coordinates from a list of route_point points.

Prototype

extend map:
    def create_path_route_points(points: list of route_point, interpolation: path_interpolation, on_road_network: bool) -> path

Return value

Returns a path in world x-y-z-coordinates.

Parameters

Table 195. Parameters for method create_path_route_points()
Parameter	Type	Description
points	list of route_point	Sequence of route_point that will be converted to world x-y-z-coordinates to create a `path`.
interpolation	path_interpolation	Choose how to join the points of the path.
on_road_network	bool	If set to true, the points of the path must be joined while keeping the whole path on the road network.

Syntax

Code 78. Syntax example for create_path_route_points()

pt1, pt2, pt3: route_point
keep(pt1.route == my_road)
keep(pt1.s == 120.0m)
keep(pt1.t == 5.3m)
# Add similar constraints for pt2 and pt3

my_path: path = create_path_route_points([pt1, pt2, pt3], smooth, true)

8.12.2.1.13 Method create_trajectory()

Creates a trajectory in world x-y-z-coordinates from a list of pose_3d points and time stamps.

Prototype

extend map:
    def create_trajectory(points: list of pose_3d, time_stamps: list of time,interpolation: path_interpolation) -> trajectory

Return value

Returns a trajectory in world x-y-z-coordinates.

Parameters

Table 196. Parameters for method create_trajectory()
Parameter	Type	Description
points	list of pose_3d	List of points in world x-y-z-coordinates.
time_stamps	list of time	Time stamps for each element in points. The lists time_stamps and points must have the same length.
interpolation	path_interpolation	Choose how to join the points of the trajectory.

Code 79. Syntax example for create_trajectory()

pose1, pose2, pose3: pose_3d
keep(pose1.position.x == 23.423)
keep(pose1.position.y == 3.43)
# Repeat for pose2 and pose3

time_stamps: list of time = [0s, 2s, 5s]

my_trajectory: trajectory = create_trajectory([pose1, pose2, pose3], time_stamps, smooth)

8.12.2.1.14 Method create_trajectory_odr_points()

Creates a trajectory in world x-y-z-coordinates from a list of odr_point points.

Prototype

extend map:
    def create_trajectory_odr_points(points: list of odr_point, time_stamps: list of time, interpolation: path_interpolation, on_road_network: bool) -> trajectory

Return value

Returns a trajectory in world x-y-z-coordinates.

Parameters

Table 197. Parameters for method create_trajectory_odr_points()
Parameter	Type	Description
points	list of odr_point	Sequence of `odr_point` that will be converted to world x-y-z-coordinates to create a `trajectory`.
time_stamps	list of time	Time stamps for each element in points. The lists time_stamps and points must have the same length.
interpolation	path_interpolation	Choose how to join the points of the trajectory.
on_road_network	bool	If set to true, the points of the trajectory must be joined while keeping the whole trajectory on the road network.

Syntax

Code 80. Syntax example for create_trajectory_odr_points()

pt1: odr_point = create_odr_point(road_id: 12, lane_id: 1, s: 10m, t: 0.2m)
pt2: odr_point = create_odr_point(road_id: 12, lane_id: 2, s: 25m, t: 0.0m)
pt3: odr_point = create_odr_point(road_id: 13, lane_id: 1, s: 30m, t: 0.0m)

time_stamps: list of time = [0s, 2s, 5s]

my_trajectory: trajectory = create_trajectory_odr_points([pt1, pt2, pt3], time_stamps, smooth, true)

8.12.2.1.15 Method create_trajectory_route_points()

Creates a trajectory in world x-y-z-coordinates from a list of route_point points.

Prototype

extend map:
    def create_trajectory_route_points(points: list of route_point, time_stamps: list of time, interpolation: path_interpolation, on_road_network: bool) -> trajectory

Return value

Returns a trajectory in world x-y-z-coordinates.

Parameters

Table 198. Parameters for method create_trajectory_route_points()
Parameter	Type	Description
points	list of route_point	Sequence of `route_point` that will be converted to world x-y-z-coordinates to create a `trajectory`.
time_stamps	list of time	Time stamps for each element in points. The lists time_stamps and points must have the same length.
interpolation	path_interpolation	Choose how to join the points of the trajectory.
on_road_network	bool	If set to true, the points of the trajectory must be joined while keeping the whole trajectory on the road network.

Syntax

Code 81. Syntax example for create_trajectory_route_points()

pt1, pt2, pt3: route_point
keep(pt1.route == my_road)
keep(pt1.s == 120.0m)
keep(pt1.t == 5.3m)
# Add similar constraints for pt2 and pt3

time_stamps: list of time = [0s, 2s, 5s]

my_trajectory: trajectory = create_trajectory_route_points([pt1, pt2, pt3], time_stamps, smooth)

8.12.2.1.16 Method resolve_relative_path()

Creates a path from a relative_path by implementing the following steps:

Sample the pose of the reference entity.
Use this pose as the origin to establish the appropriate coordinate system for the list of points that are provided in the relative_path.
Compute the world x-y-z-coordinates of the list of points.

Return this list of points in a path.

Prototype

extend map:
    def resolve_relative_path(relative_path: relative_path, reference: physical_object, transform: relative_transform) -> path

Return value

Returns a path in world x-y-z-coordinates.

Parameters

Table 199. Parameters for method map.resolve_relative_path()
Parameter	Type	Description
relative_path	relative_path	The relative path to be resolved to absolute x-y-z-coordinates.
reference	physical_object	Reference entity that marks the origin to resolve the list of points.
transform	relative_transform	Type of transformation to resolve relative points into absolute coordinates

8.12.2.1.17 Method resolve_relative_trajectory()

Creates a trajectory from a relative_trajectory by implementing the following steps:

Sample the pose of the reference entity.
Use this pose as the origin to establish the appropriate coordinate system for the list of points provided in the relative_trajectory.
Compute the world x-y-z-coordinates of the list of points.
Return this list of points in a trajectory.

The time stamps remain unchanged.

Prototype

extend map:
    def resolve_relative_trajectory(relative_trajectory: relative_trajectory, reference: physical_object, transform: relative_transform) -> trajectory

Return value

Returns a trajectory in world x-y-z-coordinates.

Parameters

Table 200. Parameters for method resolve_relative_trajectory()
Parameter	Type	Description
relative_trajectory	relative_trajectory	The relative trajectory to be resolved to absolute x-y-z-coordinates.
reference	physical_object	Reference entity that marks the origin to resolve the list of points.
transform	relative_transform	Type of transformation to resolve relative points into absolute coordinates

8.12.2.1.18 Method get_map_file()

Prototype

extend map:
    def get_map_file() -> string

Return value

Returns a string with the path and file name of the map_file.

8.12.2.2 Modifiers

8.12.2.2.1 Modifier number_of_lanes()

Creates constraints for the number of lanes within a route by lane type, lane use and/or lane directionality.

Parameters

Table 201. Parameters for modifier map.number_of_lanes()
Parameter	Type	Description
route	route	Mandatory. The route that will have these constraints.
num_of_lanes	uint	Mandatory. The desired number of lanes.
lane_type	lane_type	Optional. Apply the constraint to the number of lanes with this type.
lane_use	lane_use	Optional. Apply the constraint to the number of lanes with this use.
directionality	directionality	Optional. Apply the constraint to the number of lanes with this directionality.

Syntax

city_road: road
map.number_of_lanes(city_road, 1, pedestrian)
map.number_of_lanes(city_road, 2, driving, directionality: uni_direction)
map.number_of_lanes(city_road, 1, lane_use: mixed_traffic_vru)

highway_ls: lane_section
num: int with:
    keep(it >= 3) # constrained number
map.number_of_lanes(highway_ls, 0, pedestrian)
map.number_of_lanes(highway_ls, num, driving, directionality: uni_direction)
map.number_of_lanes(highway_ls, 2, non_driving, lane_use: stop)
map.number_of_lanes(highway_ls, 1, non_driving, lane_use: median)

8.12.2.2.2 Modifier routes_are_in_sequence()

Specifies that one route follows another in successive order.

Parameters

Table 202. Parameters for modifier map.routes_are_in_sequence()
Parameter	Type	Description
preceding	route	The first route
succeeding	route	The second route, which follows after the first route.
road	road	Optional. The road that will contain this sequence of routes.

Syntax

lane1, lane2: lane
routes_are_in_sequence(preceding: lane1, succeeding: lane2)

my_road: road
ls_a, la_b: lane_section
routes_are_in_sequence(preceding: ls_a, succeeding: ls_b, road: my_road)

8.12.2.2.3 Modifier roads_follow_in_junction()

Defines a legal route through a junction.

Table 203. Parameters for modifier map.roads_follow_in_junction()
Parameter	Type	Description
junction	junction	The junction to be used.
in_road	road	The chosen road that leads into the junction.
out_road	road	The chosen road that leads away from the junction.
direction	junction_direction	Indicates the direction of the out_road relative to the in_road.
clockwise_count	uint	out_road is clockwise_count roads from in_road, counting clockwise. Values larger than number_of_roads are illegal. Example: For a four-way junction, clockwise_count can have the following values: `1`: Left `2`: Straight `3`: Right `4`: U-turn
number_of_roads	uint	Total number of in_roads connected to the junction.
in_lane	lane	The chosen lane within in_road.
out_lane	lane	The chosen lane within out_road.
junction_route	route	The element(s) that connect the in_lane or in_road to the out_lane or out_road within the junction.
resulting_route	route	The route going from in_lane or in_road to the out_lane or out_road.

8.12.2.2.4 Modifier routes_overlap()

Specifies that two routes overlap longitudinally, see routes overlap. For example, two lanes in a lane section are considered to overlap. Two parallel roads running in the opposite direction are also considered to overlap.

Table 204. Parameters for modifier map.routes_overlap()
Parameter	Type	Description
route1	route	The first of the overlapping routes.
route2	route	The second of the overlapping routes.
overlap_kind	route_overlap_kind	The type of expected overlap. Notice route1 is considered the first route to interpret the values of the enum.

8.12.2.2.5 Modifier lane_side()

Specifies the side relation between two instances of lane.

Table 205. Parameters for modifier map.lane_side()
Parameter	Type	Description
lane1	lane	The first lane.
side	side_left_right	Locate lane1 on this side of lane2.
lane2	lane	The second lane.
count	uint	For a count of n, there are n-1 lanes between the two instances.
lane_section	lane_section	Optional. The lane_section where the lanes reside.

Syntax example:

lane_a, lane_b: lane
map.lane_side(lane_a, left, lane_b)

my_ls: lane_section
lane_c, lane_d: lane
map.lane_side(lane_c, right, lane_d, 2, my_ls)

8.12.2.2.6 Modifier compound_lane_side()

Specifies side relation between two instances of compound_lane.

Table 206. Parameters for modifier map.compound_lane_side()
Parameter	Type	Description
lane1	compound_lane	The first compound_lane.
side	side_left_right	Locate lane1 on this side of lane2.
lane2	compound_lane	The second compound_lane.
count	uint	For a count of n, there are n-1 lanes between the two instances.
route	route	Optional. The route where the compound lanes reside.

8.12.2.2.7 Modifier end_lane()

The lane ends in its lane_section and has no successor in the next lane_section.

Parameters

Table 207. Parameters for modifier map.end_lane()
Parameter	Type	Description
lane	lane	This lane ends in its current lane_section.

Syntax

ls_a, ls_b: lane_section
my_road: road
map.routes_are_in_sequence(preceeding: ls_a, succeeding: ls_b, road: my_road)

my_ending_lane: lane with:
    keep(it.lane_section == ls_a)
map.end_lane(my_ending_lane)

8.12.2.2.8 Modifier start_lane()

The lane starts in its lane_section and has no predecessor in the previous lane_section.

Parameters

Table 208. Parameters for modifier map.start_lane()
Parameter	Type	Description
lane	lane	This lane starts in its current lane_section.

Syntax

ls_a, ls_b: lane_section
my_road: road
map.routes_are_in_sequence(preceding: ls_a, succeeding: ls_b, road: my_road)

my_starting_lane: lane with:
    keep(it.lane_section == ls_b)
map.start_lane(my_starting_lane)

8.12.2.2.9 Modifier crossing_connects()

Connect a crossing between two lanes. The s-coordinate of the crossing increases from the start_lane to end_lane. If the start_angle argument is not specified, the default solves the connection with start_angle of 90 deg and a straight line to the end_lane.

Parameters

Table 209. Parameters for modifier map.crossing_connects()
Parameter	Type	Description
crossing	crossing	The crossing that will be connected to the specified lanes.
start_lane	lane	The lane where crossing starts (starting from the lane’s centerline).
end_lane	lane	The destination lane where the crossing ends (ending on the lane’s centerline).
start_s_coord	length	The crossing origin derived from a s-position along the centerline of start_lane.
start_angle	angle	Optional. The angle at which the straight centerline of the crossing originates from the start lane. Default is perpendicular.

Syntax

my_cross: crossing
sidewalk_1, sidewalk_2: lane
map.crossing_connects(my_cross, sidewalk_1, sidewalk_2, 5m)

my_cross: crossing
sidewalk_3, sidewalk_4: lane
map.crossing_connects(my_cross, sidewalk_3, sidewalk_4, 5m, 60deg)

In the future geometric constraints could be used within this modifier if the approach to the end_lane was an unusual shape rather than a straight line.

8.12.2.2.10 Modifier routes_are_opposite()

Specifies that two routes are in opposite directions.

Table 210. Parameters for modifier map.routes_are_opposite()
Parameter	Type	Description
route1	route	The first uni-directional route.
route2	route	The second uni-directional route. If route1 has no opposite, then route2 is null.
containing_road	road	The road to which both routes belong.
lateral_overlap	lateral_overlap_kind	Specifies if the routes overlap lateral, meaning they become a single two-way lane.

8.12.2.2.11 Modifier set_map_file()

Setting a map file.

Parameters

Table 211. Parameters for modifier map.set_map_file()
Parameter	Type	Description
file	string	The path and file name for the map file.

Syntax

map.set_map_file("path/to/map/my_odr_map.xodr")

8.12.2.2.12 Modifier set_traffic_lights_control_file()

Specifies a file with traffic lights control cycles. This file references traffic lights or control groups defined in the map file (specified by modifier modifier map.set_map_file). Traffic light states that are not applicable to the referenced traffic lights may result in undefined behavior. Calling this modifier results in population of map.traffic_light_control.

Parameters

Table 212. Parameters for modifier map.set_traffic_lights_control_file()
Parameter	Type	Description
file	string	The path and file name for the control file.

Syntax

map.set_traffic_lights_control_file("path/to/traffic/lights/control.file")

This specifies map.traffic_light_control.

8.12.3 Enum driving_rule

Values

Table 213. Enum driving_rule
Value	Comment
left_hand_traffic	Traffic drives on the left side of the road
right_hand_traffic	Traffic drives on the right side of the road

8.12.4 Struct junction

A junction connects roads.

Basic information

Table 214. Basic information of struct junction
Used by	map

Parameters

Table 215. Struct junction
Parameter	Type	Mandatory	Description
roads	list of road	yes	List of road elements that are connected to this junction

8.12.5 Struct route

A route is a location where a movable_object can move, creating a behavioral pathway for the actors in the scenario. An instance of route can be a single route_element (for example, lane), or it can be composed of a sequence with multiple instances of route_element.

The s-t-coordinates in a route:

Each route has an s-t-coordinate system.
- The s-axis increases longitudinally along the route.
- The t-axis is perpendicular to the s-axis, following the right-hand-rule, with positive values to the left side of the s-axis.
In modifiers that specify movement relative to another reference entity, this implies using the s-t-coordinates of the lane where the reference vehicle is located.
- Example: car1.drive() with: position(100m, ahead_of: car2) measures the 100 m relative to the lane that car2 is in.
The result of requesting drive() along a split route or a bi-directional route is undefined. The request should result in an error, unless the direction is specified in some other way.

Basic information

Table 216. Basic information of struct route
Children	compound_lane, compound_route, route_element
Used by	map

Parameters

Table 217. Struct route
Parameter	Type	Mandatory	Description
length	length	no	Nominal length of the route, measured along the s-axis of the route. Does not apply to route_point
directionality	directionality	yes	Directionality for movement of traffic_participant actors on the route
min_lanes	uint	no	Minimum number of drivable lanes along this route. Applies only to these children: road, lane_section
max_lanes	uint	no	Maximum number of drivable lanes along this route. Applies only to these children: road, lane_section
anchors	list of string	no	The strings in here can be matched to unique items in the map files specified in file_name

8.12.5.1 Methods

8.12.5.1.1 Method start_point()

Returns the start point of the route, where the s-coordinate has its minimum value (typically zero).

Prototype

extend route:
    def start_point() -> route_point

Return value

Returns a route_point.

8.12.5.1.2 Method end_point()

Returns the end point of the route, where the s-coordinate has its maximum value. The difference between the maximum and minimum values of the s-coordinate on the route is equal to the length of the route measured along the s-axis of the route.

Prototype

extend route:
    def end_point() -> route_point

Return value

Returns a route_point.

8.12.6 Enum directionality

Directionality of the route

Values

Table 218. Enum directionality
Value	Comment
uni_direction	A traffic_participant can move legally in only one direction along the longitudinal s-axis. Usually applies to lane_type driving and vru_vehicles
bi_direction	A traffic_participant can move legally in both directions along the longitudinal s-axis. Usually applies to lane_type driving and vru_vehicles
split	Applies for multi-lane elements: there are lanes with opposing uni_direction traffic flow within the route
free	A traffic_participant can legally move in any direction (longitudinal or lateral). Usually applies to lane_type pedestrian or lane_use mix_traffic_vru
none	No expected traffic flow. Usually applies to lane_type non_driving
other	Other type of directionality

8.12.7 Struct route_element

A route_element that is a lower-level route, which can be used individualy, or can eb part of a compound_route.

Basic information

Table 219. Basic information of struct route_element
Parents	route
Children	crossing, geodetic_point, lane, lane_section, odr_point, path, road, route_point, xyz_point

Inherited parameters and variables

Table 220. Inherited parameters and variables of struct route_element
Parent	Inherited parameters and variables
route	length, directionality, min_lanes, max_lanes, anchors

8.12.8 Struct road

A road is composed by ordered lists of lane_section, organized end-to-end (longitudinal direction, or s-direction).

A road is composed of instances of lane_section arranged end-to-end. A road can only be connected with another road in a junction.

A road has two separate ordered lists of lane_section:

The s_positive (mandatory) list of lane_section contains the uni-directional lanes flowing in the positive road-s-direction.
The s_negative (optional) list of lane_section contains the uni-directional lanes flowing in the negative road-s-direction.
- Both lists can include lanes with other directionalities.
- Successive lane_section elements in the list can have different properties (number of lanes, lane types, lane use, directionality, and so on).
- A road has an s-t-coordinate system.
- The s-axis of the road coincides with the s-axis of s_positive.
- A road can only be connected with another road in a junction.

Basic information

Table 221. Basic information of struct road
Parents	route_element
Has connection to	junction

Parameters

Table 222. Struct road
Parameter	Type	Mandatory	Description
s_positive	list of lane_section	yes	List of lane_section elements that flow in the positive direction of the road s-axis
s_negative	list of lane_section	no	List of lane_section elements that flow in the negative direction of the road s-axis

Inherited parameters and variables

Table 223. Inherited parameters and variables of struct road
Parent	Inherited parameters and variables
route	length, directionality, min_lanes, max_lanes, anchors

8.12.9 Struct lane_section

A block of one or more lanes, organized side-by-side (lateral direction, or T-direction).

A section composed of lanes arranged side-by-side. A road can be composed of one or multiple instances of lane_section arranged end-to-end. Lane sections are useful for these purposes:

Change the number of lanes over the course of a single road.
Change the type of lanes within a single road.
Change the use of lanes within a single road.
Change the directionality of lanes within a single road.

The representation of lane_section is similar to the implementation in ASAM OpenDRIVE.

The number of lanes is constant in the whole lane section.
Lanes cannot change lane_type or lane_use or directionality within the lane section.
A lane section has an s-t-coordinate system.
The s-axis of the lane section coincides with the s-axis of the lane chosen with the (mandatory) s_axis property.

Basic information

Table 224. Basic information of struct lane_section
Parents	route_element
Used by	road

Parameters

Table 225. Struct lane_section
Parameter	Type	Mandatory	Description
road	road	yes	Where the lane_section resides
lanes	list of lane	yes	List of lanes that compose the lane_section
s_axis	lane	yes	Choose, which lane is used to determine the s-axis of the lane_section. Must be a member of it.lanes

Inherited parameters and variables

Table 226. Inherited parameters and variables of struct lane_section
Parent	Inherited parameters and variables
route	length, directionality, min_lanes, max_lanes, anchors

8.12.10 Struct lane

A lane is pathway that has limits for movement. These limits are typically indicated by lane lines providing an indication of boundaries to traffic participants.

A lane has an s-t-coordinate system.
The lane s-axis goes along the centerline of the lane.
The lane t-axis is perpendicular to the s-axis, following the right-hand-rule.
For a lane with directionality == uni_directional, the legal traffic always moves in the positive s-direction.
One or multiple adjacent lanes arranged side-by-side compose a lane_section.

Basic information

Table 227. Basic information of struct lane
Parents	route_element
Used by	lane_section

Parameters

Table 228. Struct lane
Parameter	Type	Mandatory	Description
lane_section	lane_section	yes	Where the lane resides
lane_type	lane_type	yes	Type of lane
lane_use	lane_use	yes	A subtype of the lane_type. Use compatible pairs of lane_type and lane_use
width	length	no	Nominal width of the lane

Inherited parameters and variables

Table 229. Inherited parameters and variables of struct lane
Parent	Inherited parameters and variables
route	length, directionality, min_lanes, max_lanes, anchors

8.12.11 Struct crossing

A crossing is overlaid on existing lanes. It allows different types of usage to take place on the same surface. A typical example is a crosswalk overlaid on drivable lanes.

Basic information

Table 230. Basic information of struct crossing
Parents	route_element

Parameters

Table 231. Struct crossing
Parameter	Type	Mandatory	Description
start_lane	lane	yes	Crossing starts on this lane
end_lane	lane	yes	Crossing ends on this lane
start_s_coord	length	yes	On the starts_from lane, the crossing connects at this point in the lane s-axis (and zero in the t-axis)
end_s_coord	length	yes	On the ends_on lane, the crossing connects at this point in the lane s-axis (and zero in the t-axis)
width	length	yes	Nominal width of the crossing, measured perpendicular to the crossing s-axis
crossing_type	crossing_type	yes	Type of crossing

Inherited parameters and variables

Table 232. Inherited parameters and variables of struct crossing
Parent	Inherited parameters and variables
route	length, directionality, min_lanes, max_lanes, anchors

8.12.12 Enum lane_type

Basic information

Table 233. Basic information of enum lane_type
Used by	lane

Values

Table 234. Enum lane_type
Value	Comment
driving	Driving lane for road vehicles. See the driving_lane_use subtype
non_driving	Non-driving lanes in road vehicles infrastructure. See the non_driving_lane_use subtype
vru_vehicles	Lanes designated for VRU vehicles. See the vru_vehicles_lane_use subtype
pedestrian	Lanes for pedestrians. See the pedestrian_lane_use subtype
other	If the lane has another type

8.12.13 Enum lane_use

Subtype of the lane_type enum. lane_use contains all values from all use types

Basic information

Table 235. Basic information of enum lane_use
Used by	lane

Values

Table 236. Enum lane_use
Value	Comment
normal	A normal driving lane for road vehicles (OSI). Should be used in combination with lane_type == driving.
exit	A deceleration lane in parallel to the main road (OSI). Should be used in combination with lane_type == driving.
entry	An acceleration lane in parallel to the main road (OSI). Should be used in combination with lane_type == driving.
on_ramp	A ramp from rural or urban roads joining a motorway (OSI). Should be used in combination with lane_type == driving.
off_ramp	A ramp leading off a motorway onto rural or urban roads (OSI). Should be used in combination with lane_type == driving.
connecting_ramp	A ramp that connects two motorways (OSI). Should be used in combination with lane_type == driving.
hov	A lane for High Occupancy Vehicles (HOV), usually in highways. Should be used in combination with lane_type == driving.
bus	A lane restricted for use only by busses. Should be used in combination with lane_type == driving.
mixed_traffic_vru	A lane for mixed car and vru (vehicle and pedestrian) traffic, normally in urban areas. Should be used in combination with lane_type == driving or vru_vehicles.
parking	A lane with parking spaces (OSI). Should be used in combination with lane_type == non_driving.
stop	A hard shoulder on motorways for emergency stops (OSI). Should be used in combination with lane_type == non_driving.
restricted	A lane on which road vehicles should not drive (OSI). Should be used in combination with lane_type == non_driving.
border	A hard border on the edge of a road (OSI). Should be used in combination with lane_type == non_driving.
shoulder	A soft border on the edge of a road (OSI). Should be used in combination with lane_type == non_driving.
curb	An elevated surface with different height compared to the drivable lanes. Should be used in combination with lane_type == non_driving.
median	An inaccessible lane for road vehicles and pedestrians. Typically used to separate the traffic. Should be used in combination with lane_type == non_driving.
bicycle	A lane that is designated for bicycles (OSI). Should be used in combination with lane_type == vru_vehicles.
motorcycle	A lane that is designated for motorcycles. Should be used in combination with lane_type == vru_vehicles.
sidewalk	A lane that is designated for pedestrians (OSI). Should be used in combination with lane_type == pedestrian.
protected_sidewalk	A lane for pedestrians with a barrier to separate it from road traffic. Should be used in combination with lane_type == pedestrian.
none	The lane has no use.
other	The lane has another use.

8.12.14 Enum side_left_right

Values

Table 237. Enum side_left_right
Value	Comment
left	On the left side of the lane
right	On the right side of the lane

8.12.15 Enum lon_lat

Values

Table 238. Enum lon_lat
Value	Comment
longitudinal	Refers to longitudinal direction
lateral	Refers to lateral direction

8.12.16 Struct crossing_type

Basic information

Table 239. Basic information of struct crossing_type
Used by	crossing

Parameters

Table 240. Struct crossing_type
Parameter	Type	Mandatory	Description
marking	crossing_marking	no	Define the type of markings on the crossing
use	crossing_use	no	Define the type of use for the crossing
elevation	crossing_elevation	no	Define the type of elevation for the crossing

8.12.17 Enum crossing_marking

Basic information

Table 241. Basic information of enum crossing_marking
Used by	crossing_type

Values

Table 242. Enum crossing_marking
Value	Comment
unmarked	No crossing-markings on the road
marked	The road or walking surface has markings that indicate a crossing
zebra	Common type of marked crossing with thick zebra stripes
other	Other type of markings for the crossing

8.12.18 Enum crossing_use

Basic information

Table 243. Basic information of enum crossing_use
Used by	crossing_type

Values

Table 244. Enum crossing_use
Value	Comment
pedestrian	Crossing is used by pedestrians (person, animal) and/or vehicles that usually move on sidewalks (wheelchair, stroller)
animal	Animal crossing. For example, on a rural road or highway
bicycle	Crossing for bicycles
rail_road	Crossing for rail vehicles (train, subway, tram, …)
other	Other use for crossing

8.12.19 Enum crossing_elevation

Basic information

Table 245. Basic information of enum crossing_elevation
Used by	crossing_type

Values

Table 246. Enum crossing_elevation
Value	Comment
road_level	Crossing is at same level as driving surface
curb_level	Crossing is elevated from driving surface, often at the same level as a walking surface (sidewalk) or curb
refuge_island	Along the crossing, the elevation may change between road and curb levels. For example, with refuge island(s) in the middle
other	Another elevation type

8.12.20 Struct compound_route

A compound_route is a connected sequence of route elements.

Basic information

Table 247. Basic information of struct compound_route
Parents	route

Parameters

Table 248. Struct compound_route
Parameter	Type	Mandatory	Description
route_elements	list of route_element	yes	A list of route_element.

Inherited parameters and variables

Table 249. Inherited parameters and variables of struct compound_route
Parent	Inherited parameters and variables
route	length, directionality, min_lanes, max_lanes, anchors

8.12.21 Struct compound_lane

A connected sequence of lanes.

Basic information

Table 250. Basic information of struct compound_lane
Parents	route

Parameters

Table 251. Struct compound_lane
Parameter	Type	Mandatory	Description
lanes	list of lane	yes	A list of lane

Inherited parameters and variables

Table 252. Inherited parameters and variables of struct compound_lane
Parent	Inherited parameters and variables
route	length, directionality, min_lanes, max_lanes, anchors

8.12.22 Enum junction_direction

In a junction, indicate the direction of the out_road relative to the in_road, measuring the angle clockwise. All angles +/- 10 deg.

Values

Table 253. Enum junction_direction
Value	Comment
straight	The out_road is 0deg relative to the in_road
right	The out_road is 90deg relative to the in_road
u_turn	The out_road is 180deg relative to the in_road
left	The out_road is 270deg relative to the in_road
other	If none of the above apply

8.12.23 Enum route_overlap_kind

What type of longitudinal overlap is expected for a pair of routes.

Values

Table 254. Enum route_overlap_kind
Value	Comment
equal	Both routes have the same length, and coincide at the start and end points
start	Both routes coincide at their start points
end	Both routes coincide at their end points
inside	The first route is fully inside the second route. Their start and end points do not have to coincide
any	Any part of the first route overlaps with any part of the second route
other	If none of the above apply

8.12.24 Enum lateral_overlap_kind

Type of lateral overlap is expected for a pair of routes.

Values

Table 255. Enum lateral_overlap_kind
Value	Comment
never	The two routes never overlap laterally. They never share a common lane.
sometimes	In some segments of the route, the two routes can share a common lane.
always	The routes always share a common lane.

8.12.25 Struct route_point

A point on the route network specified in route s-t-coordinates.

Basic information

Table 256. Basic information of struct route_point
Parents	route_element
Used by	relative_path_st, relative_trajectory_st

Parameters

Table 257. Struct route_point
Parameter	Type	Mandatory	Description
route	route	Yes	route in which this point is located
s	length	No	Coordinate along the s-axis of the corresponding route
t	length	No	Coordinate along the t-axis of the corresponding route

Inherited parameters and variables

Table 258. Inherited parameters and variables of struct route_point
Parent	Inherited parameters and variables
route	length, directionality, min_lanes, max_lanes, anchors

8.12.26 Struct xyz_point

A pose in space specified in Cartesian x-y-z-coordinates.

Basic information

Table 259. Basic information of struct xyz_point
Parents	route_element

Parameters

Table 260. Struct xyz_point
Parameter	Type	Mandatory	Description
position	position_3d	No	Position in Cartesian x-y-z-coordinates

Inherited parameters and variables

Table 261. Inherited parameters and variables of struct xyz_point
Parent	Inherited parameters and variables
route	length, directionality, min_lanes, max_lanes, anchors

8.12.27 Struct odr_point

A point expressed in ASAM OpenDRIVE coordinates.

Basic information

Table 262. Basic information of struct odr_point
Parents	route_element
Used by	relative_path_odr, relative_trajectory_odr

Parameters

Table 263. Struct odr_point
Parameter	Type	Mandatory	Description
road_id	string	Yes	ASAM OpenDRIVE identifier for the road
lane_id	string	No	ASAM OpenDRIVE identifier for the lane. If specified, the t-coordinate is measured from the lane centerline. If not specified, the t-coordinate is measured from the ASAM OpenDRIVE reference line
s	length	No	Coordinate along the ASAM OpenDRIVE s-axis
t	length	No	Coordinate along the ASAM OpenDRIVE t-axis

Inherited parameters and variables

Table 264. Inherited parameters and variables of struct odr_point
Parent	Inherited parameters and variables
route	length, directionality, min_lanes, max_lanes, anchors

8.12.28 Struct geodetic_point

A point in space specified in Geographic (latitude, longitude, altitude) coordinates.

Basic information

Table 265. Basic information of struct geodetic_point
Parents	route_element

Parameters

Table 266. Struct geodetic_point
Parameter	Type	Mandatory	Description
latitude	angle	yes	The latitude of a point on the surface of the earth is the angle between the equatorial plane and the straight line that passes through that point and through the center of the earth. Range: [-90deg..90deg]
longitude	angle	yes	The longitude of a point on the surface of the earth is the angle east or west of a reference meridian to another meridian that passes through that point. Range: [-180deg..180deg]
altitude	length	no	Altitude is the earth gravity-related vertical distance from the target position, specified horizontally by its Longitude/Latitude coordinates, to the closest point on the underlying road surface. When calculating the closest point, it is accounted for an elevation of the road, an entire road super-elevation, or, in more complex cases, a road lateral shape profile that are specified in the road network definition (external to the OpenSCENARIO). Missing value is interpreted as 0. Range: [0m..inf[

Inherited parameters and variables

Table 267. Inherited parameters and variables of struct geodetic_point
Parent	Inherited parameters and variables
route	length, directionality, min_lanes, max_lanes, anchors

8.12.29 Enum connect_route_points

When building a compound_route, determine which route_element shall be used to compose the compound_route if routable point types (i.e. xyz_point, route_point or odr_point) are part of the list.

Values

Table 268. Enum connect_route_points
Value	Comment
road	Use the road element that contains this point
lane_section	Use the lane_section element that contains this point
lane	Use the lane element that contains this point
crossing	Use the crossing element that contains this point
waypoint	Use the point itself. The route must pass exactly through this point

8.12.30 Struct path

An absolute path expressed in Cartesian x-y-z-coordinates, measured in the global world coordinate system.

Basic information

Table 269. Basic information of struct path
Parents	route_element

Parameters

Table 270. Struct path
Parameter	Type	Mandatory	Description
points	list of pose_3d	Yes	List of points in world x-y-z-coordinates. The individual pose_3d elements can have unconstrained coordinates.
interpolation	path_interpolation	yes	Choose how to join the points of the path.

Inherited parameters and variables

Table 271. Inherited parameters and variables of struct path
Parent	Inherited parameters and variables
route	length, directionality, min_lanes, max_lanes, anchors

8.12.31 Struct relative_path

A relative path is a sequence of points measured with respect to a reference entity. These points can be expressed in Cartesian x-y-z-coordinates, route s-t-coordinates or ASAM OpenDRIVE coordinates.

Basic information

Table 272. Basic information of struct relative_path
Children	relative_path_odr, relative_path_pose_3d, relative_path_st

Parameters

Table 273. Struct relative_path
Parameter	Type	Mandatory	Description
interpolation	path_interpolation	yes	Choose how to join the points of the path.

8.12.32 Struct relative_path_pose_3d

A relative path expressed in Cartesian x-y-z-coordinates, measured in the local coordinate frame of the reference entity.

Basic information

Table 274. Basic information of struct relative_path_pose_3d
Parents	relative_path

Parameters

Table 275. Struct relative_path_pose_3d
Parameter	Type	Mandatory	Description
points	list of pose_3d	Yes	List of points in world x-y-z-coordinates. The individual pose_3d elements can have unconstrained coordinates.

Inherited parameters and variables

Table 276. Inherited parameters and variables of struct relative_path_pose_3d
Parent	Inherited parameters and variables
relative_path	interpolation

8.12.33 Struct relative_path_st

A relative path expressed in route s-t-coordinates, measured with respect to a reference entity.

Basic information

Table 277. Basic information of struct relative_path_st
Parents	relative_path

Parameters

Table 278. Struct relative_path_st
Parameter	Type	Mandatory	Description
points	list of route_point	Yes	Sequence of route_point that form the relative path

Inherited parameters and variables

Table 279. Inherited parameters and variables of struct relative_path_st
Parent	Inherited parameters and variables
relative_path	interpolation

8.12.34 Struct relative_path_odr

A relative path expressed in ASAM OpenDRIVE coordinates, measured with respect to a reference entity.

Basic information

Table 280. Basic information of struct relative_path_odr
Parents	relative_path

Parameters

Table 281. Struct relative_path_odr
Parameter	Type	Mandatory	Description
points	list of odr_point	Yes	Sequence of odr_point that form the relative path

Inherited parameters and variables

Table 282. Inherited parameters and variables of struct relative_path_odr
Parent	Inherited parameters and variables
relative_path	interpolation

8.12.35 Enum path_interpolation

Choose how to join the list of points in a path or trajectory

Values

Table 283. Enum path_interpolation
Value	Comment
straight_line	Join the points with straight lines
smooth	Join the points with a smooth line

8.12.36 Enum relative_transform

Type of transformation to resolve relative points into absolute coordinates

Basic information

Table 284. Basic information of enum relative_transform
Used by	follow_path, follow_trajectory, replay_path, replay_trajectory

Values

Table 285. Enum relative_transform
Value	Comment
world_relative	Use the global coordinate system axes
object_relative	Use the reference object local coordinate system axes
road_relative	Use the s-t coordinate system of the road where the reference object is located
lane_relative	Use the s-t coordinate system of the lane where the reference object is located

8.12.37 Struct trajectory

An absolute trajectory expressed in Cartesian x-y-z-coordinates, measured in the global world coordinate system.

Basic information

Table 286. Basic information of struct trajectory
Used by	hidden

Parameters

Table 287. Struct trajectory
Parameter	Type	Mandatory	Description
points	list of pose_3d	Yes	List of points in world x-y-z-coordinates. The individual pose_3d elements can have unconstrained coordinates.
time_stamps	list of time	Yes	Time stamps for each element in points. The lists time_stamps and points must have the same length.
interpolation	path_interpolation	yes	Choose how to join the points of the trajectory.

8.12.38 Struct relative_trajectory

A relative trajectory is a sequence of points measured with respect to a reference entity, where the points must be traversed at specific moments in time. These points can be expressed in Cartesian x-y-z-coordinates, route s-t-coordinates or ASAM OpenDRIVE coordinates.

Basic information

Table 288. Basic information of struct relative_trajectory
Children	relative_trajectory_odr, relative_trajectory_pose_3d, relative_trajectory_st

Parameters

Table 289. Struct relative_trajectory
Parameter	Type	Mandatory	Description
time_stamps	list of time	Yes	Time stamps for each element in points. The lists time_stamps and points must have the same length
interpolation	path_interpolation	yes	Choose how to join the points of the trajectory.

8.12.39 Struct relative_trajectory_pose_3d

A relative trajectory expressed in Cartesian x-y-z-coordinates, measured in the local coordinate frame of the reference entity.

Basic information

Table 290. Basic information of struct relative_trajectory_pose_3d
Parents	relative_trajectory

Parameters

Table 291. Struct relative_trajectory_pose_3d
Parameter	Type	Mandatory	Description
points	list of pose_3d	Yes	List of points in world x-y-z-coordinates. The individual pose_3d elements can have some unspecified coordinates.

Inherited parameters and variables

Table 292. Inherited parameters and variables of struct relative_trajectory_pose_3d
Parent	Inherited parameters and variables
relative_trajectory	time_stamps, interpolation

8.12.40 Struct relative_trajectory_st

A relative trajectory expressed in route s-t-coordinates, measured with respect to a reference entity.

Basic information

Table 293. Basic information of struct relative_trajectory_st
Parents	relative_trajectory

Parameters

Table 294. Struct relative_trajectory_st
Parameter	Type	Mandatory	Description
points	list of route_point	Yes	Sequence of route_point that form the relative trajectory

Inherited parameters and variables

Table 295. Inherited parameters and variables of struct relative_trajectory_st
Parent	Inherited parameters and variables
relative_trajectory	time_stamps, interpolation

8.12.41 Struct relative_trajectory_odr

A relative trajectory expressed in ASAM OpenDRIVE coordinates, measured with respect to a reference entity.

Basic information

Table 296. Basic information of struct relative_trajectory_odr
Parents	relative_trajectory

Parameters

Table 297. Struct relative_trajectory_odr
Parameter	Type	Mandatory	Description
points	list of odr_point	Yes	Sequence of odr_point that form the relative trajectory

Inherited parameters and variables

Table 298. Inherited parameters and variables of struct relative_trajectory_odr
Parent	Inherited parameters and variables
relative_trajectory	time_stamps, interpolation