Disclaimer

This document is the copyrighted property of ASAM e.V.

Any use is limited to the scope described in the license terms (https://www.asam.net/license). In alteration to the regular license terms, ASAM allows unrestricted distribution of this standard. §2 (1) of ASAM’s regular license terms is therefore substituted by the following clause: "The licensor grants everyone a basic, non-exclusive and unlimited license to use the standard ASAM OpenSCENARIO".

Foreword

OpenSCENARIO comprises the specification and file schema for the description of dynamic content in driving simulation applications. The primary use of OpenSCENARIO is the description of complex maneuvers that involve multiple vehicles.

OpenSCENARIO is used in virtual development, test, and validation of functions for driver assistance, automated driving and autonomous driving. The standard may be used in conjunction with ASAM OpenDRIVE [1] and ASAM OpenCRG [2], which describe static content in driving simulation.

After the standard had been developed over several years in an industry consortium, it was transferred to ASAM e.V. in March 2020.

1. Introduction

1.1. What has changed

The following main changes were made in OpenSCENARIO 1.1 compared to OpenSCENARIO 1.0:

  • Support for logical scenarios

    • Parameter value distributions for scenario variation / automated generation of concrete scenarios

    • Stochastic and deterministic distributions

    • Single- and multi-parameter distributions

  • More flexible maneuver modeling

    • Arithmetic calculations and logical expressions

    • External object referencing in road network

    • Trajectory coordinate system and positions

  • Compatibility with more road network formats

    • Geographic coordinate system and positions

  • Improved test support

    • Parameter-value constraints (ranges) prevent misuse and misunderstanding of scenarios in test design

    • Consistency with ASAM OSI (weather conditions)

  • Improved sensor test support

    • 3D model referencing

    • Precipitation

  • Improved controller test support

    • Wind, atmospheric pressure, outside temperature (for external force on vehicle calculation)

  • Improved exchangeability of scenarios

    • Licensing information can be included

  • Clarifications

    • Actions (traffic, lane change, lane offset, longitudinal/lateral distance, synchronize, controller assignment/activation, etc.)

    • Conditions ( (relative) distance, time headway, time to collision)

    • Distance calculation

    • Controller concept (control strategy)

    • Init actions and end of simulation/scenario

    • Default values

    • Restrictions on entity selection references for actions and conditions

    • Parameter usage

    • Runtime behavior of scenarios in an environment simulator

    • System boundaries of OpenSCENARIO

  • Corrected examples

    • Consistency of scenario files for User Guide

    • Validation of scenarios and road networks against schema

    • Executability in environment simulators

  • Enhanced User Guide

    • Applied consistent structure throughout ASAM OpenX standards

  • Ensured backward compatibility

    • Introduced deprecation mechanism

1.2. Overview

Scenario descriptions are essential for testing, validating, and certifying the safety of driver assistance systems and autonomous cars. The industry, certification bodies, and government authorities jointly define scenario libraries that can be used to test and validate the safe operation of such systems. A publicly developed and vendor-independent standard, such as OpenSCENARIO, supports this endeavor by enabling the exchange and usability of scenarios in various simulation applications.

As an example, with the help of OpenSCENARIO large numbers of critical situations can be run across various simulators. Thus, compared to road testing in real traffic, the number of test kilometers driven in field tests can be significantly reduced.

1.2.1. What is a scenario?

A scenario is a description of how the view of the world changes with time, usually from a specific perspective. In the context of vehicles and driving, this encompasses the developing view of both world-fixed (static) elements, such as road layout and road furniture, and world-changing (dynamic) elements, such as weather and lighting, vehicles, objects, people, and traffic light states. This description is independent of whether the environment is simulated, real, or any combination thereof.

In a simulation context, a complete scenario is comprised of the following parts:

  • Static environment description, including:

    • Logical road network

    • Optionally physical and geometric road and environment descriptions

  • Dynamic content description, including:

    • Overall description and coordination of behavior of dynamic entities

    • Optional behavior models of dynamic entities

1.2.2. What is OpenSCENARIO?

OpenSCENARIO defines a data model and a derived file format for the description of scenarios used in driving and traffic simulators, as well as in automotive virtual development, testing, and validation. The primary use case of OpenSCENARIO is to describe complex, synchronized maneuvers that involve multiple entities, like vehicles, pedestrians, and other traffic participants. The description of a scenario may be based on driver actions, for example, performing a lane change, or on trajectories, for example, derived from a recorded driving maneuver. The standard provides the description methodology for scenarios by defining hierarchical elements, from which scenarios, their attributes, and relations are constructed. This methodology comprises:

  • Storyboarding, that is usage of a storyboard and stories. Each story consists of one or more acts and maneuvers.

  • An event is triggered by a trigger, when a condition is evaluated to true. Events cause the execution of actions.

  • References to logical road network descriptions.

  • Instantiation of entities, such as vehicles, or pedestrians, acting on and off the road.

  • Catalogs and parameter declarations provide mechanisms to re-use several aspects of a scenario.

Other content, such as the description of the ego vehicle, driver appearance, pedestrians, traffic and environment conditions, is included in the standard as well.

Scenario descriptions in OpenSCENARIO are organized in a hierarchical structure and serialized in an XML file format with the file extension .xosc.

OpenSCENARIO defines the dynamic content of the (simulated) world, for example, the behavior of traffic participants. Static components, such as the road network, are not part of OpenSCENARIO but can be referenced by the format.

OpenSCENARIO does not specify the behavior models themselves or their handling by a simulation engine.

Furthermore, beyond the scenario itself, other pieces of information are needed to describe a full simulation setup and test case. OpenSCENARIO cannot not be regarded as a complete specification of a simulator, its system under test or, its test case. The following features specifically are not considered in scope for OpenSCENARIO:

Table 1. What is not part of OpenSCENARIO
Feature Description

Test configuration description

OpenSCENARIO does not describe a test instance or its structure.

Test case language

OpenSCENARIO does not specify all possible user or system interactions with a vehicle.

Test evaluation

OpenSCENARIO does not include concepts for creating test verdicts, although it contains methods for the evaluation conditions for triggering actions.

Driver model

OpenSCENARIO does not include behavioral driver models, except for basic concepts, such as the physiological description of a driver.

Vehicle dynamics

OpenSCENARIO does not include elements to describe advanced motion dynamics for vehicles.

Environmental models

OpenSCENARIO includes elements to define environmental properties, such as the current time or the weather, but does not specify how this is to be interpreted by a simulator.

1.2.3. Deliverables of OpenSCENARIO

The core of the specification is an XML schema file. It is accompanied by an HTML documentation of its underlying UML model and by this User Guide. Several example files show, how the XML schema has to be applied to model scenarios. To migrate existing scenario files to newer versions, scripts and schemas are provided. The UML model and modelling guidelines for further extensions are provided as well. Thus, the standard comprises the following content:

  • XML schema file

  • Model documentation (html)

  • User Guide

  • Examples

  • Migration scripts and schemas

  • UML model

  • Modelling guidelines

1.3. Normative and non-normative statements

This User Guide uses a standard information structure. The following rules apply regarding normativity of sections:

  • Statements expressed as requirements, permissions, or prohibitions according to the use of modal verbs, as defined in Section 1.4.3, are normative.

  • Code samples and use case descriptions are non-normative.

1.4. Conventions

1.4.1. Units

All numeric values within this standard are using SI units, unless explicitly stated otherwise. Table 2 presents details of the used units.

Table 2. Units
Unit of Unit Symbol

Length

Meter

m

Duration, (relative) time

Second

s

Speed

Meters per second

m/s

Acceleration

Meters per second squared

m/s²

Mass

Kilogram

kg

Angle

Radians

rad

Light intensity

Lux

lx

1.4.2. Data types

OpenSCENARIO uses the XSD 1.0 data types [3] string, Boolean, dateTime, double, integer, unsignedInt and unsignedShort.

In OpenSCENARIO, the usage of date and time is restricted to the ISO 8601 [4] Basic Notation. The following format pattern is used: "yyyy-MM-dd 'T' HH:mm:ss '.' FFFZ". Here 'T' is again used as time designator and '.' is used as separator for the following millisecond portion. An explanation is given in Table 3.

Table 3. Date and time format specifiers
Specifiers Meaning Example

yyyy

Year (four digits)

2011

M, MM

Month in year (without / with leading zero)

9, 09

d, dd

Day in month (without / with leading zero)

3, 09

H, HH

Hours, 0-23 count (without / with leading zero)

7, 07

m, mm

Minutes (without / with leading zero)

2, 02

s, ss

Seconds (without / with leading zero)

4, 04

F, FF, FFF

Milliseconds (without / with leading zeros)

357, 04, 002

Z

RFC 822 time zone (time shift to GMT)

+100

At a given date and time of 2011-03-10 11:23:56 in the Central European Time zone (CET), the following standard-format output is produced:

2011-03-10T11:23:56.000+0100

1.4.3. Modal verbs

To ensure compliance with the other OpenX standards, users must be able to distinguish between mandatory requirements, recommendations, permissions, as well as possibilities, capabilities, obligations and necessities.

The following rules for using modal verbs apply:

Table 4. Rules for using modal verbs
Provision Verbal form

Requirement
Requirements shall be followed strictly in order to be conform to the standard. Deviations are not allowed.

shall
shall not

Recommendation
Recommendations indicate that among several possibilities, one is recommended as particularly suitable, without mentioning or excluding others.

should
should not

Permission
Permissions indicate a course of action permissible within the limits of the ASAM standard’s deliverables.

may
need not

Possibility and capability
These verbal forms are used for stating possibilities or capabilities, being technical, material, physical, or others.

can
cannot

Obligation and necessity
These verbal forms are used to describe legal, organizational, or technical obligations and necessities that are not regulated or enforced by the ASAM standard’s.

must
must not

1.4.4. Typographic conventions

This documentation uses the following typographical conventions:

Table 5. Typographical conventions
Mark-up Definition

Code elements

This format is used for code elements, such as technical names of classes and attributes, as well as attribute values.

Code snippets

This format is used for excerpts of code that serve as an example for implementation.

Terms

This format is used to introduce glossary terms, new terms and to emphasize terms.

1.4.5. Naming conventions for OpenSCENARIO references

Elements in scenario descriptions may be referenced from other parts of the description through their names. To ensure that all references can be unambiguously resolved, the following set of rules apply for references to scenario elements:

  • Name lookup shall start at the referencing element, but shall comprise all elements at all hierarchy levels of the scenario hierarchy.

  • Element names at each level shall be unique at that level. There shall not be more than one element with the same name at the same level (within the same directly enclosing element). For example, within one Story, every Act shall use a unique name ("MyStory1": "MyAct1", "MyAct2"…​), but the names of the acts may be reused in another story ("MyStory2": "MyAct1", "MyAct2"…​).

  • If the referenced name is globally unique, then it may be used directly as the only part of the reference. If the referenced name is not globally unique, name prefixes shall be be used to make the name unique.

  • A name prefix consists of the name of a directly enclosing element, which is prefixed to the name using the separator '::', thus forming a new name reference. This implies that the '::' must not be used in names itself. The name is disambiguated by the "::" specifying a directly enclosing element name.

  • Multiple prefixes of subordinate enclosing elements may be specified, up to the root element name, until a globally unique reference name is established.

  • If a reference cannot be resolved uniquely, for example, if too few name prefixes have been specified the result of the lookup is undefined.

1.5. Contributing to OpenSCENARIO

OpenSCENARIO is maintained by ASAM. Like all ASAM standards, it grows and changes over time. To reflect these changes, ASAM regularly launches projects to enhance OpenSCENARIO, keep it up to date, and adapt it to the latest industry requirements. All ASAM members, regardless of the background of their company, are welcome to contribute to these projects by bringing in their broad range of knowledge. Only by combining the expertise of various experts, OpenSCENARIO reaches the widest possible audience.

All new projects regarding OpenSCENARIO and other ASAM standards can be found on the ASAM website.

2. Releases and relations to other standards

2.1. Earlier releases of OpenSCENARIO

Table 6. Revision history of OpenSCENARIO
Version number Release date Comments

v1.1.1

2021-11-10

Bugfix Release

v1.1.0

2021-03-18

v1.0.0

2020-03-13

Transfer to ASAM

v0.9.1

2018-09-01

2.2. Relations to other ASAM standards

OpenSCENARIO is part of the ASAM simulation standards that focus on simulation data for the automotive environment. The standard can be used together with road network descriptions defined according to the standard ASAM OpenDRIVE and the description of the road surface described by ASAM OpenCRG. The three standards complement each other, together defining the content required to describe the simulated world. When combined, all three standards provide a scenario-driven description of traffic simulation that contains both static and dynamic content.

2.3. Relations to other non-ASAM standards

The terminology of OpenSCENARIO is based on the ISO standard 8855:2011 [5]. OpenSCENARIO can be complemented by other logical road network as well as 3D model standards. The following list gives some examples:

  • Logical road network

    • Navigation Data Standard (NDS) [6]

  • 3D models of road, scenery and objects

    • CityGML [7]

    • OpenSceneGraph [8]

    • glTF (Khronos Group) [9]

    • FBX (Autodesk) [10]

    • 3ds (Autodesk) [11]

3. General concepts of OpenSCENARIO

3.1. Architecture

OpenSCENARIO provides standardized descriptions of traffic situations for the purpose of simulation. Such descriptions represent executable scenarios that enforce a specific behavior during simulation runtime. For this reason, OpenSCENARIO covers two main aspects:

  • Designing a scenario (design time)

  • Executing a scenario (runtime)

The definition of system boundaries and the existence of an abstract runtime model are fundamental for the design of a meaningful scenario because they help bridge the gap between scenario designer and tool implementer. System boundaries delimit the standard’s scope by separating concepts covered by the standard from those concepts that are covered by external systems or definitions.

An abstract runtime model represents a basic contract between the author of a scenario and the provider of a simulation environment, together with a common idea about what should happen when a specific scenario is executed.

OpenSCENARIO does not describe all these aspects in detail. OpenSCENARIO provides a solution space and data model for defining traffic situations. The data model is supplemented with an abstract runtime model necessary to interpret interactions between the components at runtime.

3.1.1. Basic architecture components

The OpenSCENARIO architecture contains the following basic components:

  • An OpenSCENARIO Model Instance (OSC Model Instance) represents a scenario description in the solution space defined by the data model.

  • An OpenSCENARIO Director (OSC Director) is a component that interprets the OSC Model Instance and governs the progress of a scenario in a simulation. The OSC Director is the component responsible for running the scenario.

  • A Simulator Core. The Simulator Core is defined as all components other than OSC Director or OSC Model Instance that are needed to run a simulation. The Simulator Core is an external concept to OpenSCENARIO and provides an interface to the OSC Director for orchestrating the traffic situations defined in the scenario.

Figure 1 illustrates how the components interact:

image
Figure 1. OpenSCENARIO base architecture
This architecture is a simple abstraction to help understand how a scenario is coupled to a running simulation. It is not the intent of the OpenSCENARIO standard to prescribe a formal software architecture for simulator implementation. The provided architecture informally illustrates how components are separated and how interaction can be achieved. Implementation-specific details are not part of this architecture, even though the ideas and concepts might be useful when designing a simulation or designing a scenario.

3.1.2. OpenSCENARIO elements

OSC Director and Simulator Core both manage the lifecycle of elements within their respective scope. An element is an object instance that exists either in the OSC Director or in the Simulator Core and may change its state during the execution of a scenario. OpenSCENARIO clearly states which elements shall be encapsulated in a OSC Director and which elements are managed by a Simulator Core.

Elements of the OSC Director

The OSC Director manages the lifecycle of the following elements:

  • Storyboard (1 per scenario)

  • Story instances (0..* per Storyboard)

  • Act instances (1..* per Story)

  • ManeuverGroup instances (1..* per Act)

  • Maneuver instances (0..* per ManeuverGroup)

  • Event instances (1..* per Maneuver)

  • Action instances (1..* per Event)

The OSC Director performs the nested and concurrent execution of the elements above. This includes:

  • Forking into different execution paths.

  • Joining from different execution paths.

  • Loop execution (ManeuverGroup , Event) for maximumExecutionCount > 1.

Section 4.2 describes the runtime behaviour of storyboard elements in detail.

Elements in the Simulator Core

OpenSCENARIO also requires an abstract understanding of elements that are not under the responsibility of the OSC Director at runtime. These are:

  • Entities representing traffic participants, such as vehicles and pedestrians.

  • Environmental parameters, such as time of day, weather, and road conditions.

  • Traffic signal controllers and traffic signals.

  • Traffic objects, such as swarms of vehicles, sources for vehicles, and sinks of vehicles.

  • Controllers: Default controllers, user-defined controllers like simulated drivers, or drivers in the loop.

  • Control strategies: Entity control instructions that originate from actions.

  • User parameters.

Element states

Elements generally have a set of property values at runtime. Because properties and relations, for example speed and position, may change during the simulation the complete set of property values and relations at a specific time represents the state of an element.

Static elements

A static element is a stateless component that does not change during runtime. Examples of static elements are the road network and road surface descriptions. These resources may be shared between OSC Director and Simulator Core.

3.1.3. Executing a scenario

Executing a scenario synchronizes the state of the elements in the OSC Director with the state of the elements in the Simulator Core.

The OSC Director interprets the OSC Model Instance at runtime, which translates in commands to the Simulator Core. The Simulator Core handles its elements, whose states are used by the OSC Director, to guide the developing scenario in the directions prescribed by the OSC Model Instance.

As an example, the SpeedCondition can be used via its application in a startTrigger to couple the speed of an entity managed by the Simulator Core to the start of an event that is managed by the OSC Director.

3.1.4. Actions and conditions

Actions and Conditions are abstract concepts that enable an OSC Director to interact with the Simulator Core and thus manage the ongoing simulation in accordance with the OSC Model Instance. Actions are used to manage the simulation by targeting the behavior of traffic simulation elements in Simulator Core. Conditions evaluate the state of traffic simulation elements in Simulator Core.

image
Figure 2. Actions and conditions
Figure 2 illustrates the idea behind the logical concepts. It is not an implementation recommendation or guideline and does not intended to represent interactions between programs or define software protocols. Condition evaluation, for example, could also be implemented with a publish-subscribe mechanism on the trigger level.

In OpenSCENARIO, actions are the exclusive mechanisms for controling and modifying the content of a simulation. Conditions are the exclusive mechanisms for evaluating the status information of a simulation.

Actions are not the only factor influencing simulations. Other influencing factors are driver models, drivers-in-the-loop, and environmental conditions. These concepts are not defined in OpenSCENARIO.

In the same way, conditions cannot describe all quantified property values that exist in a simulation. Simulations can vary in scope and details of their simulated components. In order to be compatible with other simulation standards, OpenSCENARIO builds on high-level, abstract information that represents a common denominator for a majority of simulations. For example, a condition can be used to specify the speed of a vehicle, but not the speed of the vehicle’s left front wheel.

The OpenSCENARIO format is organic, meaning it may grow dependent on the used application. It can be expected that the scope of what is possible to use in conditions expands as the format grows. The same applies for actions. Actions and conditions are described in detail in Section 4.

3.1.5. Abstract OpenSCENARIO architecture

With the definition of actions and conditions, the logical interface between OSC Director and Simulator Core can be refined into an Apply Action Interface and an Evaluate Condition Interface. More generic interfaces are also required for general commands like initialize, starting, and stopping a simulation. Figure 3 illustrates the architecture of OpenSCENARIO.

image
Figure 3. Abstract OpenSCENARIO architecture
The architecture depicted in Figure 3 illustrates the logical relations between the identified components and interfaces. It is not meant to prescribe a formal software API.

3.2. Road networks and environment models

A scenario description may require references to a specific road network as well as inclusion of specific 3D models that represent the simulated environment visually. The definition of road network logic and/or environment 3D models is optional of OpenSCENARIO. Those references are established within the RoadNetwork language element. As an example, the OpenDRIVE file format is common when it comes to describing road network logic.

Scenario authors often need to refer to items defined in the road network, for example, to instruct a vehicle to drive in a specific lane. OpenSCENARIO does not impose its own naming system for these items; they should be referred with the names allocated by their own file format.

The following features of the road network may be addressed using OpenSCENARIO:

  • Individual road

  • Lane within a road

  • Traffic signal

  • Traffic signal controller

  • Road object

As mentioned before, a road network description supported by OpenSCENARIO is the OpenDRIVE format. This format describes the logical information related to road structure, such as road id, lane id, and road geometry. This information may be used to locate and position instances of Entity acting on the road and to position traffic participants. If OpenDRIVE is used to represent the road network, the OpenSCENARIO file should follow the OpenDRIVE conventions for numbering lanes.

In addition to the road network description, 3D models representing the environment may be referenced in a scenario description. Files containing 3D models provide the geometric and visual representation, like mesh and textures for elements of the virtual environment including the road surface. Use cases for 3D models referenced from scenarios are rendering, physical modeling, and sensor simulation. Files containing 3D models are considered to be external elements to the OpenSCENARIO format.

It is also possible to outsource some parts of the scenario description to an external Catalog file. The process for referencing external scenario parts is described in Section 6.4

3.3. Coordinate systems

Following the ISO 8855:2011 [5] convention, a coordinate system consists of a set of three orthogonal directions associated with X, Y, Z axes (an axis system) and a coordinate origin. In OpenSCENARIO, there are two main types of coordinate systems:

  • A right-handed coordinate system, compliant with the ISO 8855:2011 [5] definition. Orientation is expressed by a heading(yaw)-pitch-roll sequence of rotations (see Figure 4)

    image
    Figure 4. Heading, pitch, and roll angle in an ISO 8855:2011 compliant coordinate system
  • A right-handed, road-based coordinate system defined by two coordinate axes associated with the reference line of the corresponding road (s-axis) and the direction orthogonal to it (t-axis) and pointing leftwards (see Figure 5)

    image
    Figure 5. Road-based s/t-coordinate system with origin at the beginning of the road

These coordinate system types are referenced to create the following coordinate systems:

3.3.1. World coordinate system (Xw, Yw, Zw)

Coordinate system of type (X, Y, Z) fixed in the inertial reference frame of the simulation environment, with Xw and Yw axes parallel to the ground plane and Zw axis pointing upward.

Neither origin nor orientation of the world coordinate system are defined by the OpenSCENARIO standard. If a road network is referenced from a scenario, the world coordinate system is aligned with the inertial coordinate system present in this description.

3.3.2. Road coordinate system (s/t)

To every road specified in the world coordinate system there is an s/t-type coordinate system assigned. The s-axis follows road reference line while the t-axis, orthogonal to the s-axis, points left. The origin of the s-coordinate resides at the start point of the road. The origin of the t-coordinate is fixed to the road center line at the current s-position.

3.3.3. Lane Coordinate System (s/t)

To every lane specified in a lane section of a road there is an s/t-type coordinate system assigned. The s-axis follows the lane center line while the t-axis, orthogonal to the s-axis, points left. The origin of the s-coordinate resides at the mid point between the lane’s left and right boundaries at the very start of its lane section. The origin of the t-coordinate is fixed to the lane center line at the current s-position.

3.3.4. Vehicle coordinate system (Xv, Yv, Zv)

The vehicle axis system of type (X, Y, Z), as defined in ISO 8855:2011 [5], is fixed in the reference frame of the vehicle sprung mass. The Xv axis is horizontal and forwards with the vehicle at rest. The Xv axis is parallel to the vehicle’s longitudinal plane of symmetry. The Yv axis is perpendicular to the vehicle’s longitudinal plane of symmetry and points left. The Zv axis points upward.

In OpenSCENARIO, the origin of this coordinate system is derived by projecting the center of the vehicle’s rear axis to the ground plane at neutral load conditions. The origin remains fixed to the vehicle sprung mass, as illustrated in Figure 6.

image
Figure 6. Vehicle coordinate system

3.3.5. Pedestrian / MiscObject coordinate system (Xp/m , Yp/m , Zp/m)

The axis system for a pedestrian (subscript p) or a miscellaneous object (subscript m) is fixed in the reference frame of the object’s bounding box. The X axis is horizontal and normal to the object’s front plane. The Y axis is horizontal, perpendicular to X, and points to the left. The Z-axis points upward.

The origin of this coordinate system is derived from the geometrical center of the object’s bounding box under neutral load conditions (if applicable) projected onto the ground plane.

3.3.6. Geographic coordinate system (latitude, longitude, height)

The geographic coordinate system is a spherical coordinate system of type (latitude, longitude, height). Latitude and longitude axes are parallel to the ground plane. The height axis points upward.

Neither origin nor orientation of the geographic coordinate system are defined by OpenSCENARIO. If a road network is referenced from a scenario, the geographic coordinate system is aligned with the geographic coordinate system present in the road network. The offset in coordinates and in orientation between world coordinate system and geographic coordinate system shall be defined in the road network.

3.3.7. Positioning

OpenSCENARIO provides various ways to position or localize instances of Entity acting in the scenario:

  • Absolute/relative in the world coordinate system

  • Absolute in the geographic coordinate system

  • Relative to another Entity

  • Absolute/relative in the road coordinate system

  • Absolute/relative in the lane coordinate system

  • Relative to a Route

  • Relative to a Trajectory

3.4. Distances

OpenSCENARIO interprets distances in special ways. To properly use instances of Action and Condition, it is important to understand distance interpretation.

Depending on the use case, a distance may be specified between:

  • Two points.

  • A point and an Entity (with or without bounding box considerations).

  • Two entities (with or without bounding box considerations).

The general term point used in this chapter may be replaced with the OpenSCENARIO specific term position. Within the scope of this chapter, both terms can be used interchangeably.

Distances in OpenSCENARIO may be measured in two ways:

  • From a local coordinate system, with lateral and longitudinal distance in an Entity, road, lane, or trajectory coordinate system.

  • In absolute context, that is Euclidean distance.

OpenSCENARIO assumes distances to be greater than equal to zero, (ℝ+0).

3.4.1. Visualization

If not otherwise stated, the three-dimensional Euclidean space (ℝ3) is used for distance measurement. In some cases and for better visualization, a two-dimensional space is used (ℝ2). In these cases, generalization for ℝ3 is provided.

For convenience, only one direction of travel is shown when visualizing a road, as shown in Figure 7.

image
Figure 7. Parts are not shown in road visualizations.

3.4.2. Referring to distances in OpenSCENARIO

In OpenSCENARIO, lateral and longitudinal distance depends on the type of referential, for example Entity, road, lane, or trajectory. Euclidean distance is measured in a global context.

3.4.3. Euclidean distance

Euclidean distance between two points in Euclidean space is the length of a line segment between those two points, as shown in Figure 8. It is unambiguously defined in ℝ3, independently from the coordinate system that describes the coordinates.

image
Figure 8. Euclidean distance dAB between two points A/B

3.4.4. Distances in an entity coordinate system

Given two points A = (XA , YA , ZA) and B = (XB , YB , ZB) in the coordinates of a specific Entity, the definition in OpenSCENARIO is:

  • Longitudinal Entity distance - (dXAB): |XB - XA |

  • Lateral Entity distance - (dYAB): |YB - YA |

image
Figure 9. Longitudinal entity distance dXAB and lateral entity distance dYAB between point A and point B in entity referentials

3.4.5. Distances in road coordinates

Given two points in road coordinates A = (sA , tA , hA) and B = (sB , tB , hB), the definition in OpenSCENARIO is:

  • Longitudinal road distance: dsAB: |sB - sA|

  • Lateral road distance: dtAB: |tB - tA|

image
Figure 10. Longitudinal road distance dsAB and lateral road distance dtAB between point A and point B in road referentials

3.4.6. Lane distance and trajectory distance

Distances based on the lane or trajectory referentials are measured using the same methods as distances measured in the road referential.

  • Distances measured in the lane referential use the lane center as a reference line, rather than the road reference line.

  • Distances measured in the trajectory referential use the trajectory as a reference line, rather than the road reference line.

Trajectories do not define a road plane and thus no lateral direction. Trajectories shall be projected onto a road or plane, depending on the definition for measuring unambiguous lateral trajectory distances.

3.4.7. Involving an entity in a distance calculation

In addition to distances between two points, OpenSCENARIO also support distance measurement between two entities or between an entity and a point. In both cases, it is important to identify the two points of interest and apply the distance concepts introduced in this chapter.

Identifying the point of interest for an Entity depends on the value of the Boolean attribute freeSpace. It determines whether the entities bounding box shall be taken into consideration (freeSpace = true), or shall not be taken into consideration (freeSpace = false).

freeSpace = false

In this case, the bounding boxes of the entity shall not be considered. The point of the entity used to calculate the distance is the entity’s origin. That means:

  • The distance between point P and Entity E is the distance between point P and Entity E’s origin (E0), as shown in Figure 11.

image
Figure 11. Distances between a point P and an entity E, with freespace = false

In this case, the bounding boxes of the Entity shall be considered. Which point is chosen depends on the desired distance type.

  • The distance between Entity E and Entity F is the distance between their origins (E0, F0), as shown in Figure 12.

image
Figure 12. Distances between an entity E and an entity F, with freespace = false.
freeSpace = true

For distances between entities and reference points:

  • In the Entity referential, if the desired distance is the Euclidean distance, then the point of interest is the point on the bounding box of the Entity which yields the lowest distance value to the reference point.

  • If the desired distance is longitudinal, then the point of interest is the point on the bounding box of the Entity that yields the lowest longitudinal distance to the reference point.

  • If the desired distance is lateral, then the point of interest is the point on the bounding box of the Entity that yields the lowest lateral distance to the reference point.

image
Figure 13. Distances between a point P and an entity E, with freespace = true.
If freeSpace = true, the distance between an Entity and a point on or in its bounding box is zero.

For distances between entities:

  • In the Entity referential, if the desired distance is the Euclidean distance, then the points of interest are the two points on the entities' bounding boxes that yield the lowest distance.

  • If the desired distance is longitudinal, then the points of interest are the two points on the entities' bounding boxes that yield the lowest longitudinal distance.

  • If the desired distance is lateral, then the points of interest are the the two points on the entities' bounding boxes that yield the lowest lateral distance.

image
Figure 14. Distances between an entity E and an entity F, with freespace = true.
If freeSpace = true, the distance between two entities whose bounding boxes intersect is zero.

3.5. Controllers

Controller are elements of the simulation core that control the motion of ScenarioObject. OpenSCENARIO does not specify how controllers work and how they are implemented. OpenSCENARIO considers a controller as a runtime element that is used to enforce the control strategies (see Section 4.3.2.1.1) assigned to instances of ScenarioObject.

A Controller can be assigned to objects of type Vehicle or Pedestrian.

A Controller may be internal, as a part of the simulator, or external, defined in a file. The intended use cases for controllers are:

  • Specifying that a vehicle is controlled by the system under test.

  • Defining smart actor behavior, where a controller takes intelligent decisions in response to the road network or other actors. Hence, controllers can be used, for example, to make agents in a scenario behave in a human-like way.

  • Assigning a vehicle to direct human control.

By default, controllers are assigned in a deactivated state.

3.5.1. Controller types

OpenSCENARIO defines two types of controllers:

  • The default controller that enforces control strategies exactly as they are described by the actions.

  • An user-defined controller that may have custom interpretations of control strategies.

The default controller is expected to enforce control strategies along the entity dimensions that do not have a user defined controller.

OpenSCENARIO cannot prescribe the behavior of an user-defined controller. This means that simulations with user-defined controllers can differ from simulations generated using only default controllers, even though they use the same OSC Model Instance. This allows the scenario designer to use OpenSCENARIO in a broader scope, interpreting Action as suggestions rather than commands. Repeatable simulation results are only expected when using default controllers.

3.5.2. Controlling a scenario object

A maximum of two controllers shall be defined for the same ScenarioObject dimension. If a second controller is activated for a dimension, it deactivates the currently active controller on that dimension.

Activating a new controller does not interfere with the existing control strategy and the Action associated with that control strategy. Control strategies belong to the entity they are assigned to. Having a new controller does not change this. The new controller continues to enforce the existing control strategy just like the previous controller did. Figure 23 illustrates the coupling between controllers, entities, and control strategies.

3.5.3. Assigning a user-defined controller

A user-defined controller is assigned with the AssignControllerAction:

<AssignControllerAction>
    <Controller name="HAF_Driver"/>
</AssignControllerAction>

A user-defined controller may also be implicitly assigned by including it in the definition of a ScenarioObject, for example:

<ScenarioObject name="Ego">
    <CatalogReference catalogName="VehicleCatalog" entryName="car_white"/>
    <ObjectController>
        <Controller name="HAF_Driver"/>
    </ObjectController>
</ScenarioObject>

By default, controllers are assigned to entities in deactivated state.

3.5.4. Activating a user-defined controller

User-defined controllers are activated for a given motion domain, for example longitudinal or lateral. The following actions are used to activate controllers:

3.5.5. Assigning the default controller

At runtime, all ScenarioObjects of type Pedestrian or Vehicle are assigned a default controller capable of enforcing control strategies. This controller shall not be assigned or unassigned by the OpenSCENARIO Model Instance.

3.5.6. Activating the default controller

The default controller cannot be activated or deactivated explicitly in the OpenSCENARIO Model Instance.

At runtime, the default controller is activated for a given motion domain if no user- defined controller is active for that domain. If a user- defined controller is activated for a domain, it automatically deactivates the default controller for that domain.

3.6. Routes

A Route is used to navigate instances of Entity through the road network based on a list of waypoints on the road that are linked in a specific order, resulting in directional route. A Waypoint consists of a position and a RouteStrategy. The RouteStrategy indicates how to reach the position. An Entity’s movement between the waypoints is created by the simulator which uses the RouteStrategy as constraint. There may be more than one way to travel between a pair of waypoints. If this is the case, the RouteStrategy specified in the last Waypoint shall be used.

The implementation of this strategy may vary between simulators. In order to create unambiguous routes, the user must specify a sufficient number of waypoints. As long as the waypoints describe an unambiguous path, the corresponding route specifies a one-dimensional s-coordinate system that enables unambiguous localization and positioning.

Instances of Route may be assigned to an Actor using AcquirePositionAction or AssignRouteAction. Once assigned, they remain in place until another action overwrites them.

If an Entity is on a route, it normally continues along the same route when it reaches a junction. However, actions involving routes are not lateral actions and do not override or create lateral actions. This means that a route is not followed along if the corresponding entity is in the wrong lane or conflicting lateral behavior is defined, for example, an Action involving a Trajectory. In these cases, the route is ignored.

An Actor is still considered "on the route" if it is on a road section that does not have a waypoint on it but is part of the route between waypoints as calculated at execution time.

If an entity approaches a junction and is not on a route, or is on a route that cannot be followed, the road to follow is selected randomly from the available options.

It is possible that an actor starts somewhere along a route and not at its first waypoint. There are two ways to proceed for the actor, depending on whether the route contains loops:

  • If the route contains loops it passes the same road section several times, as shown in Figure 15.

  • If the route does not contains loops, the actor ignores the part of the route ranging from the first waypoint of the route to the position where the actor enters the route. The actor follows the remaining part of the route starting at the actors current position.

If the route does contain loops, see Figure 15 for an example, some additional rules apply. The route in the example consists of four waypoints (shown in boxes) that are linked in a specific order. The part of the route highlighted in red is driven twice: once on the links between waypoints 1 and 3, and once on the links between Waypoints 3 and 5. To avoid the entity becoming stuck in a loop, the following rules apply:

  • Where an entity is on a road that belongs to more than one link between waypoints, the entity shall be treated as being on the earliest link which has not been followed yet.

    • If an entity joins the route just before Waypoint 2, it is treated as being on the link between Waypoint 1 and Waypoint 2 (and not between 3 and 4).

  • Instances of Entity only follows later links than the one they are currently on.

    • If an entity joins the route just after Waypoint 3, it goes towards Waypoint 4, then 5.

  • When an entity leaves then rejoins a route or reaches the final waypoint, any previously visited waypoints shall be ignored.

    • If an entity is teleported to waypoint 1 after reaching waypoint 4, it follows the route as if for the first time.

    image
    Figure 15. Route passing the same road section twice

When a route consists of a consecutive, unambiguous series of roads from its start to finish, InRoutePosition. PositionInRoadCoordinates and InRoutePosition.PositionInLaneCoordinates may be used to define points relative to the continuous reference line of the road or lanes. An example of this is shown in Figure 16.

image
Figure 16. A route consisting of roads with a continuous reference line and PositionInRoardCoordinates

3.7. Trajectories

Instances of Trajectory are used to define an intended path for Entity motion in precise mathematical terms. The motion path may be specified using different mathematical shapes:

  • Polyline: A concatenation of simple line segments across a set of vertices.

  • Clothoid: Euler spiral, meaning a curve with linearly increasing curvature.

  • Non-Uniform Rational B-Splines (Nurbs) of arbitrary order.

By using nurbs, most relevant paths may be expressed either directly or with arbitrary approximation: Nurbs curves form a strict superset of the curves expressible as Bézier curves, piecewise Bézier curves, or non-rational B-Splines, which can be mapped to corresponding nurbs curves. Because nurbs curves directly support the expression of conic sections, such as circles and ellipses) approximation of, for example clothoids using arc spline approaches, is feasible.

