Main Content

Export Driving Scenario to ASAM OpenSCENARIO File

ASAM OpenSCENARIO® is an open file format that describes the dynamic content of driving scenarios. Using the Driving Scenario Designer app, you can export road networks, actors, and trajectories from a driving scenario to an ASAM OpenSCENARIO file.

The app supports exporting driving scenarios to ASAM OpenSCENARIO file versions 1.0 and 1.1.

To programmatically export a driving scenario to an ASAM OpenSCENARIO file, use the export object function of the drivingScenario object.

Load Scenario File

To open the Driving Scenario Designer app, enter this command at the MATLAB® command prompt:

drivingScenarioDesigner

To load an existing scenario file, on the app toolstrip, select Open > Scenario File. The file you select must be a valid driving scenario session file with the .mat file extension. Alternatively, you can create a new scenario by using the Driving Scenario Designer app, and then export that scenario to an ASAM OpenSCENARIO file. For information about how to create a scenario, see Create Driving Scenario Interactively and Generate Synthetic Sensor Data.

Navigate to and open this driving scenario, where matlabroot is your MATLAB root folder:

matlabroot/examples/driving/data/CutInScenario.mat

The Scenario Canvas pane displays the scenario, in which an ego vehicle and a target vehicle travel on a straight road with predefined trajectories such that the target vehicle cuts into the ego lane.

Example scenario where non-ego vehicle cuts into the ego lane.

This scenario contains these ASAM OpenSCENARIO actions:

  • SpeedAction — The ego vehicle travels with an initial speed of 15 m/s and then stops momentarily when it reaches a specified waypoint. The ego vehicle then travels at a speed of 10 m/s until the end of the scenario.

  • VisibilityAction — The target vehicle enters the scenario after 3 seconds.

  • FollowTrajectoryAction — The vehicles explicitly follow their trajectories, specified using waypoints.

Run the scenario and observe the behaviors of the two vehicles.

Export to ASAM OpenSCENARIO

To export the road network, actors, and trajectories in the scenario to an ASAM OpenSCENARIO file, on the app toolstrip, select Export > ASAM OpenSCENARIO File.

Export menu for OpenSCENARIO in Driving Scenario Designer app

The app opens the ASAM OpenSCENARIO Export dialog box.

ASAM OpenSCENARIO Export dialog box

On the OpenSCENARIO tab, specify these options:

  • File Path — Specifies a name and location for the output ASAM OpenSCENARIO file with either the .xosc or .xml file extension. By default, the app saves the file in the current working directory. To specify a different file location, click Browse. If a file with the specified name already exists, the app overwrites the existing file.

  • File Version — Specifies the ASAM OpenSCENARIO version for the output file as Version 1.0 or Version 1.1.

    Default: Version 1.0

On the OpenDRIVE tab, specify information for the associated ASAM OpenDRIVE® file using these options:

  • File Version — Specifies the ASAM OpenDRIVE version for the output file as Version 1.4, Version 1.5, or Version 1.6.

    Default: Version 1.4

  • Export Actors — Select this parameter to export actors to the ASAM OpenDRIVE file.

    Default: on

Once you have specified the file information, click Export. The app creates an ASAM OpenSCENARIO file, which describes the dynamic behaviors of actors in the scenario, as well as additional data files. Each data file contains information about a specific scenario element, such as a vehicle or pedestrian. The name of each data file has the prefix filename_, where filename is the name specified using the File Path option.

Data FileElement of Scenario
filename_OpenDRIVE.xodrRoad network and barriers in the scenario
filename_VehicleCatalog.xoscProperties of vehicles
filename_PedestrianCatalog.xoscProperties of pedestrians

Note

The app exports data files based on the contents of the scenario. For example, if the scenario does not contain any pedestrians, then the data file filename_PedestrianCatalog.xosc is not exported.

ASAM OpenSCENARIO Representations

The exported files contain representations of driving scenario actors and their parameters in the ASAM OpenSCENARIO format.

Name, Class, and Actor Properties

The app exports the Name, Class, and Actor Properties for each actor to a Vehicle element within the filename_VehicleCatalog file.

