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 the 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 driver assistance functions, automated and autonomous driving. The standard may be used in conjunction with ASAM OpenDRIVE and ASAM OpenCRG, which describe static content in driving simulation.

After the standard was developed over several years in an industry consortium, it was transferred to ASAM e.V. in November 2018.

The standards' html documentation is accompanied by the more comprehensible User Guide. The specification is based on a UML data model from which XML schema files are derived. Thus, the standard comprises the following content:

  • User Guide

  • UML model

  • Model documentation (html)

  • XML schema files

  • List of analyzed deficits and proposed improvements

  • Examples

1. Introduction

1.1. Overview

1.1.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 the road layout and furniture, and world-changing (dynamic) elements such as weather and lighting, vehicles, objects, people or traffic light states. This description is irrespective of whether the environment is simulative, real or any combination thereof.

1.1.2. What is OpenSCENARIO?

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

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 instances of Entity, like Vehicles, Pedestrians and other traffic participants. The description of a scenario may be based on driver Actions (e.g. performing a lane change) or on instances of Trajectory (e.g. 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, i.e. usage of a Storyboard, Story instances, Acts, ManeuverGroups and Maneuvers

  • Usage of Events triggered by Triggers, defined by Conditions. Events cause Actions executions

  • References to logical road network descriptions

  • Instantiation of instances of Entity, such as Vehicles, or Pedestrians, acting on and off the road

  • Utilization of re-use mechanisms (i.e. Catalogs and ParameterDeclaration)

Other content, such as the description of the Ego Vehicle, driver appearance, Pedestrians, traffic and environment conditions, is included in the standard as well.

The data for scenario descriptions in OpenSCENARIO is organized in a hierarchical structure and serialized in an XML file format.

The standard is based on an UML data model which is used to derive XML schema files for XML file validation. Moreover, the standard is comprised of a reference guide and this user guide.

The standard can be used together with road network descriptions defined according to the standard ASAM OpenDRIVE . The three standards complement each other in a way that they describe the entire content required to describe the virtual world for driving simulation, virtual test, development and validation.

1.2. Motivation

Scenario descriptions are essential for testing, validating and certifying the safety of driver assistance systems and autonomous driving cars. The industry, certification agencies and government authorities jointly work on the definition of scenario libraries, which 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.

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 amount of driven test kilometers in field tests can be significantly reduced.

1.3. Scope

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

OpenSCENARIO describes the dynamic content, including the overall description and coordination of behavior of dynamic entities.

OpenSCENARIO does not specify the behavior models themselves, nor their handling by the simulation engine, including initialization and setup, runtime interfaces, packaging, etc.

OpenSCENARIO also does not define the road network or any geometric, visual or physical assets and characteristics used in a simulation. These are instead employed through references to other established formats. Hence, in certain contexts, OpenSCENARIO can be considered as a top-level container. It references other specifications for other relevant parts of the overall scenario.

Beyond the pure scenario itself, many other pieces of information are needed to describe a full simulation setup and test case. OpenSCENARIO should 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 the OpenSCENARIO standard:

Test configuration description

The standard neither describes the actual test instance nor its structure.

System under test

The exact description of the system under test, e.g. detailed vehicle configuration, sensor placement, sensor models etc. is not part of OpenSCENARIO.

Test case language

Although including a set of driver input, the standard does not attempt to specify all possible user or system interactions with a vehicle.

Test evaluation

Even though the standard includes the evaluation of conditions for triggering actions, there is no concept for creating test verdicts.

Driver model

The standard includes the physiological description of a driver such as height and weight. However, except for basic road following, the standard does not include behavioral driver models.

Vehicle dynamics

Although the standard describes maneuvers in a kinematic way, it also defines a very basic vehicle model, which can be used for more realistic vehicle dynamics simulation. The standard does not include all necessary elements to specify advanced motion dynamics.

Road network

The standard does not include elements to describe roads, other than references to an external road network description. The OpenDRIVE standard can be used for this purpose .

3D environment models

The standard only specifies how to refer to external 3D environment models. Further details, like file format or model structure, are not specified.

Environmental models

The standard incorporates elements to specify the current time and weather information but does not describe how this is to be interpreted by the simulator.

OpenSCENARIO hence focuses on information relevant to the dynamic scenario components, such as the sequence of Actions the instances of Entity would be performing. However, most of these Actions also depend on the static components that define the environment in which these Actions take place (e.g. a lane change Action may happen in a straight or a curved road, while a highway exit scenario could only be realized when the Actors are close to an actual highway exit). Therefore, OpenSCENARIO files contain references that bind the scripted dynamic movements to static environments.

2. Relations to Other Standards

2.1. Backward Compatibility to Earlier Releases and Migration

Standard version 1.0.0 and the predecessor version 0.9.1 differ in terms of semantics, naming and even structure. As consequence, the model version 1.0.0 cannot provide backward compatibility to version 0.9.1.

Instead, OpenSCENARIO provides an XSLT migration script to transform valid files of the earlier version 0.9.1 into valid OpenSCENARIO 1.0.0 files. Within this script, each element of the 0.9.1 version has a template that transforms and reshapes the element to OpenSCENARIO 1.0.0.

2.1.1. Migration Issues

The following issues may arise when migrating between versions 0.9.1 and 1.0.0:

  • Renaming of types and properties.

  • Adding required properties and assign a default value to them

  • Adding required properties even though there is no way to define default values for the new property

  • Removing classes (de-supporting classes like traffic jam)

  • Structural change (moving branches in combination with renaming types, or consolidate different branches into a single branch)

  • Migrating from an unknown or unclear semantic in Version 0.9.1

Any of these specific issues are addressed in the documentation and in the XSLT-transformation script:

Table 1. HTML class documentation migration content
Documentation Content

Forward

There is a mapping for each type declared in version 0.9.1 which enables tracking of what happened with that branch in version 1.0.0.

Backward

For each class in version 1.0.0, there is migration information that enables back tracking to the version 0.9.1.

2.1.2. Migration Execution

Any migration issue is addressed in the XSLT-transformation script. In rare cases, the migration cannot create a valid or a consistent document. If an invalid document is created, an error prompts/informs the user, that a manual check is necessary. If an inconsistent document is created, a warning will be shown to the user.

WARNING: Review catalogs since driver catalog and pedestrian catalogs are merged into controller catalog.

The original 0.9.1 description of a traffic source does not require a name property. Migration adds a name property that must be reviewed by the user.

ERROR: OSCTrafficDefinition.DriverDistribution.Driver cannot be migrated automatically and will result in invalid XML output.

The original 0.9.1 description of a driver distribution was semantically unclear. It cannot be consistently migrated to version 1.0.0.

2.1.3. Migration Prerequisites

As a core task, migration should transform a document that is validated by the schema 0.9.1 into a valid XML document that validates against the schema 1.0.0.

As a minimum prerequisite, a 0.9.1 scenario description must validate against the 0.9.1 schema. Further, the 0.9.1 description must be semantically valid in respect to valid links (e.g. to catalogs, defined parameters etc.). Migration neither checks the semantic validity for the ingoing 0.9.1 description, nor the semantic validity of the resulting 1.0.0 description.

2.2. References to Other Standards

2.2.1. OpenDRIVE

In order to use semantic road network information within a scenario, the road network description OpenDRIVE [1] can be referenced. This also includes road surface profiles, as referenced by OpenCRG [2].

3. Concepts

There are three mandatory concepts within every scenario. First, the fundamental concept of a scenario is that a RoadNetwork (the static driving infrastructure, including TrafficSignals) is populated by instances of Entity (e.g. road users, including Vehicles and Pedestrians), which interact according to a set of instructions defined in the Storyboard. Only in rare cases, no RoadNetwork description is referenced in a scenario. In this case, instances of Entity can only be positioned, moved and located using Cartesian coordinates and many Actions defined by OpenSCENARIO can only be used with restrictions.

Second, the scenario’s Storyboard contains at least one, but possibly multiple instances of Story. The elements of a Story are placed within a specific structure (as detailed in Section 3.2.1):

  • Story

  • Act

  • ManeuverGroup

  • Maneuver

  • Event

  • Action

Third, the Actions that Actors (instances of Entity which are involved in actions) ultimately take are triggered by Conditions. More generally, Conditions are used in Triggers to start Acts and Events or to stop Acts and the Storyboard. In this sense, Conditions are basic building blocks to define dynamic behavior and interactions.

There are two additional concepts, which are intended to make scenarios easy to re-use for different use cases. Catalogs are collections of OpenSCENARIO elements. Multiple scenarios can refer to the elements defined within a Catalog, thus precluding the need to define the same element multiple times. Additionally, a ParameterDeclaration provides the means to define parameters symbolically within a scenario or Catalog.

3.1. General Concepts

3.1.1. Units

All numeric values within this standard are using SI units (see Table 2), 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

For the definition of date and time the ISO 8601 [3] Basic Notation shall be used. 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 will be produced:

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

3.1.2. Naming

Elements in scenario descriptions can 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 governs the lookup of names from a reference:

Name lookup proceeds from the referencing element, but encompasses all elements at all hierarchy levels of the scenario hierarchy.

Element names at each level must be unique at that level, i.e. there cannot be more than one element with the same name at the same level (i.e. within the same directly enclosing element). For example, within one Story, every Act must use a unique name ("MyStory1": "MyAct1", "MyAct2"…​), but the names of the Acts might be reused in another Story ("MyStory2": "MyAct1", "MyAct2"…​).

If the referenced name is globally unique, then it can be used directly as the only part of the reference.

If the referenced name is not globally unique, then enough name prefixes must be supplied to make the name unique.

A name prefix consists of the name of a directly enclosing element, which is prepended to the name using the separator '::', thus forming a new name reference. This implies that the '::' must not be used in names itself. It disambiguates the name by specifying a directly enclosing element name, thus only selecting names found within elements of the given prefix name.

Multiple prefixes of ever higher enclosing element names, up to, in extreme cases, the root element name, can and must be specified 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 to disambiguate fully, the result of the lookup is undefined.

3.1.3. Road Networks and Environment Models

In order to be able to properly describe the behavior of road users, OpenSCENARIO requires a reference to the description of the road network logic. Optionally, a geometric and visual representation of the environment in the form of 3D models may be referenced. 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 will often need to refer to items defined in the road network (e.g. 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 to using 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

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

In addition to the road network description, 3D models representing the environment may be referenced in a scenario description. Essentially, files containing 3D models provide the geometric and visual representation (e.g. mesh and textures) for elements of the virtual environment including the road surface. Use-cases of 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 these is described in Section 3.4.2

3.1.4. Controllers

Controllers can be assigned to ScenarioObjects of type Vehicle or Pedestrian. Once assigned, Controllers are activated for a given domain (i.e. longitudinal or lateral) using the ActivateControllerAction ([Private action]).

While the ActivateControllerAction is executing, the Controller assigned to that ScenarioObject will manage that domain. Controllers may be internal (part of the simulator) or external (defined in another file). Intended use cases for Controllers include:

  • Specifying that a vehicle should be controlled by the system under test

  • Defining "smart actor" behavior, where a Controller will take intelligent decisions in response to the road network and/or other vehicles. 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

The Controller element contains Properties, which can be used to specify Controller behavior either directly or by a File reference.

3.1.5. Routes

Routes are used to navigate instances of Entity through the road network based on a list of Waypoints on the road which are linked in order, resulting in directional Routes. An Entity's movement between the Waypoints is left to the simulator using 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 latter of the pair will be used. Note that 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.

Routes may be assigned to Actors using AcquirePositionAction or AssignRouteAction. Once assigned, they remain in place until another Route overwrites them.

If an Entity is on a route, it will normally continue 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 will not be followed if the corresponding Entity is in the wrong lane or conflicting lateral behavior is defined (e.g. an Action involving a Trajectory). In these cases, the route will be ignored.

An Actor is still considered "on the route" if it is on a road section which 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 will be selected at random from the available options.

Some additional rules apply to Routes which pass over the same section of road more than once (see example in Figure 1). The Route in the example consists of four Waypoints (shown in boxes) which are linked in order. The part of the route highlighted in red is visited 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 are applied:

  • Where an Entity is on a road which belongs to more than one link between Waypoints, it should be treated as being on the earliest link which has not already been followed.

    • If an Entity joins the Route just before Waypoint 2, it will be treated as being on the link between Waypoint 1 and Waypoint 2 (and not between 3 and 4).

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

    • If an Entity joins the Route just after Waypoint 3, it will go towards Waypoint 4 then 5.

  • When an Entity leaves then rejoins a Route, or reaches the final Waypoint, any previously visited Waypoints should be ignored.

    • If an Entity is teleported to Waypoint 1 after reaching Waypoint 4, it will follow the Route as if for the first time.

    image
    Figure 1. Route passing over the same section of road twice

3.1.6. Trajectories

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

  • Polyline (a concatenation of simple line segments across a set of vertices)

  • Clothoid (Euler spiral, i.e. a curve with linearly increasing curvature)

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

By using Nurbs, most relevant paths can 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 trivially mapped to corresponding Nurbs curves. Since Nurbs curves directly support the expression of conic sections (such as circles and ellipses), approximation of e.g. Clothoids using arc spline approaches is feasible.

Another advantage of Nurbs curves is the relative ease with which continuity up to a given derivative can be assured: A Nurbs curve of degree k (i.e. order k+1), is infinitely continuously differentiable in the interior of each knot span and k-M-1 times continuously differentiable at a knot, where M is the multiplicity of the knot, i.e. 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, with higher order curves usually only needed to ensure continuity in higher derivatives. Since the effort to evaluate curves increases with higher orders, restricting instances of Trajectory to lower orders is recommended, where possible.

Instances of Trajectory can be specified using just the three positional dimensions (along the X, Y, and Z axes, see section Section 3.1.7 for coordinate system definitions). Alternatively, instances of Trajectory can 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.

Additionally, an instance of Trajectory can be specified with or without a time dimension, allowing for the combined or separate specification of the Entity's longitudinal domain: A Trajectory incorporating the time dimension completely specifies the motion of the entity, including its speed, whereas a trajectory without the time dimension does not specify the speed along the path, hence allowing separate control of the speed.

Whilst a Trajectory provides a mathematically precise definition of a motion path, the corresponding Entity's behavior is dependent on the Actions employing it. Either an Entity will follow this path exactly or use it as guidance for the controller to follow as best as the Entity's rules of motion allow.

Trajectory actions are further described in Section 3.2.2.1.

3.1.7. Coordinate Systems

Following ISO 8855:2011 [4] 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 ISO 8855:2011 definition. Orientation is expressed by a heading(yaw)-pitch-roll sequence of rotations (see Figure 2)

    image
    Figure 2. 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 3)

    image
    Figure 3. Road based s, t coordinate system with origin at the beginning of the road

The afore mentioned coordinate system types are referenced to create multiple coordinate systems listed in the upcoming subsections

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

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 starting node of the road. The origin of the t-coordinate is fixed to the road centerline at the current s-position.

Vehicle Coordinate System (Xv, Yv, Zv)

The vehicle axis system of type (X, Y, Z), as defined in ISO 8855:2011, is fixed in the reference frame of the vehicle sprung mass, so that the Xv axis is substantially horizontal and forwards (with the vehicle at rest), and is parallel to the vehicle’s longitudinal plane of symmetry, and the Yv axis is perpendicular to the vehicle’s longitudinal plane of symmetry and points to left with Zv axis pointing 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. Nevertheless, the origin remains fixed to the vehicle sprung mass (see Figure 4).

image
Figure 4. Vehicle coordinate system. Xv – longitudinal direction, Yv –transverse direction, Zv – vertical direction
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 and perpendicular to X and points to the left with the Z axis pointing upward.

The origin for 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.

Positioning

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

  • Absolute/relative in the world coordinate system

  • Relative to another Entity

  • Absolute/relative in the road coordinate system

  • Absolute/relative in the lane coordinate system

  • Relative to a Route

3.1.8. Traffic Simulation

Besides the definition of deterministic behavior of instances of Entity, OpenSCENARIO also provides ways to define stochastic or not precisely defined behavior. This can be useful, e.g. to create traffic within a scenario or around defined instances of Entity increasing the overall realism of a scenario, inducing variance into the scenario sequence or defining parameters of the traffic, like traffic density. For this purpose, surrounding intelligent traffic agents can be defined using TrafficActions. With the help of TrafficActions, the parameterization of traffic sources, traffic sinks and traffic swarms can be specified.

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

3.2. Components of a Scenario

3.2.1. Storyboard

In OpenSCENARIO, the Storyboard encompasses the complete scenario description. The structure and naming of the Storyboard concept is similar to that of classical storytelling in narrative fiction e.g. in a theater play. The Storyboard provides the answers to the questions "who" is doing "what", and "when" in a scenario. It contains one initialization element (Init) followed by one or more Story elements.

Init is used to set the initial conditions for the scenario, such as the position and speed of instances of Entity. It is not possible to specify conditional behavior in this section.

Story allows scenario authors to group different aspects into a higher-level hierarchy and therefore provide a structure in large scenarios.

Instances of Story in OpenSCENARIO, as in narrative fiction, contain Acts that define conditional groups of Actions. Each Act should focus on answering the question "when" something happens in the timeline of a corresponding Story. Answer to that question is provided by the startTriggers and stopTriggers of an Act. If a startTrigger evaluates to true, then and only then the included ManeuverGroups are executed.

A ManeuverGroup is part of an Act and answers the question "who" is doing something in the scenario by assigning instances of Entity as Actors (see [Maneuver groups and Actors]) to Maneuvers. ManeuverGroups can also include Catalog references to reuse existing Maneuvers. This concept is described in Section 3.4.2.

Maneuvers define "what" is happening in a scenario. They are containers for Events that need to share a common scope, whereas Events control the simulated world or corresponding instances of Entity. This is achieved through triggering Actions, given user-defined Conditions.

The overarching hierarchy is called Storyboard. It contains all the elements introduced so far and is depicted in Figure 5.

image
Figure 5. Diagram showing the structure of a storyboard

3.2.2. Entities

In a scenario, instances of Entity are those objects that can - but do not have to - change their location dynamically over time. Instances of Entity which are not Vehicles or Pedestrians are called MiscObjects. This group comprises the following object classes (which are the same as in the OpenDRIVE format):

  • none

  • obstacle

  • pole

  • tree

  • vegetation

  • barrier

  • building

  • parkingSpace

  • patch

  • railing

  • trafficIsland

  • crosswalk

  • streetLamp

  • gantry

  • soundBarrier

  • wind

  • roadMark

Instances of Entity can be specified in the scenario format but the properties are specific to their type. For example, a Vehicle is an instance of Entity which provides properties like vehicleCategory and performance. In contrast, a Pedestrian is specified by properties like model, mass and name.

Actions can change the state of an Entity, e.g. its Position, speed, or Controller. On the other hand, the state of an Entity can be queried to trigger an Action.

Two main groups of instances of Entity are distinguished in OpenSCENARIO:

  • Entity describes one specific object

  • EntitySelections describes a list of instances of Entity

Motion Control for Entities

The motion of an Entity can be controlled via Actions, user assigned Controllers or a default Controller. It is assumed that each Entity has a default Controller which takes charge of a motion domain (lateral and/or longitudinal) when Actions or user assigned Controllers are lacking.

The default Controller is expected to maintain speed and lane offset of the Entity. In the following cases, the default Controller oversees an Entity's motion domain (lateral and/or longitudinal):

  • No Actions and no user assigned Controllers are running

  • Actions and/or user assigned Controllers are running and one motion domain, either lateral or longitudinal, is not addressed

3.2.3. Entity Selections

EntitySelections can be used to conveniently group instances of Entity present in the scenario. They can be referenced anywhere single instances of Entity can be used as well, allowing for the assignment of a new status to many instances of Entity at once or using their aggregated information as a Trigger.

EntitySelections can also be purposefully formed from any combination of objects within the scenario.

One use case of EntitySelections is to choose multiple instances of Entity to perform a certain Maneuver at the same time. The EntitySelection can be directly used as the name of the Actor in the ManeuverGroup. Then, a Maneuver can be created which is triggered e.g. at a certain SimulationTimeCondition.

3.3. ManeuverGroups, Maneuvers, Events and Actions

3.3.1. ManeuverGroups and Actors

A ManeuverGroup singles out the instances of Entity that can be actuated, or referenced to, by the Maneuvers inside it. These instances of Entity are grouped and referred to as the Actors in a ManeuverGroup, since they will play a role in the Maneuvers to come. The Actors group may be left empty. This can occur in situations where the Maneuvers in a ManeuverGroup lead to Actions that are not related to instances of Entity but instead to world or simulation states.

An Actor can be defined using the EntityRef element. This element is then combined in an unbounded list in order to specify Actors for a given ManeuverGroup. An Actors list may contain several instantiations of the type EntityRef. Additionally, extra instances of Entity may be added to the Actors, at triggering time, if the selectTriggeringEntities option is active.

The EntityRef element explicitly couples an existing Entity to an Actor in the ManeuverGroup. This is achieved by specifying the name of the desired Entity in the element. Usage of EntityRef is appropriate for situations where the instances of Entity of interest are known when the scenario is defined.

The selectTriggeringEntities property is used in situations where the choice of Actors depends on runtime information and is therefore impossible to know at the time the scenario is defined.

When the selectTriggeringEntities property of the Actors of the ManeuverGroup is true, all instances of Entity whose states are used by the logical expressions in Conditions which evaluate to true and are contained in ConditionGroups which evaluate to true, are added to the EntitySelection that forms the Actors.

It is possible to combine EntityRef with selectTriggeringEntities set to true. In this case, the resulting Actors are the Union of the two.

Finally, a ManeuverGroup is defined with a maximumExecutionCount. This setting specifies how many times the ManeuverGroup shall run, where the number of runs is incremented by one each time the endTransition occurs (see Section 3.7.2).

3.3.2. Actions

Actions serve to create or modify dynamic elements of a scenario, e.g. change in lateral dynamics of a vehicle or change of the time of day. Actions are divided in three categories:

  • PrivateActions

  • GlobalActions

  • UserDefinedActions

In the initialization phase of a scenario, Actions are responsible for setting up initial states of dynamic objects, environment, infrastructure, etc. In any later phase of the scenario Actions are executed when Events are triggered. In the following subchapters, the subtypes of Actions defined in OpenSCENARIO are briefly explained.

Private Action

PrivateActions have to be assigned to instances of Entity. With PrivateActions one can describe motion, position, and visibility of an Entity in the scenario. Moreover, they can define longitudinal or lateral dynamic behavior of instances of Entity, such as speed or lane change.

The following types of PrivateActions exist:

LongitudinalAction

Controlling speed or relative distance to a target. SpeedActions are defined e.g. by an acceleration profile (dynamicShape) while longitudinalDistanceActions are setup via actual distance or a headway time (e.g. using timeGap).

LateralAction

Using 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, relative target referencing works differently than absolute referencing. Here, the Vehicles' Xv-axis serves as reference direction. Lane changes are evaluated positive if they’re aligned with the vehicles' positive Yv -axis. Thus, a positive lane change moves the corresponding vehicle to the next actual lane in its positive Yv-axis direction. The road center line is not counted as a lane and thus not considered in this counting. Finally, with LateralDistanceAction, a lateral distance to an object can be targeted. For each of the LateralActions the lateral Dynamics can be restricted.

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. This is the speed which the controlled Entity shall have when reaching the destination. This FinalSpeed can be specified either as an absolute value or relative to the reference entity.

The SynchronizeAction shall terminate when any one of the following occurs:

  • At the moment 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 can’t reach its destination for whatever reason

SynchronizeAction 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 and/or additional Actions.

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

The example in Figure 6 shows how the SychronizeAction can be used to provoke an interception situation in an intersection. The dots indicate the respective destinations, which is also the point at which the SynchronizeAction ends.

The controlled Entity (c1, yellow) will arrive at its destination, indicated by a yellow dot, whenever the reference Entity (ego, blue) arrives at its destination, indicated by a blue dot. The SynchronizeAction will then terminate, and the synchronization will stop. The controlled Entity will move into the intersection according to default behavior or any other active Action, causing a dangerous situation for the reference Entity, who still have a chance to avoid collision.

image
Figure 6. SynchronizeAction example inducing an interceptor situation

Figure 7 shows a very similar scenario to the previous example, but illustrates that the SynchronizeAction also works when the controlled Entity performs lateral operations in parallel, e.g. following an assigned Route or performing lane changes.

image
Figure 7. Example of SynchronizeAction combined with routing

Figure 8 shows a vehicle boxed in, or surrounded, by other vehicles. The SynchronizeAction is useful to form constellations at specific locations on the road network, typically proceeding a critical event - for example lead vehicle brakes.

image
Figure 8. 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

Explicitly (de-)activating a Controller model. This may be done for longitudinal, lateral or both domains.

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 ControllerAction can be alternatively used to override control signals, e.g. apply the brakes.

TeleportAction

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

RoutingAction

Specifying 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 will aim to take the shortest travelled Route from the current position to the target position along the road network.

Global Action

Global Actions are used in order 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/modifying values of parameters.

InfrastructureAction

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

TrafficAction

Populating ambient traffic of the following kinds:

  • Creation of sources and sinks

    • A source will create vehicles, while a sink deletes vehicles. A source spawns new vehicles with the rate defined in the element. If no rate is given, a sink will delete all vehicles reaching its area of influence, but a rate can 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 blacklist, meaning that only vehicles matching this list will be removed while all other vehicles may pass unhindered. However, if no definition is given, it means that all vehicles reaching the sink will be removed.

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

    • Swarm traffic is set up in the area between inner radius and the outline of the ellipsis defined by the two semi axis attributes (blue area in the picture). The blue area will 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 will be spawned instead.

      image
      Figure 9. Swarm definition

Vehicles spawned by a TrafficSwarmAction can trigger Conditions just as other instances of Entity do. They may also perform Actions by being referred to through an entity Trigger, but since their names are determined by the simulation, no Actions can be modeled by referring to these instances of Entity explicitly.

Spawned vehicles will 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 will be used. All elements make use of a TrafficDefinition, where the distribution of the spawned or removed vehicles can be defined by VehicleCategoryDistribution. Which vehicles of that category are actually spawned is up to the simulation engine.

User Defined Action

Users can create their own Actions which can incorporate a command or a script file. With UserDefinedActions, a completely customized Action can be performed that is specific to the respective simulation environment.

Conflicting Actions

At runtime, it may occur that coexisting Actions end up competing for the same resource thus creating a conflict. A quintessential example is the case where an Action which controls an Entity's speed clashes with a newly triggered Action that tries to control the speed of the same Entity.

Where an Action acts on an EntitySelection, if 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 of 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 6 and Table 7 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 stopTrigger to that Action, see Section 3.5.2.

Action Completion Criteria

Actions are considered complete, i.e. they reach their completeState directly after they complete their stopTransitions or endTransitions.

Some Actions may not be able to reach the completeState via the endTransition (for details, see chapter 3.7). By definition, these Actions are assigned a task that requires constant monitoring or actuation, thus lacking end criteria. An example of such an Action is the SpeedAction when its TargetSpeed is set to continuous. The end criteria for Actions are depicted in Table 6 and Table 7.

An Action that cannot reach the completeState via the endTransition has an impact on its parents, preventing them from also reaching a completeState. Such continuous Actions can be terminated with a stopTrigger from the Act or StoryBoard they belong to. Alternatively, continuous Actions will also be terminated when overridden by conflicting Actions.

Acting on Entity Selections

PrivateActions may be requested to control more than one Entity at the time. This occurs when the Actors resolve to an EntitySelection, in a ManeuverGroup. In these circumstances, all concerned instances of Entity shall be actuated simultaneously when the action starts.

Actions acting on EntitySelections can only be considered complete if and only if all instances of Entity in the selection have completed the tasks specified in the Action. For example, a SpeedAction acting on five instances of Entity will only be complete once 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.

Given any running Action acting on an EntitySelection, 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 fallback to default behavior simultaneously. For example, SpeedAction A controls five instances of Entity when SpeedAction B starts, aiming to control one Entity in Action A. Since the Actions are of the same nature, a conflict occurs and Action A is overridden. Action B will then resume control of the conflicting Entity while the remaining instances of Entity of Action A engage in default behavior.

3.3.3. Events

Actions are singular elements which may need to be combined in order to create meaningful behavior in a scenario. This behavior is created by Events which serve as containers for Actions. Events also incorporate startTriggers. The latter not only determine when the Event starts. They are also used to start the contained Actions.

Actions always need to be wrapped by Events with only one exception: In the Init phase, Actions are declared individually.

The maximumExecutionCount setting specifies how many times an Event is supposed to run, where the number of runs is incremented by one each time the endTransition is reached.

An Event is also parameterized with a definition of priority relatively to Events that coexist in the same scope (Maneuver). Whenever an Event is started, the priority parameter is taken into consideration to determine what will happen to already ongoing Events in the same Maneuver. The three choices concerning the corresponding Priority are:

overwrite

All other Events in the scope are stopped and the Event starts.

skip

The Event does not leave the standbyState until other Events have finished.

parallel

The Event starts without taking into consideration already running Events.

Each Event defined in a scenario corresponds to a single runtime instantiation which implies that there cannot be multiple instantiations of the same Event running simultaneously. In turn, this means that startTriggers bear no meaning unless the Event is in a standbyState, as opposed to each startTrigger starting a new instantiation of the Event.

3.3.4. Maneuver

A Maneuver groups Events together. The definition of a Maneuver can be outsourced to a Catalog and parameterized for easy re-use in a variety of scenarios. Examples for Maneuvers are driving Maneuvers, such as a (double) lane change, or an overtaker. Nevertheless, generic combinations of Actions can be grouped to Maneuvers, e.g. to simulate a weather change.

3.4. Re-Use Mechanisms

3.4.1. Parameters

In OpenSCENARIO, parameters are central to provide an extension mechanism for scenarios. With the help of parameters, a scenario designer can make parameterization points of a scenario explicit. External tools can read the provided parameters and thus implement sophisticated methods to assign concrete values to the parameters. By this extension method a scenario can be reused for a large space of concrete values, e.g. the re-simulation of one scenario with different speeds.

In ParameterDeclaration all parameters which are used in a scenario, have to be defined. Each parameter is defined by its name, the parameterType and a default, type-specific initialization value. Parameters are declared within ParameterDeclaration by their individual names (without any prefix). Assignment of values to parameters declared in a Catalog is allowed in CatalogReferences. Parameters can be referenced from within the scenario, e.g. for obtaining their values. In this case, a "$" prefix is used to indicate the referencing.

Every attribute of an OpenSCENARIO language element can contain a parameter. 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 has to be implemented by the simulator.

parameters are set and evaluated at load time of the simulation. ParameterActions and ParameterConditions do 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, it is forbidden to use the OSC prefix.

In parameter names, usage of symbols is restricted. Symbols that must not be used are:

  • " " (blank space)

  • $

  • '

  • "

Special rules apply to referencing parameters within Catalogs (see section 3.4.3).

3.4.2. 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. Catalogs offer the possibility to outsource the description of certain elements from the scenario to a separate file, which can then be referenced from a scenario.

Using Catalogs 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 has to be specified in the scenario and at the location where the element is being used the reference of both the Catalog and the specific element has to be given.

There are eight different kinds of elements that can be outsourced to a Catalog. All kinds of objects can be defined within Catalogs, i.e. Vehicle, Pedestrian, and MiscObject, as well as their respective Controllers. Navigational instructions in the form of Trajectory and Route can also be stored within Catalogs. Additionally, descriptions of the Environment and Maneuvers can be outsourced this way.

3.4.3. Parameters in Catalogs

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

For example, a catalog definition could 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.

3.4.4. 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 could hand over ParameterAssignments to resolve parameters for this specific reference.

A Catalog must be defined in a catalog file (e.g. VehicleCatalog.osc). An instance of a Catalog is identified by its name property.

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

  • VehicleCatalogLocation

  • ControllerCatalogLocation

  • PedestrianCatalogLocation

  • MiscObjectCatalogLocation

  • EnvironmentCatalogLocation

  • ManeuverCatalogLocation

  • TrajectoryCatalogLocation

  • RouteCatalogLocation

3.5. 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 since the same set of Actions can lead to a multitude of different outcomes and it all hinges on how Actions are triggered in relation to one other. A Trigger in OpenSCENARIO is the outcome arising from a combination of Conditions and will always evaluate to either true or false.

In OpenSCENARIO a Condition is a logical expression that is assessed during run time and always evaluates to either true or false. A condition is a container for logical expressions and is assessed during runtime. The Condition operates on the current and previous evaluations of its logical expressions to produce a Boolean output which is used by triggers.

3.5.1. Associating Conditions

A single Condition may not suffice to represent a desired Trigger. In complicated scenarios, it may instead be required that the relation between a set of Conditions serve as a single Trigger.

A ConditionGroup is an association of Conditions that is assessed in run time and can be only evaluated to true if and only if all associated Conditions are true, otherwise it will evaluate to false. A ConditionGroup is thus a way to bundle any given number of Conditions into a single Trigger.

3.5.2. Triggers

To account for the fact that a desired Trigger will likely be represented by a relationship between several Conditions, the latter are never directly used as a Trigger in the format and are instead bundled in ConditionGroups.

A Trigger is then defined as an association of ConditionGroups. A Trigger evaluates to true if at least one of the associated ConditionGroups evaluates to true, otherwise it evaluates to false (OR operation).

Given the nature of individual ConditionGroups (AND between its Conditions) and associations of ConditionGroups (OR between its members), a Trigger embodies a comprehensive mapping of the relationship (AND, OR) between individual Conditions.

Triggers are used to start or stop ongoing scenario elements and are referred to as startTrigger and stopTrigger, respectively.

Start Trigger

A startTrigger is used to move a runtime instantiation of a Storyboard element from the standbyState to the runningState. Only Act and Event host startTriggers and any element that does not contain a startTrigger inherits the startTrigger from its parent element. For example, starting an Act also starts its ManeuverGroups and Maneuvers, but does not start the Events since they have their own startTriggers. Furthermore, no Events can start if they do not belong to an Act that is in the runningState.

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

Stop Trigger

A stopTrigger is used to force a runtime instantiation of a StoryboardElement to jump from its standbyState or runningState to the completeState. Only the Story and the Act elements host stopTriggers. Any StoryboardElement inherits the stopTrigger from its parent. This is true even if the StoryboardElement under consideration has its own stopTrigger. For example, if a Story is affected by a stopTrigger, so are all its Acts, even though they have their own stopTrigger.

When a stopTrigger is received, the concerned StoryboardElement is expected to move to the completeState (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.

Condition Type

The base condition type contains three basic elements: name, delay, and conditionEdge. Whereas the first element is self-explanatory, the others require clarification.

delay

This element refers to the amount of time that needs to elapse between meeting the Condition and reporting it as met. Regardless of other parameters that may be used to define the Condition, this element defines a pure delay on its output.

conditionEdge

This element can be used to introduce a dynamic component to the Condition verification, since the previous states of its logical expression now play a role in the Condition output (example see Figure 10).

A Condition with a rising edge returns true if its logical expression previously evaluated false but now evaluates true.

A Condition set with a falling edge returns true if its logical expression previously evaluated true but now evaluates false.

A Condition set with risingOrFalling edge will return true if either a rising or falling edge is verified.

Finally, a Condition set with none will return true if its logical expression is true, and false if its logical expression is false.

If the parameter risingEdge is set to rising, falling, or risingOrFalling, a Condition is not defined the first time it is checked since the previous evaluation of the logical expression is not defined. To address this, it is expected that all Conditions defined with rising, falling, or risingOrFalling, return false the first time they are checked by a simulation engine.

image
Figure 10. Illustration of edge dependent outputs of a speed Condition with a greaterThan rule

All other elements of a Condition will depend on its sub-type, of which there are two, ByEntityCondition and ByValueCondition.

ByEntityConditions

ByEntityConditions will use the states of instances of Entity to perform the conditional evaluation. The conditional evaluations may depend on the value of a single state, or how the value of any one given state relates to another state (within the Entity, between instances of Entity, and between the Entity and the corresponding characteristics of the RoadNetwork).

Entity conditions require the definition of TriggeringEntities whose states are used in the conditional evaluation. In case more than one triggering Entity is defined, the user is given two alternatives to determine when the Condition evaluates to true; either all TriggeringEntities verify the logical expression or at least one Entity verifies the logical expression.

ByValueConditions

ByValueConditions represent logical expressions that are dependent on values not directly related to instances of Entity. For example, these can be scenario states, times or traffic signal information.

ByValueConditions also provide a wrapper for external conditions that may depend on values which are not accessible from the scenario and are only available to the user implementation. Examples of these are button presses and custom signals or commands.

3.6. Properties

Instances of Property are means to allow for the definition of test-instance specific or use-case specific properties of OpenSCENARIO sub elements. They are available for the following types:

  • Vehicle

  • Pedestrian

  • MiscObject

  • Controller

  • RoadCondition

Instances of Property are collected in the Properties container. Every Properties definition can contain one or more name-value pairs (i.e. 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 might influence scenario execution (e.g. driver behavior) but scenarios still shall be executable without knowledge of their meaning.

3.7. States and Transitions of StoryboardElements

The progress of a runtime instantiation for a StoryboardElements is marked by its runtime state. Runtime states must be referred to by the OpenSCENARIO standard since they can be used to create Conditions and to determine how StoryboardElements interact with Triggers. The transitions between states are also of interest since it is possible to reach the same state from different starting points and it may be of importance to a scenario developer how a state is reached. Both states and transitions of StoryBoardElements are defined by StoryBoardElementState.

From the perspective of OpenSCENARIO, a StoryboardElement shall always be in one of three possible states: Standby, Running, and Complete (see Figure 11).

image
Figure 11. State Machine for a runtime instantiation of a StoryboardElement

3.7.1. States

Table 4. Storyboard states
State Description

StandBy (standbyState)

This is the default initialization state of a StoryboardElement. When it is in this state, the runtime instantiation of the StoryboardElement is ready to execute once given a startTrigger. A runtime instantiation of any StoryboardElement is created once its parent element is in the standbyState. From the standbyState, the Story element instantaneously transitions into the runningState.

Running (runningState)

The runningState symbolizes that the execution of the runtime instantiation is now ongoing and has not yet accomplished its goal.

The concept of accomplishing a goal varies depending on the type of StoryboardElement under consideration:

Action

An Action's goal is a function of the Action type and cannot be generalized. Accomplishing an Action's goal will involve meeting some arbitrary prerequisites related with the Action type (for example, a SpeedAction accomplishes its goal when the considered Entity is travelling at the prescribed speed). If an Action is acting on an EntitySelection, all instances of Entity within the selection have to complete in order to reach the completeState of the Action.

Event

An Event's goal is accomplished when all its Actions are in the completeState.

Maneuver

A Maneuver's goal is accomplished when all its Events are in the completeState.

ManeuverGroup

A ManeuverGroup's goal is accomplished when all its Maneuvers are in the completeState.

Act

An Act's goal is accomplished when all its ManeuverGroups are in the completeState.

Story

A Story's goal is accomplished when all its Acts are in the completeState.

Complete (completeState)

The completeState signals that the runtime instantiation of the StoryboardElement cannot reach a running state without external interference. If the affected runtime instantiation of the StoryboardElement is defined with a maximumExecutionCount, to be complete implies that there are no more executions left to run, or a stopTransition has occurred.

Checking for completeness involves verifying if the given runtime instantiation of the StoryboardElement still has executions left upon finishing the runningState. This check returns false if there are executions left. This check returns true if there are no executions left, or if the maximumExecutionCount is not defined in the StoryboardElement.

Resetting the completeState can only be achieved externally by the parent StoryboardElement whose child is in the completeState. This may only occur if the parent initiates a new execution.

3.7.2. Transitions

Table 5. Storyboard transitions
Transition Description

Start (startTransition)

The startTransition symbolizes that the execution of the runtime instantiation is now starting. The startTransition can be used in conditions to trigger based on this transition.

End (endTransition)

The endTransition occurs when the runtime instantiation of the StoryboardElement accomplishes its goal. Once the endTransition occurs, a check for completeness is made. A positive outcome moves the state machine to the completeState, whereas a negative outcome moves the state machine to the standbyState. The endTransition can be used in conditions to trigger based on this transition.

Stop (stopTransition)

The stopTransition marks the reception of a stopTrigger or the storyboard element is overridden (applicable for Event and Action). This implies that the stopTransition cannot be reached other than with an external intervention to the runtime instantiation of the StoryboardElement.

When a runtime instantiation of a StoryboardElement goes through a stopTransition, all of its child elements are also forced to go through the same transition. The stopTransition can be used in conditions to trigger based on this transition.

Skip

Transition marking the moment an element is asked to move to the runningState but is instead skipped so it remains in the standbyState (only for Event instances). The skipTransition can be used in conditions to trigger based on this transition.

4. Scenario Creation

4.1. Example Description of a Scenario

This scenario is written for left-hand side traffic country, but could easily be adapted if required. The Ego vehicle (Ego), an externally controlled vehicle, is driving along an urban road approaching a junction on the offside. It is being followed by two influencing vehicles, c1 and c2 (the movements of which are controlled by the scenario). A third influencing vehicle (c3) is waiting to turn right at the junction. As The Ego vehicle (Ego) approaches the junction, c1 and c2 start to overtake. Slightly later, c3 starts to turn right, which prompts c1 and c2 to make an emergency stop. The initial positions of the vehicles are shown in Figure 12.

image
Figure 12. Initial positions of vehicles

4.2. Init Section

The following XML example shows an Action which positions The Ego vehicle (Ego) using global coordinates. Similar Actions (not shown) are used to specify speeds and positions for the other vehicles.

<Storyboard>
    <Init>
        <Actions>
            <Private entityRef = "Ego">
                <PrivateAction>
                    <!-- Set Ego to its initial position -->
                    <TeleportAction>
                        <Position>
                            <WorldPosition x = "-2.51"
                                           y = "-115.75"
                                           z = "0"
                                           h = "1.57"
                                           p = "0"
                                           r = "0" />
                        </Position>
                    </TeleportAction>
                </PrivateAction>
                ...
                <!-- Similar actions -->
            </Private>
        </Actions>
   </Init>
    ...
</Storyboard>

4.3. Stories

Instances of Story are used to group independent parts of the scenario, to make it easier to follow. It is never required to use more than one Story, and if an Act is moved from one Story to another the scenario will work in the same way (as long as there are no naming conflicts). In this example, two instances of Story are used:

  • one to describe the overtake and emergency stops

  • the other to describe the right turn

These are given the names AbortedOvertake and RightTurn respectively.

The Story AbortedOvertake contains two Acts:

  • one to control the overtaking behavior

  • and another to control the emergency stops

RightTurn contains only a single Act.

The following example shows the structure of instances of Story and Acts in this Scenario.

<Story name     = "AbortedOvertake">
    <Act name   = "AbortedOvertakeAct1">
        ...
        <!-- Act content describing overtakes -->
    </Act>
    <Act name   = "AbortedOvertakeAct2">
        ...
        <!-- Act content describing emergency stops -->
    </Act>
</Story>
<Story name = "RightTurn">
    <Act name   = "RightTurnAct">
        ...
        <!-- Act content describing right turn -->
    </Act>
</Story>

4.4. Acts

Acts, which contain ManeuverGroups, allow a set of Triggers to be applied to a substantial section of the scenario.

This example scenario contains startTriggers both at Act and Event level. At Act level, they are used to start the overtake. At the Event level they control its execution. It would be possible to define all Triggers at an Event level, but this would result in much more complex, sometimes duplicated, ConditionGroups.

In this case, c1 and c2 should both start to overtake at the same time. This makes it convenient to put all content associated with both overtakes in the same Act. This has been named AbortedOvertakeAct1, is stored within the AbortedOvertake Story, and causes c1 and c2 to change lane and then begin to accelerate past the Ego vehicle.

Instances of Story, Acts, ManeuverGroups, Maneuvers and Events may be executed in any order, as defined using Triggers. The order in which they appear in an OpenSCENARIO file makes no difference.

The example below shows the structure of an Act. This Act will trigger when the Ego vehicle is close to the junction. Movements of vehicles in this Act are defined in the ManeuverGroups section, which is omitted here but described later in this chapter.

<Act name = "RightTurnAct">
    <!-- Maneuver Group -->
    ...
    <StartTrigger>
        <ConditionGroup>
            <Condition
                name    = "EgoCloseToJunction"
                delay   = "0"
                conditionEdge   = "rising">
                <!-- ByEntity condition: Ego close to junction -->
                ...
            </Condition>
        </ConditionGroup>
    </StartTrigger>
</Act>

An Act can be terminated by a stopTrigger (see Section 3.5.2.2).

4.5. ManeuverGroups

In AbortedOvertakeAct1, the two vehicles affected both perform the same Actions. However, not all of these Actions should happen at the same time. c1 and c2 should return to their original lane when they have passed the Ego vehicle (Ego), independent of what the other one is doing.

We have achieved this behavior by using a separate ManeuverGroup for each vehicle (named c1ManeuverGroup and c2ManeuverGroup) in the example below). Each ManeuverGroup allocates a Maneuver (from a Catalog) to one vehicle. This Maneuver instructs that vehicle to change lane, accelerate, and then return to the previous lane ahead of the Ego vehicle (Ego). It would also be possible to achieve the same result using the approach discussed in [Maneuver groups and Actors].

<ManeuverGroup name                  = "c1ManeuverGroup"
               maximumExecutionCount = "1">
    <Actors    selectTriggeringEntities = "false">
        <EntityRef entityRef    = "c1"/>
    </Actors>
    <CatalogReference catalogName   = "overtake"
                       entryName     = "Overtake Ego vehicle">
        <!—Parameter assignment -->
        ...
    </CatalogReference>
</ManeuverGroup>

<ManeuverGroup name                  = "c2ManeuverGroup"
               numberOfExecutions    = "1">
    ...
            <!-- similar to above -->
</ManeuverGroup>

4.6. Maneuvers

In a similar way to multi-instantiation of Story, it is never essential to use more than one Maneuver, and if an Event is moved from one Maneuver to another (within the same ManeuverGroup) the scenario will work in the same way.

In AbortedOvertakeAct1, vehicles c1 and c2 need to perform an overtake in the same way, but it must be specified in two different ManeuverGroup elements. Therefore, a Catalog Maneuver is defined:

<Catalog name = "Overtake">
    <Maneuver name = "Overtake Ego Vehicle">
        <ParameterDeclarations>
            <ParameterDeclaration name = " $OvertakingVehicle"
                                  parameterType = " string"
                                  value = ""/>
            <!-- "" will be overwritten by scenario -->
        </ParameterDeclarations>
        <!-- Events to define overtake behaviour -->
        <Event > ... </Event>
        ...
    </Maneuver>
</Catalog>

This is then referenced within both ManeuverGroups:

<ManeuverGroup  name    = "c1ManeuverGroup"
                maximumExecutionCount   = "1">
    <Actors  selectTriggeringEntities    = "false">
        <EntityRef  entityRef   =   "c1"/>
    </Actors>
    <CatalogReference   catalogName     = "Overtake"
                        entryName   = "OvertakeEgoVehicle">
        <ParameterAssignments>
            <ParameterAssignment parameterRef  = "OvertakingVehicle"
                          		 value = "c1"/>
        </ParameterAssignments>
    </CatalogReference>
</ManeuverGroup>

<ManeuverGroup  name    = "c2ManeuverGroup"
                maximumExecutionCount   = "1">
    <Actors     selectTriggeringEntities    = "false">
        <EntityRef  entityRef   = "c2"/>
    </Actors>
    <CatalogReference   catalogName = "Overtake"
                        entryName   = "OvertakeEgoVehicle">
        <ParameterAssignments>
            <ParameterAssignment parameterRef  = "OvertakingVehicle"
                            value = "c2"/>
        </ParameterAssignments>
    </CatalogReference>
</ManeuverGroup>
The Catalog reference does not define which vehicle executes the Actions, because this is defined by the ManeuverGroup. However, the Catalog reference does contain a Condition to check when the overtaking vehicle can return to its lane. This requires the names of the two vehicles involved to be specified. To achieve this, a Parameter with the name of the vehicle overtaking is included in the Catalog reference.

4.7. Events

In this example, the lane change Action should start straight away when its parent Act is triggered. Events are required to apply Triggers to Actions, so in this case a trivial Condition is used to trigger immediate execution.

<Event  name    = "brake event"
    priority    = "overwrite">
    ...
    <!-- Emergency stop action -->
    <StartTrigger>
        <ConditionGroup>
            <Condition  name = "StartConditionOfAbortedOvertakeAct2"
                        delay = "0"
                        conditionEdge = "none">
                <ByValueCondition>
                    <SimulationTimeCondition value = "0"
                                             rule  = "greaterThan"/>
                </ByValueCondition>
            </Condition>
        </ConditionGroup>
    </StartTrigger>
</Event>

For other Events, Conditions are used to ensure a certain state is reached before the Action is applied (for example, the acceleration Event must not start until the vehicle has changed lane).

5. Examples

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

5.1. Cut-In

This example describes a traffic situation where the Ego vehicle drives behind a slower 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, usage of Events, Conditions and instances of Trajectory.

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

5.2. Slow Preceding Vehicle

This scenario 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.

This scenario teaches the instantiation of instances of Entity and the usage of ParameterDeclarations.

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

5.3. End of Traffic Jam

This scenario 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 the two vehicles have travelled a distance of 100 m / 200 m respectively, they linearly decelerate by 5 m/s2 until they reach a target speed of 70 km/h.

This example extends the Slow Preceding Vehicle example by parallel execution of Acts and the usage of Conditions.

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

5.4. End of Traffic Jam, Neighboring Lane Occupied

This scenario extends the End of Traffic Jam Scenario 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, the use of ParameterDeclarations, and use of parallel Actions.

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

5.5. Double Lane Changer

This scenario describes a traffic situation where the Ego vehicle is driving at the rightmost lane behind another vehicle driving at the same speed, leaving a gap. A faster vehicle approaches the Ego vehicle from behind on the centermost lane. This vehicle changes lane 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 instantiation of instances of Entity using Cartesian coordinates, use of Conditions and consecutive execution of LaneChangeActions.

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

5.6. Fast Overtake with Re-Initialization

This scenario describes a traffic situation were 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 consecutive execution of Acts and Actions.

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

5.7. Overtaker

This scenario 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 consecutive execution of LaneChangeActions.

examples 9 overtaker
Figure 19. Overtaker scenario example

5.8. Traffic Jam

This scenario 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 instantiation of instances of Entity using Cartesian coordinates.