Also, nurbs make it relatively easy to ensure continuity up to a given derivative: A nurbs curve of degree k, meaning order k+1, is infinitely continuously differentiable in the interior of each knot span and k-M-1 times continuously differentiable at a knot. M is the multiplicity of the knot, meaning the number of consecutive knot vector elements with the same value.

Commonly used nurbs curves are curves of quadratic (order = 3) and cubic (order = 4) degree. Higher-order curves are usually only required if continuity in higher derivatives needs to be ensured. Because the effort for evaluating curves increases with rising orders, it is recommended to restrict instances of Trajectory to lower orders.

Instances of Trajectory may be specified using just the three-positional dimensions along the X, Y, and Z axes (see Section 3.3 for coordinate system definitions). Alternatively, instances of Trajectory may also be specified using the three-positional dimensions and the three-rotational dimensions (heading, pitch and roll) for six total dimensions. In the second case, the path not only specifies the movement of the entity along the path, but also the orientation of the corresponding entity during that movement.

When a Trajectory is specified relative to the position of a moving entity, its absolute position cannot be calculated before the scenario starts. In this case, the trajectory must be calculated at runtime when the corresponding FollowTrajectoryAction is triggered.

Additionally, an instance of Trajectory may be specified with or without a time dimension, allowing for the combined or separate specification of the entities longitudinal domain: A trajectory incorporating the time dimension completely specifies the motion of the entity, including its speed. A trajectory without the time dimension does not specify the speed along the path. This approach allows for the separate control of speed.

A Trajectory provides a mathematically precise definition of a motion path. The corresponding entities behavior, however, depends on the actions employing it: Either an Entity follows this path exactly or it uses the path as a guidance for the controller to follow as best as the entities rules of motion allow.

