ncapScenario

Generate scenario descriptors for Euro NCAP test

Since R2024a

collapse all in page

Syntax

descriptor = ncapScenario(ncapTestName)
[descriptor,scenarioInfo] = ncapScenario(ncapTestName,AllScenarios=true)
[___] = ncapScenario(___,Name=Value)
descriptor = ncapScenario(euroAssessmentObj,ncapTestName)
[descriptor,scenarioInfo] = ncapScenario(euroAssessmentObj,ncapTestName,AllScenarios=true)
[___] = ncapScenario(___,Name=Value)

Description

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

Generate Scenario Descriptor

descriptor = ncapScenario(ncapTestName) generates a seed scenario descriptor, descriptor, for the input European New Car Assessment Programme (Euro NCAP®) test name ncapTestName.

example

[descriptor,scenarioInfo] = ncapScenario(ncapTestName,AllScenarios=true) generates seed scenario descriptors for all scenarios for the specified test name, and returns the scenario information scenarioInfo.

example

[___] = ncapScenario(___,Name=Value) specifies options using one or more name-value arguments, in addition to any combination of arguments from previous syntaxes. For example, ShowProgress="GUI" displays the scenario generation progress bar in a graphical user interface.

example

Generate Scenario Descriptor Using euroAssessment Object

Since R2026a

descriptor = ncapScenario(euroAssessmentObj,ncapTestName) generates a seed scenario descriptor, descriptor, for the input Euro NCAP test name ncapTestName using the Euro NCAP assessment protocol specifications euroAssessmentObj.

example

[descriptor,scenarioInfo] = ncapScenario(euroAssessmentObj,ncapTestName,AllScenarios=true) generates seed scenario descriptors for all scenarios for the specified test name, and returns the scenario information scenarioInfo.

[___] = ncapScenario(___,Name=Value) specifies options using one or more name-value arguments. For example, ShowProgress="GUI" displays the scenario generation progress bar in a graphical user interface.

Examples

collapse all

This example uses:

Open Live Script

Specify the European New Car Assessment Programme (Euro NCAP) test name for the Vulnerable Road User Automatic Emergency Braking Crossing Car-to-Pedestrian Nearside Child Obstructed test.

ncapTestName = "VRU AEB Crossing CPNCO";

Generate a seed scenario descriptor for the NCAP test, which you can use to create its variants.

descriptor = ncapScenario(ncapTestName);

To visualize the created scenario, specify the path to your local RoadRunner installation folder. This code shows the path for the default installation location of RoadRunner R2024a on Windows®.

appPath = "C:\Program Files\RoadRunner R2024a\bin\win64";

Specify the path to your RoadRunner project. This code shows the path for a sample project folder location in Windows.

projectPath = "C:\RR\MyProject";

Set up the environment for opening the scenario in RoadRunner. Update the settings group.

s = settings;
s.roadrunner.application.InstallationFolder.TemporaryValue = appPath;

Open RoadRunner using the specified path to your project, and get the ScenarioSimulation object from your scenario.

rrApp = roadrunner(projectPath);
scenario = getScenario(descriptor,Simulator="RoadRunner",SimulatorInstance=rrApp);

This example uses:

Open Live Script

Specify the Euro NCAP test name for the Safety Assist Automatic Emergency Braking Car-to-Car Front head-on lane change scenario.

ncapTestName = "SA AEB CCFhol";

Specify the path to your RoadRunner ego asset.

egoAssetInfo.AssetPath = "Vehicles/DeliveryVan.fbx_rrx.rrmeta";

Generate an array of scenario descriptors and their scenario information for the specified Euro NCAP test name.

[descriptors,scenarioInfo] = ncapScenario(ncapTestName,AllScenarios=true,EgoAssetInfo=egoAssetInfo);
SA AEB CCFhol Progress: (100%)[==================================================](  2/  2)

Specify the path to your local RoadRunner installation folder. This code shows the path for the default installation location on Windows®.

appPath = "C:\Program Files\RoadRunner R2024b\bin\win64";

Specify the path to your RoadRunner project. This code shows the path for a sample project folder location in Windows.

projectPath = "C:\RR\MyProject";

Set up the environment to open the scenario in RoadRunner. Update the settings group.

To update the MATLAB® path for the RoadRunner installation folder, get the root object within the settings hierarchical tree, and update the TemporaryValue for the RoadRunner installation folder property. For more information, see SettingsGroup.

s = settings;
s.roadrunner.application.InstallationFolder.TemporaryValue = appPath;

Open RoadRunner using the specified path to your project. The rrApp RoadRunner object enables you to interact with RoadRunner from the MATLAB workspace.

rrApp = roadrunner(projectPath);

Specify a valid index for a scenario descriptor object.

idx = 1;

Create a RoadRunner scenario for the scenario descriptor object at the specified index.

scenario = getScenario(descriptors(idx),Simulator="RoadRunner",SimulatorInstance=rrApp);

This figure shows an instance of the simulated Safety Assist Automatic Emergency Braking Car-to-Car Front head-on lane change scenario in RoadRunner, which contains an ego vehicle represented as a blue delivery van.

Simulated Safety Assist Automatic Emergency Braking Car-to-Car Front head-on lane change scenario in RoadRunner, containing an ego vehicle represented as a blue delivery van.

Since R2026a

This example uses:

Open Live Script

