Build Simple Roads Programmatically Using RoadRunner HD Map

RoadRunner HD Map is a road data model for representing high-definition (HD) map data in a RoadRunner scene. The model defines a simple structure to represent road layouts using lanes, lane boundaries, lane markings, and junctions. This example shows how to build simple roads using RoadRunner HD Map MATLAB® objects and functions. The roads can then be imported into RoadRunner. The steps to construct a road and import it into a RoadRunner scene are:

• Build an HD map in MATLAB

• Verify the representation of lanes and lane boundaries by plotting the map in MATLAB

• Write the map to a RoadRunner HD Map (.rrhd) file

• Import the file into RoadRunner and preview the RoadRunner HD Map data

• Build a RoadRunner scene from the imported file (requires RoadRunner Scene Builder).

Create a Straight Unmarked Road

A fixed-width road is defined using a series of x-y coordinates that correspond to the location of the center of the road. This figure shows a straight, unmarked road that you will create in this section. You will also plot the road in MATLAB and then save it to a binary file.

Create an empty RoadRunner HD Map by calling the roadrunnerHDMap object.

rrMap = roadrunnerHDMap;

Define the center of the straight road as a 2D array that contains three sets of x-y coordinates specifying the center of the road. Also, define the width of the road.

roadCenters = [0 0;0 50;0 100];
roadWidth = 6;

Create the left and right boundaries of the road using the roadrunner.hdmap.LaneBoundary object. Specify the lane boundary information for the lane id and the coordinates defining the lane geometry.

rrMap.LaneBoundaries(1) = roadrunner.hdmap.LaneBoundary(ID="Left",Geometry=roadCenters-[roadWidth/2 0]);
rrMap.LaneBoundaries(2) = roadrunner.hdmap.LaneBoundary(ID="Right",Geometry=roadCenters+[roadWidth/2 0]);

Create the road lane using the roadrunner.hdmap.Lane object. Specify the lane information for the lane id, coordinates defining the lane geometry, driving direction, and lane type.

rLane = roadrunner.hdmap.Lane(ID="Lane",Geometry=roadCenters,TravelDirection="Forward",LaneType="Driving");

Link the lane boundaries to the lanes. Define the left and the right lane boundaries for each lane, and specify alignment between lanes and lane boundaries.

leftBoundary(rLane,"Left",Alignment="Forward");
rightBoundary(rLane,"Right",Alignment="Forward");
rrMap.Lanes = rLane;

Plot the lane centers and lane boundaries to preview the lanes and lane boundaries before importing them into RoadRunner.

plot(rrMap);

Write the HD map plotted in the previous step to a file using the write function.

write(rrMap,"straightRoad.rrhd");

Import and Build HD Map File into RoadRunner

For detailed instructions on importing a RoadRunner HD Map file with .rrhd extension into RoadRunner, previewing the map, and building the scene, see Import Custom Data Using RoadRunner HD Map (RoadRunner).

Open RoadRunner application using roadrunner object from the MATLAB® command line. 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).

rrApp = roadrunner(ProjectFolder="C:\RR\MyProject", InstallationFolder="C:\Program Files\RoadRunner R2024a");

Alternatively, you can start the RoadRunner application interactively, using the roadrunnerSetup function. This function opens a dialog box to specify the project folder and installation folder to use when opening RoadRunner.

Import and build the RoadRunner HD Map data from a file specified into the currently open scene. Before you build the scene you must activate your RoadRunner SceneBuilder license interactively.

file = fullfile(pwd,"straightRoad.rrhd");
importScene(rrApp,file,"RoadRunner HD Map");

This figure shows a scene built using RoadRunner Scene Builder.

Add Markings to the Straight Road

In this section, you add solid white lane markings to the left and right lane boundaries of the straight road you created in the previous section. To specify a lane marking, you need an asset in RoadRunner. In this example, you use assets that are a part of the RoadRunner Asset Types (RoadRunner). These assets are specified in the map using a relative path to the RoadRunner project folder.

Define the path to the solid white lane marking asset using the roadrunner.hdmap.RelativeAssetPath function.