The following sections describe edge cases in the definition of trajectories.

3.7.1. Entity is not at the start of trajectory, timeReference is not set

Starting conditions:

  • When the FollowTrajectoryAction starts, the entity is not at the beginning of the trajectory.

  • Time references are not set.

Expected behavior:

  • If the followingMode is position, the entity teleports to the beginning of the trajectory.

  • If the followingMode is follow, the controller attempts to steer as close to the trajectory as possible. Because the timeReference is not defined, the controller steers towards the point that bring the entity in line with the trajectory as soon as feasible. Considering the current position, orientation, and performance limitations of the entity, this is possibly not the start point of the trajectory, and maybe not even the geometrically closest point, as shown in Figure 17.

image
Figure 17. Entity is not at the start of the trajectory

3.7.2. Entity is not at the start of trajectory, timeReference is set (in the future)

Starting conditions:

  • When the FollowTrajectoryAction starts, the entity is not at the beginning of the trajectory.

  • The time reference is set at beginning of the trajectory (t1), the time reference is later than the current time (t < t1).

Expected behavior:

  • If the followingMode is position, the action starts, but the entity keeps moving as before until t1 is reached. At t = t1, the entity teleports to the start of the trajectory, and continues along the trajectory.

  • If the followingMode is follow, the entity immediately starts steering towards the trajectory, with the aim to be at the trajectory start at t = t1.

3.7.3. Entity is not at the start of trajectory, timeReference is set (in the past)

Starting conditions:

  • When the FollowTrajectoryAction starts, the entity is not at the beginning of the trajectory.

  • The time reference is set at beginning of the trajectory (t1), the time reference is earlier than the current time (t > t1).

Expected behaviour:

  • If the followingMode is position, the entity behaves as if the trajectory starts at the position interpolated between the most recent time reference and the earliest future time reference. The entity teleports to that position and continues along the trajectory.

  • If the followingMode is follow, the entity starts steering towards the trajectory, aiming to hit the first referenced point in the future and taking into consideration the performance limitations.

3.7.4. Entity is at an ambiguous point near the trajectory

Starting conditions:

  • The entity is located in vicinity to more than one waypoint or segment connecting the waypoints.

Expected behavoiur:

  • The entity joins at the first possible segment, according to the user-defined orientation of the trajectory and respecting time references, if given. See section on Section 3.6 and previous points in this section.

image
Figure 18. Entity is at an ambiguous point near the trajectory

3.7.5. Trajectory-relative positions

Trajectory-relative positions may be defined using TrajectoryPosition, which define a position relative (and potentially offset) to the path of the trajectory. See Figure 19 for an example position along a linestring-defined trajectory.

image
Figure 19. Trajectory position example

3.8. Traffic simulation

In addition to deterministic behavior of instances of Entity, OpenSCENARIO also provides ways to define stochastic or not precisely defined behavior. This can be useful for the following purposes:

  • Make the scenario more realistic.

  • Induce variances into the scenario sequence.

  • Define traffic parameters, such as traffic density.

To define stochastic behavior, surrounding intelligent traffic agents may be defined using instances of TrafficAction. With the help of this action, the parameterization of traffic sources, traffic sinks, and traffic swarms may be specified.

The definition of a TrafficAction in OpenSCENARIO does not specify which maneuvers the intelligent traffic agents execute. Instead, those actions specify the initialization or termination of vehicles whose behavior is controlled by external traffic simulation models. Spawned traffic participants makes routing decisions based on their corresponding driver model, just as with the ActivateControllerAction.

3.9. Properties

Instances of Property may be used to define test-instance specific or use-case specific properties of OpenSCENARIO sub-elements. Properties are available for the following types:

  • Vehicle

  • Pedestrian

  • MiscObject

  • Controller

  • RoadCondition

Instances of Property are collected in the Properties container. Every Properties definition may contain one or more name-value pairs (meaning instances of Property) and/or references to external files using the File mechanism. Thus, properties are a powerful instrument for customizing scenarios, without the need of standardizing purpose-built features related to specific simulator, hardware, and software setups.

Typical applications of properties are extensions of vehicle dynamics specifications, additional driver behavior settings, color information of objects, etc.

Properties can influence scenario execution, for example the driver behavior, but scenarios shall be executable without knowledge of the properties meaning.

3.10. Traffic signals

Traffic signals introduce two main aspects into simulation:

  1. Position and rendering of traffic signals and their possible state in a simulation. Locations are defined in the road network. Rendering is specific to the simulator.

  2. The dynamic behavior that describes how and when the traffic signals change during a simulation. This is defined in OpenSCENARIO with referencing the objects in the road network.

3.10.1. Traffic signal controllers

Traffic signals controllers provide identical states for one or more dynamic traffic signals. Controllers serve as wrappers for the behavior of a group of signals. Traffic signal controllers are used for dynamic speed control on motorways and to control traffic light switching phases. OpenSCENARIO adds dynamic aspects, such as phases and durations, to the traffic controllers that are defined in the road network.

3.10.2. Traffic signal definition

Traffic signals are declared in the RoadNetwork section of a scenario file. TrafficSignalController instances are wrapped around their phases and their traffic signal states. A TrafficSignalController references a traffic controller instance in the road network with the name attribute.

<RoadNetwork>
  <LogicFile/>
  <SceneGraphFile/>
  <TrafficSignalController name="RoadNetwork_ID1">
    ...
  </TrafficSignalController>
  <TrafficSignalController name="RoadNetwork_ID2">
    ...
  </TrafficSignalController>
  ...
</RoadNetwork>

3.10.3. Connecting traffic signal controllers

OpenSCENARIO provides an optional mechanism to connect the dynamic behavior of multiple traffic signal controllers. The TrafficSignalController defines a delay to a referenced signal controller. The referenced signal controller shall be defined in OpenSCENARIO with its dynamic behavior.

<RoadNetwork>
  <LogicFile/>
  <SceneGraphFile/>
  <TrafficSignalController name="RoadNetwork_ID1">
    ...
  </TrafficSignalController>
  <TrafficSignalController name="RoadNetwork_ID2"
                           delay="10"
                           reference="RoadNetwork_ID1">
    ...
  </TrafficSignalController>
  ...
</RoadNetwork>

3.10.4. Phases

TrafficSignalController provides an ordered list of phases. A phase represents a dynamic element of a traffic signal controller and defines a duration and a name. The simulation sequentially runs through the phases of the declared traffic signal controller while executing the scenario with respect to each duration. The list of phases represents a cycle. That means the first phase repeats after the last phase has ended. The duration of a cycle is the sum of the phases' durations. The first phase starts with the execution of the storyboard.

Phases are connected to TrafficSignalStates. Because a traffic signal controller controls multiple traffic signals, each traffic signal is represented by a state during a specific phase.

In the current version, interpretation and notation of state are specific to the simulation engine used.

In the following example, traffic signals are encoded with boolean values:

<TrafficSignalController name="6">
  <Phase name="stop" duration="25">
    <TrafficSignalState trafficSignalId="8594" state="true;false;false"/>
    <TrafficSignalState trafficSignalId="8595" state="true;false;false"/>
  </Phase>
  ...
</TrafficSignalController>

4. Components of a scenario

4.1. Overview of a scenario

To represent a traffic situation, an OpenSCENARIO model instance is built up of four main components:

  • Road network: mapping of the different driving surfaces and all relevant elements of the road infrastructure, like traffic signals.

  • Entities: road users, including vehicles, pedestrians, and other miscellaneous objects that interact during a scenario.

  • Actions: basic building blocks to define dynamic behavior of the entities. It may also be used to modify simulation states or components of the simulated world.

  • Triggers: mechanism that determines when an action starts or stops. It is built on logical expressions revolving around the states of entities or the simulation.

It is possible to design a scenario without a road network but it restricts the application of certain OpenSCENARIO actions.

The structure of the OpenSCENARIO model instance was created with the purpose to host and combine the main components listed above in such a way that rich driving scenarios can be defined. This chapter introduces the OpenSCENARIO structure, how the different components fit in the structure, and how these components relate to one another.

4.2. Storyboard and entities

4.2.1. Storyboard

In OpenSCENARIO, the storyboard covers the complete scenario description. The storyboard provides the answers to the questions "who" is doing "what" and "when" in a scenario. An OpenSCENARIO Storyboard element consists of the following elements:

  • Init: Initialization element that sets the intial states of the scenario elements, such as the position and speed of instances of Entity. It is not possible to specify conditional behavior in this section.

  • One or more Story elements (optional): Story elements enable scenario authors to group different scenario aspects into a higher-level hierarchy and thus create a structure for large scenarios.

  • stopTrigger: determines the end of the scenario.

Instances of Story in OpenSCENARIO contain Act instances, which in turn define conditional groups of Action instances. Each act focuses on answering the question "when" something happens in the timeline of its corresponding story. The act regulates the story via its startTrigger instance and its stopTrigger instance. If a startTrigger evaluates to true, the act’s ManeuverGroup instances are executed.

A ManeuverGroup element is part of the Act element and addresses the question of "who" is doing something, by assigning entities as Actors (see Section 4.3.1) in the included Maneuver instances. Maneuver groups may also include catalog references with predefined maneuvers. This concept is described in Section 6.4.

The Maneuver element defines "what" is happening in a scenario. A Maneuver is a container for Event instances that need to share a common scope. Events control the simulated world or the actors defined in their parent maneuver group. This is achieved through triggering Action instances, via user-defined Condition instances.

Figure 20 illustrates the components of a storyboard.

image
Figure 20. Diagram showing the structure of a storyboard

4.2.2. Entities

In a scenario, instances of Entity are the participants that make up the developing traffic situation. Vehicle, Pedestrian and MiscObjects instances may change their location dynamically. A MiscObject instance represents an object type, such as tree or pole. The possible types are identical to the types that are defined in OpenDRIVE. If an object is already defined in the road network file, it can be instantiated in the scenario as Entity with ExternalObjectReference.

Instances of Entity may be specified in the scenario format but the properties are specific to their type. For example, a Vehicle is an instance of Entity that has properties like vehicleCategory and performance. In contrast, a Pedestrian is specified by a property pedestrianCategory.

Where applicable, actions may change the state of an entity, for example, its positon, speed or its associated Controller instances. The state of an entity may be queried to trigger an action, via a condition.

OpenSCENARIO and entity can be represented by any of these two model elements:

  • Entity describes one specific object

  • EntitySelection describes a list of instances of Entity

Motion control for entities

The motion of the entity types Vehicle and Pedestrian may be controlled with user-assigned controllers or a default controller.

The default controller is expected to execute the control strategies (Section 4.3.2.1.1) defined by the OpenSCENARIO MotionControlAction elements. The control strategies of the default controller are to maintain speed and lane offset of the entity. The control strategies of the default controller are called default control strategies.

The default controller is assigned to an entity’s motion domain (lateral and/or longitudinal) if:

  • No user assigned controller are running.

  • A user assigned controller is running but only controls one motion domain. In this case, the default controller is assigned to the remaining motion domain.

Entity selections

The EntitySelection element may be used to conveniently define groups of Entity instances in the scenario. In most cases, the entities may be used where single instances of Entity may be used as well, allowing actions to be applied to many ScenarioObject instances at once or to use their aggregated information ("any", "all") in a condition.

Entity selections may also be purposefully formed from any combination of objects within the scenario. Example: A named EntitySelection instance is chosen as an actor in a maneuver group. In this way, all private actions within the maneuver group are applied individually, to each ScenarioObject instance in the entity selection.

EntitiySelection instances may be defined in such a way that they include other EntitySelection instances. Circular dependencies can be formed as a result. For example, EntitySelection A includes EntitySelection B which includes EntitySelection A.

Declaring EntitySelections with circular dependencies is highly discouraged and may lead to unexpected behavior.

Spawned objects

An entity may be represented by a single ScenarioObject instance or by an EntitySelection instance. Both, ScenarioObject and EntitySelection instances, are declared in the scenario file and are globally identified by their name attribute when they are used in actions and conditions. An entity may also be represented by a SpawnedObject instance which is created by a traffic source. These objects are created dynamically and have no static name that would enable a scenario author to reference them explicitly in a defined entity condition or in a private action.

Because spawned objects are considered to be of type vehicle, they may nevertheless be used as actors in an entity selection. To do so, the ByType option is used:

<EntitySelection name="allVehicle">
  <SelectedEntities>
    <ByType objectType="vehicle"/>
  </SelectedEntities>
</EntitySelection>

Spawned objects are created dynamically and do not appear in the OpenSCENARIO Model Instance. Therefore, SpawnedObject is stereotyped with <<transient>> in the UML model. The existence of SpawnedObject in the model is therefore a reminder that an Entity instance is not limited to be represented by a declared Entity or by an declared EntitySelection.

In future versions, SpawnedObject instances may be dynamically identifiable by following a standardized naming schema that takes in consideration the ID of the traffic source, for example NamedTrafficSource.entity_1.

Entity class hierarchy

The Entity class hierarchy provides an overview of the relations between Entity, EntitySelection, EntityRef and SpawnedObject.

image
Figure 21. The entity class hierarchy

The following relations can be inferred from Figure 21:

  • An Entity may be represented by either a single ScenarioObject, a EntitySelection, or SpawnedObject.

  • An EntitySelection may include members. members may be represented by a static list of named Entity instances (via EntityRef) or by a dynamic list of Entity instances that are defined by the type of the Entity (via ByType).

  • An EntitySelection may recursively include other Entity instances (via EntitySelection).

Generalization of entities

OpenSCENARIO relates the MiscObject, Vehicle, Pedestrian, EntitySeletion classes, in the generalized concept Entity. This is useful because the concept of entity provides the building blocks for many actions and conditions - for example: A CollisionCondition instance can model the collision between a Vehicle instance and a MiscObject instance, such as a tree. With the use of other actions and Conditions, this leads to some overgeneralization. Speeding up a MiscObject of type tree with a SpeedAction instance, for example, would contradict the common understanding of the reality that should be respected when creating a scenario.

This overgeneralization requires contraints that explicitly regulate what makes sense and what does not.

This includes:

  • Restrictions on actions and conditions that are not applicable to MiscObject, ExternalObjectReference or Pedestrian instances or to entity selections containing these instances.

  • Restrictions concerning the multiplicity of a referenced Entity:

    • For a RelativeTargetLane, it is not clear in which exact lane multiple ScenarioObject instances that are grouped by an EntitySelection are located.

    • The interpretation of the distance to an EntitySelection is ambiguous. This is related to the question what the center or the bounding box of an EntitySelection is.

      In these cases, aggregation functions (average, max, min) might not be useful or even confusing. A reference to an Entity should be restricted to an instance of a ScenarioObject for such cases.

3D models for entities

The property model3d can be defined for the following entity types:

  • Vehicle

  • Pedestrian

  • MiscObject

The model3d property refers to either a model name or a path to a 3D model. 3D-model types are, for example, .GLTF, .FBX, .3DS. model3d is an optional property and therefore, even if it is specified in a OpenSCENARIO model instance, it maybe ignored, depending on the simulator’s support for this feature.

Figure 22 showcases the expected behavior depending on the simulator support for the model3d feature:

image
Figure 22. model3d behavior depending on simulator support

4.3. ManeuverGroups, Maneuvers, Events, and Actions

4.3.1. ManeuverGroups and Actors

A maneuver group singles out the instances of Entity that may be actuated, or referenced to, by the maneuvers in that group. These instances of Entity are grouped and referred to as the Actors, because they play a role in the maneuvers to come. The Actors group may be left empty. This is allowed for situations where the maneuvers in a maneuver group lead to actions that are not related to instances of Entity, but instead world or simulation states.

An actor is defined using the EntityRef element. This element is then combined in an unbounded list in order to specify actors for a given maneuver group. A list of Actor instances may contain several instantiations of the type EntityRef. Additionally, extra instances of Entity may be added to the actors’s list, at trigger time, if the selectTriggeringEntities option is active.

The EntityRef element explicitly couples an existing entity to an actor in the maneuver group. This is achieved by specifying the name of the desired entity in the element. EntityRef is used when the entity of interest is known when the scenario is defined.

The selectTriggeringEntities property may be used when the choice of actors depends on runtime information and cannot be made at scenario definition time. When the selectTriggeringEntities property is true, entities become actors if they fulfill the following criteria:

  • The states of the instances of Entity are used by the logical expressions in Conditions.

  • The Conditions using the states evaluate to true.

  • The Conditions using the states are contained in ConditionGroups that evaluate to true.

Condition groups relevant for determining which instances of Entity are added to the actors, are located in the maneuver groups parent Act. The m maneuver group inherits its parent act’s start trigger.

EntityRef may be combined with selectTriggeringEntities set to true. In this case, the resulting actors are the union of the two.

Finally, a ManeuverGroup instance is defined with a maximumExecutionCount. This setting specifies how many times the maneuver group runs, and is explained in Section 5.4.4.

4.3.2. Actions

Actions enable OpenSCENARIO to prescribe element behavior in traffic simulations or to directly affect element states, which in turn determine how a simulation evolves. An Action instance is defined in a OSC Model Instance.

There are three categories of Action:

  • Private actions are applied to entities, such as traffic participants. Either in the init section, before to the start of the simulation, or during the simulation when entities are represented by actors in a maneuver group.

  • Global actions are intended to modify non-entity related traffic simulation elements like time of day, weather conditions, or traffic signal states.

  • User-defined actions represent a customized contract between a scenario designer and a simulation provider. They realize specific behavior in the simulation that is otherwise not supported in OpenSCENARIO, by the existing actions.

In the initialization phase of a scenario, actions are responsible for setting up initial states of dynamic objects, environment, or infrastructure. In any later phase of the scenario, actions are executed when events are triggered.

Private action

Private actions shall be assigned to instances of Entity. These actions may affect motion control for their designated entity:

  • Prescribing intended dynamic behavior, for example, a LaneChangeAction instance specifies transition dynamics to describe how the lane change should be performed in respect to time or distance.

  • Directly setting entity states, for example, position.

Dynamic behavior implied by a private action is called a control strategy and is assigned to the entity when the private action is instantiated.

Control strategy

A control strategy is how an OSC Diretor assigns behavior to a simulated entity. A control strategy is not a component of the OSC Model Instance, existing only at runtime as a manifestation of a private action, in the Simulator Core. In simpler terms, a control strategy is the runtime mapping of a OSC Director PrivateAction instance to the Simulator Core.

The following guiding principles apply for private actions and control strategies:

  • Control strategies exist only in the simulator core and are not a part of the OpenSCENARIO model.

  • Only private action shall be mapped to control strategies.

    • Only those private actions that prescribe behavior, rather than setting states, shall be mapped to control strategies.

  • The control strategy is assigned to the entity when the private action is instantiated.

  • A private action does not control an entity - controllers control entities.

    • A controller controls an entity by enforcing the behavior prescribed by the control strategies assigned to that entity.

  • A private action reaches the complete state when its associated control strategy is finished, regardless of how it is finished - successfully, due to an override, or because of missing prerequisites. For information on runtime states, see Section 5.1.

    • A private action may also reach the complete state if it is terminated by its parent event, or the stop triggers of the enclosing act or storyboard. If this occurs, the associated control strategy is unassigned from the concerned entity.

