Main Content

roadNetwork

Add road network to driving scenario

Description

OpenDRIVE

example

roadNetwork(scenario,'OpenDRIVE',filename) imports roads from an OpenDRIVE® road network file into a driving scenario. This function supports OpenDRIVE format specification version 1.4H [1].

example

roadNetwork(scenario,'OpenDRIVE','ShowLaneTypes',showLaneTypes) uses the name-value pair 'ShowLaneTypes' to also import lane type information from the file and display it in the driving scenario.

HERE HD Live Map

example

roadNetwork(scenario,'HEREHDLiveMap',lat,lon) imports roads from a HERE HD Live Map[1] (HERE HDLM) road network into a driving scenario. The function imports the roads that are nearest to the latitude and longitude coordinates specified in lat and lon, respectively.

example

roadNetwork(scenario,'HEREHDLiveMap',minLat,minLon,maxLat,maxLon) imports HERE HDLM roads that are at least partially within the geographic bounding box specified by minLat, minLon, maxLat, and maxLon.

OpenStreetMap

example

roadNetwork(scenario,'OpenStreetMap',filename) imports roads from an OpenStreetMap® road network file into a driving scenario.

Examples

collapse all

Create an empty driving scenario.

scenario = drivingScenario;

Import an OpenDRIVE road network into the scenario.

filePath = 'intersection.xodr';  
roadNetwork(scenario,'OpenDRIVE',filePath);

Plot the scenario and zoom in on the road network by setting the axes limits.

plot(scenario)
xlim([350 800])
ylim([1400 2000])
zlim([0.00 10.00])

Create an empty driving scenario.

scenario = drivingScenario;

Import an OpenDRIVE road composed of driving and parking lanes into the scenario. By default, the function interprets the lane type information and imports the lanes into driving scenario without altering the lane type.

filePath = 'parking.xodr';  
roadNetwork(scenario,'OpenDRIVE',filePath);

Plot the scenario.

plot(scenario)
zoom(2)
legend('Driving lane','Parking lane')

Import the OpenDRIVE road into the scenario. Set the 'ShowLaneTypes' value to false to suppress multiple lane types. The function ignores the lane type information and imports all the lanes as driving lanes.

scenario = drivingScenario;
roadNetwork(scenario,'OpenDRIVE',filePath,'ShowLaneTypes',false);
plot(scenario)
zoom(2)

Import HERE HDLM road network data that is nearest to the coordinates of a specified driving route into a driving scenario. Plot a vehicle following this route in the driving scenario.

Load a sequence of geographic coordinates that correspond to a driving route.

data = load('geoSequence.mat');
lat = data.latitude;
lon = data.longitude;

Display the route by streaming the coordinates on a geographic player. Set the zoom level to 14 and configure the player to display all points in its history. To speed up the streaming, plot only every tenth coordinate in the route.

zoomLevel = 14;
player = geoplayer(lat(1),lon(1),zoomLevel,'HistoryDepth',Inf);
timestep = 10;

for i = 1:timestep:length(lat)
    plotPosition(player,lat(i),lon(i));
end

Create a driving scenario. Import the HERE HDLM road data that is nearest to the driving route into the scenario.

scenario = drivingScenario;
roadNetwork(scenario,'HEREHDLiveMap',lat,lon);

Use the latlon2local function to convert the driving route from geographic coordinates to local east-north-up (ENU) Cartesian coordinates used in the driving scenario. For the origin of the ENU coordinate system, use the geographic road network origin stored in the GeoReference property of the scenario. The origin is the first coordinate specified in the driving route. Because the driving route contains only latitudinal and longitudinal data, set the altitude to 0.

alt = 0;
origin = scenario.GeoReference;
[xEast,yNorth,zUp] = latlon2local(lat,lon,alt,origin);

Add a vehicle to the driving scenario. Specify the converted driving route as the trajectory of the vehicle. Set a vehicle speed of 30 meters per second.