Specify a European New Car Assessment Programme (Euro NCAP) test name from protocol specification years 2026–2028.

ncapTestName = "CA FC CCRs";

Create a Euro NCAP protocol specification object for protocol specification years 2026–2028.

euroAssessmentObj = euroAssessment(2026);

Generate a seed scenario descriptor for the Euro NCAP test, which you can use to create its variants.

descriptor = ncapScenario(euroAssessmentObj,ncapTestName);

To visualize the created scenario, specify the path to your local RoadRunner installation folder. This code shows the path for the default installation location of RoadRunner R2026a on Windows®.

appPath = "C:\Program Files\RoadRunner R2026a\bin\win64";

Specify the path to your RoadRunner project. This code shows the path for a sample project folder location in Windows.

projectPath = "C:\RR\MyProject";

Set up the environment for opening the scenario in RoadRunner. Update the settings group.

s = settings;
s.roadrunner.application.InstallationFolder.TemporaryValue = appPath;

Open RoadRunner using the specified path to your project, and get the ScenarioSimulation object from your seed scenario descriptor.

rrApp = roadrunner(projectPath);
scenario = getScenario(descriptor,Simulator="RoadRunner",SimulatorInstance=rrApp);
Connection status: 1
Connected to RoadRunner Scenario server on localhost:41430, with client id {f1494d10-dfc4-4891-8413-e0a7406e87e9}

Input Arguments

collapse all

Euro NCAP test scenario name, specified as a character vector or string scalar, representing a valid Euro NCAP test scenario name. The list of valid Euro NCAP test scenario names depends on the protocol specification year specified by the Year property of euroAssessmentObj.

For more information on the Euro NCAP test scenarios, see Euro NCAP Car Safety Protocols.

Since R2026a

Euro NCAP assessment protocol specifications, specified as a euroAssessment object.

Name-Value Arguments

collapse all

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: ncapScenario(ncapTestName,AllScenarios=true,ShowProgress="GUI") displays the scenario generation progress bar in a graphical user interface.

Show the progress bar, specified as one of these options:

  • "CommandLine" — Displays the scenario generation progress bar in the MATLAB® Command Window.

  • "GUI" — Displays the scenario generation progress bar in a graphical use interface (GUI).

  • "No" — Does not displays the progress bar.

Ego asset information, specified as a structure. The structure contains these fields:

FieldDescription
AssetPath

Ego asset path, specified as a string scalar. The value must be a valid RoadRunner asset path for an ego vehicle.

Dimension

Dimensions of the ego asset, specified as a structure with these fields:

  • Length — Length of the ego asset, specified as a positive scalar. Units are in meters.

  • Width — Width of the ego asset, specified as a positive scalar. Units are in meters.

  • Height — Height of the ego asset, specified as a positive scalar. Units are in meters.

  • FrontOverhang — Distance between the front of the vehicle and the front axle, specified as a positive scalar. Units are in meters.

  • WheelBase — Distance between the front and rear axles of the vehicle, specified as a positive scalar. Units are in meters.

  • RearOverhang — Distance between the rear axle and the rear of the vehicle, specified as a positive scalar. Units are in meters.

Note

To use the EgoAssetInfo name-value argument:

  • You must install RoadRunner and activate your RoadRunner license interactively. For more information, see Install and Activate RoadRunner (RoadRunner).

  • You must also specify AllScenarios=true to the ncapScenario function.

Output Arguments

collapse all

Scenario descriptors, returned as a ScenarioDescriptor object or an N-element array of ScenarioDescriptor objects.

If you specify AllScenarios=true to the ncapScenario function, the function returns an N-element array of ScenarioDescriptor objects. N is the number of generated scenario descriptors for a specified Euro NCAP test name. Otherwise, the function returns a single ScenarioDescriptor object that represents the seed scenario for a specified Euro NCAP test name.

Each ScenarioDescriptor object stores the scene, actor, and vehicle information of a seed scenario. You can use this information to generate scenario variants for performing safety assessments for various automated driving applications.

By default, the function specifies the ego vehicle as a sedan in the returned scenario descriptor object, and fixes the dimensions of the sedan to [4.5556 1.9378 1.4538 0.8940 0.9483 2.7133] in the form [length width height frontOverhang rearOverhang wheelbase]. Units are in meters. For more information on actor dimensions, see Actor and Vehicle Positions and Dimensions.

To plot the first frame of the scenario simulation in the ScenarioDescriptor object, use the plot function. The plot also returns a ScenarioDescriptorPlot object containing properties you can use to plot and simulate the scenario from a scenario descriptor object. To configure the properties of the ScenarioDescriptorPlot object, use the configure object function. To plot a specific frame of the scenario simulation, use the seek object function. To instead play the entire scenario simulation, use the play object function.

Scenario information, returned as a structure. The structure contains these fields:

FieldDescription
ValidScenario

Valid scenario flag, returned as 1 if the generated scenario is in accordance with the Euro NCAP test specifications. Otherwise, it returns a 0.

Messages

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

The ncapScenario function displays messages for a scenario if its ValidScenario 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

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

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

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

  • Waypoints — Waypoints referenced to the rear-wheel axle-center of the ego, returned as an M-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 M-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 M-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 M-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 M-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 M-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 M-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

To return the scenarioInfo output argument, you must also specify AllScenarios=true to the ncapScenario function.

Version History

Introduced in R2024a

expand all

See Also

| | | | |