All entities shall have a control strategy for the longitudinal and lateral domains assigned at all times. If no control strategies are explicitly assigned to the entity, then the entities are expected to activate default control strategies that define default behavior. The default controller enacts the default control strategies. Each entity control dimension shall have a default control strategy:

  • Lateral dimension: The default control strategy is to keep the lane and the entity’s offset on the lane. If the entity has an assigned route, the active controller uses that information to resolve ambiguity (intersection, merging roads, exits). If the ambiguity cannot be resolved, the control strategy changes to keep the direction defined by the entity’s current orientation.

  • Longitudinal dimension: The default control strategy is to keep the entity’s current speed.

image
Figure 23. Relations between Entity, Controller, privateAction, and control strategy
Private actions and motion control

Some configurations of private actions affect the motion control of an entity and therefore need to assign a control strategy . These actions are called MotionControl actions. Actions of type MotionControl are modeled with the MotionControl stereotype.

  • Motion control actions that assign a control strategy: SynchronizeAction, LaneChangeAction, LaneOffsetAction, LateralDistanceAction, SpeedAction, LongitudinalDistanceAction.

  • Non-motion control actions that do not assign a control strategy: VisibilityAction, ActivateControllerAction, AssignControllerAction,OverrideControllerValueAction, TeleportAction, RoutingAction, GlobalAction.

LaneChangeActions, SpeedAction, LaneOffsetAction may be used to set a state, if used with the step dynamic option. In this particular use case, these actions do not assign a control stragegy as the changes are enacted instantaneously.

Types of private action

The following types of private action exist:

LongitudinalAction

Controlling speed or relative distance to a target. Instances of SpeedAction are defined, for example, by an acceleration profile (DynamicsShape) whereas instances of longitudinalDistanceAction are set up by means of actual distance or a headway time, for example, using timeGap.

For the element SpeedAction, when the DynamicsShape attribute is set to step, the speed is set instantaneously - not over time.

LateralAction

When using instances of LaneChangeAction or LaneOffsetAction, a lateral position within a lane can be targeted. Both actions support relative and absolute referencing of the action target. For the LaneChangeAction type, relative target referencing works differently than absolute referencing. The reference entities' x-axis serves as reference direction. The speed direction (forward / backward) of the reference entity is not relevant for the reference direction. Lane changes are evaluated positive if they are aligned with the reference entities' positive y-axis. A positive lane change moves the corresponding actor to the next lane in the reference entities' positive y-axis direction. For OpenDRIVE maps, the road center lane is not counted as a lane and thus not considered in this counting. The approach is similar for the LaneOffsetAction type: Positive offset values are aligned with the reference entities' positive y-axis. Finally, with the LateralDistanceAction type, a lateral distance to an object can be targeted. For each of the LateralAction types, the lateral dynamics may be restricted.

For the LaneChangeAction type, when the DynamicsShape attribute is set to step, the lane change is performed instantaneously - not over time. In the LaneOffsetAction case, when the DynamicsShape attribute is set to step, the displacement required to achieve the desired lane offset is performed instantaneously - not over time.

VisibilityAction

Enabling/disabling detectability of an entity by sensors or other traffic participants and visibility in the image generator.

SynchronizeAction

Takes over longitudinal control of an entity in order to reach a desired position at the same time a reference entity reaches a given reference position. The controlled entity is expected to regulate its speed, in relation to the reference entity, in order to meet the explicit position constraint and implicit time constraint. Optionally, in addition to the desired position, the controlled entity may also be given a FinalSpeed setting. This is the speed that the controlled entity shall have when reaching the destination. This final speed may be specified either as an absolute value or relative to the reference entity.

The synchronize action shall terminate when any one of the following occurs:

  • When the controlled entity reaches the reference position, regardless of the states and position of the reference entity.

  • When it is concluded that the controlled entity cannot reach its destination for whatever reason.

The synchronize action does not influence routing or the lateral behavior of the controlled entity. In other words, the destination should lie along the planned route of the entity as defined by the default behavior or additional actions.

The purpose of the synchronize action is to achieve specific repeatable traffic situations, which are tolerant to flexible initial conditions and unpredicted vehicle behavior, for example, in case of a human driver in the loop.

The example in Figure 24 shows how a sychronize action may be used to provoke an interception situation in an intersection. The dots indicate the respective destinations, which is also the point at which the synchronize action ends.

The controlled entity (c1, yellow) arrives at its destination, indicated by a yellow dot, whenever the reference entity (ego, blue) arrives at its destination, indicated by a blue dot. The synchronize action terminates at this point and synchronization stops. The controlled entity then moves into the intersection according to default behavior or any other active action, causing a dangerous situation for the reference entity, which still has a chance to avoid collision.

image
Figure 24. SynchronizeAction example inducing an interceptor situation

Figure 25 shows a scenario very similar to the previous example, but illustrates that the synchronize action also works when the controlled entity performs lateral operations in parallel, for example, following an assigned route or performing lane changes.

image
Figure 25. Example of SynchronizeAction combined with routing

Figure 26 shows a vehicle surrounded by other vehicles. The synchronize action is useful to form constellations at specific locations on the road network, typically before a critical event - for example lead vehicle brakes.

image
Figure 26. SynchronizeAction constellation example

In this case, there are four controlled instances of entity (c[1-4]), each one having an individual synchronizeAction referring to the blue ego car.

ActivateControllerAction (deprecated)

Explicitly (de-)activating a Controller model. This may be done for longitudinal, lateral, or both domains. This Action is deprecated and its functionality has been moved to the ControllerAction class.

ControllerAction

Assigning a driver model to instances of entity of type Vehicle or a model controlling motion behavior for other moving instances of entity. The controller action may also be used to override control signals, for example, apply the brakes. Additionally, a controller action may be used to activate or deactivate controllers assigned to entities on the lateral domain, longitudinal domain, or both domains simultaneously.

TeleportAction

Defining a location or destination of an entity in the scenario. The target position may be described as absolute coordinates or relative to other instances of entity.

RoutingAction

Specifies the route that an entity should follow. There are three ways of specifying a routing:

  • AssignRouteAction: Using waypoints on the road network and a RouteStrategy.

  • FollowTrajectoryAction: Using vertices, timings (optionally), and a corresponding interpolation strategy.

  • AcquirePositionAction: Specifying a target position for the corresponding entity to reach. The entity aims to take the shortest distance from the current position to the target position along the road network.

Global action

The GlobalAction type is used to set or modify non-entity-related quantities.

EnvironmentAction

Setting weather state, road condition, and time.

EntityAction

Removing or adding instances of Entity.

ParameterAction

Setting or modifying values of parameters.

InfrastructureAction

Setting or modifying the state of a traffic signal or a traffic signal controller phase.

TrafficAction

Managing ambient traffic of the following kinds:

  • Creation of sources and sinks

    • A source creates vehicles, whereas a sink deletes vehicles. A source spawns new vehicles with the rate defined in the element. If no rate is given, a sink deletes all vehicles reaching its area of influence, but a rate may be defined to specify a maximum amount of vehicles to be removed per second. Removal of vehicles follows the "first in, first out" principle.

    • An optional TrafficDefinition of a sink is the equivalent of a forbidden list, meaning that only vehicles matching this list are removed while all other vehicles may pass unhindered. However, if no definition is given, all vehicles reaching the sink are removed.

  • Creation of swarm traffic following/surrounding a central object (see Figure 27)

    • Swarm traffic is set up in the area between inner radius and outline of the ellipsis defined by the two semi-axis attributes (blue area in the picture). The blue area shall never contain more swarm vehicles than defined in the numberOfVehicles. If a vehicle is leaving the blue area it is deleted and a new vehicle is spawned instead.

      image
      Figure 27. Swarm definition
    • Vehicles spawned by a TrafficSwarmAction instance may trigger conditions just as other instances of entities do. They may also perform actions by being referred to through an entity trigger, when identifying the actors in a maneuver group. Because the names of the spawned vehicles are determined in runtime, no actions can be modeled by referring to these entities.

    • Spawned vehicles make routing decisions based on their driver model, just as with the ActivateControllerAction. Optionally, a starting velocity for the spawned vehicles may be specified. If no velocity is given, the speed limit of the underlying road is used. This can lead to undefined behavior because there may be no speed limit defined for the road in the underlying road network file. To prevent errors, either a velocity of the created vehicle should be defined or use road network files should be used that have a speed limit defined. All elements make use of a TrafficDefinition, where the distribution of the spawned or removed vehicles may be defined using VehicleCategoryDistribution. Which vehicles of that category are actually spawned is up to the simulation engine.

  • Terminating any of the above traffic generation methods with an instance of the TrafficStopAction element.

User-defined action

The UserDefinedActions type enables user customized actions. When user-defined actions are used, the executability of the scenario dependents on the ability of the specific simulation environment recognizing these actions.

CustomCommandAction

Users may create their own actions which may incorporate a command or a script file.

Conflicting actions

At runtime, it may occur that coexisting actions end up competing for the same resource thus creating a conflict. A typical example: An action that controls an entity’s speed clashes with a newly triggered action that tries to control the speed of the same entity.

When an action acts on an entity selection and there is a conflict for one entity, all other instances of Entity within the selection are also treated as being in conflict. Actions are treated as conflicting if they are competing for control of the same domain in the same resource. For example, a SpeedAction always conflicts with any other SpeedAction if both target the same entity. Conflicts of actions of different types depend on how the actions relate to each other and need to be identified in a case-by-case basis. Table 7 and Table 8 depict the possible runtime conflicts between actions of different types.

If it is determined that a newly triggered action conflicts with a currently ongoing action, the latter is overridden. Overriding a running action is equivalent to issuing a stop trigger to that action, see Section 4.4.

Completing an action

For synchronizing the forked and nested execution paths of instances of storyboard elements, such as Story, Act, ManeuverGroup, Maneuver, Event, it is necessary to determine how an action is completed.

Private actions that assign control strategies are complete when the goal prescribed by the control strategy is reached. Enforcing a control strategy is done over time and, actions that assign control strategies take simulation time to complete.

All actions that do not assign control strategies are completed immediately. These actions transition from runningState to completeState, when instantiated, because the tasks associated to such actions are performed instantaneously.

The end criteria for actions are depicted in Table 7 and Table 8.

Completing a private action

A private actions may be completed as follows:

  • Regular ending: A regular ending implies endTransition from the runningState to the completeState. An action ends regularly when its goal is accomplished, for example, an instance of a SpeedAction ends when the speed is reached. An action ends regularly if its goal is accomplished upon the start of the action, for example, the entity is traveling at the desired speed when an instance of a SpeedAction starts. The end criteria are depicted in Table 7.

  • Override by another Action: A private action that defines a control strategy on a specific dimension of an entity is overridden by another action that defines a control strategy on the same dimension of the same entity. The overriden action moves to the completeState with a stopTransition. For example, an instance of FollowTrajectoryAction overrides an instance of LaneChangeAction on an entity. The LaneChangeAction instance is stopped.

  • Override by Event: An event which is stopped is forced to stop all actions in its scope. The concerned actions move to the completeState with a stopTransition. To understand how an event can be stopped, see Section 4.3.3.

  • StopTrigger: A StopTrigger instance originating from the a storyboard or the action’s parent act. The action moves to the completeState with a stopTransition.

  • Missing prerequisites: The prerequisites for running an action are not fulfilled either during execution of the action or when the action starts. The action moves to the completeState with a stopTransition. For example, if the referenced entity of an instance of a LongitudinalDistanceAction disappears, or a private action is instantiated with no actors, the action is considered to be missing prerequisites.

Action prerequisites

Missing prerequisites are one reason why actions may be stopped. Prerequisites are specific to the action type and are the components or information required for the action to run. An action that is missing prerequisites, at start or during execution, is supposed to move to the compleState with a stopTransition. For example, an instance of a LaneChangeAction has these prerequisites: an existing lane and an entity to change lane with.

Executing actions depends on the robustness of the simulation engine and on the legitimacy of the OSC Model Instance. The OpenSCENARIO format specifies how actions work and how they interact with each other - it cannot and does not classify a OSC Model Instance as wrong or right, appropriate or not appropriate. In OpenSCENARIO 1.1, the only indicator that an action could not be completed regularly, is the 'stop' transition that is taken while entering the completeState. It is up to the implementation of the simulator to warn the users about potential unintended behavior, for example, teleporting a non-existing entity, assigning conflicting control strategies simultaneously, or referencing unintended entities.
Continuous actions

Some private actions lack a regular ending by design. Their underlying control strategy pursues a permanent goal that is supposed to be continuously tracked over time. These private actions are often referred to as never-ending actions or continuous actions.

Private actions types like LongitudinalDistanceAction, LateralDistanceAction, LaneOffsetAction, and SpeedAction forfeit a regular ending when a scenario designer sets the continuous flag to true. These are the only cases of never-ending actions.

All action ends described in Section 4.3.2.5.1 are applicable to never-ending actions, with the exception of the regular end.

Acting on multiple entities - bulk action

Private actions may have to control more than one entity at a time. This occurs when the actors resolve to multiple instances of an entity or an entity selection, in a maneuver group. In this case, all concerned instances of an Entity shall be actuated simultaneously when the action starts. An action that acts on multiple entities is called a Bulk Action. For more details on the behavior of Bulk Actions in runtime, see Section 5.3.3.3.

Actions acting on entity selections shall only be considered complete if all instances of entity in the selection have completed the tasks specified in the action. For example, an instance of a SpeedAction acting on five instances of Entity is only complete when all five instances of Entity have reached the desired speed, regardless of the fact that some of them may reach that speed earlier than others.

If any of the corresponding instances of Entity sparks a conflict with a newly started action, then the running action is overridden. All its instances of Entity are supposed to fall back to default behavior simultaneously. For example, and instance of a SpeedAction, A, controls five entities when an instance of a SpeedAction, B, starts, aiming to control one entity in action A. Because the actions are of the same nature, a conflict occurs and action A is overridden. Action B resumes control of the conflicting entity while the remaining entities from the late action A, engage in default behavior.

4.3.3. Events

Actions are singular elements that may need to be combined in order to create meaningful behavior in a scenario. This behavior is created by the type Event which serves as a container for actions. Events also incorporate start triggers. The event start trigger determines when the event starts and when the actions contained in the event, start.

Actions shall always be wrapped by events with only one exception: In the InitActions class, where actions are declared individually.

The maximumExecutionCount setting specifies how many times an event is supposed to run. Interpretation of this parameter in runtime is explained in Section 5.4.2 .

An event is also parameterized with a definition of priority relatively to events that coexist in the same scope, i.e. maneuver. Whenever an event is started, the Priority parameter is taken into consideration to determine what happens to already ongoing events in the same maneuver. The three choices of the Priority parameter are:

  • overwrite: All other events in the scope are stopped and the event starts.

  • skip: The event does not leave the standbyState.

  • parallel: The event starts regardless of any other running events.

Refer to Section 5.4.2.2 for the runtime interpretation of the Priority parameter.

Each event defined in a scenario corresponds to a single runtime instantiation which implies that there shall not be multiple instantiations of the same event running simultaneously. This also means that start triggers only make sense for events in standbyState, as opposed to each start trigger starting a new instantiation of the event.

4.3.4. Maneuver

A maneuver groups events creating a scope where the events can interact with each other using the event priority rules. The definition of a maneuver may be outsourced to a catalog and parameterized for easy reuse in a variety of scenarios.

4.4. Conditions and triggers

A scenario can be regarded as a collection of meaningful actions whose activation is regulated by triggers. These triggers play an important role on how a scenario evolves because the same set of actions may lead to a multitude of different outcomes. The outcome strongly depends on how actions are triggered in relation to one other. In OpenSCENARIO a trigger is the outcome arising from a combination of conditions and always evaluates to either true or false.

In OpenSCENARIO, a condition is a container for logical expressions and is assessed at runtime. The condition operates on the current and previous evaluations of its logical expressions to produce a Boolean output that is used by triggers.

4.4.1. Triggers and condition groups

The Trigger class is an association of ConditionGroup instances, which are an association of Condition instances. At runtime, a condition group evaluates to either true or false and its outcome is calculated as the AND operation between all its conditions:

A conditionGroup is evaluated to true when all its associated conditions are evaluated to true.

The outcome of a trigger is calculated as the OR operation between all its condition groups.

A trigger evaluates to true when at least one of its condition groups evaluates to true.

Formally, a trigger containing N instances of ConditionGroup at time td is defined as:

\[T(t_{d}) = \bigvee_{n=1}^{N} ConditionGroup_{n}(t_{d})\]

Let Mn be the number of conditions in a condition group m, and Conditionnm be condition n of condition group m. Replacing the condition group formulation in the expression above gives the trigger as:

\[T(t_{d}) = \bigvee_{n=1}^{N} \left ( \bigwedge_{m=1}^{M_{n}} Condition_{nm}(t_{d}) \right )\]
OpenSCENARIO 1.0 allows instances of the Trigger class to be empty, for example, no condition groups defined. Empty triggers are not meaningful and are kept for the sake of downward compatibility. This is expected to be addressed in the next major version where a trigger shall be defined with at least one condition group. An empty trigger is always evaluated to false.

Example

A trigger is formed by three condition groups. Let Mn be the number of conditions in condition Group n. The first condition group has two associated conditions (M1 = 2), the second condition group has three associated conditions (M2 = 3) and the third condition group has one associated condition (M3 = 1).

The trigger value is T(td) and is calculated as a function of its conditions' evaluations. Let CEmn be the evaluation of condition n of condition group m:

\[T(t_{d}) = ((C_{11}(t_{d}) \wedge C_{12}(t_{d})) \vee (C_{21}(t_{d}) \wedge C_{22}(t_{d}) \wedge C_{23}(t_{d})) \vee (C_{31}(t_{d})))\]
Start trigger

An instance of the Trigger class instanciated as a start trigger is used to move a runtime instantiation of a Storyboard element from the standbyState to the runningState. Only the Act class and Event class host start triggers and any element that does not contain a start trigger inherits the start trigger from its parent element. For example, starting an act also starts its maneuver groups and maneuvers, but does not start the events because the events have their own start triggers. Furthermore, no events may start if they do not belong to an act that is in the runningState.

The Story class is an exception to the rules above since it does not require a formal start trigger given that starting a simulation is equivalent to starting the Story.

Stop trigger

A stop triggers is used to force a runtime instantiation of a StoryboardElement to transition from its standbyState or runningState to the completeState. Only the story and the act host stop triggers. All storyboard elements inherit the sstop triggers from their parent. This is true even if the storyboard element under consideration has its own stop triggers. For example, if a story is affected by a stop trigger, so are all its acts, even though they have their own stop triggers.

When a stop trigger is received, the concerned atoryboard element is expected to transition to the completeState with a stopTransition, and clear all remaining number of executions, if applicable. If the trigger occurs when the element is in the runningState, it is expected that its execution is terminated immediately.

4.4.2. Condition edges

When edges are defined, with rising, falling, and risingOrFalling, the condition evaluation is also dependent on past values of its logical expression at the discrete time td-1. See Figure 28 for the possible evaluations of a condition, given the available edges.

image
Figure 28. Evaluation of a speed condition with a greaterThan rule, for all possible edge values
Rising edges

When conditions have rising edges defined (conditionEdge = rising), the condition evaluation at discrete time td is true when its logical expressions at td evaluates to true and the logical expression at td-1 was evaluated to false:

\[C_{R}(t_{d}) = LogicalExpression(t_{d}) \wedge \overline{LogicalExpression(t_{d-1})}\]
Falling edges

In opposite to a rising edge, a falling edge condition (conditionEdge="falling") evaluates to true when its logical expression at td evaluates to false and the logical expression at td-1 evaluates to true:

\[C_{F}(t_{d}) = \overline{LogicalExpression(t_{d})} \wedge LogicalExpression(t_{d-1})\]
Rising or falling edges

