Get Started with MATLAB Functions for Scenario Authoring

The MATLAB^® functions for scenario authoring are a set of objects and functions that enable MATLAB to programmatically interact with RoadRunner projects and scenarios. The RoadRunner authoring API object roadrunnerAPI facilitates this interaction between MATLAB and RoadRunner. It enables you to programmatically author scenarios in RoadRunner from the MATLAB command-line interface, such as by adding actors, creating routes, and building scenario logic. By authoring scenarios programmatically, you can quickly automate repetitive authoring tasks, generate scenario variations for automated tests, and build and modify simulation parameters without switching between applications.

Within the RoadRunner authoring API, objects contain properties that reference other authoring API objects. For example, roadrunnerAPI contains a Scenario property that references a Scenario object, and this Scenario object contains a PhaseLogic property that references data stored in a PhaseLogic object. This diagram shows the hierarchy of objects in the RoadRunner authoring API.

Use MATLAB for RoadRunner

Before you begin using the MATLAB functions for scenario authoring, ensure that you have already created a RoadRunner project. For more details, see Get Started with RoadRunner (RoadRunner) and RoadRunner Project and Scene System (RoadRunner). If this is your first time working with RoadRunner Scenario, consider reading RoadRunner Scenario Fundamentals (RoadRunner Scenario) first.

To use MATLAB to programmatically author scenarios in RoadRunner, you must open RoadRunner by using the roadrunner function. By default, roadrunner automatically adds the path to the RoadRunner authoring API folder, enabling you to seamlessly begin using the API to create scenarios in the current RoadRunner session. If you do not open RoadRunner from MATLAB using the roadrunner function, or if you open a RoadRunner session before opening MATLAB, you must add the path to the folder containing the RoadRunner authoring API to your MATLAB session before you can use the RoadRunner authoring API functions. By default, the location of the RoadRunner authoring API folder on Windows^® and Linux^® is:

• Windows — C:\Program Files\RoadRunner R20NNx\bin\win64\Tools\MATLAB\api

• Linux, Ubuntu^® — /usr/local/RoadRunner_R20NNx/bin/glnxa64/Tools/MATLAB/api

R20NNx is the release version you are using. If you already have an open RoadRunner session, you can use the roadrunner.connect function to connect to the most recent RoadRunner instance.

If you are opening RoadRunner from MATLAB for the first time, or if you have changed the RoadRunner installation location since you last opened it from MATLAB, you can use the roadrunnerSetup (RoadRunner) function to specify new default project and installation folders to use when opening RoadRunner. You can save these project and installation folders between MATLAB sessions by setting Use Project Folder or Use Installation Folder, respectively, to Across MATLAB sessions.

To use the RoadRunner authoring API in MATLAB, you must first create a roadrunnerAPI object for your current RoadRunner session. For more information on how to set up your MATLAB environment for RoadRunner authoring functions, see Set Up MATLAB Environment for RoadRunner Authoring Functions.

Scenario Logic

To start building a scenario, you must first extract the object for your scenario from the Scenario property of the authoring API object. The extracted Scenario object enables you to specify the scenario in which to add scenario components such as actors and logic. The Scenario object extracted from a roadrunnerAPI object represents the current scenario in RoadRunner Scenario at the time you created the roadrunnerAPI object.

Scenario logic controls the behavior of the scenario during simulation, such as actor movement, action execution order, and simulation duration. The PhaseLogic object represents the scenario logic of RoadRunner Scenario. The scenario logic contains all logic components, such as phases, actions, and conditions, for a scenario. You can use the PhaseLogic object to programmatically add and modify scenario logic components to control simulation behavior.

The PhaseLogic object does not represent the interactive scenario Logic editor in the user interface. However, the interactive scenario Logic editor displays a visual representation of the logic for the current scenario and reflects any programmatic changes made to scenario logic in MATLAB. Scenario logic functions the same way both interactively and programmatically. You can modify scenario logic interactively though the RoadRunner Scenario Logic editor in the user interface, or programmatically with the RoadRunner authoring API by extracting and creating logic components and modifying their properties in MATLAB. To learn more about scenario logic and how to modify scenario logic interactively with the Logic editor, see Define Scenario Logic (RoadRunner Scenario).

