Main Content

roadrunner

Start RoadRunner application using MATLAB

Since R2022a

expand all in page

    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.

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

    Creation

    Syntax

    rrApp = roadrunner(ProjectFolder=projectFolder)
    rrApp = roadrunner
    rrApp = roadrunner(Name=Value)

    Description

    rrApp = roadrunner(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.

    example

    rrApp = roadrunner opens RoadRunner for a ProjectFolder and InstallationFolder defined using MATLAB's settings API or function.

    example

    rrApp = roadrunner(Name=Value) sets the properties using name-value pairs.

    Properties

    expand all

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

    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

    Location of local RoadRunner installation folder, specified as a string scalar. You can customize the value of InstallationFolder using MATLAB's settings API or 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 API.

    Data Types: char | string

    Start RoadRunner in console mode in a non-graphical environment, specified as logical 0 (false) or logical 1 (true). For more details on starting RoadRunner in console mode, see Control RoadRunner Programmatically in Console Mode.

    Data Types: logical

    Start RoadRunner on specified apiPort and cosimPort, specified as a matrix of size 1-by-2. RoadRunner API server port (apiPort) and RoadRunner Scenario simulation API server port (cosimPort) are automatically assigned by default when you launch the RoadRunner application. The server runs locally at localhost:port after you open a RoadRunner project. If the ports assigned are not free, a connection error occurs. In this case, you can explicitly assign values to apiPort and cosimPort using the roadrunner object or the connect function.

    Example: rrApp= roadrunner(projectFolder,Ports= [54321, 54322]) starts RoadRunner and RoadRunner Scenario on apiPort and cosimPort 54321 and 54322 respectively.

    Data Types: int

    Object Functions

    expand all

    newProjectCreate new RoadRunner project using MATLAB
    openProjectOpen RoadRunner project using MATLAB
    saveProjectSave RoadRunner project using MATLAB
    newSceneCreate new RoadRunner scene using MATLAB
    openSceneOpen RoadRunner scene using MATLAB
    saveSceneSave RoadRunner scene using MATLAB
    exportSceneExport RoadRunner scene using MATLAB
    exportCustomFormatExport RoadRunner scene to custom format using MATLAB
    importSceneImport scene into RoadRunner using MATLAB
    newScenario (RoadRunner Scenario)Create new scenario in RoadRunner Scenario using MATLAB
    openScenario (RoadRunner Scenario)Open scenario in RoadRunner Scenario using MATLAB
    saveScenario (RoadRunner Scenario)Save scenario in RoadRunner Scenario using MATLAB
    exportScenario (RoadRunner Scenario)Export scenario from RoadRunner Scenario using MATLAB
    importScenario (RoadRunner Scenario)Import file into RoadRunner Scenario using MATLAB
    createSimulation (RoadRunner Scenario)Create RoadRunner Scenario simulation using MATLAB
    prepareSimulation (RoadRunner Scenario)Submit simulation data to RoadRunner Scenario simulation engine using MATLAB
    simulateScenario (RoadRunner Scenario)Simulate RoadRunner scenario using MATLAB
    getScenarioVariable (RoadRunner Scenario)Get the value of RoadRunner scenario variable using MATLAB
    setScenarioVariable (RoadRunner Scenario)Set RoadRunner scenario variable using MATLAB
    remapAnchor (RoadRunner Scenario)Remap anchors in RoadRunner Scenario in MATLAB
    getAnchors (RoadRunner Scenario)Retrieve anchor attributes from RoadRunner scenario using MATLAB
    roadrunner.connectConnect to open instance of RoadRunner using MATLAB
    closeClose RoadRunner using MATLAB
    statusGet current status of RoadRunner using MATLAB

    Examples

    collapse all

    This example uses:

    Open Live Script

    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');

    This example uses:

    Open Live Script

    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";

    This example uses:

    Open Live Script

    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");

    This example uses:

    Open Live Script

    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

    See Also

    | | | (RoadRunner Scenario) | (RoadRunner Scenario) |

    Topics