When a condition was defined with rising or falling edges (conditionEdge="risingOrFalling"), the condition evaluation is simply a combination of rising or falling edges:

\[C_{RoF}(t_{d}) = C_{R}(t_{d}) \vee C_{F}(t_{d})\]
None edges

With none edges defined (conditionEdge="none"), the evaluation of a condition is the evaluation of its logical expression:

\[C_{N}(t_{d}) = LogicalExpression(t_{d})\]

4.4.3. Condition delay

A delay is a modification of a condition that allows past values of the condition evaluation to be used in the present td. When a delay Δt is defined, a condition at time td is represented by the evaluation of the logical expressions associated to that condition, at td-Δt, rather than the evaluation of its logical expressions at time td. In other words, evaluation of a delayed condition at time td it is equivalent to the evaluation of a similiar condition, but without delay, at timet td-Δt:

\[C_{D}(t_{d}) = C(t_{d-\Delta})\]

4.4.4. Corner cases of edges and delays

Both edge and delay concepts rely on previous evaluations of the logical expression of a condition. Depending on when the condition is evaluated, these previous evaluations of the logical expression may not be available.

The first time a condition defined with edge is checked, there is no information about previous evaluations of its logical expression. At runtime, a condition defined with edge shall always evaluate to false, the first time it is checked. OpenSCENARIO expects a condition to be checked for the first time once its enclosing storyboard element enters the standbyState. If standbyState is not defined, runningState shall be used.

In case of conditions defined with delay, if td < Δt, the concerned condition evaluates to false.

4.4.5. Condition types

The base condition type contains three basic elements: name, delay, and conditionEdge. Whereas the first element is self-explanatory, clarification on the other terms is given in the preceding sections. Other elements of a condition depend on its subtype, of which there are two: ByEntityCondition and ByValueCondition.

ByEntityConditions

The ByEntityCondition class hosts classes of conditions which use the states entities to perform the conditional evaluation. The conditional evaluation may depend on the value of a single state, or on how the value of any one given state relates to another state. The other state may be:

  • within the entity

  • between entities

  • between the entity and the corresponding characteristics of the road network

Entity conditions require the definition of triggering entities whose states are used in the conditional evaluation. If more than one triggering entity is defined, the user is given two alternatives to determine when the condition evaluates to true: either all triggering entities verify the logical expression or at least one entity verifies the logical expression.

ByValueConditions

The ByValueCondition classes hosts condition classes with logical expressions that depend on simulation states rather than entity states. Examples are scenario states, times, and traffic signal information.

Value conditions also provide a wrapper for external conditions that may depend on values that are not accessible from the scenario and are only available to the user implementation. Examples are pressing buttions, custom signals, and commands.

5. Scenario at runtime

This section covers the expected runtime behavior of the Storyboard and its nested elements in a simulation.

5.1. States

The lifecycle of a StoryboardElement instance includes five states.

initState and endState are implementation-specific and represent the creation (initState) and the cleanup (endState) of a StoryboardElement. All other states may be monitored with a StoryboardElementStateCondition.

  • standbyState: During the standbyState, a StoryboardElement waits for a start trigger. Only elements that define a start trigger or inherit a start trigger define a standbyState.

  • runningState: Represents the ongoing, unfinished execution of the StoryboardElement.

  • completeState: With transition into completeState, a StoryboardElement has reached its goal or was stopped.

5.2. Transitions

The change from one state to another is called transition. There are six transitions for the StoryboardElement lifecycle.

startElementLifecycle and stopElementLifecycle are implementation-specific and represent the creation (startElementLifecycle) and the cleanup (stopElementLifecycle) of a StoryboardElement. All other states may be monitored with StoryboardElementStateCondition.

  • startTransition: The transition into runningState. Either from standbyState, when waiting for a start trigger, or from initState, when a StoryboardElement enters runningState instantly because its parent enters runningState.

  • endTransition: The transition out of runningState. It symbolizes that runningState has ended regularly without being stopped.

  • stopTransition: The transition out of runningState or out of standbyState. It signals that the execution of the StoryboardElementelement was stopped, for example by overriding or an issued stop trigger.

  • skipTransition: This transition is specific to Event. skipTransition is used when an Event cannot be started due to its priority skip. See Section 5.4.2.

5.3. Execution

A storyboard element is defined as executing when the element either resides in standbyState or in runningState.

When a storyboard element enters runningState, its direct child elements are set into:

  • standbyState if the child element defines a start trigger.

  • runningState in all other cases.

5.3.1. Duration of an execution

The duration of an execution is determined by three factors:

  • Waiting time for start triggers.

  • Execution time for nested Action instances.

  • Waiting for Storyboards stop trigger when all Story instances have been completed.

There is no other runtime aspect that consumes simulation time.

5.3.2. Execution framework

The execution of a scenario follows a general nested pattern:

  • A Storyboard is executed by running its nested Story instances (0..*).

  • A Story is executed by running its nested Act instances (1..*)

  • An Act is executed by running its nested ManeuverGroup instances (1..*). Each ManeuverGroup is executed as often as defined in its maximumExecutionCount.

  • A ManeuverGroup is executed by running its nested Maneuver instances (0..*)

  • A Maneuver is executed by running its nested Event instances (1..*), following defined priorities. Each nested Event is executed as often as defined in its maximumExecutionCount.

  • An Event is executed by running its nested Action instances (1..*).

  • An Action in a Storyboard is executed by applying the designated behavior to any actor defined in the ManeuverGroup.

5.3.3. Execution patterns

OpenSCENARIO applies several execution patterns while running the Storyboard:

  • Parallel execution: Nested StoryboardElement instances are usually executed in parallel, for example, multiple Act instances in a Story.

  • Loop execution: Event instances and ManeuverGroup instances are executed in a loop. maximumExecutionCount states the number of executions.

  • Priority based execution: Event instances are executed based on a defined priority. See Section 5.4.2 for details.

  • Bulk action execution: Action instances in a Storyboard are executed by applying the defined behavior to any defined actor concurrently.

Parallel execution

When nested StoryboardElement instances are executed, the parent element forks into different execution paths. The parent execution completes when all execution paths have joined into a single path. Execution time of the parent element is defined by the nested element that takes the longest time to execute, as shown in Figure 29.

As an example, an Event completes when all concurrently executed Action instances are completed. The Action instance that took the longest time to execute defines the execution of the enclosing Event instance.

The execution of a Storyboard does not complete when all nested stories have been completed. See Section 5.4.7 for more information.
When referencing parallel actions and making them dependend of each other, the creation of deadlocks or undeterministic race conditions shall be avoided.
image
Figure 29. Petrinet model shows the parallel execution pattern with three nested elements
Loop execution

ManeuverGroup and Event instances are executed as many times as specified by maximumExecutionCount. The executions are performed sequentially. Figure 30 illustrates how a ManueverGroup or an Event are executed when maximumExecutionCount is set to three:

image
Figure 30. Petrinet model that shows the loop execution pattern with three executions per element

Figure 31 shows a general representation of the same behavior:

image
Figure 31. Petrinet model that shows a general loop execution pattern
Bulk action execution

A bulk action is a PrivateAction that must handle more than one entities at the time. This can occur when the actors of the enclosing ManeuverGroup are resolved to multiple ScenarioObject instances, rather than to a single one. Executing a bulk action is called a bulk execution. It applies the PrivateAction in parallel to all given ScenarioObject instances. Figure 32 shows how a bulk action is ran. It completes when all its child actions complete. The behavior is applied to multiple actors, that is ScenarioObject instances, in parallel.

A bulk action is in runningState as long as there is one child action instance in runningState. It reaches completeState with endTransition only under the condition that all child actions reach completeState with an endTransition. Otherwise the bulk action reaches completeState with stopTransition.

image
Figure 32. Petrinet model that shows a bulk execution of an action

5.4. Storyboard element execution

5.4.1. Execution of a action

An Action instance enters runningState when the parent Event enters runningState. An Action transfers into completeState either when its execution is stopped or when it ends regularly, as shown in Figure 33. stopTransition may be used for different reasons.

image
Figure 33. State diagram for an action

5.4.2. Execution of an event

An Event enters standbyState when its enclosing Maneuver is started and enters runningState, as shown in Figure 34. When the start trigger of the Event is executed and the priority allows execution, the Event enters runningState. An Event lacking an own start trigger inherits its start trigger from its parent Act.

While in runningState, the Event ends regularly when every nested Action is completed. The Event transfers to completeState with stopTransition under two conditions:

  • A stop trigger is issued by the enclosing Act or Storyboard.

  • It is overridden by another Event in the same scope (Maneuver).

image
Figure 34. State diagram for an event
Execution count

The number of executions of an Event is represented as the sum of the number of startTransitions and skipTransitions.

When the Event is about to transfer out of runningState with endTransition, two things may happen:

  • The Event transfers to completeState if the number of executions is equal to maximumExecutionCount .

  • The Event transfers to standbyState if the number of executions is lower than the defined maximumExecutionCount.

If in standbyState and the number of executions is equal to the number stated by maximumExecutionCount, the Event transfers to completeState with skipTransition.

Event priority
  • Override: A triggered Event with priority override terminates any running Event in the same scope (Maneuver), when it moves to runningState. A terminated Event moves to completeState with stopTransition, regardless of the number of executions left.

  • Skip: A triggered Event with priority skip does not move to runningState and instead moves to completeState if no number of executions is defined, or there is an execution left. If there are execution left, the Event increases the number of executions by one.

  • Parallel: A triggered Event with priority parallel moves to the runningState regardless of the states of other Event instances in the same scope (Maneuver).

5.4.3. Execution of a maneuver

A Maneuver enters runningState as soon as its enclosing ManeuverGroup is started. In this state, all nested Event instances are set to standbyState and wait for their start trigger, as shown in Figure 35.

The Maneuver completes when all nested Event instances have entered the completeState or when the Maneuver is stopped by an issued stop trigger from the enclosing Act or Storyboard.

image
Figure 35. State diagram for a maneuver

5.4.4. Execution of a ManeuverGroup

ManeuverGroup instances are set to runningState when the start trigger of their enclosing Act is executed and the Act enters runningState. At this point, the nested Maneuver instances are set to runningState.

A ManeuverGroup ends regularly when all its Maneuvers are completed.

The number of executions of a ManeuverGroup corresponds to the number of startTransitions performed from the standbyState to the runningState. The ManeuverGroup transfers out of the runningState depending on the number of executions:

  • If the number of executions is smaller than maximumExecutionCount the ManeuverGroup transfers from runningState into standbyState and waits until the start trigger is executed. The start trigger is inherited from the enclosing Act.

  • If the number of executions is equal to the maximumExecutionCount, the ManeuverGroup transfers from runningState into completeState.

When the ManeuverGroup resides either in runningState or in standbyState, it may be stopped by a stop trigger that is issued by its enclosing Act or its Storyboard. When stopped, the ManeuverGroup transfers to completeState regardless of the number of execution counts left.

OpenSCENARIO allows empty ManeuverGroup instances. Figure 36 clarifies that in this case, the ManeuverGroup ends instantly and directly transfers to completeState without being started.
image
Figure 36. State diagram for a maneuver group

5.4.5. Execution of an act

An Act is set into standbyState as soon as its enclosing Story is started. When the start trigger of the Act is executed, the Act enters runningState, as shown in Figure 37. The nested ManeuverGroup instances transfer to runningState.

The Act may be stopped by its stop trigger or by the stop trigger in the enclosing Storyboard and let the Act transfer to completeState.

The Act ends regularly and enters completeState when all nested ManeuverGroup instances are completed.

image
Figure 37. State diagram for an act

5.4.6. Execution of a story

A Story is started and set into runningState when its enclosing Storyboard starts and enters runningState. Its nested Act instances are set to standbyState and wait for their start triggers to execute, as shown in Figure 38.

The execution of a Story is stopped when the enclosing Storyboard issues a stop trigger. The execution transfers from runningState into completeState when all nested Acts are completed.

image
Figure 38. State diagram for an Story

5.4.7. Execution of a storyboard

The Storyboard enters runningState when the simulation starts, as shown in Figure 39. This marks the start of the simulation time. Nested Story instances are started and set into runningState. A Storyboard does not transfer to completeState when all its nested stories are complete. A Storyboard only transfers to completeState with a stopTransition when its stop trigger is executed.

A Storyboard instance is able to run without defined stories, for example, when it is empty.

image
Figure 39. State diagram for a storyboard

5.5. Init section execution

The init section of a scenario defines actions to set entity states or global states providing initialization to a simulation. These actions are handled in the init phase prior to the execution of the StoryboardElement instances.

The order of the actions in the InitActions section is not translated into an execution order at runtime. All actions in init shall run concurrently and conflicts shall be handled according to the conflict solving guidelines provided in Section 4.3.2.4.

5.5.1. Running actions in the init phase

The actions defined in init are handled prior to the execution of the Storyboard. Because the simulation time starts with the execution of the Storyboard (see Section 5.4.7), the init phase does not consume simulation time. All types of Action may be used in init, even those that require elapsed simulation time to fulfill their designated goal, meaning that they cannot be executed instantaneously.

Handling of instantaneous actions

During the init phase, those actions that may be applied instantaneously are instantiated, executed, and reach the completeState, as shown in Figure 40.

image
Figure 40. State machine evolution for instantaneous actions during the init phase
Handling of non-instantaneous actions

During the init phase, those actions that require elapsed time to fulfill their goals, for example, instances of non-instantaneous actions, are instantiated and moved to runningState, as shown in Figure 41. These actions are left in runningState and are applied once the simulation starts with the execution of the storyboard. During storyboard execution, they shall be treated like any other actions that is instantiated during event execution. They may create conflicts with any newly created action and may be overridden by such an action.

image
Figure 41. State machine evolution for non-instantaneous Actions during the init phase
Non-instantaneous motion control actions shall assign the motion control strategy in the init phase.

6. Reuse mechanisms

6.1. Parameters

In OpenSCENARIO, parameters provide a central extension mechanism for scenarios.

  • With the help of parameters, a scenario designer can make parameterization points of a scenario explicit.

  • The scenario designer can define constraints to restrict the possible concrete parameter values to reasonable values. This avoids misuse and improves understandability of scenarios, especially when passed to test designers.

External applications can read the provided parameters and thus implement sophisticated methods to assign concrete values to the parameters. This extension method allows scenarios to be reused for a large space of concrete values, for example, the re-simulation of one scenario with different speeds.

Every attribute of an OpenSCENARIO language element may contain either the actual attribute or a reference to a parameter. Each parameter is defined in the ParameterDeclaration by its name, the parameterType, a default, type-specific initialization value and optional constraintGroups. When using a parameter, more precisely the parameter value, anywhere in the scenario, then the parameter is referenced by its name with a "$" prefix.

All parameters that are used in a scenario shall be defined in ParameterDeclaration where they are declared by their individual names. Because they are declared and not used as a reference, the name has no "$" prefix.

Naming of parameters works different than naming of scenario elements (see Section 1.4.5). While scenario elements may be made unique by providing prefixes, this does not apply to parameter names. The reason for this is that scenario elements are globally referencable, whereas parameters have a scope.

The scope of a parameter is the subtree rooted in the element where the ParameterDeclarations is located. That means, if a parameter "ego_speed" is defined at the root of a Maneuver, "ego_speed" may be referenced in every Event, Action and Trigger located in that Maneuver. The parameter shall not be used in other Maneuver instances.

If there are multiple parameters with the same name and overlapping scopes in the scenario, only the parameter with the smallest scope that subsumes the location is accessible. As an example, if the Maneuver "Overtake" declares a parameter "ego_speed" and "Overtake" contains a FollowTrajectoryAction that also declares a parameter "ego_speed", then only the second declaration of "ego_speed" is visible in the FollowTrajectoryAction.

A parameter is considered global if it is a child of the OpenSCENARIO element that is the root of any OpenSCENARIO file. Global parameters may be overwritten by external tools (see, for example, Section 6.3).

Since every language element may either be the actual type or a referenced parameter, it is also generally allowed to use a reference as, for example, parameterType on another ParameterDeclaration. Using a parameter reference in another parameter declarations name field is allowed, but it is strongly advised not to do such chaining of parameters or mutual referencing as this can easily lead to deadlocks.

The assignment of values to parameters declared in a Catalog is allowed in a CatalogReference.

There is a type inference check defined by the standard, which ensures that the parameterType matches. The check is not ensured by the XML validator and therefore must be implemented by the simulator.

Parameters are set and evaluated at load time of the simulation. A ParameterAction or ParameterCondition does not affect these parameters. Moreover, they act during simulation runtime.

Parameter names starting with OSC are reserved for special use in future versions of OpenSCENARIO. Generally, the OSC prefix shall not be used.

These naming rules apply to parameters:

  • All parameter names must begin with a letter of the alphabet (a-z, A-Z) or an underscore (_).

  • After the first initial character, names can also contain numbers (0-9).

  • Parameters names are treated case-sensitive.

The parameter name must match the regular expression [A-Za-z_][A-Za-z0-9_]*.

Special rules apply to referencing parameters within a Catalog (see section Section 6.5).

6.2. Expressions

OpenSCENARIO supports mathematical operations for evaluating expressions. Every attribute of a language element may contain either the actual attribute as a literal (constant value), a reference to a parameter, or an expression.

Expressions are notated with the following syntax:

${Expr}

OpenSCENARIO expressions are build on literals and parameters. Because of that circumstance, the expressions are typed as well.

Expressions are designed to define relatively simple operations in scenario files. Checks and more sophisticated, complex calculations should not be expressed in a scenario file.

6.2.1. Operators

Operators are used to define mathematical operations between expressions. The precedence of the operator is defined by general mathematical rules. Nested expressions with brackets are supported. Operators are exclusively supported for numerical (int, unsingedInt, unsignedShort, and double) and boolean data types. They are not defined for string, dateTime, or other data types.

All arithmetic operators ordered by their precedence are listed as follows:

Supported arithmetic operators (ordered by operator precedence):
  • Operators with highest precedence

    • Unary Minus (-): numeric → numeric

    • Round operator (round): doubleint

    • Floor operator (floor): doubleint

    • Ceil operator (ceil): doubleint

    • Square root operator (sqrt): doubledouble

  • Operators with middle precedence

    • Power operator (pow): double, doubledouble

    • Multiply operator (*): numeric, numeric → numeric

    • Division operator (/): double, doubledouble

    • Remainder operator(%): numeric, numeric → numeric

  • Operators with lowest precedence

    • Plus operator (+): numeric, numeric → numeric

    • Minus operator (-): numeric, numeric → numeric

The operators -, +, %, and * are defined for all numeric data types. Furthermore, the result of such an operator has the same data type as its arguments and all of its arguments have the same type.

For the definition of the arithmetic operators [12] shall be used. It is noteworthy that % is the remainder operator, not the modulo operator. For integers greater zero, both operators give equal results. Furthermore, the arguments of the operators round, floor, ceil, and pow are given behind the operator name and need to be surrounded by parentheses.

Additionally, OpenSCENARIO has three Boolean operators:

Supported Boolean operators (ordered by operator precedence):
  • Negation operator (not)

  • Conjunction operator (and)

  • Disjunction operator (or)

Example expressions:
  • Arithmetic expressions:

${pow(2, 8) - 1}
${-round(2.6)}
${1 + sqrt(9) * 2.2}

is equivalent to

${1 + (sqrt(9) * 2.2)}
  • Boolean expressions:

${not $A and $B}

is equivalent to

${(not $A) and $B}
${$A or $B and not $C}