The RoadRunner authoring API organizes scenario logic into phases. These phases contain properties that reference actions, conditions, and other phase objects. For example, the PhaseLogic object contains a RootPhase property that references data from a ParallelPhase object. The ParallelPhase object can contain multiple child phases, such as actor action phases, system action phase, serial phases, and other parallel phases. This diagram shows how RoadRunner organizes phase objects in the scenario logic.

Create Scenarios with RoadRunner Authoring API

The RoadRunner authoring API enables you to programmatically perform many of the same authoring tasks for creating scenarios as the interactive user interface, such as adding and modifying actors and assets, designing routes, and designing scenario logic.

Add and Modify Actors and Assets

An actor is an object within a scenario that interacts with scenario logic to perform assigned scenario behaviors, such as a vehicle actor changing lanes on a road. The addActor function creates an actor using the specified asset and scene location and adds it to the specified scenario. You can programmatically modify the attributes of an actor in your scenario by changing the property values of the corresponding actor object. For more information on actors, see Actors in RoadRunner Scenario (RoadRunner Scenario).

Assets are files containing data that influences how components of the scenario appear visually in the scene or behave during simulation, such as a 3D model of a car for an actor or an .rrbehavior file containing user-defined simulation behavior information. You can use the getAsset and createAsset functions to extract an existing asset object or create a new asset object, respectively. You can use an asset object to modify the properties of the corresponding asset. For more information on assets, see Create, Import, and Modify Assets (RoadRunner).

Design Routes

A route is a series of waypoints that inform the driving direction, position, and orientation of an actor as it moves during simulation. The Route object represents a sequence of waypoints that an actor traverses during simulation and contains data that defines how RoadRunner Scenario interpolates the points. You can use a Route object to build routes for actors by specifying the route on which to add new points. The addPoint function adds a point to the end of the specified route at the specified position. For more information on editing routes, see Path Editing (RoadRunner Scenario).

Note

The properties of a route constrain the behaviors of actors that follow them. Therefore, some actions and conditions, such as the Change Lane action, are not compatible with actors that follow routes.

Design Scenario Logic

Use the initialPhaseForActor function to get the initial phase for the specified actor. The initial action phase sets the state of the actor at the start of the simulation, and you can use your initial phase object and PhaseLogic object to programmatically specify subsequent logic phases in the RoadRunner scenario logic.

The addPhaseInSerial and addPhaseInParallel functions create serial or parallel logic phases, respectively, with the specified phase type and add them before or after the specified existing phase in the RoadRunner scenario logic. Once you add phases to your scenario logic, you can influence actor behavior during simulation by using the addAction, setEndCondition, and setFailCondition functions to specify action types and conditions for the phases. To learn more about scenario logic, see Define Scenario Logic (RoadRunner Scenario).

Further Exploration

RoadRunner provides several sample files that demonstrate how to programmatically build different kinds of scenario behavior in MATLAB. By default, the location of the example files on Windows and Linux is:

• Windows — C:\Program Files\RoadRunner R20NNx\bin\win64\Tools\MATLAB\api\scenario\examples

• Linux, Ubuntu — /usr/local/RoadRunner_R20NNx/bin/glnxa64/Tools/MATLAB/api/scenario/examples

R20NNx is the release version you are using. To open the example files in MATLAB, use the open function and specify the path to the example file you want to open.

RoadRunner includes these examples:

• CreateCutInAndSlow.m

• CreateFreeDrive.m

• CreateKeepSpaceGap.m

• CreateLaneChangeInterruptsSwerve.m

• CreateLeadCollision.m

• CreateSwervingLeadVehicle.m

• CreateTrajectoryCutIn.m

To open the examples in RoadRunner, create a roadrunner object for your current RoadRunner session, rrApp. Then, specify the example you want to run and your rrApp object.

rrApp = roadrunner;
CreateCutInAndSlow(rrApp)

For more information on the scenarios created by the RoadRunner sample files, see Open and Explore Sample Scenarios (RoadRunner Scenario).