RoadRunner Scenario Reader

Reads selected topic from RoadRunner scenario

Since R2022a

expand all in page
  • RoadRunner Scenario Reader block

Libraries:
Automated Driving Toolbox / RoadRunner Scenario

Description

The RoadRunner Scenario Reader block reads the selected topic from the RoadRunner scenario. You can set the Topic Category parameter to Actor, Action, Sensor, or Event. The block outputs data as messages.

When you select the Actor topic, the block outputs the data associated with the actor, such as Actor Specifications and Actor Pose. When you select the Action topic, the block outputs data such as Speed Change and Lane Change. The block returns the simulation states from the previous time step. You can filter data based on the actor associated with the Simulink® actor model.

When you select the Sensor topic, the block outputs the data associated with the sensor of specified Sensor ID. You can select the type of sensor data the block must output by specifying Target Poses or Lane Boundaries. When you select the Event topic, the block outputs data for the user-defined event specified for the Event name parameter.

Examples

expand all

This example uses:

Open Live Script

This example shows how you can read traffic signal information from a RoadRunner Scenario simulation in a Simulink actor behavior model. The vehicle associated with the behavior model regulates its speed in response to an approaching traffic signal.

Set Up MATLAB-RoadRunner Scenario Cosimulation Environment

In the MATLAB command prompt, specify the path to your local RoadRunner installation folder. This code snippet uses the default installation path of the RoadRunner application on Windows.

RRInstallationFolder = "C:\Program Files\RoadRunner " + matlabRelease.Release + "\bin\win64";

Update the path for the RoadRunner installation folder by getting the root object within the settings hierarchical tree. Then, use the root object to set the installation path of the RoadRunner application. For more information, see SettingsGroup.

s = settings;
s.roadrunner.application.InstallationFolder.PersonalValue = RRInstallationFolder;

Change the project location to the RoadRunner project path on your machine.

rrProjectLocation = "C:\TrafficSignal\New RoadRunner Project";

Create the roadrunner object that represents the specified project.

rrApp = roadrunner(rrProjectLocation,InstallationFolder=RRInstallationFolder);

Add the SceneTrafficSignal scene file to the Scenes folder within your RoadRunner project.

copyfile("SceneTrafficSignal.rrscene",fullfile(rrProjectLocation,"Scenes"));

Add the TrafficSignal_SpeedReg scenario file to the Scenarios folder within your RoadRunner project.

copyfile("TrafficSignal_SpeedReg.rrscenario",fullfile(rrProjectLocation,"Scenarios"));

Add the TrafficSignal_Behavior behavior asset file that links the MATLAB System object behavior to the vehicle in the scenario.

copyfile("TrafficSignal_Behavior.rrbehavior.rrmeta",fullfile(rrProjectLocation,"Assets","Behaviors"));

Explore the Scenario

Open the scenario file TrafficSignal_SpeedReg.rrscenario. 

openScenario(rrApp,"TrafficSignal_SpeedReg");

The scenario contains a white sedan in a lane. The path of the white sedan is laid out using waypoints and passes through the single traffic signal junction in the scene. The junction contains ten traffic signals that are converted to actors using the Traffic Signal Tool (RoadRunner Scenario).

Connect to the RoadRunner Scenario server to enable cosimulation by using the createSimulation function. 

sim = createSimulation(rrApp);
Connection status: 1
Connected to RoadRunner Scenario server on localhost:60729, with client id {a58293d1-c04a-4fbf-81f0-35f1f2415edc}

Explore the Model

Open the model and load the required reference bus types into the base workspace:

modelname = "TrafficSignal_Stop";
open_system(modelname);
load("rrScenarioSimTypes.mat");

Snapshot of Simulink model that represents the actore behavior model of the white sedan.

The model programs the movement of the sedan along a predefined path, and reads traffic signal information to detect changes in the signal light.

If the traffic signal is red when the sedan approaches the corresponding junction, it slows down and stops. If the traffic signal turns green for the stopped sedan, then it starts moving and accelerates until it reaches a fixed speed.

The model contains these blocks:

  1. Ego Traffic Signal – MATLAB System Object that uses the roadrunnerHDMap object to check if the sedan has reached within a certain distance of the traffic signal junction. Based on this information, the System Object calculates the time left to stop and remaining distance before stopping. It also returns the state of the traffic signal.

  2. Speed Modulation – MATLAB function that controls the speed of the sedan. When the traffic signal is red, the MATLAB function calculates the necessary deceleration to slow down and stop the sedan, given that the time taken to stop is less that the time it takes for the signal to change color. When the traffic signal turns green, the function calculates the required acceleration to move the sedan forward.

  3. Path Following – Subsystem that controls the movement of the sedan along a predefined path. The subsystem contains three MATLAB Function blocks: Vehicle Movement finds the current position vectors of the sedan along the X, Y, and Z axes, Actor Pose constructs the 4-by-4 transformation matrix representing the current pose of the sedan, and Actor Velocity constructs the velocity vector based on its yaw angle and speed.

