Introduction to Route elements

Route elements enable the scenario writer to:

Constrain routes: Define specific characteristics for routes on the map, such as a route entering a junction from one road, turning in a direction, and exiting the junction from another road; routes with a certain slope range; routes with speed limits within a specific range; or routes that pass through a junction controlled by traffic-lights.
Trigger events: Activate events when actors reach locations with specified characteristics (see track_road_element). This can be used for various purposes, such as coverage and action triggers.

The Foretify map representation consists of basic structures like the msp_road and msp_lane which define the road network. See map semantics topology. However, users typically interact with the map through higher level constructs known as route elements.

Route elements classify routes on the map based on sets of characteristics and are represented by OSC structures that inherit struct road_element. Each route element type defines a set of traits for classifying map routes. For a given route element type, every route associated with a particular set of values for that type’s traits is called an occurrence of that route element type.

Occurrences of different route element types can overlap. A point on a road may belong to multiple route elements, such as a speed_limit_section element representing the speed limit, a slope_section element representing the slope, and a road_curvature element representing the curvature. While these occurrences may overlap, they are not necessarily (nor typically) congruent.

For example, in the image below, occurrences of two types of route element are highlighted: road_to_crosswalk - a route that leads to a crosswalk (highlighted in green), and road_on_crosswalk - a route that exactly covers a crosswalk (highlighted in pink).

Route element routes

The route associated with a route element occurrence consists of a list of connected msp_road structures. The route can be limited to a specific range of lanes on each of the msp_roads, as long as there are connected lanes between each pair of successive msp_roads. The route can start at any offset on the first msp_road in the list and end at any offset on the last msp_road.

In OSC, the route is represented as a list of road_part:

struct road_part:
    var road: msp_road
    var start_offset: length
    var end_offset: length
    var min_lane_idx: uint
    var max_lane_idx: uint

struct element_to_road_parts:
    var element: road_element
    var road_parts: list of road_part

Typically, route element routes include only driving lanes, except for those route elements that describe non-driving routes, such as sidewalks, shoulders, and bike lanes.

Driving on constrained route element occurrences

A scenario may specify a drive over some route element occurrence using the along modifier.

In the following scenario, route elements road_on_crosswalk and road_to_crosswalk are used to constrain the SUT drive to a route that reaches a crosswalk when exiting a junction.

extend top.main:
    # on_crosswalk - a route exactly over a crosswalk
    on_crosswalk: road_on_crosswalk with:
        # constrain a road_on_crosswalk that is reached when exiting a junction
        keep(it.kind == junction_exit)

    # to_crosswalk - a route that leads to a crosswalk
    to_crosswalk: road_to_crosswalk with:
        # constrain the road_to_crosswalk to one that leads to 'the 'on_crosswalk'
        keep(it.road_on_crosswalk == self.on_crosswalk)

    do serial:
        sut.car.drive() with:
            along(to_crosswalk, at: start)
            along(on_crosswalk, at: end)

Route element types

All route element types are represented by structs that inherit road_element. It has two properties:

id - A unique occurrence ID over all route element occurrences in the map. This ID remains constant for each Foretify run, but it may change between different versions of Foretify, when maps are changed and possibly also across different configurations using the same map and Foretify version.
length - The length in terms of msp_road length.

Occurrences of the different route element types are registered during the post-processing of the map. By default, Foretify registers the occurrences for the types below. You can add additional types or occurrences by extending the OSC method map_support_package.mark_road_elements(). See Add MSP-specific road_elements for more details.

Fundamental route elements

The route elements one_way_road and internal_road define junctions and the roads connecting them. Each road position on the map, specified by a longitudinal-offset on a specific msp_road, belongs to either a single one_way_road or a single internal_road.

one_way_road and internal_road occurrences

For interchange junctions that are modeled without overlapping msp_roads, the area of the junction is artificially defined to extend half a meter from the incoming road(s) and half a meter from the outgoing road(s).

internal_roads for an interchange junction with no overlap between internal_roads

Categories of route elements

This section provides a brief description of the route element types provided out of the box by Foretify. It categorizes them and explains their relationships to provide a high-level perspective. You can link to the subsequent sections that provide detailed descriptions of each route element type, along with examples and illustrations.

One way road elements

Element	Description
`one_way_road`	A one-way road or one driving-side of a two-way-road that runs between two junctions without crossing any junction.

Each one_way_road overlaps with one or more occurrences of each of the following route element types.

Every one_way_road is congruent with:

a set of mutually exclusive occurrences of 'lane_section'
a set of mutually exclusive occurrences of 'lane'
a set of mutually exclusive occurrences of ‘slope_section’
a set of mutually exclusive occurrences of ‘speed_limit_section’
a set of mutually exclusive occurrences of ‘road_curvature’

