Main Content

exportToDrivingScenario

Export trajectory to driving scenario

Since R2024b

collapse all in page

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.

example

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

example

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.

example

Examples

collapse all

This example uses:

Open Live Script

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

This example uses:

Open Live Script

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

collapse all

Trajectory data, specified as a Trajectory 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 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 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 NameShort NameRGB TripletHexadecimal Color CodeAppearance
"red""r"[1 0 0]"#FF0000"

Sample of the color red

"green""g"[0 1 0]"#00FF00"

Sample of the color green

"blue""b"[0 0 1]"#0000FF"

Sample of the color blue

"cyan" "c"[0 1 1]"#00FFFF"

Sample of the color cyan

"magenta""m"[1 0 1]"#FF00FF"

Sample of the color magenta

"yellow""y"[1 1 0]"#FFFF00"

Sample of the color yellow

"black""k"[0 0 0]"#000000"

Sample of the color black

"white""w"[1 1 1]"#FFFFFF"

Sample of the color white

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

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.

ClassIDClass Name
1Car
2Truck
3Bicycle
4Pedestrian

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

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

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"

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 1 (HDLM) web service.

  • "ZenrinJapanMap" — Imports roads from a Zenrin Japan Map API 3.0 (Itsumo NAVI API 3.0) 2 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.

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 SourceValid File ExtensionsSample Syntax
OpenDRIVE®

.xodr

.xml

 
FileName="C:\Desktop\roads.xodr"
OpenStreetMap

.osm

.xml

 
FileName="C:\Desktop\map.osm"

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.

Map of an intersection with a rectangular bounding box around it. Moving clockwise from the top, the sides are labeled maxLat, maxLon, minLat, and minLon.

  • 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.

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

collapse all

Driving scenario, returned as a drivingScenario object.

Version History

Introduced in R2024b

See Also

| | | |

1 You need to enter into a separate agreement with HERE in order to gain access to the HDLM services and to get the required credentials (access_key_id and access_key_secret) for using the HERE Service.

2 To gain access to the Zenrin Japan Map API 3.0 (Itsumo NAVI API 3.0) service and get the required credentials (a client ID and secret key), you must enter into a separate agreement with ZENRIN DataCom CO., LTD.