solidWhiteAsset = roadrunner.hdmap.RelativeAssetPath(AssetPath="Assets/Markings/SolidSingleWhite.rrlms");

Create a solid white lane marking on the straight road using the roadrunner.hdmap.LaneMarking object. Specify the lane marking information for the lane marking id and the path to the asset.

rrMap.LaneMarkings = roadrunner.hdmap.LaneMarking(ID="SolidWhite",AssetPath=solidWhiteAsset);

Create a reference for the solid white marking to apply to lane boundaries using the roadrunner.hdmap.MarkingReference object.

markingRefSW = roadrunner.hdmap.MarkingReference(MarkingID=roadrunner.hdmap.Reference(ID="SolidWhite"));

Use parametric attributes to apply this lane marking to span the full length of the left and right lane boundaries.

markingSpan = [0 1];
markingAttribSW = roadrunner.hdmap.ParametricAttribution(MarkingReference=markingRefSW,Span=markingSpan);
rrMap.LaneBoundaries(1).ParametricAttributes = markingAttribSW;
rrMap.LaneBoundaries(2).ParametricAttributes = markingAttribSW;

Write the modified HD map to a file.

write(rrMap,"straightRoadWithMarkings.rrhd");

Import and build the RoadRunner HD Map data from a file specified into the currently open scene.

file = fullfile(pwd,"straightRoadWithMarkings.rrhd");
importScene(rrApp,file,"RoadRunner HD Map");

This figure shows a scene built using RoadRunner Scene Builder.

Create a Two-Way Road

A two-way road has two lanes with opposite driving directions. A solid yellow lane marking separates the lanes. This figure shows a straight two-way road that you will create in this section. You use the same road centers and road width used in the previous sections.

Create an empty RoadRunner HD Map by calling the roadrunnerHDMap object.

rrMap = roadrunnerHDMap;

Specify the lane and the lane boundaries. In this example, pre-initialization of values results in improved performance as the number of objects in the map increases.

rrMap.Lanes(2,1) = roadrunner.hdmap.Lane();
rrMap.LaneBoundaries(3,1) = roadrunner.hdmap.LaneBoundary();

Assign the Lane property values. Use the deal function to match up the input and the output lists.

[rrMap.Lanes.ID] = deal("Lane1","Lane2");
[rrMap.Lanes.Geometry] = deal(roadCenters-[roadWidth/4 0],roadCenters+[roadWidth/4 0]);
[rrMap.Lanes.TravelDirection] = deal("Backward","Forward");
[rrMap.Lanes.LaneType] = deal("Driving");

Assign the LaneBoundaries property values. In this example, the center lane is shared between Lane1 and Lane2.

[rrMap.LaneBoundaries.ID] = deal("Left","Center","Right");
[rrMap.LaneBoundaries.Geometry] = deal(roadCenters-[roadWidth/2 0],...
  roadCenters,roadCenters+[roadWidth/2 0]);

Link the lane boundaries to the lanes. Define the left and the right lane boundaries for each lane, and specify alignment between lanes and lane boundaries.

leftBoundary(rrMap.Lanes(1),"Left",Alignment="Forward");
rightBoundary(rrMap.Lanes(1),"Center",Alignment="Forward");
leftBoundary(rrMap.Lanes(2),"Center",Alignment="Forward");
rightBoundary(rrMap.Lanes(2),"Right",Alignment="Forward");

Add a yellow solid marking in addition to the solid white marking you added before. Define the path to the solid yellow lane marking asset using the roadrunner.hdmap.RelativeAssetPath function.

solidYellowAsset = roadrunner.hdmap.RelativeAssetPath(AssetPath="Assets/Markings/SolidSingleYellow.rrlms");

Create a solid yellow lane marking on the straight road using the roadrunner.hdmap.LaneMarking object. Specify the lane marking information for the lane marking id and the path to the asset.

rrMap.LaneMarkings(2,1) = roadrunner.hdmap.LaneMarking();
[rrMap.LaneMarkings.ID] = deal("SolidWhite","SolidYellow");
[rrMap.LaneMarkings.AssetPath] = deal(solidWhiteAsset,solidYellowAsset);