v = vehicle(scenario,'ClassID',1);
speed = 30;
trajectory(v,[xEast,yNorth,zUp],speed);

Plot the scenario and pause every 0.01 seconds to slow down the simulation. To maintain the same alignment with geographic coordinate displays, the X-axis is on the bottom and the Y-axis is on the left. In driving scenarios not imported from maps, the X-axis is on the left and the Y-axis is on the bottom. This alignment is consistent with the Automated Driving Toolbox™ world coordinate system.

After a few seconds, the vehicle appears to drive underneath the road. This issue occurs because the converted trajectory contains no altitude data but the imported road network does. To avoid this issue, if you are specifying a driving route recorded from a GPS, include the altitude data.

plot(scenario)
while advance(scenario)
    pause(0.01)
end

Import HERE HDLM road network data into driving scenario. Select this data from a region that is centered around a specified geographic coordinate.

Define a latitude and longitude coordinates corresponding to a roundabout.

latCenter = 42.302324;
lonCenter = -71.384970;

Specify the minimum and maximum latitudinal and longitudinal coordinates for a rectangular region around the roundabout. Display a bounding box corresponding to this region on a geographic plot.

offset = 5e-4;
minLat = latCenter - offset;
minLon = lonCenter - offset;
maxLat = latCenter + offset;
maxLon = lonCenter + offset;

gx = geoaxes;
LineSpec = '.-k';
geoplot(gx, ...
        [minLat maxLat],[minLon minLon],LineSpec, ...
        [maxLat maxLat],[minLon maxLon],LineSpec, ...
        [maxLat minLat],[maxLon maxLon],LineSpec, ...
        [minLat minLat],[maxLon minLon],LineSpec)

Create a driving scenario and import roads from the region by using the minimum and maximum coordinates. The roadNetwork function imports roads that are at least partially within this region.

scenario = drivingScenario;
roadNetwork(scenario,'HEREHDLiveMap',minLat,minLon,maxLat,maxLon);

Plot the scenario. To maintain the same alignment with geographic coordinate displays, the X-axis is on the bottom and the Y-axis is on the left. In driving scenarios not imported from maps, the X-axis is on the left and the Y-axis is on the bottom. This alignment is consistent with the Automated Driving Toolbox™ world coordinate system.

plot(scenario) 

Import roads from the OpenStreetMap® web service into a driving scenario. Then, plot a vehicle following a route in the imported road network.

Import a road network of the MathWorks® Apple Hill campus into an empty driving scenario. The file was downloaded from https://www.openstreetmap.org, which provides access to crowd-sourced map data all over the world. The data is licensed under the Open Data Commons Open Database License (ODbL), https://opendatacommons.org/licenses/odbl/.

Plot the imported road network. To maintain the same alignment with geographic coordinate displays, the X-axis is on the bottom and the Y-axis is on the left. In driving scenarios not imported from maps, the X-axis is on the left and the Y-axis is on the bottom. This alignment is consistent with the Automated Driving Toolbox™ world coordinate system.

scenario = drivingScenario;
roadNetwork(scenario,'OpenStreetMap','applehill.osm');
plot(scenario)

Load the latitude and longitude coordinates for a driving route in this road network.

data = load('geoRouteAH.mat');
lat = data.latitude;
lon = data.longitude;

Use the latlon2local function to convert the driving route from geographic coordinates to local east-north-up (ENU) Cartesian coordinates used in the driving scenario. For the origin of the ENU coordinate system, use the geographic road network origin stored in the GeoReference property of the scenario. The origin is the first coordinate specified in the driving route. Because the driving route contains only latitudinal and longitudinal data, set the altitude to 0.

alt = 0;
origin = scenario.GeoReference;
[xEast,yNorth,zUp] = latlon2local(lat,lon,alt,origin);