is equivalent to

${$A or ($B and (not $C))}

6.2.2. Types

OpenSCENARIO allows Boolean literals to be given as 0, 1, true, and false. However, it results in a type error if an arithmetic function is used in an expression where a Boolean value is expected.

For arithmetic expressions, OpenSCENARIO does not support explicit type casting. Instead, the standard allows for type conversion from double to int via the operators round, floor, and ceil.

Moreover, implicit type conversion is applied where information loss is not an issue. The implicit type conversion follows the following rules:

  • Integer values (signed and unsigned) may be implicitly converted to double values.

  • Integer literals can be implicitly converted to any integer data type.

For the user this means that integer literals, such as 0, 1, and 2 are automatically correctly used as int, unsignedInt, unsignedShort, and double as needed. Furthermore, for unsignedInt and unsignedShort only the operators +, *, %, and - may be used, where - should be used carefully to avoid underflow errors. Additionally, parameters of the types unsignedInt, unsignedShort, and int shall not be mixed.

The rest of this subsection details the type inference. The expected type is defined to be the type that an expression or a value is expected to have. For example, WorldPosition has attributes x, y, and z to describe coordinate positions. All of these attributes have double as data type. A type mismatch occurs if the expected type and the actual type differ. A type error occurs if a type mismatch cannot be resolved by an implicit conversion.

Example of type mismatches

For example, in

<WorldPosition x="${pow(2, 8) - 1}" y="${-round(2.6)}" />

the expected type of both expressions is double.

When analyzing the type of the first expression and its subexpression, several type mismatches are found. To find the mismatches we propagate the expected type backwards through the expression. The expected type of the whole expression is double. The actual types of the arguments of the subtraction are double for pow(2, 8) and int for 1. Because the types of the arguments of the subtraction are required to be equal to the type of the result (which is expected to be a double), we have a type mismatch. The integer literal 1 can be implicitly converted to double, which resolves the mismatch. The operator pow expects two double arguments, which results in another type mismatch. The given arguments 2 and 8 can be implicitly converted to double.

Analyzing the second expression shows that the result of round has int as actual type, while the expected type is double. This is a type mismatch, which can be resolved by implicitly converting the result of round to double. There are no more mismatches.

Because all type mismatches can be resolved in both expressions can be resolved, we conclude that neither of the two expressions cause a type error.

6.2.3. General restrictions

Because OpenSCENARIO does not use NaN or infinity, all operations where [12] defines the result to be either NaN or infinity shall instead result in an error.

Furthermore, an implementation must raise an appropriate error if:

  • The application detects arithmetic errors (division by zero, sqrt of a negative value, …​).

  • An unresolvable type mismatch occurs.

  • An arithmetic overflow or underflow occurs.

The following example illustrates this:

<Dimensions width="${$defaultWidth + 12.3}" length="4.2" height="1.6"/>

6.3. Parameter value distribution file

To use parameters in a convenient way to parametrize scenarios, a parameter value distribution file may be used to describe in which way those parameters vary.

Parameters in OpenSCENARIO are evaluated at the load time of the scenario. At this point, all parameters are replaced with the current value of the parameter wherever the parameter is referenced. The actual value is given in the ParameterDeclaration part.

With a parameter distribution file, the actual value is not taken out of the ParameterDeclaration but is computed at load times regarding the information in the distribution file.

The file should be separated from the OpenSCENARIO file and is handled like catalogs. The file format is included into the OpenSCENARIO element and contains the same FileHeader. An OpenSCENARIO file shall be referenced from the parameter distribution file.

An example without the definition part is shown below:

<OpenSCENARIO xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xsi:noNamespaceSchemaLocation="OpenSCENARIO.xsd">
   <FileHeader revMajor="1"
               revMinor="0"
               date="2020-09-08T12:00:00+01:00"
               description="Example"
               author="Max"/>
   <ParameterValueDistributions>
      <ScenarioFile filepath="Scenarios/file.xosc"/>
      <!-- distribution definition goes here -->
    </ParameterValueDistributions>
</OpenSCENARIO>

A distribution file may contain two different types of distributions. There are either Stochastic or Deterministic distributions, containing single-parameter distributions and multi-parameter distributions. For single-parameter distributions, every parameter value distribution is independent of other parameters. Therefore, every distribution definition is bound to a single parameterName. For multi-parameter distributions the values of the parameters are changed dependent on each other. Single-parameter and multi-parameter distributions may be used at the same time, but they shall not contain the same value for parameterName.

6.3.1. Deterministic distributions

A deterministic distribution definition may be either a single-parameter or a multi-parameter distribution.

Single-parameter distribution
  • DistributionSet: Single values may be given as a set in which each value is varied in order of definition.

  • DistributionRange: A range may be used by defining the lower and upper limit in combination with a step width.

  • UserDefinedDistribution: Other custom distributions which may be implemented by the application.

All parameters are varied separately. If two different parameters are varied by deterministic distribution, only one parameter is varied at a time. Therefore, the resulting parameter space is the cartesian product of both variation sets.
Multi-parameter distribution
  • ValueSetDistribution: Complete sets of parameter values may be given. For each concrete scenario, one set is used and all parameter values given within this set are changed.

6.3.2. Stochastic distributions

When using stochastic distributions, a random seed and number of test runs may be defined globally for all types.

Currently, the following single-parameter distributions are defined for stochastic distribution definitions:

Single-parameter distributions
  • ProbabilityDistributionSet: Set of values with defined probability.

  • NormalDistribution: Normal distribution of the parameter.

  • UniformDistribution: Uniform distribution of the parameter.

  • PoissonDistribution: Poisson distribution of the parameter.

  • Histogram: Histogram distribution of the parameter.

  • UserDefinedDistribution: Other custom distributions which may be implemented by the application.

All parameters are varied at a time. If two different parameters are varied by stochastic distribution, all parameters are varied all the time.

Additionally, by defining a Range element, the upper and lower limits of the distribution may be defined. The Range element shall not be used at ProbabilityDistributionSet or UserDefinedDistribution.

6.4. Catalogs

Many elements of a scenario require a detailed description, which may not only be rather lengthy but can also be tedious to repeatedly write if the element is used in several different scenarios. The Catalog element offers the possibility to outsource the description of certain elements from the scenario to a separate file, which may then be referenced from a scenario.

Using a Catalog enhances the reusability of elements and the readability of the scenario at the cost of technical detail in the scenario file. In order to refer to an element detailed within a Catalog, a reference to the Catalog shall be specified in the scenario. At the location where the element is being used, the reference to both the Catalog and the specific element shall be given.

There are eight different kinds of elements that may be outsourced to a Catalog. All kinds of objects may be defined within a Catalog, for example, Vehicle, Pedestrian, and MiscObject, as well as their respective Controller. Navigational instructions in the form of Trajectory and Route may also be stored. Additionally, descriptions of the Environment and instances of Maneuver may be outsourced this way.

6.5. Parameters in catalogs

Catalog files are designed for reuse. For this reason, they can store their own set of parameters. All parameters used within a catalog shall be declared within their ParameterDeclaration, which sets a default value for each parameter. When a catalog is referenced, the ParameterAssignment element within CatalogReference may be used to override these defaults.

For example, a catalog definition may contain the following ParameterDeclaration:

<ParameterDeclarations>
    <ParameterDeclaration name = "x" value = "5"/>
    <ParameterDeclaration name = "y" value = "7"/>
</ParameterDeclarations>

When referenced in the main scenario, the value of x is overridden by using a ParameterAssignment within the CatalogReference:

<CatalogReference catalogName = "eg_catalog" entryName = "eg_entry">
    <ParameterAssignments>
        <ParameterAssignment parameterRef = "x" value = "0"/>
    </ParameterAssignments>
</CatalogReference>

This means that, for this use of the catalog, any reference to "$x" should be replaced with "0", and any reference to "$y" should be replaced with the default value of "7". No other parameters may be referenced from within the catalog.

The value attribute of a ParameterAssignment may itself reference a parameter.

6.6. Resolving catalog references

Catalog references are resolved by locating the catalog by name and the entry within this catalog by its entry name (catalogName and entryName of the CatalogReference). A CatalogReference may hand over a ParameterAssignment to resolve parameters for this specific reference.

A Catalog shall be defined in a catalog file (for example, "VehicleCatalog.xosc"). An instance of a Catalog is identified by its name property.

Any valid catalog file of the correct catalog type and catalog name shall be processed that resides in the defined directory. A directory for every catalog type may be defined in a scenario:

  • VehicleCatalogLocation

  • ControllerCatalogLocation

  • PedestrianCatalogLocation

  • MiscObjectCatalogLocation

  • EnvironmentCatalogLocation

  • ManeuverCatalogLocation

  • TrajectoryCatalogLocation

  • RouteCatalogLocation

7. Tutorial: How to create a scenario

7.1. Example description of a scenario

The file for the sample scenario used in this tutorial is named SimpleOvertake.xosc. The file is located in the examples directory.

This scenario is written for a country with right-hand traffic, but can easily be adapted to left-hand traffic.

Vehicle 2 and Vehicle 1 are located on the same lane on SampleDatabase.xodr 58 meters apart, with Vehicle 2 being in front of Vehicle 1. Vehicle 1, having the larger speed, catches up with Vehicle 2 , and needs to change to the left lane. After some time, when it has overtaken Vehicle 2, it moves back to its previous lane, ending in front of Vehicle 2.

image
Figure 42. Initial positions of vehicles (Vehicle is shortened to v in this graphic)

7.2. Entities

In the Entities section we define the traffic participants used in the scenario: one or more instances of Vehicle, Pedestrian or MiscObject.

  <Entities>
    <ScenarioObject name="Vehicle 1">
      <Vehicle name="Vehicle 1" vehicleCategory="car">
        <ParameterDeclarations/>
        <BoundingBox>
          <Center x="1.3" y="0.0" z="0.75"/>
          <Dimensions width="1.8" length="4.5" height="1.5"/>
        </BoundingBox>
        <Performance maxSpeed="200.0" maxDeceleration="30.0" maxAcceleration="200.0"/>
        <Axles>
          <FrontAxle positionZ="0.4" trackWidth="1.68" positionX="2.98" maxSteering="0.5235987756" wheelDiameter="0.8"/>
          <RearAxle positionZ="0.4" trackWidth="1.68" positionX="0.0" maxSteering="0.5235987756" wheelDiameter="0.8"/>
        </Axles>
        <Properties/>
      </Vehicle>
      <ObjectController/>
    </ScenarioObject>

    <ScenarioObject name="Vehicle 2">
      <Vehicle name="Vehicle 2" vehicleCategory="car">
        <ParameterDeclarations/>
        <BoundingBox>
          <Center x="1.4" y="0.0" z="0.9"/>
          <Dimensions width="2.0" length="5.0" height="1.8"/>
        </BoundingBox>
        <Performance maxSpeed="200.0" maxDeceleration="30.0" maxAcceleration="200.0"/>
        <Axles>
          <FrontAxle positionZ="0.4" trackWidth="1.68" positionX="2.98" maxSteering="0.5235987756" wheelDiameter="0.8"/>
          <RearAxle positionZ="0.4" trackWidth="1.68" positionX="0.0" maxSteering="0.5235987756" wheelDiameter="0.8"/>
        </Axles>
        <Properties/>
      </Vehicle>
      <ObjectController/>
    </ScenarioObject>
  </Entities>

To state you want to use an entity from the catalog use the following syntax:

<ScenarioObject name="Entity name in scenario">
  <CatalogReference catalogName="VehicleCatalog" entryName="Entity name in catalog"/>
</ScenarioObject>

In this scenario we are not using catalogs. Instead, both entities are defined directly. It should be noticed that the entities do not have an initial position and initial speed yet. These are added in the following sections.

7.3. Init section

The following XML example shows multiple instances of Action that position the entities Vehicle 1 and Vehicle 2 using road coordinates and define initial velocities. Vehicle 1 has speed 150 km/h and is located 58 m behind Vehicle 2, which has speed 130 km/h.

Values in the scenario xosc are in SI unit system.
OpenSCENARIO does not enforce specifying the initial position and speed of entities, but it is considered best practice to do so. Most actions and conditions require those values to be set.
<Init>
    <Actions>
      <Private entityRef="Vehicle 1">
        <PrivateAction>
          <TeleportAction>
            <Position>
              <RoadPosition roadId="3" s="2.0" t="-11.0">
                <Orientation h="0.0" p="0.0" r="0.0" type="relative"/>
              </RoadPosition>
            </Position>
          </TeleportAction>
        </PrivateAction>
        <PrivateAction>
          <LongitudinalAction>
            <SpeedAction>
              <SpeedActionDynamics dynamicsDimension="time" dynamicsShape="step" value="0.0"/>
              <SpeedActionTarget>
                <AbsoluteTargetSpeed value="41.6666666667"/>
              </SpeedActionTarget>
            </SpeedAction>
          </LongitudinalAction>
        </PrivateAction>
      </Private>

      <Private entityRef="Vehicle 2">
        <PrivateAction>
          <TeleportAction>
            <Position>
              <RoadPosition roadId="3" s="60.0" t="-11.0">
                <Orientation h="0.0" p="0.0" r="0.0" type="relative"/>
              </RoadPosition>
            </Position>
          </TeleportAction>
        </PrivateAction>
        <PrivateAction>
          <LongitudinalAction>
            <SpeedAction>
              <SpeedActionDynamics dynamicsDimension="time" dynamicsShape="step" value="0.0"/>
              <SpeedActionTarget>
                <AbsoluteTargetSpeed value="36.1111111111"/>
              </SpeedActionTarget>
            </SpeedAction>
          </LongitudinalAction>
        </PrivateAction>
      </Private>
    </Actions>
  </Init>

7.4. Stories

Instances of Story may be used to group independent parts of the scenario, to make it easier to follow. In this example we need only one Story. If an Act is moved from one Story to another, the scenario works in the same way, as long as there are no naming conflicts.

In this scenario, one Story defines just one Act.

<Story name="Story 1">
  <!-- Act 1-->
</Story>

7.5. Acts

An Act allows a set of multiple instances of Trigger to determine when the specific Act starts.

This example scenario contains a startTrigger at Act and Event level. At Act level, they are used just to start the simple overtaking scenario. At the Event level, they control the scenario’s execution.
All OpenSCENARIO storyboard elements may run in parallel. Sequential execution is introduced indirectly by triggers, which can control how certain storyboard elements start or stop.

The example below shows the structure of an Act. This Act starts when the scenario starts because it has one SimulationTimeCondition condition checking when time becomes larger than zero. Movements of vehicles in Act are defined in the ManeuverGroups section, which is omitted here but described later in this chapter.

<Act name="Act 1">
  <!-- ManeuverGroup 1-->
  <StartTrigger>
    <ConditionGroup>
      <Condition delay="0.0" conditionEdge="rising" name="Simulation Time">
        <ByValueCondition>
          <SimulationTimeCondition rule="greaterThan" value="0.0"/>
        </ByValueCondition>
      </Condition>
    </ConditionGroup>
  </StartTrigger>
</Act>

An Act may be terminated by a stopTrigger (see Section 4.4.1.2).

7.6. ManeuverGroups

Using ManeuverGroup we specify the Actors that are executing the actions. Because we want Vehicle 1 to change lanes, we specify its name under Actors. This means that all the actions under this ManeuverGroup are executed by Vehicle 1.

For executing global actions Actors may be left empty.
For determining actors during runtime, you have to use selectTriggeringEntities = true, which is explained in Section 4.3.1.

ManeuverGroups receives its name from grouping one or multiple instances of Maneuver which is used in the next section.

<ManeuverGroup maximumExecutionCount="1" name="ManeuverGroup 1">
  <Actors selectTriggeringEntities="false">
    <EntityRef entityRef="Vehicle 1"/>
  </Actors>
  <!-- Maneuver 1-->
</ManeuverGroup>

7.7. Maneuvers

In this example, one Maneuver is used to group two instances of Event. Two instances of Maneuver may also be used, each hosting one Event. Both alternatives yield the same simulation outcome, as long as each Event retain its startTrigger.

<Maneuver name="Maneuver 1">
  <ParameterDeclarations/>
  <Event priority="overwrite" maximumExecutionCount="1" name="Turn left">
    <!-- ... -->
  </Event>
  <Event priority="overwrite" maximumExecutionCount="1" name="Turn right">
    <!-- ... -->
  </Event>
</Maneuver>

7.8. Events and actions

Under Maneuver_1 we define two instances of Event, one for left lane change called Turn left and the other one with right lane change named Turn right. Left and right means relative to the current lane.

In the first Event that we want to execute, which is Turn left, we use one ConditionGroup and inside it one RelativeDistanceCondition. This condition checks if the current longitudinal distance between Vehicle 1 and Vehicle 2 is shorter than 20 m. Because Vehicle 1 has a higher speed than Vehicle 2 their relative distance falls below 20 m at some point and StartTrigger gets triggered on Turn left event, and Vehicle 1 starts its LaneChange action to the left.

The second Event named Turn right contains also one LaneChangeAction, but this one targets the same lane where Vehicle 2 is currently located. That means, the target is to get back to the same lane where Vehicle 1 was, but this time in front of Vehicle 2.

In this action we specified the exact coordinates on the target lane, but we could have also used relative road coordinates relative to Vehicle 2. Using relative coordinates makes the scenario more portable to other road networks.

For triggering the event Turn right we use two conditions in one condition group, which means they both have to be true at the exact same time. We use RelativeDistanceCondition that checks whether the relative longitudinal distance between Vehicle 2 and Vehicle 1 is no longer greater than 10 m. However, we have to combine this condition with SimulationTimeCondition to disallow triggering RelativeDistanceCondition anytime before 5 seconds.

<Event priority="overwrite" maximumExecutionCount="1" name="Turn left">
  <Action name="Lane Change">
    <PrivateAction>
      <LateralAction>
        <LaneChangeAction targetLaneOffset="0.0238800048828">
          <LaneChangeActionDynamics dynamicsDimension="distance" dynamicsShape="cubic" value="36.6430664063"/>
          <LaneChangeTarget>
            <AbsoluteTargetLane value="-3"/>
          </LaneChangeTarget>
        </LaneChangeAction>
      </LateralAction>
    </PrivateAction>
  </Action>
  <StartTrigger>
    <ConditionGroup>
      <Condition delay="0.0" conditionEdge="rising" name="Relative Distance">
        <ByEntityCondition>
          <TriggeringEntities triggeringEntitiesRule="any">
            <EntityRef entityRef="Vehicle 1"/>
          </TriggeringEntities>
          <EntityCondition>
            <RelativeDistanceCondition freespace="false" rule="lessThan" entityRef="Vehicle 2" value="20.0" relativeDistanceType="longitudinal"/>
          </EntityCondition>
        </ByEntityCondition>
      </Condition>
    </ConditionGroup>
  </StartTrigger>
</Event>