Assign the white marking to the lane boundaries at lane edges and yellow marking to the center lane boundary. These markings span the entire length of the boundary.

markingRefSY = roadrunner.hdmap.MarkingReference(MarkingID=roadrunner.hdmap.Reference(ID="SolidYellow"));
markingAttribSY = roadrunner.hdmap.ParametricAttribution(MarkingReference=markingRefSY,Span=markingSpan);
[rrMap.LaneBoundaries.ParametricAttributes] = deal(markingAttribSW,markingAttribSY,markingAttribSW);

Plot the lane centers and lane boundaries.

plot(rrMap)

Write the HD map to a file.

write(rrMap,"twoWayRoad.rrhd");

Import and build the RoadRunner HD Map data from a file specified into the currently open scene.

file = fullfile(pwd,"twoWayRoad.rrhd");
importScene(rrApp,file,"RoadRunner HD Map");

This figure shows a scene built using RoadRunner Scene Builder.

Add a Lane to a One-Way Road

In this section, you add a lane to a one-way road. A dashed white marking is used to separate two lanes with the same travel direction. To add a lane to a one-way road, you will need to split one lane into two from the left edge of a lane. This requires creating additional lanes and lane boundaries in the RoadRunner HD map where the lane splits. This figure shows the lane that you will adding to the one-way road:

Create an empty RoadRunner HD Map by calling the roadrunnerHDMap object.

rrMap = roadrunnerHDMap;

Specify the lane and the lane boundaries.

rrMap.Lanes(5,1) = roadrunner.hdmap.Lane();
rrMap.LaneBoundaries(8,1) = roadrunner.hdmap.LaneBoundary();

Specify the lane groups and the lane markings.

rrMap.LaneGroups(3,1) = roadrunner.hdmap.LaneGroup();
rrMap.LaneMarkings(3,1) = roadrunner.hdmap.LaneMarking();

Assign the Lane property values. Split Lane1 into Lane4 and Lane5 and use Lane2 and Lane3 for transition.

[rrMap.Lanes.ID] = deal("Lane1","Lane2","Lane3","Lane4","Lane5");
[rrMap.Lanes.Geometry] = deal([0 -20;0 0;0 20;],[0 20;0 40;0 60;],[0 20;-3 40;-6 60],[-6 60;-6 80;-6 100],[0 60;0 80;0 100]);
[rrMap.Lanes.TravelDirection] = deal("Forward");
[rrMap.Lanes.LaneType] = deal("Driving");

Assign the LaneBoundaries property values. Lane3 shares its right boundary with Lane2, which is denoted by Left2.

[rrMap.LaneBoundaries.ID] = deal("Left1","Right1","Left2","Right2","Left3","Left4","Center4","Right4");
[rrMap.LaneBoundaries.Geometry] = deal([-3 -20;-3 0;-3 20],[3 -20;3 0;3 20],[-3 20;-3 40;-3 60;],...
        [3 20;3 40;3 60],[-3 20;-6 40;-9 60],[-9 60;-9 80;-9 100],[-3 60;-3 80;-3 100],[3 60;3 80;3 100]);

Link the lane boundaries to the lanes. Define the left and the right lane boundaries for each lane, and specify alignment between lanes and lane boundaries.

leftBoundary(rrMap.Lanes(1),"Left1",Alignment="Forward");
rightBoundary(rrMap.Lanes(1),"Right1",Alignment="Forward");
leftBoundary(rrMap.Lanes(2),"Left2",Alignment="Forward");
rightBoundary(rrMap.Lanes(2),"Right2",Alignment="Forward");
leftBoundary(rrMap.Lanes(3),"Left3",Alignment="Forward");
rightBoundary(rrMap.Lanes(3),"Left2",Alignment="Forward");
leftBoundary(rrMap.Lanes(4),"Left4",Alignment="Forward");
rightBoundary(rrMap.Lanes(4),"Center4",Alignment="Forward");
leftBoundary(rrMap.Lanes(5),"Center4",Alignment="Forward");
rightBoundary(rrMap.Lanes(5),"Right4",Alignment="Forward");

