Main Content

table2scenario

Generate scene and scenario from tabular data

Since R2024a

Description

descriptor = table2scenario(sceneSpec) generates a scene as a ScenarioDescriptor object, descriptor, by using the information in the input scene specification table sceneSpec. For best results, create specification tables using CSV files or spreadsheet files (including from Microsoft® Excel®), and then convert them to the MATLAB table format by using the readtable function.

example

descriptor = table2scenario(sceneSpec,actorSpec) includes actors in the generated scene by using the information in the input actor specification table actorSpec.

descriptor = table2scenario(sceneSpec,actorSpec,eventSpec) includes a scenario with trajectories for the actors in the generated scene by using the information in the event specification table eventSpec.

example

descriptor = table2scenario(___,Name=Value) specifies options using one or more name-value arguments in addition to any combination of input arguments from previous syntaxes. For example, ShowPlot=true creates a figure and displays the generated scene.

Note

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

example

Examples

collapse all

Load a table containing scene specifications into the workspace.

sceneSpec = load("sceneData.mat");

Generate a ScenarioDescriptor object by using the loaded data.

scenarioDescriptor = table2scenario(sceneSpec.sceneData);

Create a drivingScenario object from the generated ScenarioDescriptor object.

scenarioDS = getScenario(scenarioDescriptor,Simulator="DrivingScenario");

Visualize the roads in the scene created using the scene specification table.

plot(scenarioDS)

Load a table containing lane specifications and a table containing scene specifications into the workspace

laneSpec = load("laneData.mat");
sceneSpec = load("sceneDataWithLane.mat");

Generate a ScenarioDescriptor object by using the loaded tabular data, and plot the scene.

scenarioDescriptor = table2scenario(sceneSpec.sceneData,LaneSpec=laneSpec.laneData,ShowPlot=true);

Load a table containing scene specifications, a table containing actor specifications, and a table containing actor event specifications into the workspace.

sceneSpec = load("sceneData.mat");
actorSpec = load("actorData.mat");
eventSpec = load("eventData.mat");

Generate a ScenarioDescriptor object by using the loaded tabular data.

scenarioDescriptor = table2scenario(sceneSpec.sceneData,actorSpec.actorData,eventSpec.eventData);

Create a drivingScenario object from the ScenarioDescriptor object.

scenarioDS = getScenario(scenarioDescriptor,Simulator="DrivingScenario");

Open the generated driving scenario in the Driving Scenario Designer app.

drivingScenarioDesigner(scenarioDS)

This figure shows the generated driving scenario in the Driving Scenario Designer app.

Click the Run button to run and visualize the scenario. Observe that the scenario contains three actors performing their events as specified in the event specification table, eventSpec.eventData.

This figure shows thre generated driving scenario containing three actors in the Driving Scenario Designer app.

Input Arguments

collapse all

Scene specifications, specified as a table. Each row in the table contains the specifications for a road element, such as a road or junction. Each column specifies one type of road element information, such as element ID, element type, length of the road, or change in heading angle of the road. For more information on the scene specification table, see Scene Specification Table.

Actor specifications, specified as a table. Each row in the table contains the specifications for an actor. Each column specifies one type of actor information, such as actor ID, actor type, actor name, or actor position. For more information on the actor specification table, see Actor Specification Table.

Actor event specifications, specified as a table. Each row in the table contains the specifications for an actor event, such as initialization, turning, lane change, or speed change. Each column specifies one type of actor event information, such as event ID, actor ID, event type, or actor speed. For more information on the actor event specification table, see Event Specification Table.

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: table2scenario(sceneSpec,ShowPlot=true) returns a descriptor which contains a scene and displays it in a figure.

Lane specifications, specified as a table. Each row in the table contains the lane specifications for a road, and each column specifies one type of lane specification information, such as number of lanes, lane markings, and lane type. For more information on the lane specification table, see Lane Specification Table.

Driving direction of the lanes, specified as "Right" or "Left".

Scene plot display, specified as a logical 1 (true) or 0 (false). Specify true to display the generated scene with travel directions of lanes embedded. Otherwise, specify this value as false.

Output Arguments

collapse all

Scenario descriptor, returned as a ScenarioDescriptor object. The Status property of the descriptor object indicates "DescriptorCreated" when the object has been successfully created.

The ScenarioDescriptor object stores scene, actor, and vehicle information extracted from the input tabular data. You can use this information to generate scenario variants to perform safety assessments for various automated driving applications.

More About

collapse all

Scene Specification Table

Specify the column names in the first row of your spreadsheet or CSV file. The scene specification tables can contain these columns.

ColumnDescription
RoadElementID

