Main Content

generateVariants

Generate variant scenario descriptors from seed scenario descriptor using specified variations

Since R2023a

Description

example

variantDescriptors = generateVariants(descriptor,variations) generates scenario variant descriptors using the seed scenario descriptor descriptor and variation properties object variations.

[variantDescriptors,variantInfo] = generateVariants(descriptor,variations) also returns a structure, variantInfo, containing the properties of actor and collision variations.

Note

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

Examples

collapse all

Load a driving scenario into the workspace.

load("scenarioWithSingleActor.mat")

Create a scenario descriptor from the input seed scenario.

seedScenarioDescriptor = getScenarioDescriptor(scenario,Simulator="DrivingScenario");

Create a variationProperties object.

variation = variationProperties;

Specify actor dimension variations.

dimension=struct("Length",2,"Width",2,"Height",4);

Add a speed variation for the actor with an actorID of 1.

varyActorProperties(variation,1,Speed=10,Dimension=dimension);

Using the seed scenario descriptor and the speed variation, generate a scenario variant descriptor.

scenarioVariantDescriptor = generateVariants(seedScenarioDescriptor,variation);

Generate a variant scenario, as a drivingScenario object, from the scenario variant descriptor object.

scenarioVariant = getScenario(scenarioVariantDescriptor,Simulator="DrivingScenario");

Create a custom figure window to plot the seed scenario and the scenario variant.

figScene = figure;
set(figScene,Position=[200 200 600 300])
hCarViewPanel1 = uipanel(figScene,Position=[0 0 0.5 1],Title="Input Seed Scenario");
hCarPlot1 = axes(hCarViewPanel1);
hCarViewPanel2 = uipanel(figScene,Position=[0.5 0 0.5 1],Title='Generated Scenario Variant');
hCarPlot2 = axes(hCarViewPanel2);

Plot both the scenarios and run the simulation. Observe the actor speed and dimension variation in the generated scenario variant.

plot(scenario,Waypoints="on",Parent=hCarPlot1)
plot(scenarioVariant,Waypoints="on",Parent=hCarPlot2)
flag1 = 1;
flag2 = 1;
while (flag1 || flag2)
    if(flag1)
        flag1 = advance(scenario);
    end
    if(flag2)
        flag2 = advance(scenarioVariant);
    end
    pause(0.01)
end

Input Arguments

collapse all

Scenario descriptor, specified as a ScenarioDescriptor object. The ScenarioDescriptor object stores scene, actor, and vehicle information extracted from a seed scenario.

To get a ScenarioDescriptor object from an input scenario, use the getScenarioDescriptor function.

Variation properties, specified as a 1-by-N vector of variationProperties objects. N is the number of scenarios with variation properties. The variationProperties object stores actor and collision variation properties to use to create scenario variants.

Output Arguments

collapse all

Scenario variant descriptors, returned as a 1-by-N vector of ScenarioDescriptor objects. N is the number of variant scenarios. For each variation specified in the input variations argument, this function generates a scenario variant descriptor.

The generateVariants function extracts information from the input seed scenario descriptor descriptor, modifies the actor and collision properties specified by the variations input argument, and stores the returned scenario variant descriptors in variantDescriptors. You can use these scenario variant descriptors to perform safety assessments for various automated driving applications.

Variant information, returned as a 1-by-N array of structures. N is the number of scenarios with variant information. Each structure contains these fields:

FieldDescription
ValidVariant

Valid variant flag, returned as 1 if the generated variant has all the specified variations. Otherwise, it returns a 0.

ActorVariationProperties

Actor variation properties, returned as a structure with these fields:

  • ActorID — ID of the actor, returned as a positive integer.

  • Speed — Speed of the actor, returned as a scalar or an M-element row vector. M is the number of waypoints. Units are in meters per second.

  • Dimension — Dimensions of the actor, returned as a structure with fields Length, Width, and Height. Units are in meters.

  • Waypoints — Waypoints of the actor, returned as an M-by-3 matrix. M is the number of waypoints. Each row represents the actor position in the form [x y z]. Units are in meters.

  • Yaw — Yaw angle of the actor, returned as an M-element column vector. M is the number of waypoints. Units are in radians.

CollisionVariationProperties

Collision variation properties, returned as a structure with these fields:

  • Actor1ID — ID of the first colliding actor in the pair, returned as a positive integer.

  • Actor2ID — ID of the second colliding actor in the pair, returned as a positive integer.

  • Actor1CollisionFraction — Point of collision relative to the collision side of the first actor, returned as a scalar in the range [0, 1]. For more information, see Collision Fraction.

  • Actor1CollisionSide — Side of the first actor at which the collision occurs, returned as "Front", "Left", "Back", or "Right".

  • Actor2CollisionFraction — Point of collision relative to the collision side of the second actor, returned as a scalar in the range [0, 1]. For more information, see Collision Fraction.

  • Actor2CollisionSide — Side of the second actor at which the collision occurs, returned as "Front", "Left", "Back", or "Right".

  • VariationType — Parameter to change to generate variant, returned as "WaitTime", "EntryTime", or "Waypoints".

Messages

Messages and warnings related to the generated variants, returned as a string scalar or character vector.

The generateVariants function displays messages for a variant if its ValidVariant value is 0.

BehaviourUnderTest

Behavioural safety assessment test parameters, returned as a structure with these fields:

  • HandoverTime — Time to handover control. Units are in seconds.

  • StartTestTime — Time to start the safety assessment test. Units are in seconds.

  • EndTestTime — Time to end the safety assessment test. Units are in seconds. By default, this function returns the simulation end time.

Limitations

  • To apply collision variations, your seed scenario must contain actor collisions.

  • The collision side of an actor in the seed scenario must match the collision side of that actor for which you generate variants.

  • To generate actor collision fraction variations, the actors in the seed scenario must collide at 0 degree and 90 degree angles.

Version History

Introduced in R2023a

expand all