Scenario

Overview

The scenario configuration file (*.xosc) describes all dynamic configurations of a simulation run, i.e. position of various road users as well as conditional events that change the behavior of the simulation during the run. The scenario control is carried out using the OpenScenarioEngine, which processes scenarios according to ASAM OpenSCENARIO. It is interfaced using the MantleAPI. For the list of MantleAPI features supported by openPASS see Scenario API Support.

At the time of writing, the OpenScenarioEngine processes scenario configurations in version 1.1.1, but please refer to the corresponding documentations for possible and implemented features.

In the following, the most important features for openPASS are described.

ParameterDeclarations

The tag ParameterDeclarations allow to define generic parameters, which can be referenced later the file by its name, prefixed with $.

Example declaration

<ParameterDeclarations>
  <ParameterDeclaration name="simulation_time" parameterType="double" value="123.4"/>
</ParameterDeclarations>

Example usage

<StopTrigger>
  <ConditionGroup>
    <Condition name="EndTime" delay="0" conditionEdge="rising">
      <ByValueCondition>
        <SimulationTimeCondition value="$simulation_time" rule="greaterThan"/>
      </ByValueCondition>
    </Condition>
  </ConditionGroup>
</StopTrigger>

Supported ParameterTypes
string
integer
double

Note

Only string allows empty values.

Catalogs

The Catalogs tag defines locations of various other files containing sub features of OpenSCENARIO for easier reusing (and written in the same format).

The following catalogs are the most important:

• VehicleCatalog

• PedestrianCatalog

• TrajectoryCatalog for the case that a FollowTrajectory action is defined

The VehicleCatalog is also used by openPASS itself for spawning of Common vehicles and therefore mandatory.

Example

<CatalogLocations>
  <VehicleCatalog>
    <Directory path="Vehicles"/>
  </VehicleCatalog>
  <PedestrianCatalog>
    <Directory path="Vehicles"/>
  </PedestrianCatalog>
  <ControllerCatalog>
    <Directory path=""/>
  </ControllerCatalog>
  <ManeuverCatalog>
    <Directory path=""/>
  </ManeuverCatalog>
  <MiscObjectCatalog>
    <Directory path=""/>
  </MiscObjectCatalog>
  <EnvironmentCatalog>
    <Directory path=""/>
  </EnvironmentCatalog>
  <TrajectoryCatalog>
    <Directory path=""/>
  </TrajectoryCatalog>
  <RouteCatalog>
    <Directory path=""/>
  </RouteCatalog>
</CatalogLocations>

VehicleCatalog

This path is mandatory. It has to contain a file named “VehicleModelsCatalog.xosc”. This file contains the available vehicle model catalogs for the simulation. For each vehicle the physical parameters are stored here.

Supported Models
car_bmw_i3
car_bmw_3
car_bmw_7_1
car_bmw_7_2
car_mini_cooper
bus
truck
bicycle

Example Catalog:

/../../../repo/sim/contrib/examples/Common/Vehicles/VehicleModelsCatalog.xosc

PedestrianCatalog

It contains the available pedestrian model catalogs for the simulation. For each pedestrian the physical parameters are stored here.

Note

Within openPASS, pedestrian models are internally handled the same way as vehicle models, i.e. they behave like simplified vehicles. Meaningless parameters, such as number of gears, are set to operational defaults.

Supported Models
pedestrian_child
pedestrian_adult

Full Example: /../../../repo/sim/contrib/examples/Common/Vehicles/PedestrianModelsCatalog.xosc

RoadNetwork

The RoadNetwork tag contains the mandatory reference to the OpenDRIVE Scenery.

Example

<RoadNetwork>
  <LogicFile filepath="SceneryConfiguration.xodr"/>
  <SceneGraphFile filepath=""/>
</RoadNetwork>

Furthermore the controllers of the traffic lights are defined in this section. Each controller defines the phases of a set of linked traffic lights (e.g. one junction).

Example

<TrafficSignals>
  <TrafficSignalController name="">
    <Phase duration="3" name="Phase1">
      <TrafficSignalState state="green" trafficSignalId="1"/>
    </Phase>
    <Phase duration="3" name="Phase2">
      <TrafficSignalState state="yellow" trafficSignalId="1"/>
    </Phase>
    <Phase duration="3" name="Phase3">
      <TrafficSignalState state="red" trafficSignalId="1"/>
    </Phase>
    <Phase duration="3" name="Phase4">
      <TrafficSignalState state="red yellow" trafficSignalId="1"/>
    </Phase>
  </TrafficSignalController>
</TrafficSignals>

Supported States
off
red
yellow
green
red yellow
yellow flashing

Entities

The Entities tag defines all agents that are present at the start of the simulation at predefined positions. There may be any number of these so called Scenario Agents (also zero).

