CollisionUtility

Specify locations of collision points between two vehicle actors

Since R2026a

Description

The CollisionUtility object is a programmatic representation of the Collision Authoring Tool (RoadRunner Scenario) from RoadRunner Scenario. Use a CollisionUtility object to configure the attributes of the Collision Authoring Tool that specify the location collision points between two vehicle actors.

You can use a CollisionUtility object with the roadrunner.extensions.setupCollision function to run collision analysis computations with MATLAB^®. RoadRunner Scenario uses the computation results to automatically adjust the timing of the scenario so that the collision happens at the specified point during simulation. By designing precise collision scenarios, you can study timing-critical interactions between vehicles, and use the results to validate safety features.

To use this object, you must have these products installed:

• Automated Driving Toolbox™ R2026a or later

• Automated Driving Toolbox Test Suite for Euro NCAP^® Protocols support package

For details on the Automated Driving Toolbox Test Suite for Euro NCAP Protocols support package, see Automated Driving Toolbox Test Suite for Euro NCAP Protocols. For information on how to get and install support packages, see Get and Manage Add-Ons.

Creation

To return the CollisionUtility object that represents the Collision Authoring Tool in your RoadRunner scenario, extract the CollisionUtility property of your Scenario object and assign it to a variable. For example, given the Scenario object scnro, collisionUtil = scnro.CollisionUtility creates the CollisionUtility object collisionUtil.

Properties

Actor1CoordinateSystem — Collision point coordinate system for ego actor

"normalizedcollisionpoint" (default) | "vehicleoriginoffset"

Collision point coordinate system for the ego actor, specified as one of these options:

• "normalizedcollisionpoint" — Collision point location in the normalized 2D coordinate space relative to the bounding box of the actor. If you specify this option, RoadRunner Scenario uses the value of Actor1CollisionPoint and ignores the value of Actor1CollisionPointOffset.

• "vehicleoriginoffset" — Collision point location in the 2D coordinate space defined using an offset vector relative to the local origin of the actor. If you specify this option, RoadRunner Scenario uses the value of Actor1CollisionPointOffset and ignores the value of Actor1CollisionPoint.

These options correspond to the Normalized Collision Point and Vehicle Origin Offset attributes in the Actor 1 section of the Collision Authoring Tool user interface.

Actor2CoordinateSystem — Collision point coordinate system for target actor

"normalizedcollisionpoint" (default) | "vehicleoriginoffset"

Collision point coordinate system for the target actor, specified as one of these options:

• "normalizedcollisionpoint" — Collision point location in the normalized 2D coordinate space relative to the bounding box of the actor. If you specify this option, RoadRunner Scenario uses the value of Actor2CollisionPoint and ignores the value of Actor2CollisionPointOffset.

• "vehicleoriginoffset" — Collision point location in the 2D coordinate space defined using an offset vector relative to the local origin of the actor. If you specify this option, RoadRunner Scenario uses the value of Actor2CollisionPointOffset and ignores the value of Actor2CollisionPoint.

These options correspond to the Normalized Collision Point and Vehicle Origin Offset attributes in the Actor 2 section of the Collision Authoring Tool user interface.

Actor1 — Ego actor for collision

[] (default) | Vehicle object

Ego actor for the collision, specified as a Vehicle object.

Actor2 — Target actor for collision

[] (default) | Vehicle object

Target actor for the collision, specified as a Vehicle object.

Actor1CollisionPoint — Location of collision point relative to ego actor bounding box

0 (default) | numeric scalar

Location of the collision point in the normalized 2D coordinate space relative to the ego actor bounding box, specified as a numeric scalar in the interval [0 4). A value of 0 corresponds to the front, right corner of the bounding box, and increasing values move the point counterclockwise relative to the forward position of the actor.

Actor2CollisionPoint — Location of collision point relative to target actor bounding box

0 (default) | numeric scalar

Location of the collision point in the normalized 2D coordinate space relative to the target actor bounding box, specified as a numeric scalar in the interval [0 4). A value of 0 corresponds to the front, right corner of the bounding box, and increasing values move the point counterclockwise relative to the forward position of the actor.

