Set Up MATLAB Environment for RoadRunner Authoring Functions
MATLAB® functions for scenario authoring enable you to programmatically author scenarios in RoadRunner, such as by adding actors, creating routes, and building scenario logic, from the MATLAB command-line interface. By authoring scenarios programmatically, you can quickly build and modify simulation parameters without switching between applications, automate repetitive authoring tasks, and generate scenario variations for automated tests.
This example demonstrates how to set up your MATLAB environment to start using the RoadRunner authoring functions, and provides basic steps for adding a new actor to your scenario and retrieving objects for your scenario phase logic and initial actor phase.
This example assumes that you have prior knowledge of working with RoadRunner, and that you have already created a 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.
Open RoadRunner and Create New Scenario
Create a roadrunner
object, specifying the
path to an existing project. For example, this code shows the path to a project, on a
Windows® machine, located at "C:\RR\MyProject"
. This code assumes that
RoadRunner is installed in the default location, and returns an object,
rrApp
, that provides functions for performing basic tasks such as
opening, closing, and saving scenes and projects.
rrApp = roadrunner(ProjectFolder="C:\RR\MyProject");
Note
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
function to specify new default
project and installation folders to use when opening RoadRunner. You can save these folders between MATLAB sessions by selecting the Across MATLAB
sessions
option from the corresponding drop down.
Open an existing scene in RoadRunner by using the openScene
function, specifying the
roadrunner
object rrApp
and the filename of the
specific scene that you want to open. Then, use the newScenario
function to
create a new
scenario.
openScene(rrApp,"ScenarioBasic.rrscene")
newScenario(rrApp)
Create Authoring API Object
Create an object for the RoadRunner authoring API, rrApi
, that references the object for the
current RoadRunner instance rrApp
. The rrApi
object enables you
to programmatically author scenarios, such as by adding and modifying actors and logic
components, using MATLAB.
rrApi = roadrunnerAPI(rrApp);
Scenario
property of the authoring API object rrApi
. The extracted Scenario
object enables you
to specify the scenario in which to add scenario components such as actors and
logic.scnro = rrApi.Scenario;
Project
property of the authoring API object
rrApi
. The extracted Project
object enables you to
specify the project folder for the current RoadRunner session from which to retrieve asset objects. You can use the asset objects to
assign assets to actors in your
scenario.prj = rrApi.Project;
Add Actor and Set Up Initial Logic
Add a Vehicle
actor to the
scenario. Use the getAsset
function to
extract a VehicleAsset
object, mySedan
, that represents
the Sedan.fbx
asset in the project prj
. Then, use the
addActor
function,
specifying the scenario object scnro
, the asset object, and the location at
which to place the actor. Place the vehicle actor car
at the world origin,
specified as [0 0 0]
.
mySedan = getAsset(prj,"Vehicles/Sedan.fbx","VehicleAsset"); car = addActor(scnro,mySedan,[0 0 0]);
findSceneAnchor
to reference an existing
anchor in the scene, then use anchorToPoint
to relocate the actor from its
current location to the location specified by the referenced anchor. For more information, see
findSceneAnchor
and
anchorToPoint
.anchorPoint = findSceneAnchor(scnro,"ScenarioStart"); carPoint = car.InitialPoint; anchorToPoint(carPoint,anchorPoint,PosePreservation="reset-pose")
PhaseLogic
property of your scenario object
scnro
. By default, RoadRunner Scenario creates an initial phase in the scenario logic for each actor added to a scenario.
Use the initialPhaseForActor
function to extract the object for the initial phase of the actor car
. You
can use the initial phase object initPhase
to modify the properties of the
initial phase or specify subsequent logic
phases.rrLogic = scnro.PhaseLogic; initPhase = initialPhaseForActor(rrLogic,car);
Further Exploration
This example provided a basic demonstration of setting up your MATLAB environment to start using the RoadRunner authoring functions. To explore ways to build more complex scenarios, you can try:
Placing additional actors and modifying their properties.
Adding logic phases and conditions to your scenario phase logic and varying parameters to influence simulation behavior.
Designing routes to simulate custom actor movement.
For more information on potential scenario designs, see Get Started with RoadRunner Scenario (RoadRunner Scenario).
See Also
roadrunnerAPI
| Scenario
| PhaseLogic
| addActor
| initialPhaseForActor
Topics
- Get Started with MATLAB Functions for Scenario Authoring (RoadRunner Scenario)
- Simulate a RoadRunner Scenario Using MATLAB Functions (RoadRunner Scenario)
- Define Scenario Logic (RoadRunner Scenario)