exportToDrivingScenario

Export trajectory to driving scenario

Since R2024b

Syntax

outputScenario = exportToDrivingScenario(trajectory)

outputScenario = exportToDrivingScenario(trajectory,inputScenario)

outputScenario = exportToDrivingScenario(___,Name=Value)

Description

outputScenario = exportToDrivingScenario(trajectory) exports the input trajectory trajectory to driving scenario outputScenario.

outputScenario = exportToDrivingScenario(trajectory,inputScenario) exports the trajectory trajectory into the input scenario inputScenario and returns the updated scenario outputScenario.

outputScenario = exportToDrivingScenario(___,Name=Value) specifies options using one or more name-value arguments in addition to any combination of input arguments from the previous syntaxes. For example, AssetType="Bicycle" exports a bicycle actor to driving scenario.

Note

This function requires the Scenario Builder for Automated Driving Toolbox™ support package. You can install the Scenario Builder for Automated Driving Toolbox support package from the Add-On Explorer. For more information about installing add-ons, see Get and Manage Add-Ons.

Examples

Export Trajectory to Driving Scenario

Load recorded GPS trajectory data into the workspace.

load("recordedGPSData.mat","X","Y","Z","timestamps")

Create a trajectory object by using the loaded timestamps and xyz-coordinates.

traj = scenariobuilder.Trajectory(timestamps,X,Y,Z);

Normalize timestamps of trajectory object.

normalizeTimestamps(traj)

Smooth the trajectory in the trajectory object.

smooth(traj)

Export the trajectory to driving scenario.

scenario = exportToDrivingScenario(traj)

scenario = 
  drivingScenario with properties:

        SampleTime: 0.0500
          StopTime: 19.5498
    SimulationTime: 0
         IsRunning: 1
            Actors: [1×1 driving.scenario.Vehicle]
          Barriers: [0×0 driving.scenario.Barrier]
       ParkingLots: [0×0 driving.scenario.ParkingLot]

Add a 6 meter width road along the waypoints.

road(scenario,traj.Position,6);

Visualize the driving scenario.

restart(scenario)
chasePlot(scenario.Actors,Centerline="on")
while advance(scenario)
     pause(0.01)   
end

Export Trajectory with Road Network to Driving Scenario

Load recorded GPS data into the workspace.

load("recordedGPSData.mat","latitudes","longitudes","altitudes","timestamps")

Initialize a GPSData object using the information from the GPS data.

gpsData = scenariobuilder.GPSData(timestamps,latitudes,longitudes,altitudes)

gpsData = 
  GPSData with properties:

          Name: ''

    NumSamples: 392
      Duration: 19.5498
    SampleRate: 20.0513
    SampleTime: 0.0500
    Timestamps: [392×1 double]

      Latitude: [392×1 single]
     Longitude: [392×1 single]
      Altitude: [392×1 single]

    Attributes: []

Create a trajectory object from GPS data object.

traj = trajectory(gpsData)

traj = 
  Trajectory with properties:

               Name: ''

         NumSamples: 392
           Duration: 19.5498
         SampleRate: 20.0513
         SampleTime: 0.0500
         Timestamps: [392×1 double]

           Position: [392×3 double]
        Orientation: [392×3 double]
           Velocity: [392×3 double]
             Course: [392×1 double]
        GroundSpeed: [392×1 double]
       Acceleration: [392×3 double]
    AngularVelocity: [392×3 double]

        LocalOrigin: [45.5278 -122.6556 0]
         TimeOrigin: 1.4616e+09

         Attributes: []

Smooth the trajectory in the trajectory object.

smooth(traj)

Use the latitude and longitude to fetch the map parameters.

mapParameters = getMapROI(gpsData.Latitude,gpsData.Longitude);

Use the osmUrl parameter in the mapParameters output structure to import and save the OpenStreetMap® file.