Simulate the Scenario

Play the scenario, TrafficSignal_SpeedReg.

set(sim,SimulationCommand="Start");

In the Simulation Tool (RoadRunner Scenario), you can change the Camera View to front to view the changing traffic signals, and the response of the car.

The sedan moves along the path towards the traffic signal junction.

Sedan approaching the traffic signal as seen from an overhead view.

Traffic signal as seen from the front of the car in the 'front' camera view.

The sedan stops at the junction when the traffic signal turns red. It remains stationary while the signal is red.

Traffic signal light is red, as seen in the 'front' camera view.

When the traffic signal turns green, the sedan starts to accelerate and move along the path again.

Traffic signal light turns green, as seen in the 'front' camera view.

Sedan resumes motion after the traffic signal turns green as seen from an overhead view.

Extended Examples

Add Sensors to RoadRunner Scenario Using Simulink

Add Sensors to RoadRunner Scenario Using Simulink

Simulate a RoadRunner Scenario with sensor models defined in Simulink and visualize object and lane detections.

Ports

Input

expand all

Specify the ID of the actor whose parent or children information you require.

To convert the ID to the uint64 data type, you can either set the Constant value parameter of the Constant (Simulink) block to uint64(ID), where ID is the Actor ID, or use the Data Type Conversion (Simulink) block.

Dependencies

To enable this port, set the Filter parameter to Actor ID (provided by input).

Data Types: uint64

Output

expand all

State information from scenario, returned as a Simulink message. To extract data from the Simulink message, connect the RoadRunner Scenario Reader block to the Receive (Simulink) block.

Parameters

expand all

Topic category, specified as one of these values:

  • Actor — Reads the actor data from the scenario

  • Action — Reads the action data from the scenario

  • Sensor — Reads the sensor data from the scenario

  • Event — Reads the event data from the scenario

Type of actor in scenario, specified as All Types, Vehicle, Traffic Signal, or Traffic Signal Controller. The Vehicle type includes additional wheel information of the actor.

The Traffic Signal type represents traffic signal actors, while the Traffic Signal Controller type represents a traffic signal controller entity that connects all traffic signal actors of a junction together.

Dependencies

To enable this parameter, set Topic Category to Actor.

Type of action that can be read from the scenario, specified as one of these values:

Field NameDescription
Change Parameter

Reads the user-created parameter from the scenario. For more information, see Change Parameter.

Lateral Offset

Reads the lateral offset action data from the scenario. For more information, see Lateral Offset.

Path Following

Reads the path following action data from the scenario. For more information, see Path Following.

Speed Change

Reads the speed change action data from the scenario. For more information, see Speed Change.

Lane Change

Reads the lane change action data from the scenario. For more information, see Lane Change.

Longitudinal Distance

Reads the longitudinal distance action data from the scenario. For more information, see Longitudinal Distance.

User Defined

Reads the custom parameters of a user-defined action from the scenario. For more information, see User Defined.

Dependencies

To enable this parameter, set Topic Category to Action.

Sensor data derived from the scenario ground truth, specified as one of these options:

  • Target Poses — The block outputs poses of targets within sensor range in host vehicle coordinates. For the bus structure of the output target poses, see the output argument description of the targetPoses function.

  • Target Poses For Host — The block outputs poses of all targets in the in host vehicle coordinates. For the bus structure of the output target poses, see the output argument description of the targetPoses function.

  • Lane Boundaries — The block outputs lane boundaries within sensor range in host vehicle coordinates. For the bus structure of the output lane boundaries, see the output argument description of the laneBoundaries function.

  • Target Poses And Lane Boundaries — The block outputs both lane boundaries and poses of targets within the sensor range in host vehicle coordinates.

The origin of the host vehicle coordinates is the geometric center of the host vehicle.

You can send the above outputs directly to sensor detection generator blocks and obtain detections.

Dependencies

To enable this parameter, set Topic Category to Sensor.

Type of event to read from a scenario.

The event being read must be mapped to the corresponding bus object in the RoadRunner Scenario block.

Dependencies

To enable this parameter, set Topic Category to Event.

Actor data, or lane boundary captured through sensor views.

The Topic parameter can hold various sets of options, as specified in the tables below, depending on the configuration of other fields.

The Topic parameter holds the options described in the table below if both these field configurations are true:

  • Topic Category is set to Actor.

  • Actor Type is set to All Types.

OptionDescription
Actor Specifications (default)

Static attributes associated with the actor, such as actor ID, actor name, and bounding box. For more information, see Actor Specifications.

Actor Pose