Specify alignment between the lanes by defining information about their predecessor and successor relationship.

rrMap.Lanes(3).Successors = roadrunner.hdmap.AlignedReference(Reference=roadrunner.hdmap.Reference(ID="Lane4"),Alignment="Forward");
rrMap.Lanes(3).Predecessors = roadrunner.hdmap.AlignedReference(Reference=roadrunner.hdmap.Reference(ID="Lane1"),Alignment="Forward");
rrMap.Lanes(2).Successors = roadrunner.hdmap.AlignedReference(Reference=roadrunner.hdmap.Reference(ID="Lane5"),Alignment="Forward");
rrMap.Lanes(2).Predecessors = roadrunner.hdmap.AlignedReference(Reference=roadrunner.hdmap.Reference(ID="Lane1"),Alignment="Forward");
rrMap.Lanes(1).Successors = roadrunner.hdmap.AlignedReference(Reference=roadrunner.hdmap.Reference(ID="Lane2"),Alignment="Forward");
rrMap.Lanes(1).Successors(2,1) = roadrunner.hdmap.AlignedReference(Reference=roadrunner.hdmap.Reference(ID="Lane3"),Alignment="Forward");
rrMap.Lanes(4).Predecessors = roadrunner.hdmap.AlignedReference(Reference=roadrunner.hdmap.Reference(ID="Lane3"),Alignment="Forward");
rrMap.Lanes(5).Predecessors = roadrunner.hdmap.AlignedReference(Reference=roadrunner.hdmap.Reference(ID="Lane2"),Alignment="Forward");

Add a dashed white marking in addition to the solid white and yellow markings you added before. Define the path to the dashed white lane marking asset using the roadrunner.hdmap.RelativeAssetPath function.

dashedWhiteAsset = roadrunner.hdmap.RelativeAssetPath(AssetPath="Assets/Markings/DashedSingleWhite.rrlms");

Create a dashed white lane marking on the road using the roadrunner.hdmap.LaneMarking object.

rrMap.LaneMarkings(3,1) = roadrunner.hdmap.LaneMarking();
[rrMap.LaneMarkings.ID] = deal("SolidWhite","SolidYellow","DashedWhite");
[rrMap.LaneMarkings.AssetPath] = deal(solidWhiteAsset,solidYellowAsset,dashedWhiteAsset);

Assign lane markings using the parametric attributes.

markingRefDW = roadrunner.hdmap.MarkingReference(MarkingID=roadrunner.hdmap.Reference(ID="DashedWhite"));
markingAttribDW = roadrunner.hdmap.ParametricAttribution(MarkingReference=markingRefDW,Span=markingSpan);
[rrMap.LaneBoundaries.ParametricAttributes] = deal(markingAttribSY,markingAttribSW,markingAttribDW,markingAttribSW,...
    markingAttribSY,markingAttribSY,markingAttribDW,markingAttribSW);

Plot lane centers and lane boundaries.

plot(rrMap)

Write the HD map to a file.

write(rrMap,"laneAdd.rrhd");

User must copy the HD map file to the current project's asset folder when using import and build options.

copyfile("laneAdd.rrhd", "C:\RR\MyProject\Assets");

Create RoadRunner HD Map import options that loads the map.

importOptions = roadrunnerHDMapImportOptions(ImportStep="Load"); 

Load the RoadRunner HD Map data from the specified file into the currently open scene.

file = fullfile("C:\RR\MyProject\Assets","laneAdd.rrhd");
importScene(rrApp,file,"RoadRunner HD Map",importOptions);

Create RoadRunner HD Map build options that builds the map.

buildOptions = roadrunnerHDMapBuildOptions(DetectAsphaltSurfaces=true);

Build the RoadRunner HD Map data from the specified file into the currently open scene.

buildScene(rrApp,"RoadRunner HD Map",buildOptions);

This figure shows a scene built using RoadRunner Scene Builder.