table2scenario

Generate scene and scenario from tabular data

Since R2024a

Syntax

descriptor = table2scenario(sceneSpec)

descriptor = table2scenario(sceneSpec,actorSpec)

descriptor = table2scenario(sceneSpec,actorSpec,eventSpec)

descriptor = table2scenario(___,Name=Value)

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.

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.

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.

Examples

Create Scene Using Scene Specification Table

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)

Create Scene Using Scene and Lane Specification Tables

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);

Generate Scenario Using Tabular Data

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)

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.

Input Arguments

sceneSpec — Scene specifications

table

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.

actorSpec — Actor specifications

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.

eventSpec — Actor event specifications

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.

LaneSpec — Lane specifications

table

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.

DrivingDirection — Driving direction of lanes

"Right" (default) | "Left"

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

ShowPlot — Scene plot display

false or 0 (default) | true or 1

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

descriptor — Scenario descriptor

ScenarioDescriptor object

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

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.

Column	Description
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.
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 Table	Generated Scene

Lane Specification Table

Lane specification tables must contain these columns.

Column	Description
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 Tables	Generated Scene
An example of scene specification table:
An example of lane specification table:

Actor Specification Table

Actor specification tables must contain these columns.

Column	Description
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. 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. 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.

Column	Description
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 Name Description 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 Name Description TurnLeft Actor makes a left turn. TurnRight Actor makes a right turn. Lane Events Event Name Description 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 Name Description 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 EventType Distance Value AcceleratedStart Specify as a positive scalar. The default value is 1.5. FixedVelocityStart Not applicable. Leave this field as blank. Turn Events EventType Distance Value TurnLeft Not applicable. Leave this field as blank. TurnRight Not applicable. Leave this field as blank. Lane Events EventType Distance 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 EventType Distance 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