5 Storyboard

ASAM OpenSCENARIO 1.2.0 storyboard elements are:

  • Story

  • Act

  • ManeuverGroup

  • Maneuver

  • Event

  • Action

Storyboard elements have three possible states during the runtime:

  1. Standby
    Ready to execute, given that the start trigger conditions are met.

  2. Running
    Indicates that the element is currently executing until the goal is reached. Action elements have their specific goals, depending on the action. Other elements run until all child elements finish execution.

  3. Complete
    Reached when the maximum execution count is reached upon finishing with the Running state. This state can be reset by the parent element. The reset causes initiating a new execution and resetting the count.

A special StoryboardElementStateCondition can trigger other elements when the target element reaches some state or enters a specific state transition (see Section 6.1.4, "StoryboardElementStateCondition").

5.1 Structure

The following types of storyboard elements map to scenario of ASAM OpenSCENARIO 2.0.0:

  • Story

  • Act

  • ManeuverGroup

  • Maneuver

An entire ASAM OpenSCENARIO 1.2.0 Scenario definition maps to the top-level scenario object named top.

Event and Action have different meanings in ASAM OpenSCENARIO 2.0.0 (see Section 3, "Terms and definitions").

Depending on the concrete storyboard hierarchy in a given scenario, only a partial mapping may be needed.

Most of the intermediate levels of the storyboard structure probably do not have to be mapped to the scenario object.

5.1.1 File headers

<OpenScenario> is the top-level tag in an ASAM OpenSCENARIO 1.2.0 file. It contains a <FileHeader> with some basic scenario metadata (revision, date, description and author).

It also contains either a scenario definition or a catalog definition. This tag does not need a conversion. Metadata can be added as fields to the top-level scenario.

5.1.2 Scenario

ASAM OpenSCENARIO 1.2.0 scenario maps to the top-level scenario in ASAM OpenSCENARIO 2.0.0 (top). A scenario can have a stop trigger.

5.1.3 Story

An ASAM OpenSCENARIO 1.2.0 Story element maps to the first level sub-scenarios within the top scenario. Stories start when the top-level scenario starts and all of the stories execute in parallel.

A Story definition can have parameter declarations and has one or more of the Act child elements.

5.1.4 Act

Act storyboard elements are sub-scenarios of the Story element. Once started they execute in parallel. Act is not started automatically when the parent Story starts. Act execution starts when its startTrigger is satisfied. Act can be started again if startTrigger is satisfied, but only after all child ManeuverGroups are exhausted (their maximumExecutionCount is reached).

5.1.5 ManeuverGroup

ManeuverGroup is a sub-scenario of Act. It connects the set of Actors to the set of Maneuvers. ManeuverGroup has the maximumExecutionCount property and lists Actors explicitly or with the selectTriggeringEntities property.

The selectTriggeringEntities property can extend this list at runtime. This list of actors is effective for all PrivateActions defined within Elements of the child Maneuvers.

ManeuverGroup without EntitySelection can be transformed by executing appropriate sub-scenarios with multiple actors.

Translation is more difficult when selectTriggeringEntities is active. In that case, actors from the ConditionGroups of the parent Act that evaluate to True at the starting time of the Act will be appended to the list of actors executing this instance of ManeuverGroup.

Each ConditionGroup maps via a one to one relationship to an ASAM OpenSCENARIO 2.0.0 event. Each event can set the relevant actors in the scenario variable. This variable can then be used to invoke a scenario with different actors.

5.1.6 Maneuver

An ASAM OpenSCENARIO 1.2.0 Maneuver is a container for Event elements. Maneuver determines the scope for Event priorities (see Section 5.1.7, “Event”).

5.1.7 Event

An event is started by a trigger. An event stops running when all actions that it contains are finished. As a ManeuverGroup it also has a maximumExecutionCount property. Events have the following defined priorities:

  • overwrite

  • skip

  • parallel

Priority extends only to events in the same maneuver.

An event with the priority overwrite stops other events that are already executing. An event with the priority skip does not start if something else is already active in the same maneuver.

