Main Content

Highway Lane Change Planner with RoadRunner Scenario

This example shows how to simulate a highway lane change planner, designed in Simulink®, with RoadRunner Scenario.


RoadRunner Scenario is an interactive editor that enables you to design scenarios for simulating and testing automated driving systems. You can place vehicles, define their paths and interactions in the scenario, and then simulate the scenario in the editor. RoadRunner Scenario supports in-editor playback for scenario visualization and connecting to other simulators, such as MATLAB® and Simulink, for cosimulation.

The lane change planner is a fundamental component of a highway lane change system that enables an ego vehicle to move from one lane to another. The lane change planner is expected to handle different driving behaviors to safely navigate the ego vehicle from one point to another point. This example shows how to use RoadRunner Scenario to simulate the highway lane change planner reference model used in the Generate Code for Highway Lane Change Planner example.

This figure shows an overview of the information exchanged between RoadRunner Scenario and the highway lane change planner. The lane change planner reads path action, map data, and all actor runtime from RoadRunner Scenario. The planner uses this information to sample trajectories, and then finds an optimal collision-free trajectory to navigate the ego vehicle in the scenario.

In this example, you:

  • Set up the environment — Configure MATLAB settings to interact with RoadRunner Scenario.

  • Explore RoadRunner scenario — Explore the RoadRunner scene and scenario required for simulating the highway lane change planner.

  • Explore the highway lane change planner test bench — The test bench model has interfaces for RoadRunner Scenario, the highway lane change planner, metrics assessment, and visualization.

  • Simulate the lane change scenario — Cosimulate the lane change planner with RoadRunner Scenario and assess performance.

  • Explore additional scenarios — These scenarios test the system under additional conditions.

Set Up Environment

This section shows how to set up the environment to cosimulate the highway lane change planner with RoadRunner Scenario.

Start RoadRunner application interactively by using the roadrunnerSetup function. When the function opens a dialog box, specify the RoadRunner Project Folder and RoadRunner Installation Folder locations.

rrApp = roadrunnerSetup;

The rrApp RoadRunner object enables you to interact with RoadRunner from the MATLAB workspace. You can open the scenario and update scenario variables using this object. For more information on variables, see Generate Scenario Variations Using gRPC API (RoadRunner Scenario).

To explore the test bench model, load the highway lane change planner project.


Copy the RoadRunner scene, scenario, and behavior files to the RoadRunner project. To learn more about the RoadRunner environment, see RoadRunner Project and Scene System (RoadRunner).