fileName = websave("drive_map.osm",mapParameters.osmUrl, ...
    weboptions(ContentType="xml"));

Export the trajectory and the imported OpenStreetMap road network to driving scenario.

scenario = exportToDrivingScenario(traj,"RoadNetworkSource","OpenStreetMap",FileName=fileName);

Visualize the driving scenario.

restart(scenario)
chasePlot(scenario.Actors,Centerline="on")
while advance(scenario)
     pause(0.01)   
end

Input Arguments

trajectory — Trajectory data

Trajectory object

Trajectory data, specified as a Trajectory object.

inputScenario — Driving scenario

drivingScenario object

Driving scenario, specified as a drivingScenario object.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: exportToDrivingScenario(trajectory,Color="blue") exports a blue color actor to driving scenario.

Name — Name of actor in driving scenario

"auto" (default) | string scalar | character vector

Name of the actor in driving scenario, specified as a string scalar or character vector. driving scenario uses the name specified by this argument for the actor it associates with your exported trajectory. By default, the function assigns the name for the actor as vehicle. For an existing actor with name Name, the function appends an incremental numeric integer at the end of the name. For example, if an actor with name vehicle already exists, the function names the actor as vehicle1 instead.

Example: Name="Actor1" specifies the name of the actor as Actor1.

Data Types: char | string

Color — Color of actor in driving scenario

"auto" (default) | string scalar | character vector | 3-element row vector | hexadecimal color code

Color of the actor in driving scenario, specified as "auto", a string scalar, or character vector corresponding to an SVG 1.0 color name, such as "blue", a 3-element row vector of values in the range [0,1], where the values correspond to the intensities of the red, green, and blue components of color, respectively, or a hexadecimal color code, such as "#0072BD". Driving scenario uses the color specified by this argument for the actor it associates with your exported trajectory. By default, the function automatically assigns a color for the actor.

This table lists the valid color names with the equivalent RGB triplets and hexadecimal color codes.

Color Name	Short Name	RGB Triplet	Hexadecimal Color Code	Appearance
"red"	"r"	[1 0 0]	"#FF0000"
"green"	"g"	[0 1 0]	"#00FF00"
"blue"	"b"	[0 0 1]	"#0000FF"
"cyan"	"c"	[0 1 1]	"#00FFFF"
"magenta"	"m"	[1 0 1]	"#FF00FF"
"yellow"	"y"	[1 1 0]	"#FFFF00"
"black"	"k"	[0 0 0]	"#000000"
"white"	"w"	[1 1 1]	"#FFFFFF"

Example: Color="Green" sets the color of the actor in driving scenario to green.

ClassID — Classification identifier

1 (default) | nonnegative integer

Classification identifier of actor, specified as a nonnegative integer.

The ClassID as 0 is reserved for an object of an unknown or unassigned class. If you plan to import drivingScenario objects into the Driving Scenario Designer app, do not set the ClassID property of actors to 0. The app does not recognize a ClassID of 0 for actors and returns an error. Instead, set one of these ClassID values of actors.

ClassID	Class Name
1	Car
2	Truck
3	Bicycle
4	Pedestrian

Mesh — Mesh representation of actor

driving.scenario.carMesh (default) | extendedObjectMesh object

Mesh representation of the actor, specified as an extendedObjectMesh object. You can use a mesh created by one of these functions:

• driving.scenario.carMesh — Represents mesh of a car in driving scenario.

• driving.scenario.truckMesh — Represents mesh of a truck in driving scenario.

• driving.scenario.bicycleMesh — Represents mesh of a bicycle in driving scenario.

• driving.scenario.pedestrianMesh — Represents mesh of a pedestrian in driving scenario.

You can develop your own mesh by using a prebuilt mesh as a starting point. For example, to edit a car mesh, at the MATLAB^® command line, enter:

edit driving.scenario.carMesh

AssetType — Type of 3-D display asset

"Sedan" (default) | string scalar of valid asset type