ID of the road element, specified as a positive integer.

RoadElementType

Type of road element, specified as one of these road element types:

  • Straight — Creates a straight road.

  • Right — Creates a road turning to the right.

  • Left — Creates a road turning to the left.

  • SymmetricJunction — Creates a symmetric junction.

Note

When you specify RoadElementType as Right or Left, you must specify DeltaHeading as a positive scalar greater than or equal to 1.

Length_Radius

Length of the road or radius of curvature for the junction, specified as a positive scalar. This table describes the values of Length_Radius that you must specify for each value of RoadElementType. The value you specify for Length_Radius depends on the value of RoadElementType for that road:

  • Straight, Right, or Left — The Length_Radius column specifies the length of the road, in meters, as a scalar.

  • SymmetricJunction — The Length_Radius column specifies the radius of a circle between two adjacent roads connecting at a symmetric junction, in meters, as a scalar.

    Radius of a circle between two adjacent roads connecting at a symmetric junction.

DeltaHeading

Change in the heading angle of a road, specified as positive scalar. Units are in degrees. This table describes the values of DeltaHeading that you must specify for its respective types of RoadElementType. The value you specify for DeltaHeading depends on the value of RoadElementType for that road:

  • Straight — The DeltaHeading column specifies the change in the heading angle of a road, specified as 0.

  • Right, or Left — The DeltaHeading column specifies the change in the heading angle of a road, in degrees, specified as a positive scalar.

  • SymmetricJunction — The DeltaHeading is not applicable, specified as NaN.

ParentIntersectionID (optional)

ID of parent intersection junction linked to the current road, specified as a positive integer. The ParentIntersectionID must be one of the RoadElementIDs that you specified for a junction in the table. Specify the ParentIntersectionID for only the roads with RoadElementType of Straight, Right, or Left connected to a junction.

This value must be NaN for roads that satisfy one or more of these conditions:

  • Roads that you do not connect to a junction.

  • Roads with a RoadElementType of SymmetricJunction.

  • The table row specified before the row with a RoadElementType of SymmetricJunction.

  • The table row specified after the row with a RoadElementType of SymmetricJunction.

Note

Include the ParentIntersectionID column when you create a scene that contain junctions.

LaneSpecID (optional)

ID of the lane specification, specified as a positive integer. The ID must match a LaneSpecID value from the lane specification table, LaneSpec. For more information on lane specification tables, see Lane Specification Table.

Note

Include the LaneSpecID column when you specify lane specifications using the LaneSpec name-value argument.

This example shows a scene specification table and the scene created using it.

Scene Specification TableGenerated Scene

An example of a scene specification table.

Generated scene using the scene specification table.

Lane Specification Table

Lane specification tables must contain these columns.

ColumnDescription
LaneSpecID

ID of the lane specification, specified as a positive integer.

LeftLaneCount

Number of left lanes, specified as a positive integer.

The default value is 0.

RightLaneCount

Number of right lanes, specified as a positive integer.

The default value is 0.

LaneMarking

Lane marking, specified as Solid, Dashed, or Unmarked.

The default value is Solid.

This example shows a scene specification table, a lane specification table, and the scene created using them.

Scene and Lane Specification TablesGenerated Scene

An example of scene specification table:

An example of a scene specification table.

Generated scene using the scene and lane specification tables.

An example of lane specification table: An example of a lane specification table.

Actor Specification Table

Actor specification tables must contain these columns.

ColumnDescription
ActorID

ID of the actor, specified as a positive integer.

RoadID

ID of the road on which to place the actor, specified as a positive integer.

LaneID

ID of the lane on which to place the actor, specified as a positive integer.

ActorType

Type of the actor, specified as Car, Truck, Bicycle, Pedestrian, or Other.

The default actor type is Car.

ActorName

Name of the actor, specified as a string.

The default name is a concatenation of the string Actor with the value of ActorID for the corresponding row. For example, for an actor with an ActorID value of 1, the default ActorName value is Actor1.

Dimension

Dimensions of the actor, specified as a six-element row vector of the form [L, W, H, FO, RO, WB].

  • L — Length of the vehicle, in meters, specified as a scalar.

  • W — Width of the vehicle, in meters, specified as a scalar.

  • H — Height of the vehicle, in meters, specified as a scalar.

  • FO — Front overhang of the vehicle, in meters, specified as a scalar.

  • RO — Rear overhang of the vehicle, in meters, specified as a scalar.

  • WB — Distance between the front and rear axles of the vehicle, in meters, specified as a positive scalar.

For more information on these dimensions, see Actor and Vehicle Positions and Dimensions.