HLCWithRRScenarioProject = currentProject;
projectPath = convertStringsToChars(HLCWithRRScenarioProject.RootFolder);
projectRootFolder = projectPath(1:find(projectPath=='\',1,'last')-1);


Explore RoadRunner scenario

This example reuses the highway lane change planner from the Generate Code for Highway Lane Change Planner example. This planner supports specific road types and needs a reference path for planning its trajectories. As it requires time input for re-planning, you must synchronize the step size of the lane change planner model with RoadRunner scenario.

Road Design

Highway lane change planner supports roads with elevation and non-uniform lane width. This example uses FreewayGauntlet.rrscene to simulate the highway lane change planner. The scene contains a one-way highway road which forks up to a bridge. Open the scene.


Notice that the road in the scene has elevations and variable lane width.

Ego Reference Path

To navigate the ego vehicle, the lane change planner requires a predefined global reference path. You can specify the path for the vehicle using RoadRunner Scenario editor. For more information on how to specify a path, see Path Editing (RoadRunner Scenario). If you do not specify path for the vehicle, this example generates a path using lane centers.

This example uses the scenario_HLCRR_09_Freeway_Exit.rrscenario scenario. Open the scenario.


The scenario consists of four vehicles. The blue sedan is named Ego. An explicit driving path is not specified for Ego. The planner uses the global reference path generated using lane centers. The other three vehicles are configured to use the built-in behavior of RoadRunner Scenario. In this example, these vehicles are the target actors. To simulate lane change behavior for the ego vehicle Ego, specify custom behavior for it using the HLCPlanner.rrbehavior.rrmeta file. For more information on custom behavior, see Overview of Simulating RoadRunner Scenarios with MATLAB and Simulink.

Connect to the RoadRunner Scenario server for cosimulation using the createSimulation function, and enable data logging.

rrSim = rrApp.createSimulation;
Connection status: 1
Connected to RoadRunner Scenario server on localhost:54322, with client id {fea68f41-f400-4eb8-8afd-6b43753a032b}

rrSim is the ScenarioSimulation object. Use this object to set variables and to read scenario and map-related information.

Simulation Step Size

The lane change planner is designed to run at a step size of 0.1 seconds. Set the simulation step size of RoadRunner Scenario to 0.1 seconds.

Ts = 0.1;

Explore Highway Lane Change Planner Test Bench

In this example, you use a system level test bench model to simulate and test the behavior of a lane change planner with RoadRunner Scenario. Open the test bench model.


The test bench model contains RoadRunner Scenario blocks, which configure, read from, and write to RoadRunner Scenario, as well as these modules:

  • Highway Lane Change Planner — Reference model that implements the lane change planner algorithm.

  • Planner Configuration Parameters — Subsystem that specifies the configuration parameters required for the highway lane change planner algorithm.

  • Reference Path Lane Info — System object™ that reads the reference path and populates the required lane information for the lane change planner.

  • Target Actors — Subsystem that converts the runtime information of all the target vehicles to the required bus format for the lane change planner.

  • Metrics Assessment — Subsystem that specifies metrics to assess the highway lane change planner behavior.

  • Pack Ego Pose — Subsystem that updates the actor bus using the current state of the ego vehicle from the lane change planner.

  • Visualization — System object that visualizes the status of the ego vehicle and other vehicles defined in the scenario.

The Highway Lane Change Planner model and Planner Configuration Parameters, Metrics Assessment, and Pack Ego Pose subsystems are based on the subsystems used in the Generate Code for Highway Lane Change Planner example. This example focuses on the RoadRunner Scenario blocks and the Reference Path Lane Info, Pack Ego Pose, and Visualization subsystems.

RoadRunner Scenario Blocks

The RoadRunner Scenario blocks consist of:

  • RoadRunner Scenario — Defines the interface for an actor model.

  • Path Action — RoadRunner Scenario Reader block that reads the reference path of the ego vehicle.

  • All Actor Runtime — RoadRunner Scenario Reader block that reads runtime information of all the vehicles.

  • Self Actor Runtime Reader — RoadRunner Scenario Reader block that reads ego actor runtime information.

  • Self Actor Runtime Writer — RoadRunner Scenario Writer block that writes the ego vehicle runtime to RoadRunner Scenario.

Reference Path Lane Info

The Reference Path Lane Info System object is implemented as HelperReferencePathLaneInfo.m. The System object reads the specified reference path of the ego vehicle from the RoadRunner scenario to calculate the lane-related information RefPathLaneInfo, required by the highway lane change planner. If you do not specify the reference path for the ego vehicle, the System object generates the reference path using lane centers of the ego lane. The System object reads the ActorRuntime and Follow Path Action messages from RoadRunner Scenario, then constructs lane information for the reference path. The primary interface of the subsystem is:

RefPathLaneInfo = stepImpl(obj,ActorRuntime,PathAction)
  • ActorRuntime — Self actor runtime message from RoadRunner Scenario.

  • PathAction — Path action message from RoadRunner Scenario.

  • RefPathLaneInfo — Bus with lane and path information required for highway lane change planner.

RefPathLaneInfo contains this information:

  • NumLanes — Number of lanes in the scenario.

  • LaneWidth — Width of each lane.

  • LaneCenters — Lane center offsets from the reference path.

  • NumGlobalPlanPoints — Number of points in the reference path.

  • GlobalPlanPoints — Reference path points.

HelperReferencePathLaneInfo uses the helperGetLaneInfo function to read lane and lane boundary information from RoadRunner.

[lanes,laneBoundaries] = helperGetLaneInfo(rrSim);

The lanes output argument is a structure that contains these fields:

  • ID — ID of the lane.

  • TravelDir — Travel direction of the lane.

  • LaneType — Type of lane.

  • LeftLaneBoundary — Left lane boundary information.

  • RightLaneBoundary — Right lane boundary information.

  • SuccessorLanes — Successor of the current lane.

  • PredecessorLanes — Predecessor of the current lane.

  • Geometry — Lane center coordinates.

The laneBoundaries output argument is a structure with these fields:

  • ID — ID of the lane boundary.

  • Geometry — Lane boundary coordinates.

Pack Ego Pose

The Pack Ego Pose subsystem packs the planner output into the actor runtime message and actor pose. The Self Actor Runtime Writer blocks writes the actor runtime message to RoadRunner Scenario. The actor pose is used as input for the Metrics Assessment subsystem.

open_system("HLCPlannerRRTestBench/Pack Ego Pose");

The Map Matching System object calculates roll and pitch information of the ego vehicle using map information. The System object outputs the actor pose with elevation and banking information.


Visualization System object creates a MATLAB plot of the capsule list of all vehicles and candidate trajectories of the ego vehicle. The HelperPlotHLCPlannerWithRRScenario script implements the visualization using this primary interface:

  • VisualizationInfo — Trajectory information obtained from the planner.

  • TargetActorsWorld — Target actor runtime information.

  • EgoActor — Ego vehicle runtime information.

Simulate and Visualize Lane Change Scenario

This example uses the helperSLHLCPlannerRRSetup function to initialize the ego and target actor profiles based on the selected scenario.


This model may take a couple of minutes to update the diagram when you are compiling for the first time. Update the model before running the simulation.


Simulate the scenario and observe the lane changes made by the ego vehicle to avoid collisions with the target actors.

while strcmp(rrSim.get("SimulationStatus"),"Running")
hLCPlot = findobj(Type="Figure",Name="Lane Change Status Plot");
if ~isempty(hLCPlot)

Notice that the ego vehicle changes lanes twice to avoid collision. Visualize the top view of the scenario using a MATLAB figure that plots the ego vehicle, sampled trajectories, capsule list, and other vehicles in the scenario. The visualization also shows the optimal, colliding, infeasible, and non-evaluated trajectories of the ego vehicle, in the MATLAB figure.

During the simulation, the model logs signals to base workspace as logsout. You can analyze the simulation results and debug any failures in the system behavior using the HelperAnalyzeLCRRSimulationResults object. The visualizeSimulationData function of the object creates a MATLAB figure and plots the scenario. The slider in the figure enables you to select a desired simulation step to analyze different parameters shown in these panes:

  • Top View — Shows top view of the scenario showing ego vehicle, sampled trajectories, capsule list, and other vehicles.

  • Trajectory Information — Shows different attributes of sampled trajectories. The highlighted rows show the type of sampled trajectory by using the same color coding as shown in the Top View.

  • MIO Information — Shows different attributes of identified most important objects (MIOs). The color of the row matches the face color of the corresponding vehicle.

  • Mode — Shows the selected behavior for the ego vehicle.

  • Ego Velocity — Shows the velocity of ego vehicle. Units are in meters per second.

  • Simulation Step — Shows the simulation step number set using the slider.

  • Simulation Time — Shows time corresponding to simulation step. Units are in seconds.

  • Ego State — Shows parameters of the ego vehicle and identified lead vehicle.

  • Planner Parameters — Shows configuration parameters for the planner.

Run the script and explore the plot.

visualizatonObj = HelperAnalyzeLCRRSimulationResults(logsout);

Explore Other Scenarios

In this example, you have explored the system behavior for the scenario_HLCRR_09_Freeway_Exit scenario, which used FreewayGauntlet.rrscene. You can use the same test bench model to explore other scenarios. This example provides these additional scenarios, which are compatible with the HLCPlannerRRTestBench model.

  • scenario_HLCRR_01_SlowMoving

  • scenario_HLCRR_02_SlowMoving_PassingCar

  • scenario_HLCRR_03_DisabledCar

  • scenario_HLCRR_04_DenseTraffic

  • scenario_HLCRR_05_ALKS_CutIn_NoCollision

  • scenario_HLCRR_06_ALKS_Cutout_DisabledCar

  • scenario_HLCRR_07_Cutin_DisabledCar

  • scenario_HLCRR_08_Freeway_CutIn

scenario_HLCRR_04_DenseTraffic scenario use CurvedRoad.rrscene scene, which consists of a curved highway scene with four lanes and other scenarios use WindingRoad.rrscene scene, which consists of a winding highway scene with eight lanes. You can configure the HLCPlannerRRTestBench model to simulate these scenarios using the helperSLHLCPlannerRRSetup function. For example, to configure, the test bench to simulate the scenario_HLCRR_01_SlowMoving scenario, enter this command.


See Also



Related Topics