Actor1CollisionPointOffset — Location of collision point relative to ego actor origin

[0 0] (default) | two-element vector

Collision point location relative to the ego actor origin, specified as a two-element vector. The vector specifies the 2D position of the collision point, in the form [x, y], in a coordinate system with the local origin of the ego actor as its origin.

Actor2CollisionPointOffset — Location of collision point relative to target actor origin

[0 0] (default) | two-element vector

Collision point location relative to the target actor origin, specified as a two-element vector. The vector specifies the 2D position of the collision point, in the form [x, y], in a coordinate system with the local origin of the target actor as its origin.

Result — Result of collision analysis computation

Read-only: "" (default) | string scalar

This property is read-only.

Result of the collision analysis computation, represented as a string scalar. The value of this property corresponds to the values in the Result section of the Collision Authoring Tool Attributes pane in the RoadRunner Scenario user interface.

After running the collision analysis, the Result property lists these values in the Collision Analysis Results section:

Name	Description
Collision Point	Location on the actor where the collision occurs.
Collision Time	Simulation time, in seconds, when the collision occurs.
Waiting Actor ID	Unique ID for the actor that is required to wait during simulation to achieve accurate collision timing. The collision analysis determines which actor must wait by evaluating which would otherwise arrive at the specified collision point before the other.
Wait Time	Recommended duration, in seconds, that the waiting actor should wait to achieve accurate collision. The collision analysis determines the duration of the wait time by calculating the time difference between the arrival of the first and second actor to the collision point.
Recommended StepSize	Suggested simulation step size to ensure accurate collision timing and analysis.

The Result property also lists these attributes for each actor at the point of collision:

Name	Description
Actor ID	Unique ID for the actor.
Travelled Distance	Distance traveled by the actor until it reaches the collision point.
Position	Position of the actor in the scene at the point of collision.
Speed	Speed of the actor at the time of collision.
Heading	Heading of the actor at the point of collision.

Examples

Design Collision Scenario Using MATLAB

To design a collision scenario using MATLAB, use a CollisionUtility object to specify the colliding actors and the locations of the collision points.

This example assumes that you have prior knowledge of working with RoadRunner in MATLAB. Before proceeding, follow the steps outlined in Set Up MATLAB Environment for RoadRunner Authoring Functions to set up your scenario using MATLAB functions for scenario authoring.

Add Vehicle Actors and Create Paths

To create a collision scenario, you must first add two vehicle actors to your scenario by specifying the asset to use for the actors and the location in the scenario to place them. Use the getAsset function to extract a VehicleAsset object, mySedan, that represents the Sedan.fbx asset in the project prj. Then, use addActor to specify the scenario object scnro, the asset object, and the initial location at which to place each actor.

mySedan = getAsset(prj,"Vehicles/Sedan.fbx","VehicleAsset");
car1 = addActor(scnro,mySedan,[0.4 -2 0]);
car2 = addActor(scnro,mySedan,[11.5 17 0]);

To create paths for each actor, create objects to represent the starting point of each of the actor routes. Extract the route for both actors from the Route property of the InitialPoint property and assign each route to a variable. Then, to add a new point to each route farther along the road, use the addPoint (RoadRunner Scenario) function and specify the new point locations so the paths intersect each other.

rrRoute1 = car1.InitialPoint.Route;
rrRoute2 = car2.InitialPoint.Route;

rrPoint1 = addPoint(rrRoute1,[31 -5 0]);
rrPoint2 = addPoint(rrRoute2,[9 -21 0]);

Create CollisionUtility Object and Specify Collision Properties

To design a collision scenario between the two actors, you must specify them as the ego and target actor of a CollisionUtility object and specify the collision point location on each actor. First, extract the CollisionUtility property from the Scenario object scnro. Then, to specify the colliding actors as car1 and car2, assign them to the Actor1 and Actor2 properties, respectively.