Note

EntitySelections are currently not supported by the OpenScenarioEngine

An entity consits of a VehicleModel (typically a reference an entry from the VehicleCatalog) and a controller. The controller is optional and if no controller is specified, a default contoller will be instantiated, which strictly follows OpenSCENARIO actions as requested by the standard. Unless requested differently through specific actions, it follows the default behaviors KeepVelocity and KeepLateralOffset. To use the openPASS specific scenario controller a controller with a single parameter named AgentProfile needs to be specified.

AgentProfile and ProfilesCatalog

The AgentProfile links to a profile in the mandatory ProfilesCatalog.xml (see ProfilesCatalog). This is an extension w.r.t. the OpenSCENARIO standard, as the standard currently does not allow to specifiy a stochastic composition of entities.

Example

<Entities>
  <ScenarioObject name="Ego">
    <CatalogReference catalogName="VehicleCatalog" entryName="car_mini_cooper"/>
    <ObjectController>
      <Controller name="Ego">
        <Properties>
          <Property name="AgentProfile" value="MiddleClassCarAgent"/>
        </Properties>
      </Controller>
    </ObjectController>
  </ScenarioObject>
</Entities>

Overriding Parameters

Parameters defined in the VehicleCatalog can be assigned inside the CatalogReference element. In this case the assigned parameter will overwrite the definition in the VehicleCatalog. Otherwise the value defined in the VehicleCatalog is used. The type of the parameter must match that in the VehicleCatalog.

Example

<CatalogReference catalogName="VehicleCatalog" entryName="car_mini_cooper">
    <ParameterAssignments>
        <ParameterAssignment parameterRef="Length" value="4.0" />
    </ParameterAssignments>
</CatalogReference>

Storyboard

The Storyboard tag contains the initial setup of the scenario and manipulator actions. These actions control the behavior of the simulation at runtime based on predefined conditions. In short it is divided into an Init phase, an actual Story, and a StopTrigger.

For the definition of the storyboard please refert to the OpenSCENARIO 1.1.1 Model Definition.

In the following sections, clarifications with respect to openPASS will be given:

Init

As desribed above, agents need to be defined in the Entities section. For proper spawning they need to be parameterized within the Init phase:

• A TeleportAction specifies the initial position If no TeleportAction is defined the agent will not be spawned (the TeleportAction can also happen inside the Story).

• A SpeedAction specifies the desired velocity. [optional] If not defined, a spawned agent will start at standstill.

• A FollowRouteAction forces the agent onto a specific trajectory [optional] If not defined, a random route will be assigned.

Note

VisiblilityAction is currently not supported by openPASS

Example: TeleportAction + SpeedAction

<Init>
  <Actions>
    <Private entityRef="Ego">
      <PrivateAction>
        <TeleportAction>
          <Position>
            <LanePosition roadId="1" laneId="-1" offset="0.0" s="0.0">
              <Orientation type="relative"/>
            </LanePosition>
          </Position>
        </TeleportAction>
      </PrivateAction>
      <PrivateAction>
        <LongitudinalAction>
          <SpeedAction>
            <SpeedActionDynamics dynamicsShape="step" value="0.0" dynamicsDimension="rate"/>
            <SpeedActionTarget>
              <AbsoluteTargetSpeed value="43.5"/>
            </SpeedActionTarget>
          </SpeedAction>
        </LongitudinalAction>
      </PrivateAction>
      <PrivateAction>
        <ControllerAction>
          <ActivateControllerAction controllerRef="Ego" lateral="true" longitudinal="true" />
        </ControllerAction>
      </PrivateAction>
    </Private>
  </Actions>
</Init>

Example: TeleportAction + FollowRouteAction

<Init>
  <Actions>
    <Private entityRef="Ego">
      <PrivateAction>
        <TeleportAction>
          <Position>
            <LanePosition roadId="1472558076" laneId="-1" offset="0.0" s="200.0">
              <Orientation type="relative"/>
            </LanePosition>
          </Position>
        </TeleportAction>
      </PrivateAction>
      <PrivateAction>
        <RoutingAction>
          <AssignRouteAction>
            <Route closed="false" name="">
              <Waypoint routeStrategy="fastest">
                <Position>
                  <RoadPosition roadId="1472558076" t="-1.0" s="230"/>
                </Position>
              </Waypoint>
              <Waypoint routeStrategy="fastest">
                <Position>
                  <RoadPosition roadId="3083973" t="-1.0" s="8.5"/>
                </Position>
              </Waypoint>
              <Waypoint routeStrategy="fastest">
                <Position>
                  <RoadPosition roadId="2015840166" t="-0.2" s="100"/>
                </Position>
              </Waypoint>
            </Route>
          </AssignRouteAction>
        </RoutingAction>
      </PrivateAction>
      <PrivateAction>
        <ControllerAction>
          <ActivateControllerAction lateral="true" longitudinal="true" controllerRef="Ego"/>
        </ControllerAction>
      </PrivateAction>
    </Private>
  </Actions>