Type of 3-D display asset, specified as a string scalar of valid asset type. You can specify one of these 3-D display assets:

• "Cuboid"

• "Sedan"

• "MuscleCar"

• "Hatchback"

• "SportUtilityVehicle"

• "SmallPickupTruck"

• "BoxTruck"

• "Bicyclist"

• "MalePedestrian"

• "FemalePedestrian"

RoadNetworkSource — Source of road network to import road data

[] (default) | string scalar of valid road network source

Source of the road network to import road data, specified as a string scalar of valid road network source. You can specify one of these road network sources:

• "OpenDrive" — Imports roads from an ASAM OpenDRIVE^® road network file. You must specify the road network filename using the FileName name-value argument.

• "OpenStreetMap" — Imports roads from an OpenStreetMap^® road network file. You must specify the road network filename using the FileName name-value argument.

• "HEREHDLiveMap" — Imports roads from a HERE HD Live Map ¹ (HDLM) web service.

• "ZenrinJapanMap" — Imports roads from a Zenrin Japan Map API 3.0 (Itsumo NAVI API 3.0) ² web service.

  Importing roads from the Zenrin Japan Map API 3.0 (Itsumo NAVI API 3.0) service requires Automated Driving Toolbox Importer for Zenrin Japan Map API 3.0 (Itsumo NAVI API 3.0) Service.

FileName — Name of road network file

[] (default) | character vector | string scalar

Name of the road network file, specified as a character vector or string scalar.

FileName must specify a file in the current folder, a file that is on the MATLAB search path, or a full or relative path to a file.

FileName must end with a file extension that is valid for the source of the road network.

Road Network Source	Valid File Extensions	Sample Syntax
OpenDRIVE®	.xodr .xml	FileName="C:\Desktop\roads.xodr"
OpenStreetMap	.osm .xml	FileName="C:\Desktop\map.osm"

GeoCoordinates — Geographic coordinates to download road network

N-by-2 matrix | 4-element row vector

Geographic coordinates to download road network from HERE HD Live Map or Zenrin Japan Map API 3.0 (Itsumo NAVI API 3.0), specified as an N-by-2 matrix or a 4-element row vector.

If you specify an N-by-2 matrix, value must be in the form [lat; lon]. N is the number of geographic coordinates. Values of lat must be in the range [–90, 90] and values of lon must be in range [–180, 180]. Units are in degrees.

If you specify a 4-element row vector, value must be in the form [minLat minLon maxLat maxLon] representing a bounding box. The exportToDrivingScenario function imports any roads that are at least partially within the specified bounding box. This figure displays the relationship between these coordinates.

• minLat — Minimum latitude coordinate of the bounding box, specified as a scalar in the range [–90, 90]. minLat must be less than maxLat. Units are in degrees.

• minLon — Minimum longitude coordinate of the bounding box, specified as a scalar in the range [–180, 180]. minLon must be less than maxLon. Units are in degrees.

• maxLat — Maximum latitude coordinate of the bounding box, specified as a scalar in the range [–90, 90]. maxLat must be greater than minLat. Units are in degrees.

• maxLon — Maximum longitude coordinate of the bounding box, specified as a scalar in the range [–180, 180]. maxLon must be greater than minLon. Units are in degrees.

SetupSimulation — Set up driving scenario simulation status

true or 1 (default) | false or 0

Set up driving scenario simulation status, specified as a logical 1 (true) or 0 (false).

By default, the function updates the simulation stop time and sample time per the input trajectory trajectory. Use this name-value argument when you export multiple trajectories to a scenario and you want to set up the driving scenario simulation parameters for a specific actor trajectory. For example, specify true for an ego trajectory and specify false for other actor trajectories.

Data Types: logical

Output Arguments

outputScenario — Driving scenario

drivingScenario object

Driving scenario, returned as a drivingScenario object.

Version History

Introduced in R2024b