ASAM OpenSCENARIO: User Guide

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.

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:

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.

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

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

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.

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.

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

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.

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.

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.

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:

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.

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:

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

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.

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:

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:

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.

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:

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

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.

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.

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):

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:

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.

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

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:

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.

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:

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.

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.

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:

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

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.

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:

When referenced in the main scenario, the value of x is overridden by using a ParameterAssignment within the 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.

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:

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.

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.