95. Match scenario coverage functions

The following built-in functions are used within match scenarios for implementing coverage and KPI collection.

95.1 Sample, cover, and record constructs

Sample, cover, and record are used in match scenarios to collect coverage and key performance indicators (KPIs). These constructs are explained in the OSC_monitoring section.

Example

    # Sample the start and end times of the lane-change phase of the cut-in scenario
    var lane_change_start_time: time = sample(top.time ,@change_lane.start)
    var lane_change_end_time: time = sample(top.time ,@change_lane.end)

    # Compute the duration of the lane-change maneuver
    var lane_change_duration: time = sample(lane_change_end_time - lane_change_start_time ,@end)

    # Collect the duration as a cover point
    cover(lane_change_duration, unit: s, range: [0..5], every: 1,
    text: "Duration of cut in vehicle lane change")

Limitations

1. Events used in sample(), cover(), and record() can only be scenario or phase start or end events. User defined events declared using the event constructs are not supported.
2. Expressions used in the above-mentioned constructs may only refer to data collected during the ingestion run.

95.2 collect()

Collect accumulates values of an expression during a run, starting at a start-event and ending at an end-event.

Syntax

collect_<exp-type>(exp: <exp>
    [, measure: <collect_measure_type>]
    [, text: <description>]
    [, start_event: <start_event_string>]
    [, end_event: <end_event_string>]
    )

The collect() modifier is a family of modifiers where each member collects expressions of a specific type. Currently, the family includes:

• collect_time()
• collect_distance()
• collect_speed()
• collect_acceleration()
• collect_jerk()

Accessing collect results

You can access the collect() computed_result output field for later analysis with the cover() and record() modifiers.

Example

   # Collect the minimal local longitudinal speed during the change lane phase of the cut-in scenario
    cut_in_vehicle_local_min_speed_lon_record: top.collect_speed(measure: min,
        exp: vehicle_actor.state.local_speed.lon,
        start_event: "change_lane.start", end_event: "change_lane.end")

    # Cover the result to analyze the bucketized values
    cover(cut_in_vehicle_local_min_speed_lon,
        expression: cut_in_vehicle_local_min_speed_lon_record.computed_result,
        range: [0..55], every: 10,
        unit: mps, text: "Minimum longitudinal local speed of cut in vehicle")

Limitations

1. start_event and end_event can only be scenario or phase start or end events. User defined events declared using the event constructs are not supported.
2. provide start_event and end_event paths as strings, enclosed in double quotes.
3. The Evaluation Pipeline does not flag any collected value related failures.

95.3 General built-in functions

The following functions may be used for coverage collection within monitor scenarios.

95.3.1 side_of_vehicle()

side_of_vehicle(ref_car: vehicle) -> av_rel_side

Returns the ref_car's relative position with respect to the Ego.

Parameters

Return value

One of the following enum values:

enum av_rel_side: [
   SAME = 0,
   LEFT = -1,
   RIGHT = 1,
   FAR_RIGHT = 2,
   FAR_LEFT = -2,
   UNKNOWN = 3
]

95.3.2 position()

position(ref_car: vehicle) -> length

Returns the Ego's distance from the reference vehicle.

Parameters

Return value

The Ego's distance from the ref_car

95.3.3 lane_occupied_speed()

lane_occupied_speed(side: av_side, distance_behind: length, distance_ahead: length) -> speed

Returns the speed of the lead vehicle at the indicated side of the Ego. This function scans the lane adjacent to the Ego for traffic, between the indicated distance_behind and distance_ahead. If there are any actors in the scanned region, the speed of the leading actor is returned. 0 is returned if the indicated lane is not occupied (no actors are present in the scanned region).

Parameters

Return value

The speed of the leading actor if found in the scanned region of the indicated lane, or 0 if no actors were found in that region.

95.3.4 lane_occupied_speed_by_time

lane_occupied_speed_by_time(side: av_side, time_behind: time, time_ahead: time) -> speed