<Event priority="overwrite" maximumExecutionCount="1" name="Turn right">
  <Action name="Lane Change">
    <PrivateAction>
      <LateralAction>
        <LaneChangeAction>
          <LaneChangeActionDynamics dynamicsDimension="distance" dynamicsShape="cubic" value="20.0"/>
          <LaneChangeTarget>
            <AbsoluteTargetLane value="-4"/>
          </LaneChangeTarget>
        </LaneChangeAction>
      </LateralAction>
    </PrivateAction>
  </Action>
  <StartTrigger>
    <ConditionGroup>
      <Condition delay="0.0" conditionEdge="rising" name="Relative Distance">
        <ByEntityCondition>
          <TriggeringEntities triggeringEntitiesRule="any">
            <EntityRef entityRef="Vehicle 2"/>
          </TriggeringEntities>
          <EntityCondition>
            <RelativeDistanceCondition freespace="false" rule="greaterThan" entityRef="Vehicle 1" value="10.0" relativeDistanceType="longitudinal"/>
          </EntityCondition>
        </ByEntityCondition>
      </Condition>
      <Condition delay="0.0" conditionEdge="none" name="Simulation Time">
        <ByValueCondition>
          <SimulationTimeCondition rule="greaterThan" value="5.0"/>
        </ByValueCondition>
      </Condition>
    </ConditionGroup>
  </StartTrigger>
</Event>

7.9. Sequential execution

The basic execution pattern for StoryboardElement instances is parallel execution of nested elements, for example, a Storyboard executes a Story concurrently, while a Story executes one or multiple instances of Act in parallel.

In many use cases, however, an Action is applied only when others have finished. That means sequentialization of multiple occurences of Action is a major concept when writing and executing scenarios.

Two major concepts are provided:

  • Implicit synchronization of StoryboardElement instances: An action increases the speed of the Ego vehicle. Another event starts when the Ego vehicle reaches a specific speed.

  • Explicit synchronization of StoryboardElement instances: A start trigger of an event or of an act listens to the state of a storyboard element.

7.9.1. First example of sequential execution

The scenario comprises the following Event instances:

  1. The Ego vehicle increases speed from 0 to 100 km/h, starting at simulationTime = 0.

  2. The Ego vehicle brakes to a stop, starting when its speed reaches 100 km/h.

The following two examples show implicit and explicit synchronization.

Implicit sequentialization

Deterministic order can be ensured by using resulting states from one action as StartTrigger for another Action.

<Maneuver name="AccelerateAndBrakeManeuver">
  <Event name="AccelerateEvent"
         priority="overwrite"
         maximumExecutionCount="1">
    <Action name="AccelerateAction">
      <PrivateAction>
        <LongitudinalAction>
          <SpeedAction>
            <SpeedActionDynamics dynamicsShape="linear"
                                 value="4.0"
                                 dynamicsDimension="rate" />
              <SpeedActionTarget>
                <AbsoluteTargetSpeed value="27.78" />
              </SpeedActionTarget>
          </SpeedAction>
        </LongitudinalAction>
      </PrivateAction>
    </Action>
    <StartTrigger>
      <ConditionGroup>
        <Condition name="AccelerateStartCondition"
                   delay="0"
                   conditionEdge="none">
          <ByValueCondition>
            <SimulationTimeCondition value="0"
                                     rule="greaterThan"/>
          </ByValueCondition>
        </Condition>
      </ConditionGroup>
    </StartTrigger>
  </Event>
  <Event name="BrakeEvent" priority="overwrite" maximumExecutionCount="1">
    <Action name="BrakeAction">
      <PrivateAction>
        <LongitudinalAction>
          <SpeedAction>
            <SpeedActionDynamics dynamicsShape="linear"
                                 value="-4.0"
                                 dynamicsDimension="rate" />
              <SpeedActionTarget>
                <AbsoluteTargetSpeed value="0" />
              </SpeedActionTarget>
          </SpeedAction>
        </LongitudinalAction>
      </PrivateAction>
    </Action>
    <StartTrigger>
      <ConditionGroup>
        <Condition name="BrakeStartCondition"
                   delay="0"
                   conditionEdge="rising">
          <ByEntityCondition>
            <TriggeringEntities triggeringEntitiesRule="any">
              <EntityRef entityRef="Ego"/>
            </TriggeringEntities>
            <EntityCondition>
              <SpeedCondition value="27.78"
                              rule="greaterOrEqual"/>
            </EntityCondition>
          </ByEntityCondition>
        </Condition>
      </ConditionGroup>
    </StartTrigger>
  </Event>
</Maneuver>

The fully executable scenario is provided in the examples folder as SequentialEvents_0-100-0kph_Implicit.xosc.

Explicit sequentialization

The sequence of events may also be enforced by using the elements of storyboard state or storyboard transitions between states as trigger.

  1. The Ego vehicle increases speed from 0 to 100 km/h, starting at simulationTime = 0.

  2. The Ego vehicle brakes to a stop, starting when first event moves into completeState.

The StartTrigger of the brake changes to:

<StartTrigger>
  <ConditionGroup>
    <Condition name="BrakeCondition" delay="0" conditionEdge="rising">
      <ByValueCondition>
        <StoryboardElementStateCondition storyboardElementType="event"
                                         storyboardElementRef="AccelerateEvent"
                                         state="completeState"/>
      </ByValueCondition>
    </Condition>
  </ConditionGroup>
</StartTrigger>

The fully executable scenario is provided in the examples folder as SequentialEvents_0-100-0kph_Explicit.xosc.

7.9.2. Second example

The example shows an Ego vehicle that is speeding up to 20 m/s. At the time it reaches the speed, the red_vehicle should start to catch up with a speed of 30 m/s.

The example shows two instances of Act, each with a ManeuverGroup where Actor are Ego and red_vehicle.

Ego setup

The first act starts at the beginning of the simulation. Its ManeuverGroup defines the Ego vehicle as the Actor. An Event starts by increasing the speed with a linear value of 2 m/s. After 10 seconds, Ego vehicle reaches the speed of 20 m/s.

<Act name ="EgoSpeedUpAct">
  <ManeuverGroup maximumExecutionCount="1" name="EgoSpeedUpManeuverGroup">
    <Actors selectTriggeringEntities="false">
      <EntityRef entityRef="Ego"/>
    </Actors>
    <Maneuver name="EgoSpeedUp">
      <Event name="EgoSpeedUpEvent" priority="overwrite">
        <Action name="EgoSpeedUpAction">
          <PrivateAction>
            <LongitudinalAction>
              <SpeedAction>
                <SpeedActionDynamics dynamicsShape="linear"
                                     value="2"
                                     dynamicsDimension="time"/>
                <SpeedActionTarget>
                  <AbsoluteTargetSpeed value="20"/>
                </SpeedActionTarget>
              </SpeedAction>
            </LongitudinalAction>
          </PrivateAction>
        </Action>
        <StartTrigger>
          <ConditionGroup>
            <Condition name="AtSimulationStarts"
                     delay="0"
                     conditionEdge="none">
              <ByValueCondition>
                <SimulationTimeCondition value="0" rule="greaterThan"/>
              </ByValueCondition>
            </Condition>
          </ConditionGroup>
        </StartTrigger>
      </Event>
    </Maneuver>
  </ManeuverGroup>
  <StartTrigger>
    <ConditionGroup>
	  <Condition name="AtSimulationStarts"
			 delay="0"
			 conditionEdge="none">
	    <ByValueCondition>
		  <SimulationTimeCondition value="0" rule="greaterThan"/>
	    </ByValueCondition>
	  </Condition>
    </ConditionGroup>
  </StartTrigger>
</Act>
Implicit sequentialization

When synchronizing implicitly, the red_vehicle SpeedAction is applied when Ego is reaching the 20 m/s, as stated in StartTrigger.

<Act name="RedVehicleSpeedUpAct">
  <ManeuverGroup maximumExecutionCount="1"
                 name="RedVehicleSpeedUpManeuverGroup">
    <Actors selectTriggeringEntities="false">
      <EntityRef entityRef="red_vehicle"/>
    </Actors>
    <Maneuver name="RedVehicleSpeedUp">
      <Event name="RedVehicleSpeedUpEvent" priority="overwrite">
        <Action name="RedVehicleSpeedUpAction">
          <PrivateAction>
            <LongitudinalAction>
              <SpeedAction>
                <SpeedActionDynamics dynamicsShape="step"
                                     value="0"
                                     dynamicsDimension="time"/>
                <SpeedActionTarget>
                  <AbsoluteTargetSpeed value="30"/>
                </SpeedActionTarget>
              </SpeedAction>
            </LongitudinalAction>
          </PrivateAction>
        </Action>
        <StartTrigger>
          <ConditionGroup>
            <Condition name="StartOnEgoReachingSpeed"
                       delay="0"
                       conditionEdge="rising">
              <ByEntityCondition>
                <TriggeringEntities triggeringEntitiesRule="any">
                  <EntityRef entityRef="ego"/>
                </TriggeringEntities>
                <EntityCondition>
                  <SpeedCondition value="20"
                                  freespace="false"
                                  rule="greaterOrEqual"/>
                </EntityCondition>
              </ByEntityCondition>
            </Condition>
          </ConditionGroup>
        </StartTrigger>
      </Event>
    </Maneuver>
  </ManeuverGroup>
  <StartTrigger>
    <ConditionGroup>
      <Condition name="StartOnEgoReachingSpeed"
                 delay="0"
                 conditionEdge="rising">
        <ByEntityCondition>
	      <TriggeringEntities triggeringEntitiesRule="any">
	        <EntityRef entityRef="ego"/>
	      </TriggeringEntities>
	      <EntityCondition>
	        <SpeedCondition value="20"
			                freespace="false"
                            rule="greaterOrEqual"/>
	      </EntityCondition>
        </ByEntityCondition>
      </Condition>
    </ConditionGroup>
  </StartTrigger>
</Act>
Explicit sequentialization

When synchronizing the red_vehicle explicitly, SpeedAction is applied when RedVehicleSpeedUpAction successfully ends, as stated in StartTrigger.

The StartTrigger element now includes a StoryboardElementStateCondition.

<StartTrigger>
  <ConditionGroup>
    <Condition name="StartOnEgoActionEnd"
			 delay="0"
			 conditionEdge="rising">
	  <ByValueCondition>
	    <StoryboardElementStateCondition storyboardElementType="action"
                                         storyboardElementRef="RedVehicleSpeedUpAction"
                                         state="endTransition"
                                         />
	  </ByValueCondition>
    </Condition>
  </ConditionGroup>
</StartTrigger>

7.10. Traffic signal

7.10.1. First traffic signal example

The following example shows a T-junction with five traffic signals (T1…​T5). All traffic signals are controlled by one TrafficSignalController (TJunctionController). The controller defines 6 phases (Phase_1…​Phase_6). The duration of a cycle is 69 seconds.

<TrafficSignalController name="TJunctionController">
  <Phase name="Phase_1" duration="40">
    <TrafficSignalState state="green" trafficSignalId="T1"/>
    <TrafficSignalState state="red" trafficSignalId="T2"/>
    <TrafficSignalState state="red" trafficSignalId="T3"/>
    <TrafficSignalState state="red" trafficSignalId="T4"/>
    <TrafficSignalState state="green" trafficSignalId="T5"/>
 </Phase>
 <Phase name="Phase_2" duration="3">
    <TrafficSignalState state="yellow" trafficSignalId="T1"/>
    <TrafficSignalState state="red" trafficSignalId="T2"/>
    <TrafficSignalState state="red" trafficSignalId="T3"/>
    <TrafficSignalState state="red" trafficSignalId="T4"/>
    <TrafficSignalState state="green" trafficSignalId="T5"/>
 </Phase>
 <Phase name="Phase_3" duration="10">
    <TrafficSignalState state="red" trafficSignalId="T1"/>
    <TrafficSignalState state="red" trafficSignalId="T2"/>
    <TrafficSignalState state="green" trafficSignalId="T3"/>
    <TrafficSignalState state="green" trafficSignalId="T4"/>
    <TrafficSignalState state="green" trafficSignalId="T5"/>
 </Phase>
 <Phase name="Phase_4" duration="3">
    <TrafficSignalState state="red" trafficSignalId="T1"/>
    <TrafficSignalState state="red" trafficSignalId="T2"/>
    <TrafficSignalState state="green" trafficSignalId="T3"/>
    <TrafficSignalState state="yellow" trafficSignalId="T4"/>
    <TrafficSignalState state="yellow" trafficSignalId="T5"/>
 </Phase>
 <Phase name="Phase_5" duration="10">
    <TrafficSignalState state="red" trafficSignalId="T1"/>
    <TrafficSignalState state="green" trafficSignalId="T2"/>
    <TrafficSignalState state="green" trafficSignalId="T3"/>
    <TrafficSignalState state="red" trafficSignalId="T4"/>
    <TrafficSignalState state="red" trafficSignalId="T5"/>
 </Phase>
 <Phase name="Phase_6" duration="3">
    <TrafficSignalState state="red" trafficSignalId="T1"/>
    <TrafficSignalState state="yellow" trafficSignalId="T2"/>
    <TrafficSignalState state="yellow" trafficSignalId="T3"/>
    <TrafficSignalState state="red" trafficSignalId="T4"/>
    <TrafficSignalState state="red" trafficSignalId="T5"/>
 </Phase>
</TrafficSignalController>

In Phase_1, T1 and T5 show green signals. All other traffic signals are red.

In Phase_2, T1 turns yellow.

image
Figure 43. Traffic signal example for Phase_1 and Phase_2

In Phase_3, T1 turns red and enables T3 and T4 to turn green.

In Phase_4, T4 and T5 turn yellow.

image
Figure 44. Traffic signal example for Phase_3 and Phase_4

In Phase_5, T4 and T5 turn red and enable T2 to turn green.

In Phase_6, T2 and T3 turn yellow, before Phase_1 is repeated.

image
Figure 45. Traffic signal example for Phase_5 and Phase_6

7.10.2. Extended example

In some countries, traffic lights turn red+yellow, before they turn green. This would extend the example from above with 3 more phases.

  • Phase_2a, between Phase_2 and Phase_3

  • Phase_4a, between Phase_4 and Phase_5

  • Phase_6a, between Phase_6 and Phase_1

<TrafficSignalController name="TJunctionController">
 <Phase name="Phase_1" duration="40">
    ...
 </Phase>
 <Phase name="Phase_2" duration="3">
    ...
 </Phase>
 <Phase name="Phase_2a" duration="2">
    <TrafficSignalState state="red" trafficSignalId="T1"/>
    <TrafficSignalState state="red" trafficSignalId="T2"/>
    <TrafficSignalState state="red/yellow" trafficSignalId="T3"/>
    <TrafficSignalState state="red/yellow" trafficSignalId="T4"/>
    <TrafficSignalState state="green" trafficSignalId="T5"/>
 </Phase>
 <Phase name="Phase_3" duration="10">
     ...
 </Phase>
 <Phase name="Phase_4" duration="3">
     ...
 </Phase>
 <Phase name="Phase_4a" duration="2">
    <TrafficSignalState state="red" trafficSignalId="T1"/>
    <TrafficSignalState state="red/yellow" trafficSignalId="T2"/>
    <TrafficSignalState state="green" trafficSignalId="T3"/>
    <TrafficSignalState state="red" trafficSignalId="T4"/>
    <TrafficSignalState state="red" trafficSignalId="T5"/>
 </Phase>
 <Phase name="Phase_5" duration="10">
    ...
 </Phase>
 <Phase name="Phase_6" duration="3">
    ...
 </Phase>
 <Phase name="Phase_6a" duration="2">
    <TrafficSignalState state="red/yellow" trafficSignalId="T1"/>
    <TrafficSignalState state="red" trafficSignalId="T2"/>
    <TrafficSignalState state="red" trafficSignalId="T3"/>
    <TrafficSignalState state="red" trafficSignalId="T4"/>
    <TrafficSignalState state="red/yellow" trafficSignalId="T5"/>
 </Phase>
</TrafficSignalController>

During Phase_2a, T3 and T4 show red+yellow signals.

During Phase_4a, T2 shows a red+yellow signal.

During Phase_6a, T1 and T5 show red+yellow signals.

image
Figure 46. Traffic signal example for Phase_2a, Phase_4a, and Phase_6a

8. Examples

The following paragraphs describe the examples provided with OpenSCENARIO. The examples are defined for right-hand traffic.

8.1. Cut-in

This example, which is shown in Figure 47, describes a traffic situation where the Ego vehicle drives behind a vehicle on the rightmost lane of a two-lane straight highway. At the same time, the Ego vehicle is overtaken by a faster vehicle on the left lane. After overtaking, the faster vehicle cuts in to the Ego vehicle’s lane.

At the initialization phase, the environment conditions are set. The Ego vehicle is instantiated in the rightmost lane, driving at 100 km/h. A vehicle, driving at the same speed and in the same lane, is instantiated 84 m ahead of the Ego vehicle. A second car, driving at 110 km/h, is instantiated 100 m behind the Ego vehicle in the lane left of it.

At simulation runtime, after the second car has passed the Ego vehicle by 20 m, it cuts in to the Ego vehicle’s lane, using a prescribed trajectory.

This scenario teaches the use of the EnvironmentAction, instantiation of instances of Entity, Event, Condition and Trajectory.

examples 1 cut in
Figure 47. Cut-in scenario example

8.2. Slow preceding vehicle

This example, which is shown in Figure 48, describes a traffic situation where the Ego vehicle approaches a slower vehicle in the same lane of a two-lane curved highway.

At the initialization phase, the environment conditions are set. The preceding vehicle is instantiated at the rightmost lane. It is driving at a constant speed of 80 km/h. The Ego vehicle is instantiated relative to this vehicle in the same lane, but 200 m behind, driving at 100 km/h.

Each ParameterDeclaration assign a default value to each parameter in the scenario. Default parameter assignments can be overwritten by external applications or parameter distribution files.

For this scenario, a deterministic and stochastic distribution are defined:

  • SlowPrecedingVehicleDeterministicParameterSet.xosc for the deterministic distribution parameter set. The parameters for the speed of the Ego and the speed of A1 are varied in a deterministic manner. All possible values from the speed of the Ego are combined with all possible values from the speed of A1.

  • SlowPrecedingVehicleStochasticParameterSet.xosc for the stochastic distribution parameter set. The parameters for the speed of the Ego and the speed of A1 are varied in a stochastic manner. For each of the simulation runs, the parameters are varied independendly from each other. The weight defines how often the values appears for a given parameter.

This scenario teaches the instantiation of instances of Entity, the use of ParameterDeclaration, and the definition of deterministic and stochastic parameter sets.

examples 2 slow preceding vehicle
Figure 48. Slow preceding scenario example

8.3. End of traffic jam

This example, which is shown in Figure 49, describes a traffic situation where the Ego vehicle approaches two slower vehicles driving side-by-side on a straight two-lane highway running over a crest.

The environment conditions are set in the initialization phase. The Ego vehicle is instantiated at a constant velocity of 100 km/h on the rightmost lane of the road. 200 m ahead of Ego vehicle, two vehicles are instantiated at a velocity of 80 km/h in the rightmost lane and the neighboring lane to the left.

At simulation runtime, after vehicle A1 has travelled a distance of 100 m and vehicle A2 has travelled a distance of 200 m, they linearly decelerate by 5 m/s2 until they reach a target speed of 70 km/h.

The EndOfTrafficJamParameterSet.xosc defines two possibilities for the scene graph and the road network for this example. Both can be applied without changing the scenario itself.

This scenario extends the scenario in Section 8.2 by parallel execution of instances of Act and Condition. Moreover, it shows the possibility to change the road network and the scene graph with a deterministic multi parameter set.

examples 3 end of traffic jam
Figure 49. End of traffic jam scenario example

8.4. End of traffic jam, neighboring lane occupied

This example, which is shown in Figure 50, extends the scenario described in Section 8.3 by a fourth vehicle on a three-lane highway with limited friction. The rightmost and the leftmost lanes of this highway are blocked by stationary vehicles. A third vehicle performs a lane change to the centermost lane in order to prevent a collision with the stationary vehicle on the rightmost lane. At the same time, it decelerates until it arrives at a full stop.

