roadrunner

Start RoadRunner application using MATLAB

Since R2022a

Description

A roadrunner object enables you to perform common workflow tasks in the RoadRunner application, such as opening, closing, and saving scenes and projects, from the MATLAB^® command line. You can also use object functions to import data from files and export scenes from RoadRunner to other formats.

Before you create a roadrunner object for the first time, you must install RoadRunner and activate your RoadRunner license interactively. For more information, see Install and Activate RoadRunner (RoadRunner).

The roadrunner object requires a license for Automated Driving Toolbox™.

Creation

Syntax

rrApp = roadrunner

rrApp = roadrunner(Name=Value)

Description

rrApp = roadrunner opens RoadRunner for a ProjectFolder and InstallationFolder defined using the MATLAB settings function or roadrunnerSetup function.

rrApp = roadrunner(Name=Value) sets additional options using one or more name-value arguments. For example, ProjectFolder=projectFolder starts RoadRunner from the default installation folder location, and opens a new scene in an existing project at the location specified by ProjectFolder.

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: rrApp = roadrunner(NoDisplay=true,Ports=[54321,54322]) specifies to start RoadRunner in console mode without initializing graphical resources and start the RoadRunner and RoadRunner Scenario API servers on ports 54321 and 54322, respectively.

ProjectFolder — RoadRunner project folder path

string scalar

RoadRunner project folder path, specified as a string scalar. You can customize the value of ProjectFolder using the MATLAB settings function or roadrunnerSetup function. For details about the RoadRunner project folder structure, see RoadRunner Project and Scene System (RoadRunner).

Example: roadrunner("C:\My Project") opens the project located in the C:\My Project folder in the RoadRunner application on a Windows^® machine.

Data Types: string

Ports — RoadRunner API and simulation API server ports

two-element row vector

RoadRunner API and simulation API server ports, specified as a two element row vector of form [apiPort,cosimPort]. While RoadRunner automatically assigns default RoadRunner API server port (apiPort) and RoadRunner Scenario simulation API server port (cosimPort) values when you launch the RoadRunner application, you can explicitly assign the values using this property when you create the roadrunner object, or by using the connect function on an existing roadrunner object. The RoadRunner and RoadRunner Scenario API servers run locally at localhost:port, where port is the value of the API and simulation API server ports, after you open a RoadRunner project. If the ports assigned are not free, a connection error occurs.

Example: rrApp = roadrunner(projectFolder,Ports=[54321,54322]) starts the RoadRunner and RoadRunner Scenario API servers on ports 54321 and 54322, respectively.

InstallationFolder — Location of local RoadRunner installation folder

character vector | string scalar

Location of local RoadRunner installation folder, specified as a character vector or string scalar. You can customize the value of InstallationFolder using the MATLAB settings function or roadrunnerSetup function.

These are the default RoadRunner installation locations on Windows and Linux^® platforms:

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

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

R20NNx is the release version you are using. To customize the default value of the RoadRunner installation folder, use the MATLAB settings function or roadrunnerSetup function.

Data Types: char | string

NoDisplay — RoadRunner starts in console mode

false or 0 (default) | true or 1

RoadRunner starts in console mode in a nongraphical environment, specified as a logical 0 (false) or 1 (true). When you set NoDisplay to true, RoadRunner does not initialize any graphical resources. This enables you to run RoadRunner on systems that do not have graphics cards or display servers installed. For more details on starting RoadRunner in console mode, see Control RoadRunner Programmatically in Console Mode (RoadRunner).

Setting NoDisplay to true restricts you from using features that require graphical resources, such as exporting videos from RoadRunner Scenario or exporting overhead tile textures for scene LODs. To enable graphics-dependent features in console mode, set NoDesktop to true instead.

If you set NoDisplay to true, then NoDesktop must be false.

Data Types: logical

NoDesktop — RoadRunner starts in console mode and initializes graphical resources

false or 0 (default) | true or 1

RoadRunner starts in console mode and initializes graphical resources, specified as a logical 0 (false) or 1 (true). When you set NoDesktop to true, RoadRunner does not display the graphical user interface, but still initializes graphical resources to enable graphics-dependent features, such as exporting videos from RoadRunner Scenario or exporting overhead tile textures for scene LODs. For more details on starting RoadRunner in console mode, see Control RoadRunner Programmatically in Console Mode (RoadRunner).

