varyCollisionProperties

R2026b

Add variations to collision properties

Since R2023a

Syntax

varyCollisionProperties(variations,actor1ID,actor2ID,Name=Value)

varyCollisionProperties(variations,collisionObj,Name=Value)

Description

Add-On Required: This feature requires the Automated Driving Toolbox Test Suite for Euro NCAP Protocols add-on.

varyCollisionProperties(variations,actor1ID,actor2ID,Name=Value) adds property variations for a collision between a pair of actors, actor1ID and actor2ID, in the variationProperties object variations by using one or more name-value arguments.

varyCollisionProperties(variations,collisionObj,Name=Value) adds property variations for a collision specified by the collision object collisionObj in the variationProperties object variations by using one or more name-value arguments.

Examples

Add Collision Property Variations for Pair of Actors

Create an empty variationProperties object.

variation = variationProperties;

Add a collision variation for a pair of actors with actorID values of 1 and 2.

varyCollisionProperties(variation,1,2,Actor2CollisionFraction=0.3)

Display the collision variation information.

disp(variation.CollisionVariationProperties)

                   Actor1ID: 1
                   Actor2ID: 2
    Actor2CollisionFraction: 0.3000
              VariationType: 'WaitTime'

Add Collision Property Variations for Pair of Actors Using collision Object

Load a seed scenario with a single collision into the workspace.

load("seedScenarioWithSingleCollision.mat")

Create a scenarioDescriptor object using the loaded driving scenario scenario.

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

Extract collision information from the scenarioDescriptor object using the collision information from the seed scenario.

collisionsInScenario = getCollisionData(scenarioDescriptor);

Create an empty variationProperties object.

variation = variationProperties;

Add collision variation properties to the variationProperties object.

varyCollisionProperties(variation,collisionsInScenario.Collision,Actor2CollisionFraction=0.3);

Display the collision property variations.

disp(variation.CollisionVariationProperties)

                   Actor1ID: 1
                   Actor2ID: 2
    Actor2CollisionFraction: 0.3000
              VariationType: 'WaitTime'

Generate Collision Variant from Intersecting Trajectories

Load a seed scenario that contains two actors with intersecting trajectories but no collision.

load("scenarioWithNoCollision.mat")

Create a scenario descriptor object from the loaded seed scenario.

scenarioDescriptor = getScenarioDescriptor(scenarioWithNoCollision);

Plot and play the seed scenario and verify that it contains no collision.

plotObj = plot(scenarioDescriptor);
play(plotObj)

Create an empty variationProperties object. Add collision property variations for actors with actorID values of 1 and 2. Specify the collision fraction and collision side for each actor.

variation = variationProperties;
varyCollisionProperties(variation,1,2,Actor1CollisionFraction=0.5,Actor1CollisionSide="Front",Actor2CollisionFraction=1,Actor2CollisionSide="Front")

Generate variants from the seed scenario using the specified collision properties.

[variantDescriptor,variantInfo] = generateVariants(scenarioDescriptor,variation);

Plot and play the variant scenario. Observe that the variant now contains a collision between the two actors.

plotObj = plot(variantDescriptor);
play(plotObj,StopAtEvent="Collision")

Input Arguments

variations — Variation properties

variationProperties object

Variation properties, specified as a variationProperties object.

actor1ID — First actor ID

positive integer

First actor ID, specified as a positive integer.

actor2ID — Second actor ID

positive integer

Second actor ID, specified as a positive integer.

collisionObj — Collision information

collision object

Collision information, specified as a collision object.

To get a collision object from the input scenario, use the getCollisionData function. For more information on the collision object, see the collisionInfo output argument of the getCollisionData function.

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: varyCollisionProperties(variation,collisionObj,Actor1CollisionFraction=0.3) specifies a variant collision fraction of 0.3 for the first actor.

Actor1CollisionFraction — Point of collision relative to collision side of first actor

scalar

Point of collision relative to the collision side of the first actor, specified as a scalar in the range [0, 1]. For more information on collision fractions, see Collision Fraction.

Example: Actor1CollisionFraction=0.3 specifies a variant collision fraction of 0.3 for the first actor.

Actor1CollisionSide — Side of first actor at which collision occurs

"Front" | "Left" | "Back" | "Right"

Side of the first actor at which collision occurs, specified as "Front", "Left", "Back", or "Right". For more information on how to use this argument, see Tips and Limitations.

Example: Actor1CollisionSide="Front" specifies the variant collision side as "Front" for the first actor.

Actor2CollisionFraction — Point of collision relative to the collision side of second actor

scalar

Point of collision relative to the collision side of the second actor, specified as a scalar in the range [0, 1]. For more information on collision fractions, see Collision Fraction.

Example: Actor2CollisionFraction=0.3 specifies a variant collision fraction of 0.3 for the second actor.

Actor2CollisionSide — Side of the second actor at which collision occurs

"Front" | "Left" | "Back" | "Right"

Side of the second actor at which collision occurs, specified as "Front", "Left", "Back", or "Right". For more information on how to use this argument, see Tips and Limitations.

Example: Actor2CollisionSide="Front" specifies the collision side as "Front" for the second actor.

VariationType — Parameter to vary to generate variants

"WaitTime" | "EntryTime" | "Waypoints"

Parameter to vary to generate variants, specified as "WaitTime", "EntryTime", or "Waypoints".

• WaitTime — Varies wait time of an actor to create scenario variants.

• EntryTime — Varies entry time of an actor to create scenario variants.

• Waypoints — Varies waypoints of an actor to create scenario variants.

Example: VariationType="WaitTime" varies wait time of an actor to create scenario variants.

Limitations

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

• If the seed scenario contains two intersecting trajectories, the generateVariants function can create a scenario variant with a collision. However, if the two actors are traveling head-on or the two trajectories are overlapping, then the function cannot create a collision variant.

Tips

• To apply collision variations to your seed scenario, use the generateVariants function.

• The actor collision points Actor1CollisionFraction and Actor2CollisionFraction are relative to their respective collision sides, Actor1CollisionSide and Actor2CollisionSide.

• You can find the collision side of an actor in the seed scenario by referring to the CollisionSide field of the collision object.

Version History

Introduced in R2023a

R2026b: Generate collision variants from intersecting trajectories

Before R2026b, the seed scenario required to have a collision instance to create collision variants. From R2026b, if the seed scenario does not contain collision but contains two intersecting trajectories, the generateVariants function can create a scenario variant with a collision. However, if the two actors are traveling head-on or the two trajectories are overlapping, then the function cannot create a collision variant.