Element	Description
`lane_section`	A division of a `one_way_road` into the longest segments that have a constant number of driving lanes. A `lane_section` is a continuous path along a `one_way_road` where the number of driving lanes remains the same. When the number of driving lanes changes along the road, it marks the beginning of a new `lane_section`.
`lane`	A single lane within a `lane_section`.
`slope_section`	A division of a `one_way_road` based on slope. A `slope_section` is a continuous path along a `one_way_road` where the slope does not change by more than a specified factor.
`speed_limit_section`	A division of `one_way_road` based on the speed limit. A `speed_limit_section` is a continuous path along a `one_way_road` where the speed limit remains the same. Neighbor driving lanes may belong to different `speed_limit_section`.
`road_curvature`	A division of a `one_way_road` based on curvature. A `road_curvature` is a continuous path along a `one_way_road` where the curvature does not change by more than a specified factor.

Junction elements category

Element	Description
`internal_road`	A route within a junction that connects one incoming `one_way_road` entering the junction to one outgoing `one_way_road` exiting the junction.
`internal_road_with_conflict`	A pair of `internal_roads` that overlap and have different incoming `one_way_roads`.

Roundabout elements category

Element	Description
`roundabout_entry`	A route congruent with an `internal_road` that enters a roundabout.
`roundabout_from_entry`	A circular route inside the roundabout from a `roundabout_entry` completing exactly one full round of the roundabout.
`roundabout_exit`	A route congruent with an `internal_road` that exits a roundabout.
`roundabout_to_exit`	A circular route inside the roundabout to a `roundabout_exit` completing exactly one full round of the roundabout.

Highway elements

Element	Description
`highway`	A `one_way_road` that is classified as a `highway`.
`highway_entry`	A `one_way_road` that is classified as a `highway-entry-ramp`.
`highway_exit`	A `one_way_road` that is classified as a `highway-exit-ramp`.
`highway_acceleration_lane`	An acceleration lane for merging from a `highway-entry-ramp` onto the `highway`.

Signs and traffic lights elements

Element	Description
`road_with_sign`	Indicates the position where a road sign takes effect, such as the stop line for a stop sign. The element ends at the stop line.
`road_with_traffic_light`	Indicates the position of the stop line for a traffic light.
`lane_with_lane_mark`	Specifies the marking of a lane border line.

Crosswalk route elements

Element	Description
`road_on_crosswalk`	Represents a driving route across a crosswalk.
`road_to_crosswalk`	Represents a route that begins at the start of the overlapping or preceding `one_way_road` and ends precisely at the start of a `road_on_crosswalk`.
`road_from_crosswalk`	Represents a route that starts precisely at the end of a `road_on_crosswalk` and ends at the end of the overlapping or following `one_way_road`.

Non-driving lanes route elements

Element	Description
`shoulder`	A shoulder lane along, or along part of, a `one_way_road`
`road_by_shoulder`	Driving lanes parallel to a shoulder lane.
`sidewalk`	A lane designated for pedestrian use, that runs along, or along part of, a `one_way_road`.
`road_by_sidewalk`	Driving lanes parallel to a sidewalk lane.
`bike_lane`	A lane designated for use by cyclists, that runs along, or along part of, a `one_way_road`.
`junction_bike_lane`	A `bike_lane` crossing a junction along an `internal_road`.

Virtual route elements

Element	Description
`crossing_path`	Virtual roads that do not exist in the source map. Their geometry is based on predefined patterns, and they are added to the map at scenario generation solving stage.

Other road elements

Element	Description
`road_with_merging_lane`	Represents a sequence of two `lane_section` occurrences where the number of lanes decreases from the first section to the next.
`road_to_force_merge`	Represents a pair of adjacent lanes - from-lane and to-lane - within the same `one_way_road` road.
`lane_to_force_merge_conflict`	Represents the lane in a road that leads to a force merge location.
`road_with_facing_road`	Represents a pair of `one_way_roads` - 'main' and 'facing' - that enter a junction from opposite directions.
`road_with_opposite_side`	Represents a one-way route that has an opposing one-way route driving in the opposite direction from start to end
`road_with_opposite`	Represents a pair of `road_with_opposite_side` lanes that have opposite driving directions.

OpenDRIVE MSP-specific elements

Element	Description
`odr_point`	For custom routes, the odr_point element is relevant only for .xodr source maps. It represents a specific lane position on the ODF map, defined by road ID, lane ID, and longitudinal offset.
`explicit_odr_route`	For custom routes, the explicit_odr_route element is relevant only for .xodr source maps. It represents the shortest route according to an ordered list of `odr_points`.
`odr_road`	Represents the driving lanes on one side of an OpenDRIVE road.