<Vehicle name="Car1" vehicleCategory="car">
  <BoundingBox>
    <Center x="1.35" y="0" z="0"/>
    <Dimensions height="1.4" length="4.7" width="1.8"/>
  </BoundingBox>
  <Performance maxAcceleration="5.36" maxDeceleration="6" maxSpeed="39"/>
  <Axles>
    <FrontAxle maxSteering="0.5" positionX="2.8" positionZ="0.1905" trackWidth="1.8" wheelDiameter="0.381"/>
    <RearAxle maxSteering="0.5" positionX="0" positionZ="0.1905" trackWidth="1.8" wheelDiameter="0.381"/>
  </Axles>
  <Properties/>
</Vehicle>

ASAM OpenSCENARIO vehicles include parameters without equivalent actor characteristics. This table shows the default values for those ASAM OpenSCENARIO parameters for various types of exported actors.

Vehicle ParameterDefault Value in Exported File
CarTruckBicycle
maxAcceleration5.3645 m/s20.897 m/s20.231 m/s2
maxDeceleration6 m/s20.474 m/s27 m/s2
maxSpeed39 m/s30 m/s22 m/s
maxSteering0.5 rad0.5 rad0.61 rad
trackWidthWidth of vehicleWidth of vehicle0
wheelDiameter0.381 m0.5715 m0.571 m

This table describes how each attribute in the exported file maps to the actor properties in the app.

Exported Attribute in ASAM OpenSCENARIOConversion from Actor Properties
x-coordinate of center of bounding boxx-coordinate of actor Position + RearOverhang + 0.5 * Length
y-coordinate of center of bounding boxy-coordinate of actor Position
z-coordinate of center of bounding boxz-coordinate of actor Position
positionX of front axlex-coordinate of actor Position + FrontOverhangRearOverhang + Length
positionZ of front axle0.5 * wheelDiameter
positionX of rear axlex-coordinate of actor Position
positionZ of rear axle0.5 * wheelDiameter

Waypoints

The app exports the waypoints of an actor to the Trajectory element of the FollowTrajectoryAction in the Init section of the output ASAM OpenSCENARIO file. The Trajectory element defines the motion of the associated vehicle in the world position format using a polyline. Setting TrajectoryFollowingMode to position forces the actor to strictly adhere to the specified trajectory. Exported trajectories do not include a time dimension.

<PrivateAction>
  <RoutingAction>
    <FollowTrajectoryAction>
       <Trajectory closed="false" name="Trajectory1">
         <Shape>
           <Polyline>
             <Vertex time="1">
               <Position>
                 <WorldPosition h="0" p="0" r="0" x="5" y="0" z="0"/>
               </Position>
             </Vertex>
             <Vertex time="2">
               <Position>
                 <WorldPosition h="0" p="0" r="0" x="10" y="0" z="0"/>
               </Position>
             </Vertex>
           </Polyline>
         </Shape>
      </Trajectory>
      <TimeReference/>      
      <TrajectoryFollowingMode followingMode="position"/>
    </FollowTrajectoryAction>
  </RoutingAction>
</PrivateAction>

Note

  • The app interpolates additional waypoints between the ones specified in the driving scenario, to generate smooth trajectories for exported actors in the output ASAM OpenSCENARIO file.

  • The app does not support exporting reverse waypoints of actors to an ASAM OpenSCENARIO file.

Speed

When the speed of a vehicle changes in the scenario, the app exports this information to a SpeedAction element in the output ASAM OpenSCENARIO file. The app exports speed changes as a constant rate of change toward a target speed by setting the dynamicsDimension and dynamicsShape attributes of the SpeedActionDynamics element to rate and linear, respectively.

<PrivateAction>
  <LongitudinalAction>
    <SpeedAction>
      <SpeedActionDynamics dynamicsDimension="rate" dynamicsShape="linear" value="5"/>
      <SpeedActionTarget>
        <AbsoluteTargetSpeed value="26"/>
      </SpeedActionTarget>
    </SpeedAction>
  </LongitudinalAction>
</PrivateAction>

Wait Time