Because NoDesktop uses graphical resources, you cannot specify this option for systems that do not have graphics cards or display servers installed. To start RoadRunner on systems without graphical capabilities, set NoDisplay to true instead.

If you set NoDesktop to true, then NoDisplay must be false.

Data Types: logical

Properties

InstallationFolder — Location of local RoadRunner installation folder

character vector | string scalar

This property is read-only after object creation. To set this property, use the InstallationFolder argument when you create the roadrunner object.

Location of local RoadRunner installation folder, specified as a character vector or string scalar. You can customize the value of InstallationFolder using the MATLAB settings function or roadrunnerSetup function.

These are the default RoadRunner installation locations on Windows and Linux platforms:

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

• Linux, Ubuntu — /usr/local/RoadRunner_R20NNx/bin/glnxa64

R20NNx is the release version you are using. To customize the default value of the RoadRunner installation folder, use the MATLAB settings function or roadrunnerSetup function.

Data Types: char | string

Version — Version number of currently running RoadRunner instance

Read-only: string scalar

This property is read-only.

Version number of the currently running RoadRunner instance, represented as a string scalar.

NoDisplay — RoadRunner starts in console mode

false or 0 (default) | true or 1

This property is read-only after object creation. To set this property, use the NoDisplay argument when you create the roadrunner object.

RoadRunner starts in console mode in a nongraphical environment, specified as a logical 0 (false) or 1 (true). When you set NoDisplay to true, RoadRunner does not initialize any graphical resources. This enables you to run RoadRunner on systems that do not have graphics cards or display servers installed. For more details on starting RoadRunner in console mode, see Control RoadRunner Programmatically in Console Mode (RoadRunner).

Setting NoDisplay to true restricts you from using features that require graphical resources, such as exporting videos from RoadRunner Scenario or exporting overhead tile textures for scene LODs. To enable graphics-dependent features in console mode, set NoDesktop to true instead.

If you set NoDisplay to true, then NoDesktop must be false.

Data Types: logical

NoDesktop — RoadRunner starts in console mode and initializes graphical resources

false or 0 (default) | true or 1

This property is read-only after object creation. To set this property, use the NoDesktop argument when you create the roadrunner object.

RoadRunner starts in console mode and initializes graphical resources, specified as a logical 0 (false) or 1 (true). When you set NoDesktop to true, RoadRunner does not display the graphical user interface, but still initializes graphical resources to enable graphics-dependent features, such as exporting videos from RoadRunner Scenario or exporting overhead tile textures for scene LODs. For more details on starting RoadRunner in console mode, see Control RoadRunner Programmatically in Console Mode (RoadRunner).

Because NoDesktop uses graphical resources, you cannot specify this option for systems that do not have graphics cards or display servers installed. To start RoadRunner on systems without graphical capabilities, set NoDisplay to true instead.

If you set NoDesktop to true, then NoDisplay must be false.

Data Types: logical

Object Functions

Project

newProject	Create new RoadRunner project using MATLAB
openProject	Open RoadRunner project using MATLAB
saveProject	Save RoadRunner project using MATLAB

Scenes

newScene	Create new RoadRunner scene using MATLAB
openScene	Open RoadRunner scene using MATLAB
saveScene	Save RoadRunner scene using MATLAB
exportScene	Export RoadRunner scene using MATLAB
exportCustomFormat	Export RoadRunner scene to custom format using MATLAB
importScene	Import scene into RoadRunner using MATLAB

Scenarios

newScenario	Create new scenario in RoadRunner Scenario using MATLAB
openScenario	Open scenario in RoadRunner Scenario using MATLAB
saveScenario	Save scenario in RoadRunner Scenario using MATLAB
exportScenario	Export scenario from RoadRunner Scenario using MATLAB
importScenario	Import file into RoadRunner Scenario using MATLAB
createSimulation	Create RoadRunner Scenario simulation using MATLAB
prepareSimulation	Submit simulation data to RoadRunner Scenario simulation engine using MATLAB
simulateScenario	Simulate RoadRunner scenario using MATLAB
getScenarioVariable	Get the value of RoadRunner scenario variable using MATLAB
setScenarioVariable	Set RoadRunner scenario variable using MATLAB
remapAnchor	Remap anchors in RoadRunner Scenario in MATLAB
getAnchors	Retrieve anchor attributes from RoadRunner scenario using MATLAB
exportActorTrajectoryToCSV	Export trajectories of actors in RoadRunner scenario to comma-separated values (CSV) files using MATLAB