If you specify this value in a form other than a six-element row vector, by default, this function uses this value: [4.7, 1.8, 1.4, 0.9, 1.0, 2.8].

Heading

Travel direction of the actor, specified as Along or Across. If the actor travels in the direction of travel of a lane, specify Along. If the actor travels perpendicular to the directions of travel of the road, specify Across.

Travel direction of a car along the road and travel direction of a pedestrian across the road.

The default actor direction is Along.

RelativePosition

Start position of the actor on a lane relative to the lane direction, in percentage, specified as a comma-separated string of the form [longitudinalPercentage, lateralPercentage].

  • longitudinalPercentage — Position of the actor, in percentage, along the lane travel direction, with respect to the total length of the lane. The start and end of the lane represent longitudinal percentages of 0 and 100, respectively. Specify this value as a scalar followed by "%". For example: 30%.

  • lateralPercentage — Position of the actor, in percentage, across the lane travel direction, with respect to the total width of the lane. The left and right lane boundaries represent lateral percentages of 0 and 100, respectively. Specify this value as a scalar followed by "%". For example: 50%.

This figure shows the longitudinal and lateral positions of an actor on a lane, in percentages, relative to the directional lane length and lane width. Note that percentage values are relative to the lane, rather than the road, the actor occupies. Positions of actors on lane relative to lane length and lane width.

The default value of RelativePosition depends on the value you specify for Heading:

  • Along — Default value is ["0%, 50%"].

  • Across — Default value is ["50%, 0%"].

For more information on using the actor specification table, see the Generate Scenario Using Tabular Data example.

Event Specification Table

Actor event specification tables must contain these columns.

ColumnDescription
EventID

ID of the actor event, specified as a positive integer.

ActorID

ID of the actor, specified as a positive integer.

EventType

Type of event, specified as one of these values which are specified in the Event Name column.

Initialization Events

Event NameDescription
AcceleratedStart

Actor accelerates to achieve a specified speed, Speed, at a specified distance, Distance.

FixedVelocityStart

Actor spawns at a specified speed Speed.

Turn Events

Event NameDescription
TurnLeft

Actor makes a left turn.

TurnRight

Actor makes a right turn.

Lane Events

Event NameDescription
LaneChangeLeft

Actor changes lane to the lane on the left.

LaneChangeRight

Actor changes lane to the lane on the right.

DriftLeft

Actor drift towards the left lane boundary.

DriftRight

Actor drift towards the right lane boundary.

Speed Change Event

Event NameDescription
SpeedChange

Actor accelerates or decelerates to a specified speed, Speed, within a specified distance, Distance.

Speed

Speed of the actor at the end of the event, specified as a scalar. Units are in meters per second.

  • For initialization events, the default speed is 30.

  • For the events other than initialization events, the default value is the speed of the actor at the end of the previous event.

  • Negative speed value represents the actor travels in the direction opposite to the lane direction.

Distance

Distance at which the actor completes the event, specified as a scalar or a three-element row vector. Units are in meters.

These table describes how to specify Distance for each type of event, EventType.

Initialization Events

EventTypeDistance Value
AcceleratedStart

Specify as a positive scalar.

The default value is 1.5.

FixedVelocityStart

Not applicable. Leave this field as blank.

Turn Events

EventTypeDistance Value
TurnLeft

Not applicable. Leave this field as blank.

TurnRight

Not applicable. Leave this field as blank.

Lane Events

EventTypeDistance Value
LaneChangeLeft

Specify as a positive scalar. For more information on lane change events, see the generateWaypoints function.

The default value is 5.

LaneChangeRight

Specify as a positive scalar. For more information on lane change events, see the generateWaypoints function.

The default value is 5.

DriftLeft

Specify as a two-element row vector of positive values of the form [curveDriftDistance, radiusOfCurvature]. For more information on these parameters, see Lane Drift Parameters.

The default value is [0.54, 1200].

DriftRight

Specify as a two-element row vector of positive values of the form [curveDriftDistance, radiusOfCurvature]. For more information on these parameters, see Lane Drift Parameters.

The default value is [0.54, 1200].

Speed Change Event

EventTypeDistance Value
SpeedChange

Specify as a positive scalar.

The default value is 1.5.

EventTrigger

Distance for the actor to travel on its current lane to trigger the event, specified as a positive scalar. Units are in meters.

The default value is 0.

For more information on using the actor event specification table, see Generate Scenario Using Tabular Data example.

Tips

  • To create input specification tables from a spreadsheet file (including from Microsoft Excel), use the readtable function.

  • To get a scenario from a ScenarioDescriptor object, use the getScenario function.

Version History

Introduced in R2024a