</Init>

Story

The tag Story is optional and defines all conditional interventions during runtime. Please refer to the Model Documentation for a general overview and the OpenScenarioEngine for supported actions and conditions within a story.

StopTrigger

It is mandatory for openPASS to define a StopTrigger that will fire in any case (otherwise, the simulation will never stop). This does not necessarily have to be a SimulationTimeCondition, but it is recommended to use it, perhaps in conjunction with another trigger.

Current Restrictions

Conditions

openPASS support different kind of conditions, belonging either to ByValueCondition or ByEntityCondition. While a by value condition triggers based on a specified value and is unrelated to any specific agent, a by entity condition is bound to an triggering agent, defined by a mandatory section TriggeringEntities. Entities can be either ego or scenario agents.

Note

Reacting on “common” cars is currently not supported.

Actions

The following OpenSCENARIO actions are supported:

• FollowRouteAction

• LaneChangeAction

• FollowTrajectoryAction

• AcquirePositionAction

• TeleportAction

• SpeedAction

• TrafficSinkAction

In addition, the following user defined actions are interpreted:

• SetComponentState (UserDefinedAction)

• DefaultCustomCommandAction (UserDefinedAction)

FollowRouteAction

The FollowRouteAction is mainly used as part of the Init phase of the Storyboard. It defines Waypoints, which are located by road_id and further with s and t coordinates. The Agent will try to follow the specified points.

Example Right turn, by specifying three waypoints

          <RoutingAction>
            <AssignRouteAction>
              <Route closed="false" name="">
                <Waypoint routeStrategy="fastest">
                  <Position>
                    <RoadPosition roadId="1472558076" t="-1.0" s="230"/>
                  </Position>
                </Waypoint>
                <Waypoint routeStrategy="fastest">
                  <Position>
                    <RoadPosition roadId="3083973" t="-1.0" s="8.5"/>
                  </Position>
                </Waypoint>
                <Waypoint routeStrategy="fastest">
                  <Position>
                    <RoadPosition roadId="2015840166" t="-0.2" s="100"/>
                  </Position>
                </Waypoint>
              </Route>
            </AssignRouteAction>
          </RoutingAction>

LaneChangeAction

If this action triggers, the actor is forced to perform a trajectory, calculated at the time of triggering. The target lane be given either absolute or with respect to another entity. The trajectory can either have a fixed length (in s) or a fixed time.

Currently openPASS only supports the type sinusoidal.

Example with absolute target and fixed length

<Action name="LaneChange">
  <PrivateAction>
    <LateralAction>
      <LaneChangeAction>
        <LaneChangeActionDynamics value="2.0" dynamicsShape="sinusoidal" dynamicsDimension="time"/>
        <LaneChangeTarget>
          <AbsoluteTargetLane value="-4"/>
        </LaneChangeTarget>
      </LaneChangeAction>
    </LateralAction>
  </PrivateAction>
</Action>

Example with relative target and fixed time

<Action name="LaneChange">
  <PrivateAction>
    <LateralAction>
      <LaneChangeAction>
        <LaneChangeActionDynamics value="2.0" dynamicsShape="sinusoidal" dynamicsDimension="time"/>
        <LaneChangeTarget>
          <RelativeTargetLane entityRef="Ego" value="+1"/>
        </LaneChangeTarget>
      </LaneChangeAction>
    </LateralAction>
  </PrivateAction>
</Action>

FollowTrajectoryAction

If triggered, the defined trajectory is relayed as signal to listening components. The trajectory can be defined either directly in the story or as separate TrajectoryCatalog. For the points (vertices) of the trajectory only world coordinates, given as openScenario::WorldPosition, are supported. Right now, the mandatory attributes z, pitch and roll are ignored.

Example

<Action name="Trajectory">
  <PrivateAction>
    <RoutingAction>
      <FollowTrajectoryAction>
        <TrajectoryRef>
          <Trajectory name="LaneChange" closed="false">
            <Shape>
              <Polyline>
                <Vertex time="0">
                  <Position>
                    <WorldPosition x="100" y="3" z="0" h="1.570796326" p="0" r="0"/>
                  </Position>
                </Vertex>
                <Vertex time="5">
                  <Position>
                    <WorldPosition x="100" y="8" z="0" h="1.570796326" p="0" r="0"/>
                  </Position>
                </Vertex>
              </Polyline>
            </Shape>
          </Trajectory>
        </TrajectoryRef>
        <TimeReference>
          <None/>
        </TimeReference>
        <TrajectoryFollowingMode followingMode="position"/>
      </FollowTrajectoryAction>
    </RoutingAction>
  </PrivateAction>
