7.4 Actions

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

There are three categories of Action:

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

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

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

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

7.4.1 Private action

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

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

  • Directly setting entity states, for example, position.

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

7.4.1.1 Control strategy

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

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

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

  • Only private actions shall be mapped to control strategies.

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

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

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

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

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

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

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

  • Lateral domain: The default control strategy is to keep the lane (meaning, not to change to a neighboring lane) and keep the offset of the entity to the lane centerline. Default routing behavior is described in Section 6.8, "Routes".

  • Longitudinal domain: The default control strategy is to keep the current speed of the entity by controlling the length of the vehicle’s speed vector.

  • Lighting domain: Lights turned off

  • Animation domain: Animations off

image
Figure 27. Relations between Entity, Controller, privateAction, and control strategy

7.4.1.2 Private actions and motion control

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

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

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

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

7.4.1.3 Types of private action

The following types of private action exist:

LongitudinalAction

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

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

SpeedProfileAction provides a flexible way to define multiple speed changes over time, with acceleration and jerk settings optionally taken into account.

LateralAction

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

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

VisibilityAction

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

SynchronizeAction

Takes over longitudinal control of an entity 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, to meet the explicit position constraint and implicit time constraint. Optionally, in addition to the desired position, the controlled entity may also be given a FinalSpeed setting. This is the speed that the controlled entity shall have when reaching the destination. This final speed may be specified either as an absolute value or relative to the reference entity.

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

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

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

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

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

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

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

image
Figure 28. SynchronizeAction example inducing an interceptor situation

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

image
Figure 29. Example of SynchronizeAction combined with routing

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

image
Figure 30. SynchronizeAction constellation example

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

ActivateControllerAction (deprecated)

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

ControllerAction

Manages user-defined controllers using an action. Use one of these actions:

  • AssignControllerAction: Assigning either a driver model to instances of entity of type Vehicle, a model controlling motion behavior for other moving instances of entity, or an animation scheme (for example, a policeman).

  • ActivateControllerAction: Activating or deactivating user-defined controllers assigned to entities on the lateral, longitudinal, lighting, animation domain, or all domains simultaneously.

  • OverrideControllerValueAction: Overriding control signals of a user-defined controller, for example, applying the brakes or setting a steering wheel angle.

TeleportAction

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

RoutingAction

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

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

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

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

  • RandomRouteAction: If an entity approaches a junction, the road to follow is selected randomly from the available options.

AppearanceAction

Grouping actions that do not change the position or speed of an entity or modify the controller of an entity, but have an impact on the appearance of an entity. There are two ways of specifying a change in appearance:

  • AnimationAction: Using an AnimationType to animate a component of an entity, for example, opening the front left door of a vehicle or a pedestrian’s motion and gestures.

  • LightStateAction: Using a LightType and LightState to change the lights of an entity, for example, turning on the daytime running lights of a vehicle.

    <AppearanceAction>
    <LightStateAction>
        <LightType>
            <VehicleLight vehicleLightType="daytimeRunningLights"/>
        </LightType>
        <LightState state="on"/>
    </LightStateAction>
</AppearanceAction>
TrailerAction

Group of actions handling the connection of trailer vehicles. ConnectTrailerAction connects a trailer to a towing vehicle. DisconnectTrailerAction disconnects any connected trailer from the towing vehicle. Actions apply to the towing vehicle.

7.4.2 Global action

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

EnvironmentAction

Setting weather state, road condition, and time.

EntityAction

Removing or adding instances of Entity.

VariableAction

Setting or modifying values of variables.

InfrastructureAction

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

TrafficAction

Managing ambient traffic of the following kinds:

  • Creation of sources and sinks

    • A source creates vehicles or pedestrians, whereas a sink deletes them.

    • A source spawns new entities with the rate defined in the element. A sink deletes a maximum amount of entities to be removed per second through the specified 'rate'. If no rate is given in a traffic sink, it deletes all entities reaching its area of influence. Removal of entities follows the "first in, first out" principle.

  • Creation of traffic in an area, using TrafficAreaAction

    • The type of spawned entities and their controllers can be specified with the TrafficDistribution

    • The area where the traffic shall be spawned can be defined as either a closed Polygon (useful for urban areas where all roads shall contain traffic) or a RoadRange (useful for highways where only a few specific roads shall contain traffic).

    • A RoadRange is defined by one RoadCursor as start, one cursor as end-cursor and optional cursors in between to limit the included lanes (see Figure 31 and Figure 32).

      image
      Figure 31. Road Cursor definition
      image
      Figure 32. Road Range definition

      This code example shows how to define the range in Figure 32:

      <RoadRange>
  <RoadCursor id="road0" s="500">
    <Lane id="-1" />
    <Lane id="-2" />
  </RoadCursor>
  <RoadCursor id="road1" s="0">
    <Lane id="-2" />
    <Lane id="-3" />
  </RoadCursor>
  <RoadCursor id="road2" s="500" />
</RoadRange>

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

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

      image
      Figure 33. Swarm definition

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

    • Spawned vehicles make routing decisions based on their driver model, just as with the ActivateControllerAction. Optionally, a starting speed for the spawned entities may be specified. If no speed is given, for vehicles the speed limit of the underlying road is used. This can lead to undefined behavior because there may be no speed limit defined for the road in the underlying road network file. To prevent errors, either a speed of the created entity should be defined or road network files should be used that have a speed limit defined. All elements make use of a TrafficDistribution, where the distribution of the spawned and removed entities may be defined explicitly.

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

7.4.3 User-defined action

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

CustomCommandAction

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