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
    rrApp = roadrunner(Name=Value)

    Description

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

    example

    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.

    example

    Name-Value Arguments

    expand all

    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.

    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.

    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

    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.

    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

    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.

    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

    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.

    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

    expand all

    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

    This property is read-only.

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

    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.

    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

    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.

    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

    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
    exportActorTrajectoryToCSV (RoadRunner Scenario)Export trajectories of actors in RoadRunner scenario to comma-separated values (CSV) files 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

    expand all

    See Also

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

    Topics