</Action>

Example using a TrajectoryCatalog

<Action name="FollowTrajectory">
  <Private>
    <Routing>
      <FollowTrajectoryAction>
        <CatalogReference catalogName="TrajectoryCatalog.xosc" entryName="TrajectoryA">
      </FollowTrajectoryAction>
    </Routing>
   </Private>
</Action>

AcquirePositionAction

If triggered, the defined position is relayed as signal to listening components.

Warning

Currently, this is only supported by the component FMU_Wrapper for OSMP messages.

Warning

An FMU might contain routing logic not visible to the openPASS simulation core. For that reason, an equivalent RoutingAction should be set when using AcquirePosition. Otherwise the simulation output might contain missing data for fields depending on the localization along the route (PositionRoute, TCoordinate, AgentInFront, …).

Example (WorldPosition)

<Action name="AcquirePosition">
  <PrivateAction>
    <RoutingAction>
      <AcquirePositionAction>
        <Position>
          <WorldPosition x="1.0" y="2.0" z="0.0" h="3.1415" p="0.0" r="0.0" />
        </Position>
      </AcquirePositionAction>
    </RoutingAction>
  </PrivateAction>
</Action>

Example (RelativeObjectPosition)

<Action name="AcquirePosition">
  <PrivateAction>
    <RoutingAction>
      <AcquirePositionAction>
        <Position>
          <RelativeObjectPosition dx="1.0" dy="1.0" entityRef="S1"/>
        </Position>
      </AcquirePositionAction>
    </RoutingAction>
  </PrivateAction>
</Action>

TeleportAction

The TeleportAction instantly changes the position of an entity.

TrafficSinkAction

The TrafficSinkAction is used to remove agents when they reach a certain position.

Note

At spawning time, the TrafficSinkAction is executed the common traffic is initiated, which means vehicles will spawn at the first timestamp in the defined zone, but are immediately removed at the next timestep.

SpeedAction

The SpeedAction adjusts the velocity of an entity based on parameters of the SpeedAction.

Note

If the openPASS specific controller is used, the SpeedAction might not reflect actual values used by the simulator due to physical boundaries of the simulator.

Example AbsoulteTargetSpeed

<Action name="SpeedAction">
  <PrivateAction>
    <LongitudinalAction>
      <SpeedAction>
        <SpeedActionDynamics dynamicsShape="step" value="0.0" dynamicsDimension="rate"/>
        <SpeedActionTarget>
          <AbsoluteTargetSpeed value="20"/>
        </SpeedActionTarget>
      </SpeedAction>
    </LongitudinalAction>
  </PrivateAction>
</Action>

Example RelativeTargetSpeed

<Action name="SpeedAction">
  <PrivateAction>
    <LongitudinalAction>
      <SpeedAction>
        <SpeedActionDynamics dynamicsShape="step" value="0.0" dynamicsDimension="rate"/>
        <SpeedActionTarget>
          <RelativeTargetSpeed entityRef="ScenarioAgent" value="10"
                               speedTargetValueType="delta" continuous="false"/>
        </SpeedActionTarget>
        </SpeedAction>
    </LongitudinalAction>
  </PrivateAction>
</Action>

SetComponentState (UserDefinedAction)

Command Keyword: SetComponentState

Influences the maximum reachable state of an agent component handled by the ComponentController, i.e. it can either activate or deactivate a component. For more details see the description of the ComponentController.

Example

<Action name="ComponentStateChange">
    <UserDefinedAction>
        <CustomCommandAction>SetComponentState Dynamics_TrajectoryFollower Acting</CustomCommandAction>
    </UserDefinedAction>
</Action>

DefaultCustomCommandAction (UserDefinedAction)

This is the default custom command, and is always selected, if the first WORD (Keyword) in the command string is not registered as a special custom command. The command is universally accessible across all components via ScenarioControlInterface::GetCustomCommands(), empowering users to define personalized actions tailored to their specific needs. Once defined, the functionality of this command is unique to the user, based on their custom implementation.

FMU_Wrapper component for OSMP messages only

The linked string signal is set as custom action of the TrafficCommand. For more information on OSMP FMUs see the FMU Wrapper documentation.

Example

<Action name="CustomParameters">
    <UserDefinedAction>
        <CustomCommandAction>Arbitrary String, e.g. { "hello": "world"}</CustomCommandAction>
    </UserDefinedAction>
</Action>

Note

Here, “Arbitrary” is first checked, if it matches any other available Keyword for used defined actions, such as SetComponentState (UserDefinedAction).