When an actor in a driving scenario uses the wait (s) parameter, the app exports this information using the delay attribute of the condition element that triggers the event that executes the next SpeedAction.

In this sample code, the ego vehicle stops at the specified waypoint for 0.5 seconds and then continues traveling forward. The event DS_Event_Ego4 specifies that the ego vehicle comes to a rest position. The code represents the wait time information using the delay attribute of the DS_Cond5 condition, which triggers the event after DS_Event_Ego4. As a result, the ego vehicle waits for 0.5 seconds after coming to rest before it begins moving again.

<Event name="DS_Event_Ego4" priority="overwrite">
  <Action name="DS_Action_Ego4">
    <PrivateAction>
      <LongitudinalAction>
        <SpeedAction>
          <SpeedActionDynamics dynamicsDimension="rate" dynamicsShape="linear" value="-0.54932"/>
          <SpeedActionTarget>
            <AbsoluteTargetSpeed value="0"/>
          </SpeedActionTarget>
        </SpeedAction>
      </LongitudinalAction>
    </PrivateAction>
  </Action>
  <StartTrigger>
    <ConditionGroup>
      <Condition conditionEdge="none" delay="0" name="DS_Cond4">
        <ByEntityCondition>
          <TriggeringEntities triggeringEntitiesRule="any">
            <EntityRef entityRef="Ego"/>
          </TriggeringEntities>
          <EntityCondition>
            <ReachPositionCondition tolerance="2.0">
              <Position>
                <WorldPosition x="57" y="0" z="0"/>
              </Position>
            </ReachPositionCondition>
          </EntityCondition>
        </ByEntityCondition>
      </Condition>
    </ConditionGroup>
  </StartTrigger>
</Event>
<Event name="DS_Event_Ego5" priority="overwrite">
  <Action name="DS_Action_Ego5">
    <PrivateAction>
      <LongitudinalAction>
        <SpeedAction>
          <SpeedActionDynamics dynamicsDimension="rate" dynamicsShape="linear" value="0.77556"/>
          <SpeedActionTarget>
            <AbsoluteTargetSpeed value="2.5926"/>
          </SpeedActionTarget>
        </SpeedAction>
      </LongitudinalAction>
    </PrivateAction>
  </Action>
  <StartTrigger>
    <ConditionGroup>
      <Condition conditionEdge="none" delay="0.5" name="DS_Cond5">
        <ByValueCondition>
          <StoryboardElementStateCondition state="completeState" storyboardElementRef="DS_Action_Ego4" storyboardElementType="action"/>
        </ByValueCondition>
      </Condition>
    </ConditionGroup>
  </StartTrigger>
</Event>

Actor spawn and despawn

When you enable the Actor spawn and despawn parameter, with valid values for the Entry Time (s) and Exit Time (s) parameters, the app exports this information using the VisibilityAction element.

<PrivateAction>
  <VisibilityAction graphics="true" sensors="true" traffic="true"/>
</PrivateAction>

Limitations

The Driving Scenario Designer app does not support all components of the ASAM OpenSCENARIO specification. This table shows the list of supported elements and attributes.

Supported Element or Attribute
AbsoluteTargetSpeed
Act
Action
Actors
Axle
Axles
BoundingBox
ByEntityCondition
ByValueCondition
CatalogReference
Center
Clothoid
Condition
ConditionGroup
Dimensions
Directory
Entities
EntityCondition
EntityObject
EntityRef
Event
File
FileHeader
FollowTrajectoryAction
Init
LongitudinalAction
Maneuver
ManeuverGroup
MiscObject
OpenScenario
Pedestrian
Performance
Polyline
Position
Private
PrivateAction
ReachPositionCondition
RoadNetwork
Route
RoutingAction
ScenarioObject
Shape
SimulationTimeCondition
SpeedAction
SpeedActionTarget
Story
Storyboard
StoryboardElementStateCondition
TeleportAction
Trajectory
Trigger
TriggeringEntities
Vehicle
VehicleCatalogLocation
Vertex
VisibilityAction
Waypoint
WorldPosition

See Also

Apps

Objects

Functions

Related Topics

External Websites