Connect, Close and Status

roadrunner.connect	Connect to open instance of RoadRunner using MATLAB
close	Close RoadRunner using MATLAB
status	Get current status of RoadRunner using MATLAB

Examples

Start RoadRunner Application from Default Installation Folder

Specify the path to an existing project using the ProjectFolder variable. For example, this code shows the path to a project, on a Windows® machine, located at C:\RR\MyProject.

projectFolder = "C:\RR\MyProject";

Create a roadrunner object and open RoadRunner by specifying your project as the location where you want to create a scene. This example assumes that RoadRunner is installed in its default location.

rrApp = roadrunner(ProjectFolder=projectFolder, InstallationFolder='C:\Program Files\RoadRunner R2023b\bin\win64'); 

Change Default RoadRunner Installation Folder Settings

Modify the default RoadRunner installation folder settings by using the MATLAB settings function.

You can specify a value for the InstallationFolder property of a roadrunner object that persists across MATLAB sessions, or for a given MATLAB session, using the settings function.

To set a persistent default value for the InstallationFolder property, edit the value of PersonalValue.The specified value persists across multiple MATLAB sessions for an individual user.

s = settings;
s.roadrunner.application.InstallationFolder.PersonalValue = "C:\Program Files\RoadRunner R2022a\bin\win64";

You can also set a temporary default value for the InstallationFolder property. The specified value persists for only the current MATLAB session, and is cleared at the end of the session.

s = settings;
s.roadrunner.application.InstallationFolder.TemporaryValue = "C:\MyRoadRunner Install\bin\win64";

Start Multiple RoadRunner Application Instances Simultaneously

Open multiple RoadRunner applications by creating multiple instances of the roadrunner object. You can use each instance to programmatically interact with the RoadRunner application that it opens. The scenes used in this code are included in RoadRunner projects by default.

Open a first instance of RoadRunner by specifying the Lane Keep project. In this example, the project is located on the path C:\RR\Lane Keep.

rrApp1 = roadrunner("C:\RR\Lane Keep");

Open the FourWaySignal scene in the first project.

openScene(rrApp1,"FourWaySignal.rrscene");

Open a second instance of RoadRunner by specifying the USCity project. In this example, the project is located on the path C:\RR\USCity.

rrApp2 = roadrunner("C:\RR\USCity");

Open the SanAntonio scene in the second project

openScene(rrApp2,"SanAntonio.rrscene");

Start RoadRunner Application in Console Mode

Specify the path to an existing project using the projectFolder variable. For example, this code shows the path to a project, on a Windows® machine, located at C:\RR\MyProject.

projectFolder = "C:\RR\MyProject";

Create a roadrunner object and open RoadRunner by specifying your project as the location where you want to create a scene. This example assumes that RoadRunner is installed in its default location. Specify the NoDisplay property to launch the application in console mode using a non-graphical terminal.

rrApp = roadrunner(projectFolder,InstallationFolder="C:\Program Files\RoadRunner R2022b\bin\win64",NoDisplay=true); 

Limitations

• The roadrunner object and its associated functions are supported only in RoadRunner R2022a and later.

• The project you specify using the projectFolder argument, when creating the roadrunner object must already exist.

• The projectFolder argument and InstallationFolder property do not support Unicode characters in the path.

• The roadrunner object and its associated functions are not supported in MATLAB Online™.

Tips

• Deleting the roadrunner object from the MATLAB workspace does not close the RoadRunner application associated with it. You must manually close the RoadRunner application. Also, exiting from the current MATLAB session does not close any RoadRunner applications created by roadrunner.

Version History

Introduced in R2022a

R2025b_plus: Change to display options

As of R2025b Update 2, NoDisplay specifies for RoadRunner to start in console mode without initializing any graphical resources. This change enables you to run RoadRunner on systems that do not have graphics cards or display servers installed. However, because RoadRunner does not initialize graphical resources, you cannot use graphics-dependent features, such as exporting videos from RoadRunner Scenario or exporting overhead tile textures for scene LODs.

In previous releases, specifying NoDisplay as true starts RoadRunner in console mode, but still initializes graphical resources. To reproduce this old behavior as of R2025b Update 2, specify NoDesktop as true instead. This option enables you to use graphics-dependent features.

R2025a: Export trajectories of the actors in scenario to CSV files

You can now export trajectories of the actors in a scenario to CSV files using the new exportActorTrajectoryToCSV object function.