Add a vehicle to the driving scenario. Specify the converted driving route as the trajectory of the vehicle. Set a vehicle speed of 30 meters per second. Plot the vehicle trajectory and pause every 0.01 seconds to slow down the simulation.

v = vehicle(scenario,'ClassID',1);
speed = 30;
trajectory(v,[xEast,yNorth,zUp],speed);

while advance(scenario)
    pause(0.01)
end

Input Arguments

collapse all

Driving scenario, specified as a drivingScenario object. scenario must contain no previously created or imported roads.

Name of the road network file, specified as a character vector or string scalar.

filename must specify a file in the current folder, a file that is on the MATLAB® search path, or a full or relative path to a file.

filename must end with a file extension that is valid for the source of the road network.

Road Network SourceValid File ExtensionsSample Syntax
OpenDRIVE

.xodr

.xml

roadNetwork(scenario, ...
    'OpenDRIVE','C:\Desktop\roads.xodr'
OpenStreetMap

.osm

.xml

roadNetwork(scenario, ...
    'OpenStreetMap','C:\Desktop\map.osm'

Import lane type information from the OpenDRIVE road network file and display it in the driving scenario, specified as a comma-separated pair consisting of 'ShowLaneTypes' and one of these values:

  • true or 1 — Import lane type information and render lane types.

  • false or 0 — Ignore lane type information and import all lanes as driving lanes in the driving scenario.

The table summarized the supported lane types and their default appearance after importing them into the driving scenario.

Supported Lane TypesDescriptionDefault Appearance
Driving lanesLanes for driving

Border lanesLanes at the road borders

Restricted lanesLanes reserved for high-occupancy vehicles

Shoulder lanesLanes reserved for emergency stopping

Parking lanesLanes alongside driving lanes, intended for parking vehicles

Any other unsupported lane types are rendered as border lanes.

Example: 'ShowLaneTypes',false

Latitude coordinates, specified as a vector of elements in the range [–90, 90]. lat must be the same size as lon. Units are in degrees.

Longitude coordinates, specified as a vector of elements in the range [–180, 180]. lon must be the same size as lat. Units are in degrees.

Minimum latitude coordinate of the bounding box, specified as a scalar in the range [–90, 90]. minLat must be less than maxLat. Units are in degrees.

The roadNetwork function imports any roads that are at least partially within the bounding box specified by inputs minLat, minLon, maxLat, and maxLon. This diagram displays the relationship between these coordinates.

Minimum longitude coordinate of the bounding box, specified as a scalar in the range [–180, 180]. minLon must be less than maxLon. Units are in degrees.

The roadNetwork function imports any roads that are at least partially within the bounding box specified by inputs minLat, minLon, maxLat, and maxLon. This diagram displays the relationship between these coordinates.

Maximum latitude coordinate of the bounding box, specified as a scalar in the range [–90, 90]. maxLat must be greater than minLat. Units are in degrees.

The roadNetwork function imports any roads that are at least partially within the bounding box specified by inputs minLat, minLon, maxLat, and maxLon. This diagram displays the relationship between these coordinates.

Maximum longitude coordinate of the bounding box, specified as a scalar in the range [–180, 180]. maxLon must be greater than minLon. Units are in degrees.

The roadNetwork function imports any roads that are at least partially within the bounding box specified by inputs minLat, minLon, maxLat, and maxLon. This diagram displays the relationship between these coordinates.

Limitations

OpenDRIVE Import Limitations

  • You can import only lanes, lane type information, and roads. The import of road objects and traffic signals is not supported.

  • OpenDRIVE files containing large road networks can take up to several minutes to load. Examples of large road networks include ones that model the roads of a city or ones with roads that are thousands of meters long.

  • Lanes with variable widths are not supported. The width is set to the highest width found within that lane. For example, if a lane has a width that varies from 2 meters to 4 meters, the function sets the lane width to 4 meters throughout.

  • Roads with lane type information specified as driving, border, restricted, shoulder, and parking are supported. Lanes with any other lane type information are imported as border lanes.

  • Roads with multiple lane marking styles are not supported. The function applies the first found marking style to all lanes in the road. For example, if a road has Dashed and Solid lane markings, the function applies Dashed lane markings throughout.

  • Lane marking styles Bott Dots, Curbs, and Grass are not supported. Lanes with these marking styles are imported as unmarked.

HERE HD Live Map Import Limitations

When importing HERE HDLM data, these road and lane features are not supported:

  • Lanes with varying widths — In the generated road network, each lane is set to have the maximum width found along its entire length. Consider a HERE HDLM lane with a width that varies from 2 to 4 meters along its length. In the generated road network, the lane width is 4 meters along its entire length.

  • Roads with varying numbers of lanes along their lengths — In the generated road network, each road is set to have the maximum number of lanes along its entire length. Consider a HERE HDLM road with 3 lanes on one half and 2 lanes on the other half. In the generated road network, the road has 3 lanes along its entire length.

  • Multiple lane marking styles along a lane — In the generated road network, each lane is set to have the marking style of the lane segment with the maximum width along the road. Consider a HERE HDLM lane with 2 lane segments. The first lane segment is 2 meters wide and has solid markings. The second lane segment is 4 meters wide and has dashed markings. In the generated road network, the lane has a fixed width of 4 meters throughout and dashed markings along its entire length.

These modifications to the road networks can sometimes cause roads to overlap in the driving scenario. Consider the HERE HDLM roads for the divided highway highlighted in blue in the table. Due to the unsupported features, in the imported driving scenario, the lane widths of the roads increase. This limitation causes the roads to overlap and appear as one road. Sensors that detect lanes are unable to detect the covered lanes.

HERE HDLM Road NetworkImported Driving Scenario

If you receive a warning that the geometry of a road is unable to be computed, then the curvature of the road is too sharp for it to render properly and it is not imported.

OpenStreetMap Import Limitations

When importing OpenStreetMap data, road and lane features have these limitations:

  • Lane-level information is not imported from OpenStreetMap roads. Lane specifications are based only on the direction of travel specified in the OpenStreetMap road network, where:

    • One-way roads are imported as single-lane roads with default lane specifications. These lanes are programmatically equivalent to lanespec(1).

    • Two-way roads are imported as two-lane roads with bidirectional travel and default lane specifications. These lanes are programmatically equivalent to lanespec([1 1]).

    The table shows these differences in the OpenStreetMap road network and the road network in the imported driving scenario.

    OpenStreetMap Road NetworkImported Driving Scenario

    Two one-way roads gradually taper into one lane.

    Two single-lane roads, with no direction of travel indicated, abruptly transition into a two-lane road with bidirectional travel.

  • When importing OpenStreetMap road networks that specify elevation data, if elevation data is not specified for all roads being imported, then the generated road network might contain inaccuracies and some roads might overlap.

  • The basemap used in the app can have slight differences from the map used in the OpenStreetMap service. Some imported road issues might also be due to missing or inaccurate map data in the OpenStreetMap service. To check whether the data is missing or inaccurate due to the map service, consider viewing the map data on an external map viewer.

  • If you receive a warning that the geometry of a road is unable to be computed, then the curvature of the road is too sharp for it to render properly and it is not imported.

Tips

  • If the roads that you import do not look as expected, consider importing them by using the Driving Scenario Designer app. The app can make the process of troubleshooting and correcting roads easier than trying to troubleshoot and correct them by using the roadNetwork function.

References

[1] Dupuis, Marius, et al. OpenDRIVE Format Specification. Revision 1.4, Issue H, Document No. VI2014.106. Bad Aibling, Germany: VIRES Simulationstechnologie GmbH, November 4, 2015.

Introduced in R2018b

[1] You need to enter into a separate agreement with HERE in order to gain access to the HDLM services and to get the required credentials (access_key_id and access_key_secret) for using the HERE Service.