Dynamic data associated with the actor, such as pose, velocity, and angular velocity. For vehicle assets included with or created in RoadRunner, the actor origin is the geometric center of the actor. For more information, see Actor Pose.

Actor Pose (Driving Scenario compatible)

Dynamic data associated with the actor, such as actor ID, position, velocity, roll, pitch, yaw, and angular velocity. For vehicle assets included with or created in RoadRunner, the actor origin is the point on the ground below the center of its rear axle. For more information, see Actor Pose (Driving Scenario compatible).

Actor Lane Location

Dynamic data associated with the lane location of actors. For more information, see Actor Lane Location.

The Topic parameter holds the options described in the table below if both these field configurations are true:

  • Topic Category is set to Actor.

  • Actor Type is set to Vehicle.

OptionDescription
Vehicle Specifications (default)

Static attributes associated with the vehicle, such as paint color, and wheel specifications. For more information, see Vehicle Specifications.

Vehicle Pose

Dynamic data associated with the actor, such as wheel poses. For more information, see Vehicle Pose.

The Topic parameter holds the options described in the table below if both these field configurations are true:

  • Topic Category is set to Actor.

  • Actor Type is set to Traffic Signal.

OptionDescription
Traffic Signal Specifications (default)

Static specifications of a traffic signal actor. For more information, see Traffic Signal Specifications Topic.

Traffic Signal Runtime

Run-time information of a traffic signal actor. For more information, see Traffic Signal Runtime Topic.

The Topic parameter holds the options described in the table below if both these field configurations are true:

  • Topic Category is set to Actor.

  • Actor Type is set to Traffic Signal Controller.

OptionDescription
Traffic Signal Controller Specifications (default)

Static specifications of a traffic signal controller. For more information, see Traffic Signal Controller Specifications Topic.

Traffic Signal Controller Runtime

Run-time information of a traffic signal controller. For more information, see Traffic Signal Controller Runtime Topic.

The Topic parameter holds the options described in the table below if both these field configurations are true:

  • Topic Category is set to Sensor.

  • Sensor View is set to Lane Boundaries.

OptionDescription
Ego-Lane (default)

Boundaries of the lane in which the host vehicle actor is traveling

Ego and Adjacent Lanes

Boundaries of the adjacent left and right lanes, as well as the lane in which host vehicle actor is traveling

All Lanes

Boundaries of all lanes on the road

Filter criteria for relevant topic data, specified as one of these options:

OptionDescription
None

Output data for all actors in the scenario.

When you set Filter to None, the block outputs a message for each actor in your simulation. Messages carry data, including the actor ID. You can store messages in a Queue (Simulink) block. Then, you can process these messages using, for example, a MATLAB System block. For more information, see Process Message Payload Using MATLAB System Block (Simulink).

RoadRunner Scenario Reader block outputs messages associated actors when Filter is selected as None. Queue block stores messages and MATLAB Function block processes messages.

Self

Output data for the actor associated with the Simulink model behavior.

Actor ID (provided by input)

Output data for a specific actor. Selecting this option exposes input port Port_1 through which you can provide an actor ID. For example, you can connect the Constant block to Port_1 to provide a fixed value that represents the ID of an actor in a scenario.

Dependencies

To enable this parameter, set Topic Category to Actor or Action.

Relationship to the filtered entity, specified as one of these options:

  • None — No selection. The RoadRunner Scenario reader block outputs data associated with the entity filtered according to the Filter parameter.

  • Parent — Parent actor of filtered entity. The RoadRunner Scenario reader block outputs data associated with the parent of the entity filtered according to the Filter parameter.

  • Children — Children actors of filtered entity. The RoadRunner Scenario reader block outputs data associated with the children of the entity filtered according to the Filter parameter.

For example, select Actor ID (provided by input) as the filter to expose input port Port_1. Attach a Constant block that outputs a value of uint64(2) to the input port. If you select Parent from the Additional Relationship field, then the RoadRunner Scenario Reader block outputs data associated with the parent of the actor with ID 2.

Note

You can also use the Additional Relationship parameter to output information about actions of parent or child actors.

Dependencies

To enable this parameter, set Filter to Actor ID (provided by input) or Self.

Unique index of the sensor, specified as a positive integer. The Sensor ID must correspond to the Unique identifier of sensor parameter of the corresponding sensor model detection generator block.

Dependencies

To enable this parameter, set Topic Category to Sensor and Sensor View to either Target Poses, Lane Boundaries or Target Poses And Lane Boundaries.

Sample time of simulation in seconds, specified as a positive real scalar.

Name of the user-defined event to read from a scenario.

Dependencies

To enable this parameter, set Topic Category to Event and Event Type to User-Defined.

More About

expand all

Version History

Introduced in R2022a

expand all

See Also

| | (Simulink)