At the initialization phase, the environment conditions are set. The Ego vehicle is instantiated at a constant velocity of 80 km/h on the rightmost lane of the road. 300 m ahead of the Ego vehicle, a vehicle is instantiated in the same lane at a velocity of 70 km/h. 1000 m ahead of the Ego vehicle, a third vehicle is instantiated in the same lane as the other two vehicles. This vehicle is stationary (velocity 0 km/h). It is accompanied by a fourth vehicle, which is situated two lanes left and 1000 m ahead of the Ego vehicle.

At simulation runtime, the vehicle driving in front of the Ego vehicle at a velocity of 70 km/h performs a lane change to the left as soon as it approaches the stationary vehicle in the same lane by 55 m. In parallel to the lane change, it decreases its speed linearly by 10 m/s2 until it arrives at a full stop.

This scenario teaches the instantiation of instances of Entity. Moreover parameters are introduced by a ParameterDeclaration and parallel actions are used.

examples 4 end of traffic jam neighboring lane occupied
Figure 50. Neighboring lane occupied scenario example

8.5. Double lane changer

This example, which is shown in Figure 51, describes a traffic situation where the Ego vehicle is driving at the rightmost lane of a three-lane motorway behind another vehicle at the same speed, leaving a gap. A faster vehicle approaches the Ego vehicle from behind on the centermost lane. This vehicle changes lanes into the gap on the rightmost lane after it has passed the Ego vehicle. In order to avoid collision with the vehicle driving ahead of the Ego vehicle, it immediately changes back to the center lane.

At the initialization phase, the Ego vehicle is initialized at the rightmost lane at a speed of 130 km/h. A second vehicle is initialized 13 m behind the Ego vehicle at the centermost lane driving at a speed of 170 km/h. A third vehicle is initialized 70 m ahead of the Ego vehicle on the rightmost lane driving at 130 km/h.

At simulation runtime, when the fast vehicle on the centermost lane has passed the Ego vehicle by 5 m, it performs a sinusoidal lane change to the rightmost lane. When this action is completed, the vehicle immediately changes back to the centermost lane, using another sinusoidal lane change.

This scenario teaches the instantiation of instances of Entity using Cartesian coordinates, use of conditions and consecutive execution of LaneChangeAction.

examples 5 double lane change
Figure 51. Double lane changer scenario example

8.6. Fast overtake with re-initialization

This example, which is shown in Figure 52, describes a traffic situation where the Ego vehicle approaches a truck that slows down on the right lane of a three-lane highway. An overtaking vehicle is initialized in the centermost lane when the truck performs this action.

At the initialization phase, the Ego vehicle is initialized at a velocity of 130 km/h on the rightmost lane. A truck driving at a velocity of 90 km/h is initialized 120 m ahead of it in the same lane. The overtaking vehicle is initialized at an arbitrary position and orientation.

At simulation runtime, when the Ego vehicle approaches the truck by 60 m, the latter linearly reduces its velocity to 60 km/h. This action triggers the relocation of the overtaking vehicle to the centermost lane at a velocity of 200km/h at 200m behind of the truck. This action is delayed by 2 s.

This scenario teaches the consecutive execution of instances of Act and Action.

examples 7 fast overtake with reinit
Figure 52. Fast overtake with re-initialization scenario example

8.7. Overtaking

This example, which is shown in Figure 53, describes a traffic situation where the Ego vehicle is approached by a faster vehicle driving on the rightmost lane of a three-lane motorway.

At the initialization phase, the Ego vehicle is initialized at the rightmost lane driving at a velocity of 130 km/h. The other vehicle is initialized 79 m behind of the Ego vehicle driving in the same lane at a velocity of 150 km/h.

At simulation runtime, when the faster vehicle approaches the Ego vehicle by 30 m, it performs a sinusoidal lane change to the left. As soon as the vehicle is 5 m ahead of the Ego vehicle, it changes its lane back to the rightmost lane.

This scenario teaches the use of conditions and the consecutive execution of instances of LaneChangeAction.

examples 9 overtaker
Figure 53. Overtaker scenario example

8.8. Traffic jam

This example, which is shown in Figure 54, describes a traffic situation where the Ego vehicle approaches a traffic jam of six other vehicles on a three-lane motorway.

At the initialization phase, the Ego vehicle is initialized at a velocity of 130 km/h at the leftmost lane. The vehicles forming the traffic jam are initialized 145 m ahead of the Ego vehicle at a velocity of 0 km/h. Pairs of vehicles block all three lanes of the motorway. Each of the pairs features a longitudinal gap of 8 m between its two corresponding vehicles.

This scenario teaches the instantiation of instances of Entity using Cartesian coordinates.

examples 10 traffic jam
Figure 54. Traffic jam scenario example

8.9. Synchronized arrival at intersection

This example, which is shown in Figure 55 recreates a critical situation at an intersection where the Ego vehicle and another vehicle are in a collision course. The Ego vehicle is instantiated with an initial speed of 10m/s and is assigned a route guiding it straight through an intersection (south to north). A second vehicle is instantiated with no speed and a route that guides it straight through the same intersection (west to east).

The moment at which the distance between the vehicles becomes smaller than 70m, a SynchronizeAction is triggered. At this stage, the crossing vehicle is regulating its speed in order to reach its synchronization position, at the same time as the Ego vehicle reaches its synchronization position. Additionally, the crossing vehicle is constrained to reach its synchronization position with a final speed of 7m/s.

When the vehicles reach their synchronization positions, the action is complete and vehicle A1 resumes default behavior driving through the intersection at 7m/s.

This scenario teaches the use of SynchronizeAction.

examples 11 synchronized arrival to intersection
Figure 55. Synchronized arrival at intersection scenario example

8.10. Close Vehicle Crossing

This scenario describes a critical traffic situation where the Ego vehicle approaches an intersection coinciding with two other vehicles crossing perpendicularly.

At the initialization phase, the Ego vehicle is spawned 110m west of the intersection with a speed of 23 km/h. The other vehicles are spawned 255m north of the intersection on a trajectory crossing the intersection at about 18 seconds.

At simulation runtime, the non ego vehicles follow the same trajectory crossing the intersection, coinciding with the Ego vehicle.

This scenario teaches the use of TrajectoryCatalog, TrajectoryPositions and FollowTrajectoryActions with initialDistanceOffset.

examples 12 close vehicle crossing
Figure 56. Critical close vehicle crossing scenario example

Terms and definitions

For the purposes of this ASAM standard, the following terms and definitions apply (in alphabetical order). These are consistent with [13].

OpenSCENARIO language elements (indicated using monospaced font) are defined within the body of this document, and their complete semantics are given in the Reference Guide ( [14]). Therefore they do not appear in this table.
Term Definition

Ego vehicle

The vehicle(s) that is(are) the focus of a scenario, meaning the vehicle(s) under test. For evaluation of automated driving systems, the Ego vehicle is the vehicle controlled by the system-under-test. For human driver experiments, the Ego vehicle is the vehicle driven by the human driver. There may be zero, one, or multiple _Ego vehicle_s within a scenario.

Parameterization

The use of parameters, which are symbols that may be replaced by concrete values at a later stage according to either user needs or stochastic selection.

World

Everything that falls within the spatial extent of a scenario and therefore may form a part of the scenario description.

Abbreviations

Abbreviated term Written-out term

3D

Three-dimensional

ASAM

Association for Standardization of Automation and Measuring systems

CET

Central European Time

CRG

Curved Regular Grid

OSC

OpenSCENARIO

HTML

Hypertext Markup Language

SI

Systéme international (d' unités)

UML

Unified Modeling Language

XML

Extensible Markup Language

XSLT

Extensible Stylesheet Language Transformation

Bibliography

[1] OpenDRIVE. ASAM e.V., 2020.

[2] OpenCRG. ASAM e.V., 2020.

[3] W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes. World Wide Web Consortium, 2012.

[4] ISO 8601:2019 Data elements and interchange formats — Information interchange — Representation of dates and times. International Organization for Standardization, Geneva, Switzerland., 2004-12.

[5] ISO8855:2011 Road vehicles — Vehicle dynamics and road-holding ability — Vocabulary. International Organization for Standardization, Geneva, Switzerland., 2011-12.

[6] Navigation Data Standard. Navigation Data Standard (NDS) e.V., 2012.

[7] City Geography Markup Language. Special Interest Group 3D, 2008.

[8] OpenSceneGraph. 2020.

[9] Graphics Language Transmission Format. Khronos Group, 2017.

[10] FBX Filmbox. Autodesk, 2008.

[11] 3ds Max. Autodesk, 2019.

[12] IEEE Standard for Floating-Point Arithmetic. International Organization for Standardization, Geneva, Switzerland, 2019.

[13] DIN SAE SPEC 91381 Terms and Definitions Related to Testing of Automated Vehicle Technologies. 2019-06.

[14] OpenSCENARIO Model Reference. ASAM e.V., 2020.

List of figures

Figure 1

OpenSCENARIO base architecture

Figure 2

Actions and conditions

Figure 3

Abstract OpenSCENARIO architecture

Figure 4

Heading, pitch, and roll angle in an ISO 8855:2011 compliant coordinate system

Figure 5

Road-based s/t-coordinate system with origin at the beginning of the road

Figure 6

Vehicle coordinate system

Figure 7

Parts are not shown in road visualizations

Figure 8

Euclidean distance dAB between two points A/B

Figure 9

Longitudinal entity distance dXAB and lateral entity distance dYAB between point A and point B in entity referentials

Figure 10

Longitudinal road distance dsAB and lateral road distance dtAB between point A and point B in road referentials

Figure 11

Distances between a point P and an entity E, with freespace = false

Figure 12

Distances between an entity E and an entity F, with freespace = false.

Figure 13

Distances between a point P and an entity E, with freespace = true.

Figure 14

Distances between an entity E and an entity F, with freespace = true.

Figure 15

Route passing the same road section twice

Figure 16

A route consisting of roads with a continuous reference line and PositionInRoardCoordinates

Figure 17

Entity is not at the start of the trajectory

Figure 18

Entity is at an ambiguous point near the trajectory

Figure 19

Trajectory position example

Figure 20

Diagram showing the structure of a storyboard

Figure 21

The entity class hierarchy

Figure 22

model3d behavior depending on simulator support

Figure 23

Relations between entity, controller, privateAction, and control strategy

Figure 24

SynchronizeAction example inducing an interceptor situation

Figure 25

Example of SynchronizeAction combined with routing

Figure 26

SynchronizeAction constellation example

Figure 27

Swarm definition

Figure 28

Evaluation of a speed condition with a greaterThan rule, for all possible edge values

Figure 29

Petrinet model shows the parallel execution pattern with three nested elements

Figure 30

Petrinet model that shows the loop execution pattern with three executions per element

Figure 31

Petrinet model that shows a general loop execution pattern

Figure 32

Petrinet model that shows a bulk execution of an action

Figure 33

State diagram for an action

Figure 34

State diagram for an event

Figure 35

State diagram for a maneuver

Figure 36

State diagram for a ManeuverGroup

Figure 37

State diagram for an act

Figure 38

State diagram for a story

Figure 39

State diagram for a storyboard

Figure 40

State machine evolution for instantaneous Actions during the init phase

Figure 41

State machine evolution for non-instantaneous actions during the init phase

Figure 42

Initial positions of vehicles (Vehicle is shortened to v in this graphic)

Figure 43

Traffic signal example for Phase_1 and Phase_2

Figure 44

Traffic signal example for Phase_3 and Phase_4

Figure 45

Traffic signal example for Phase_5 and Phase_6

Figure 46

Traffic signal example for Phase_2a, Phase_4a, and Phase_6a

Figure 47

Cut-in scenario example

Figure 48

Slow preceding scenario example

Figure 49

End of traffic jam scenario example

Figure 50

Neighboring lane occupied scenario example

Figure 51

Double lane changer scenario example

Figure 52

Fast overtake with re-initialization scenario example

Figure 53

Overtaker scenario example

Figure 54

Traffic jam scenario example

Figure 55

Synchronized arrival at intersection scenario example

Figure 56

Critical close vehicle crossing scenario example

List of tables

Table 1

What is not part of OpenSCENARIO

Table 2

Units

Table 3

Date and time format specifiers

Table 4

Rules for using modal verbs

Table 5

Typographical conventions

Table 6

Revision history of OpenSCENARIO

Table 7

Action table: private actions

Table 8

Action table: global actions

Table 9

Action table: user defined actions

Table 10

Constraints on entity references

Table 11

Constraints on actions context

Appendix A: Action tables

Table 7. Action table: private actions
Action Settings (time, space, domain) Goal Assigns longitudinal control strategy Assigns lateral control strategy Action Ends

LongitudinalAction. SpeedAction

target is "absolute" or "relative" with continuous = "false"

reach a longitudinal speed

Yes

No

on reaching the speed

LongitudinalAction. SpeedAction

target is "relative" with continuous = "true"

reach and keep a relative longitudinal speed

Yes

No

no regular ending

LongitudinalAction. LongitudinalDistanceAction

continuous = "false"

reach a longitudinal distance to another object

Yes

No

by reaching the targeted distance

LongitudinalAction. LongitudinalDistanceAction

continuous = "true"

reach and keep a longitudinal distance to another object

Yes

No

no regular ending

LateralAction. LaneChangeAction

not applicable

reach a lane

No

Yes

by reaching the lane

LateralAction. LaneOffsetAction

continuous = "false"

reach a lane offset

No

Yes

by reaching the targeted lane offset

LateralAction. LaneOffsetAction

continuous = "true"

reach and keep a lane offset

No

Yes

no regular ending

LateralAction. LateralDistanceAction

continuous = "false"

reach a lateral distance

No

Yes

by reaching the targeted lateral distance

LateralAction. LateralDistanceAction

continuous = "true"

reach and keep a lateral distance

No

Yes

no regular ending

VisibilityAction

not applicable

change an objects visibility

No

No

immediately

SynchronizeAction

not applicable

reach a destination with timing constraints

Yes

No

controlled vehicle reaching the target point

ActivateControllerAction

not applicable

activate or deactivate controller

No

No

immediately

ControllerAction. AssignControllerAction

not applicable

assign a controller model (e.g. driver model) to a vehicle

No

No

immediately

ControllerAction. OverrideControllerValueAction. [throttle;brake;clutch;parkingBrake;gear]

active = “true”

override longitudinal controls

Yes

No

immediately

ControllerAction. OverrideControllerValueAction. [throttle;brake;clutch;parkingBrake;gear]

active = “false”

deactivate overriding longitudinal controls

No

No

immediately

ControllerAction. OverrideControllerValueAction. SteeringWheel

active = “true”

override lateral controls

No

Yes

immediately

ControllerAction. OverrideControllerValueAction. SteeringWheel

active = “false”

override lateral controls

No

No

immediately

TeleportAction

not applicable

instant change an objects position

No

No

immediately

RoutingAction. AssignRouteAction

not applicable

use a specific route as routing target

No

No

immediately

RoutingAction. FollowTrajectoryAction

TimeReference = timing; TrajectoryFollowingMode = position

use a specific trajectory and move the actor along that trajectory without any controller behavior

Yes

Yes

by reaching the end of the trajectory

RoutingAction. FollowTrajectoryAction

TimeReference = none; TrajectoryFollowingMode = position

use a specific trajectory and move the actor along that trajectory with the current longitudinal control (e.g. speed keeping); time information contained in the trajectory is ignored

No

Yes

by reaching the end of the trajectory

RoutingAction. FollowTrajectoryAction

TimeReference = none; TrajectoryFollowingMode = follow

use a specific trajectory as steering input for a controller; time information contained in the trajectory is ignored

No

Yes

by reaching the end of the trajectory

RoutingAction. FollowTrajectoryAction

TimeReference = timing; TrajectoryFollowingMode = follow

use a specific trajectory as steering and timing input for a controller

Yes

Yes

by reaching the end of the trajectory

RoutingAction. AcquirePositionAction

not applicable

use the specified position as routing target; i.e. a route with two waypoints is created: current position as first and specified position as last waypoint

No

No

immediately

CustomCommandAction

not applicable

activate a custom action native to the specific user environment

unspecified

unspecified

immediately

Table 8. Action table: global actions
Action Settings Goal Action Ends

EnvironmentAction

not applicable

set weather, road conditions and time of the day

immediately

EntityAction.AddEntityAction

not applicable

 add an entity to the scenario, at a predefined position

immediately

EntityAction.DeleteEntityAction

not applicable

delete an entity at runtime from the simulation

immediately

ParameterAction.ParameterSetAction

not applicable

set a parameter to a given value

immediately

ParameterAction.ParameterModifyAction

not applicable

modify a global parameter according to given rules

immediately

InfrastructureAction.TrafficSignalAction.TrafficSignalControllerAction

not applicable

set a specific phase of a traffic signal controller, typically affecting a collection of signals 

immediately

InfrastructureAction.TrafficSignalAction.TrafficSignalStateAction

not applicable

control the state of a traffic signal

immediately

TrafficAction.TrafficSourceAction

not applicable

define a source of traffic at a specific position

immediately

TrafficAction.TrafficSinkAction

not applicable

define a sink of traffic at a specific position

immediately

TrafficAction.TrafficSwarmAction

not applicable

define swarm traffic within an elliptical planview around a given central entity

immediately

Table 9. Action table: user defined actions
Action Settings Goal Action Ends

CustomCommandAction

not applicable

activate a custom action native to the specific user environment

immediately

Appendix B: Entity type constraints

Table 10. Constraints on entity references

Reference attribute (Class.attribute)

EntitySelection allowed

MiscObject and ExternalObjectReference allowed

CentralSwarmObject.entityRef

No

Yes

LateralDistanceAction.entityRef

No

Yes

LongitudinalDistanceAction.entityRef

No

Yes

PositionOfCurrentEntity.entityRef

No

Yes

RelativeLanePosition.entityRef

No

Yes

RelativeObjectPosition.entityRef

No

Yes

RelativeRoadPosition.entityRef

No

Yes

RelativeTargetLane.entityRef

No

Yes

RelativeTargetLaneOffset.entityRef

No

Yes

RelativeTargetSpeed.entityRef

No

Yes

RelativeWorldPosition.entityRef

No

Yes

SynchronizeAction.masterEntityRef

No

No

CollisionCondition.entityRef

No

Yes

RelativeSpeedCondition.entityRef

No

Yes

RelativeDistanceCondition.entityRef

No

Yes

TimeHeadwayCondition.entityRef

No

Yes

TimeToCollisionConditionTarget.entityRef

No

Yes

ByEntityCondition.triggeringEntities

Yes

Yes

EntityAction.entityRef

Yes

Yes

Private.entityRef

Yes

Yes

Table 11. Constraints on actions context

Action

Context

Constraint

ActivateControllerAction

AssignControllerAction

AssignRouteAction

LateralDistanceAction

LaneChangeAction

LaneOffsetAction

LongitudinalDistanceAction

SpeedAction

SynchronizeAction

ManeuverGroup.actors/ Private.entityRef

If a single ScenarioObject, it may be either of vehicle type or a pedestrian type. If an EntitySelection, it may consist of either a group of only vehicle instances or a group of only pedestrian instances.

OverrideControllerValueAction

ManeuverGroup.actors/ Private.entityRef

Only vehicle type allowed for either a single ScenarioObject or an EntitySelection.

TeleportAction

ManeuverGroup.actors/ Private.entityRef

No ExternalObjectReference.

VisibilityAction

ManeuverGroup.actors/ Private.entityRef

No restrictions.