Returns the speed of the lead vehicle found in the indicated side of the Ego. The function scans the lane adjacent to the Ego for presence of any actors, between the indicated distance_behind and distance_ahead, measured by time. (The distance is the Ego's speed divided by the time parameter). The speed of the leading actor found in the scanned region is returned. 0 is returned if no actors were found in the region.

Parameters

Return value

The speed of the leading actor if found in the scanned region of the indicated lane, or 0 if no actors were found in that region.

95.3.5 speed_drop()

speed_drop(start_time: time, end_time: time, speed_gap_threshold: speed) -> bool

Returns true if the receiver vehicle's speed drops by more than the specified threshold within the indicated time interval.

Parameters

Return value

Returns true if the receiver speed dropped by more than the speed_gap_thrashold within the observation interval.

95.3.6 on_different_lane()

on_different_lane(ref_car: vehicle) -> bool

Returns true if the ref_car is not in the Ego lane.

Parameters

Return value

Returns true if the ref_car is not in the Ego lane.

95.3.7 abs_distance()

abs_distance(distance: length) -> length

Returns the absolute value of distance.

Parameters

Return value

Returns the absolute value of distance.

95.3.8 ego_min_ttc()

ego_min_ttc(start_time: time, end_time: time) -> time

Returns the minimal time-to-collision for the Ego, as measured in the interval between start_time and end_time. The TTC is computed for all actors on the scene and the minimal value is returned.

Parameters

Return value

The minimal TTC of the Ego computed during the observation interval.

95.3.9 num_of_parallel_lanes()

num_of_parallel_lanes() -> int

Returns the number of lanes on the Ego's road for traffic driving in the same direction as the Ego.

Return value

The number of lanes on the Ego's road that are driving in the same direction as the Ego.

95.3.10 num_of_anti_parallel_lanes()

num_of_anti_parallel_lanes() -> int

Returns the number of lanes on the Ego's road that are driving in the opposite direction of the Ego.

Return value

The number of lanes on the Ego's road that are driving in the opposite direction of the Ego.

95.3.11 road_speed_limit()

road_speed_limit() -> speed

Returns the Ego road speed limit.

Return value

The speed limit of the road the Ego is driving on.

95.3.12 road_width()

road_width() -> length

Returns the width of the road segment the Ego is driving on.

Return value

Returns the width of the road segment the Ego is driving on.

95.3.13 side_of_vehicle_in_lane()

side_of_vehicle_in_lane(ref_car: vehicle) -> av_side

Returns the side of ref_car relative to the Ego when the ref_car is in the Ego lane. In this case the ref_car may be a bicycle, motorcycle or any other narrow vehicle that could be adjacent to the Ego on its lane.

Parameters

Return value

One of the following enum values:

enum av_side: [
   UNKNOWN = 0,
   LEFT = -1,
   RIGHT = 1
]

95.3.14 side_of_vehicle_in_lane()

side_of_vehicle_in_lane(ref_car: vehicle) -> av_side

Returns the side of the ref_vehicle relative to the Ego. This function uses the lateral distance between the vehicles to determine the side and ignores map-related considerations.

Parameters

Return value

One of the following enum values:

enum av_side: [
   UNKNOWN = 0,
   LEFT = -1,
   RIGHT = 1
]

95.3.15 min_gap()

min_gap(ref_car: vehicle, start_time: time, end_time: time) -> length

Returns the minimal distance between the Ego and the ref_car. Distance is computed over a time interval between start_time and end_time and the minimal value is returned.

Parameters

Return value

The minimal distance computed over the observation interval.

95.3.16 min_ttc_with_ref_car()

min_ttc_with_ref_car(ref_car: vehicle, start_time: time, end_time: time) -> time

Returns the minimal Time To Collision (TTC) between the Ego and the ref_car. TTC is computed over a time interval between start_time and end_time and the minimal value is returned.

Parameters

Return value

The minimal TTC computed over the observation interval.

95.3.17 get_ego_lane()

get_ego_lane() -> int

Returns the Ego's lane number.

Return value

The Ego's lane number.

95.3.18 max_actors_in_interval

max_actors_in_interval(start_time: time, end_time: time, max_distance: length, min_speed: speed, stationary: bool) -> int

Returns the maximal number of actors in a single frame within the interval between start_time and end_time. Actors are counted if their distance from the Ego is less than max_distance and their speed is over min_speed. Stationary actors are excluded unless stationary is true.

Parameters

Return value

The maximal number of qualifying actors in a single frame within the observation interval.

95.3.19 get_relative_time_distance()

get_relative_time_distance(car: vehicle)-> time

Returns the time it would take the Ego to reach the reference car's position. It is calculated by dividing the distance between the Ego and the reference car by their closing speed.

Parameters

Return value

Returns the time it would take to reach the reference actor, assuming fixed speeds.

95.3.20 get_time_headway()

get_time_headway(ref_car: vehicle)-> time

Returns the time it would take the Ego to reach the current position of the ref_car, taking into account the Ego's speed and ignoring the possibility that the reference actor may move from its current position.

Parameters

Return value

Returns the time it would take the Ego to reach the reference actor's current position assuming the Ego moves at a constant speed.

95.3.21 abs_distance()

abs_distance(distance: length)-> length

Returns the absolute value of the distance provided (which may be negative).

Parameters

Return value

The absolute value of the input distance value.

95.4 Junction related built-in functions

95.4.1 traversal_direction()

vehicle.traversal_direction() -> traversal_direction

Returns the traversal direction of the vehicle within a junction.

Return value

One of the following enum values:

enum traversal_direction: [
   other = 0,
   straight = 1,
   right = 3,
   backwards = 5,
   left = 7,
   unknown = 9
]

95.4.2 traffic_control_device()

traffic_control_device(max_distance_from_junction: length) -> traffic_control

Returns the type of traffic control implemented at a junction that is within the maximal distance from the vehicle.

Parameters

Return value

One of the following enum values:

enum traffic_control: [none = 0, traffic_light = 1, stop_sign = 2, yield_sign = 3]

95.4.3 traffic_light_color_change()

traffic_light_color_change(start_time: time, end_time: time) -> tl_color_change

Returns the traffic light transition observed within the specified time interval.

Parameters

Return value

One of the following enum values:

    enum tl_color_change: [
        unknown_to_unknown = 0,
        unknown_to_green = 1,
        unknown_to_yellow = 2,
        unknown_to_red = 3,
        green_to_unknown = 4,
        green_to_green = 5,
        green_to_yellow = 6,
        green_to_red = 7,
        yellow_to_unknown = 8,
        yellow_to_green = 9,
        yellow_to_yellow = 10,
        yellow_to_red = 11,
        red_to_unknown = 12,
        red_to_green = 13,
        red_to_yellow = 14,
        red_to_red = 15,
        no_traffic_light = 16
    ]

95.4.4 traversal_relative_direction()

traversal_relative_direction(ref_car: vehicle) -> traversal_relative_direction

Returns the traversal direction of the ref_car relative to the Ego. If called when the Ego is not by a junction, then the returned direction is unknown.

Parameters

Return value

One of the following enum values:

enum traversal_relative_direction: [
    parallel_to_right = 0,
    parallel_to_parallel = 1,
    parallel_to_left = 2,
    parallel_to_opposite = 3,
    right_to_parallel = 4,
    right_to_left = 5,
    right_to_opposite = 6,
    right_to_right = 7,
    opposite_to_opposite = 8,
    opposite_to_right = 9,
    opposite_to_left = 10,
    opposite_to_parallel = 11,
    left_to_parallel = 12,
    left_to_right = 13,
    left_to_opposite = 14,
    left_to_left = 15,
    unknown = 16
]

95.4.5 traversal_type()

traversal_type(start_time: time, end_time: time) -> traversal_type

Returns the right-of-way status during the Ego's traversal of a junction with a traffic light. The default value is unprotected. If the Ego has the right-of-way such as driving straight at a green light, turning right at a green light, or turning left at a left arrow, the returned value is protected. If the traffic light changes during the traversal, the relevant transitional value is returned. For junctions with no traffic light, unprotectedis returned.

Return value

Returns one of the following enum values:

enum traversal_type: [
   protected = 1,
   unprotected = 2,
   protected_to_unprotected = 3,
   unprotected_to_protected = 4
]

95.4.6 max_num_of_lanes_in_oncoming_legs()

max_num_of_lanes_in_oncoming_legs() -> int

Returns the number of lanes for the widest road classified as oncoming (see traversal_relative_direction()).

Return value

Returns the number of lanes for the widest oncoming road.

95.4.7 max_num_of_lanes_in_crossing_legs()

max_num_of_lanes_in_crossing_legs() -> int

Returns the number of lanes for the widest road classified as crossing (see traversal_relative_direction()).

Return value

Returns the number of lanes for the widest crossing road.

95.4.8 max_num_of_lanes_in_incoming_legs()

max_num_of_lanes_in_oncoming_legs() -> int

Returns the number of lanes for the widest road classified as incoming (see traversal_relative_direction()).

Return value

Returns the number of lanes for the widest incoming road.

95.4.9 number_of_junction_legs()

number_of_junction_legs() -> int

Returns the number of roads entering or exiting the junction. A road that has both entering and exiting lanes is counted as one.

Return value

Returns the number of entering and exiting roads connected to the junction.

95.4.10 planned_path_complexity_index()

planned_path_complexity_index(start_time: time, end_time: time) -> int

Returns the number of potential paths in a junction that cross the Ego's path. This index reflects the complexity or difficulty of traversing the junction.

Return value

Returns the complexity index, which is the number of potential internal paths crossed during junction traversal.

95.4.11 lane_gap_post_junction

lane_gap_post_junction(ref_car: vehicle) -> int

Returns the absolute number of lane changes between the Ego and the ref_car if both end up on the same road after exiting a junction. If the two actors don't end up on the same road, -1 is returned.

Parameters

Return value

The number of lane changes between the Ego and the reference actor when they end up in the same lane as they exit a junction. If they are not in the same lane, -1 is returned.