Main Content

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

    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 roadrunnerSetup 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 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

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

    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
    newScenarioCreate new scenario in RoadRunner Scenario using MATLAB
    openScenarioOpen scenario in RoadRunner Scenario using MATLAB
    saveScenarioSave scenario in RoadRunner Scenario using MATLAB
    exportScenarioExport scenario from RoadRunner Scenario using MATLAB
    importScenarioImport file into RoadRunner Scenario using MATLAB
    createSimulationCreate RoadRunner Scenario simulation using MATLAB
    prepareSimulationSubmit simulation data to RoadRunner Scenario simulation engine using MATLAB
    simulateScenarioSimulate RoadRunner scenario using MATLAB
    getScenarioVariableGet the value of RoadRunner scenario variable using MATLAB
    setScenarioVariableSet RoadRunner scenario variable using MATLAB
    remapAnchorRemap anchors in RoadRunner Scenario in MATLAB
    getAnchorsRetrieve 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

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

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

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

    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