Events with priority parallel execute in parallel if all actions for defined in parallel are compatible with currently running ones, for example, one event with only longitudinal actions and one event with lateral actions.

An event ends when the execution of all actions within the event end.

Multiple actions in the same ASAM OpenSCENARIO 1.2.0 Event are converted with the parallel temporal operator, where the default behavior causes actions to start at the same time, but not force the same ending time for the actions.

Example 1. An Event in ASAM OpenSCENARIO 2.0.0

  • Trigger:

    • simulationTime == 5s

  • Actions:

    • LaneChangeAction, duration 4s

    • SpeedAction, duration 2s

The event is finished when the longer-lasting action is finished.

    do serial:
        wait elapsed(5 s):
        parallel:
            serial(duration: 4s):
                car1.change_lane(1, right)
            serial(duration: 2s):
                car1.change_speed(60kph, at:end)

As for ASAM OpenSCENARIO 1.2.0, the phase is finished when the longer-lasting action is finished.

5.1.7.1 Event priorities

When translating an ASAM OpenSCENARIO 1.2.0 Maneuver, all the Event elements within the maneuver need to be considered. Furthermore, appropriate modifiers have to be applied to scenarios representing these events. ASAM OpenSCENARIO 1.2.0 priorities are represented with the override modifier.

Example 2. Event priority

Consider two events e1 and e2.

If the event e1 within the same maneuver has overwrite priority, it needs to list other events, in this case e2, in the which parameter of the override modifier.

If e2 has been triggered first (chronologically) and is still executing when the conditions for e1 are met, such an override(which: e2) construction causes e2 to finish (without failing) and e1 to start.

do parallel:
    serial:
        wait car_1.time_to_collision(car_2) < 5s
        e1: car_1.slow_down()
    serial:
        wait car_1.time_headway(car_2) > 3s
        e2: car_1.speed_up()
with:
    override(e2, e1)
    override(e1, e2)
e2 is also taken to have overwrite priority, but the code for defining e1 is the same. Only the code for e2 is different in this case.

To indicate, that e1 has skip priority, use the when_active parameter. In this case, list all other events from the maneuver. This is because e1 needs to be skipped if any of the events are in progress (even other events with skip priority).

Example 3. Event with skip priority
do parallel:
    serial:
        wait car_1.time_to_collision(car_2) < 5s
        e1: car_1.slow_down() with:
    serial:
        wait car_1.time_headway(car_2) > 3s
        e2: car_1.speed_up() with:
with:
    override(e2, e1, when_active)
    override(e1, e2)
e1 was changed to skip priority, but e2 was left as overwrite.

5.1.7.2 Translating the parallel priority

When translating the parallel priority, take additional care.

The modifier override is not selective when terminating running events (overwrite), or events about to start (skip).

Similar to Section 5.1.7.1, “Event priorities”, start with considering other events from the same Maneuver.

If the other event contains actions compatible with the event with parallel priority, no adding of an override line for that event is needed. New actions start to execute in parallel with old ones.

For the other events that contain actions not compatible with the event, a conversion is done by adding the override modifier as if to convert the overwrite priority.

5.1.8 Action

If multiple actors are executing the action, the action ends when all of these actors have finished executing the action. They are listed in the parent ManeuverGroup.

The action is considered to end when every of the listed actors finishes executing it.

Individual actors can take different amounts of time to execute, depending on initial conditions, performance limits, and action parameters.

Example 4. Action with actors that have different execution times

Lane change for "Car 1", "Car 2", and "Car 3", defined with length 30 m.

  • Speed of "Car 1" is 20 km/h

  • Speed of "Car 2" is 50 km/h

  • Speed of "Car 3" is 80 km/h

This action ends when the slowest car finishes changing the lane.

5.2 Initialization

Initialization of ASAM OpenSCENARIO 1.2.0 defines the entities within the scenario and optionally gives them a starting position, an orientation, and a speed.

Entities that do not get assigned a position in the Init section will not be active at the simulation start. Entities of that kind can be activated and positioned later during the scenario execution using AddEntityAction.

See Section 4, "Entities" for more details. Adding entities after the scenario has started is not supported.