Main Content

generateVariants

Generate variant scenario descriptors from seed scenario descriptor using specified variations

Since R2023a

collapse all in page

Syntax

variantDescriptors = generateVariants(descriptor,variations)
[variantDescriptors,variantInfo] = generateVariants(descriptor,variations)

Description

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

example

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

Note

This function requires the Automated Driving Toolbox™ Test Suite for Euro NCAP® Protocols support package. You can install 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

collapse all

This example uses:

Open Live Script

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

Figure contains 2 axes objects and other objects of type uipanel. Axes object 1 with xlabel X (m), ylabel Y (m) contains 6 objects of type patch, line. One or more of the lines displays its values using only markers Axes object 2 with xlabel X (m), ylabel Y (m) contains 6 objects of type patch, line. One or more of the lines displays its values using only markers

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.

BehaviorUnderTest

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

  • HandoverTime — Time to hand over of control. Units are in seconds.

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

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

EventTime (since R2024a)

Time at which an event occurs, returned as a scalar. For example, for a collision event, this field represents the time at which the collision occurs. Units are in seconds.

EgoTrajectory (since R2024a)

Trajectory information of the ego vehicle, returned as a structure with these fields:

  • Timestamps — Ego simulation timestamps, returned as an N-element column vector. N is the number of timestamps.

  • Waypoints — Waypoints referenced to the rear-wheel axle-center of the ego, returned as an N-by-3 matrix. The number of waypoints is equal to the number of timestamps. Each row is a waypoint of the ego vehicle in the form [x y z]. Units are in meters.

  • Velocity — Velocities of the ego vehicle, returned as an N-by-3 matrix. Each velocity value corresponds to the associated element of Waypoints. Each row is a velocity of the ego vehicle in the form [vx vy vz]. Units are in meters per second.

  • Roll — Roll angles of the ego vehicle, returned as an N-element column vector. Each roll value corresponds to the associated element of Waypoints. Units are in radians.

  • Pitch — Pitch angles of the ego vehicle, returned as an N-element column vector. Each pitch value corresponds to the associated element of Waypoints. Units are in radians.

  • Yaw — Yaw angles of the ego vehicle, returned as an N-element column vector. Each yaw value corresponds to the associated element of Waypoints. Units are in radians.

  • AngularVelocity — Rotational velocities of the ego vehicle, returned as an N-by-3 matrix. Each velocity value corresponds to the associated element of Waypoints. Each row is an angular velocity of the ego vehicle in the form [avx avy avz]. The magnitude of each element defines the angular speed, in degrees per second, and the direction defines the axis of clockwise rotation.

  • EgoCenterWaypoints — Waypoints referenced to the ego vehicle center, returned as an N-by-3 matrix. Each center waypoint value corresponds to the associated element of Waypoints. Each row is a waypoint of the ego vehicle center in the form [x y z]. Units are in meters.

Note

If the function is unable to identify an ego, it returns the trajectory data of its first identified actor.

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

See Also

| | | |