collisionUtil = scnro.CollisionUtility;
collisionUtil.Actor1 = car1;
collisionUtil.Actor2 = car2;

To specify the location of the collision point for each actor, first specify the coordinate system to use for each actor by setting the Actor1CoordinateSystem and Actor2CoordinateSystem properties. Then, specify the desired collision location for each actor to its corresponding collision point property. For example, if you specify the Actor1CoordinateSystem property as "normalizedcollisionpoint", then use the Actor1CollisionPoint property to specify the normalized collision point location value for Actor1.

collisionUtil.Actor1CoordinateSystem = "normalizedcollisionpoint";
collisionUtil.Actor2CoordinateSystem = "normalizedcollisionpoint";
collisionUtil.Actor1CollisionPoint = 1;
collisionUtil.Actor2CollisionPoint = 0;

Run Collision Analysis Computations and Simulate Scenario

To ensure that the vehicle actors arrive at the specified collision point during simulation, you can run a collision analysis on your scenario. You can run the collision analysis either interactively or programmatically.

To run the collision analysis interactively, in the RoadRunner Scenario user interface, on the toolbar, click the Collision Authoring Tool . Then, in the Attributes pane, select Run in MATLAB.

To run the collision analysis programmatically, create a ScenarioSimulation object, rrSim, to represent the RoadRunner Scenario simulation by using the createSimulation function and specifying your roadrunner object rrApp. Then, use the roadrunner.extensions.setupCollision function to perform the collision analysis by specifying the roadrunner object, the RoadRunner authoring API object, and the scenario simulation object.

To learn more about collision analysis, see Running Collision Analysis in MATLAB (RoadRunner Scenario).

rrSim = createSimulation(rrApp);
collisionResults = roadrunner.extensions.setupCollision(rrApp,rrApi,rrSim);

MATLAB displays a message when it completes the collision analysis, but does not automatically display the analysis results. To view the results of the collision analysis, extract the Result property from the CollisionUtility object.

collisionResults = collisionUtil.Result

To simulate the collision scenario, use the set function to specify the scenario simulation object rrSim and set the "SimulationCommand" argument to "Start".

set(rrSim,"SimulationCommand","Start")

Limitations

• The Collision Authoring Tool supports only two actors at a time.

• The Collision Authoring Tool supports scenario logic that contains only these actions, conditions, and attributes for each actor:

  • A Wait action with an associated Duration condition preceding the Initialize Speed action.

  • The Initialize Speed action must have the Relative to attribute set to either Absolute or Waypoint Time Data.

• Both actors must have defined paths that intersect at least once. The Collision Authoring Tool does not support actors that use the built-in lane-following behavior.

• Both actors must have a speed value greater than 0. The Collision Authoring Tool does not support collision scenarios with static actors.

• The Collision Authoring Tool does not update the collision analysis results if you change the scenario after MATLAB runs the collision analysis computations. If you modify the scenario after performing an initial collision analysis, you must run the computation again by clicking Run in MATLAB.

• The Collision Authoring Tool does not support collision scenarios that have elevation differences between the two actors. To enable accurate collision analysis, the z-axis values of your actors and path waypoints must match.

• Scenarios with roads that have banked angles or superelevation might cause inaccurate collision results.

• Collision analysis does not support actors with more than two logic phases in the Logic editor.

• Collision analysis does not support collisions between actors with Heading values at 0 or 180 degrees, such as head-on collisions.

• Because RoadRunner Scenario uses a fixed-step simulation solver, the timing of collision scenarios might be inaccurate at greater step sizes. To increase collision accuracy, reduce the Step Size value of the Simulation Properties to the Recommended StepSize value in the collision analysis results.

• The Collision Authoring Tool does not support actors that have attachments, such as trucks with trailers.

• Collision analysis does not support vehicle actors with assets that have a Forward Offset value other than 0. To check if an actor asset has a supported Forward Offset value, select the asset for the vehicle actor in the Library Browser. Then, in the Attributes pane, in the Vehicle Parameters section, verify that the Forward Offset value is 0.

  

Version History

Introduced in R2026a