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:

  1. Sample the pose of the reference entity.

  2. Use this pose as the origin to establish the appropriate coordinate system for the list of points that are provided in the relative_path.

  3. Compute the world x-y-z-coordinates of the list of points.

  4. 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:

  1. Sample the pose of the reference entity.

  2. Use this pose as the origin to establish the appropriate coordinate system for the list of points provided in the relative_trajectory.

  3. Compute the world x-y-z-coordinates of the list of points.

  4. Return this list of points in a trajectory.

  5. 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:

  1. The s_positive (mandatory) list of lane_section contains the uni-directional lanes flowing in the positive road-s-direction.

  2. 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