7.2 Storyboard and entities

7.2.1 Storyboard

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

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

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

  • stopTrigger: Determines the end of the scenario. If no stopTrigger is defined, the Storyboard will never be stopped.

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

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

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

Figure 22 illustrates the components of a storyboard.

image
Figure 22. Diagram showing the structure of a storyboard

7.2.2 Entities

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

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

Trailers are modeled as an instance of Vehicle and can be connected to other instances of Vehicle.

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

In ASAM OpenSCENARIO, an entity can be represented by any of these two model elements:

  • Entity — describes one specific object

  • EntitySelection — describes a list of instances of Entity

7.2.2.1 Motion control for entities

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

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

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

  • No user assigned controller are running.

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

7.2.2.2 Entity selections

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

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

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

Declaring instances of EntitySelection with circular dependencies is highly discouraged and may lead to unexpected behavior.

7.2.2.3 Spawned objects

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

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

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

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

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

7.2.2.4 Entity class hierarchy

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

image
Figure 23. The entity class hierarchy

The following relations can be inferred from Figure 23:

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

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

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

7.2.2.5 Generalization of entities

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

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

This includes:

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

  • Restrictions concerning the multiplicity of a referenced Entity:

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

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

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

7.2.2.6 Trailer modeling

Class Vehicle has a set of optional attributes to be able to act as a trailer or to connect a trailer:

  • trailerHitch is the mounting point on the tow vehicle

  • trailerCoupler is the trailer mounting point

  • trailer is a reference to the connected trailer Vehicle instance

A vehicle can define both trailerHitch and trailerCoupler, in which case it describes a trailer being able to pull another trailer.

Mounting points are defined along the X-axis of the vehicles. The point can be within or outside the bounding box of the vehicle body.

Basically any trailer configuration can be modeled, like Figure 24 or Figure 25.

Image showing how coupler and hitch are used for a semi truck
Figure 24. Example 1: A semi truck with "fifth-wheel" connector
Image showing how coupler and hitch are used for a car with a trailer
Figure 25. Example 2: A car trailer hooked up to a tow bar

Only one trailer can be connected to a vehicle at a time. A trailer may connect to another trailer. There is no limit to the recursive number of trailers that can be interconnected.

The connection is defined by a valid setting of the Trailer reference attribute. The connection can be set up at vehicle definition. It can also be dynamically controlled (during simulation) with the ConnectTrailerAction.

7.2.2.7 3D models for entities

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

  • Vehicle

  • Pedestrian

  • MiscObject

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

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

image
Figure 26. model3d behavior depending on simulator support