Main Content

roadNetwork

Add road network to driving scenario

collapse all in page

Syntax

roadNetwork(scenario,'OpenDRIVE',filename)
roadNetwork(scenario,'OpenDRIVE',filename,'ShowLaneTypes',showLaneTypes)
roadNetwork(scenario,'HEREHDLiveMap',lat,lon)
roadNetwork(scenario,'HEREHDLiveMap',minLat,minLon,maxLat,maxLon)
roadNetwork(scenario,'OpenStreetMap',filename)
roadNetwork(scenario,'ZenrinJapanMap',lat,lon)
roadNetwork(scenario,'ZenrinJapanMap',minLat,minLon,maxLat,maxLon)

Description

OpenDRIVE

roadNetwork(scenario,'OpenDRIVE',filename) imports roads from an ASAM OpenDRIVE® road network file into a driving scenario. The function supports importing road networks from OpenDRIVE® file versions 1.4 and 1.5, as well as ASAM OpenDRIVE file version 1.6.

example

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

Note

As of R2021b, the ASAM OpenDRIVE import feature offers functional and visual improvements, as well as a few additional limitations.

  • You can now import roads with multiple lane specifications.

  • Imported roads show boundary lines that were not shown previously.

  • Road centers always appear in the middle of imported roads. Previously, some roads were showing road centers on the road edges.

  • Junctions are represented using a RoadGroup object that combines road segments within a junction. Previously, each road segment within a junction was represented separately. As a result, imported road networks now use a smaller number of roads.

  • The road IDs, number of roads, junction IDs, and number of junctions in a driving scenario may not match those specified in the imported ASAM OpenDRIVE file.

example

HERE HD Live Map

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.

example

OpenStreetMap

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

example

Zenrin Japan Map API 3.0 (Itsumo NAVI API 3.0)

roadNetwork(scenario,'ZenrinJapanMap',lat,lon) imports roads from a Zenrin Japan Map API 3.0 (Itsumo NAVI API 3.0) 2 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.

Importing roads from the Zenrin Japan Map API 3.0 (Itsumo NAVI API 3.0) service requires Automated Driving Toolbox Importer for Zenrin Japan Map API 3.0 (Itsumo NAVI API 3.0) Service.

example

roadNetwork(scenario,'ZenrinJapanMap',minLat,minLon,maxLat,maxLon) imports Zenrin Japan Map API 3.0 (Itsumo NAVI API 3.0) roads that are at least partially within the geographic bounding box specified by minLat, minLon, maxLat, and maxLon.

example

Examples

collapse all

Open Live Script

Create an empty driving scenario.

scenario = drivingScenario;

Import an ASAM OpenDRIVE road network into the scenario.

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

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

plot(scenario)
xlim([-250 150])
ylim([-175 225])

Figure contains an axes object. The axes object with xlabel X (m), ylabel Y (m) contains 5 objects of type patch, line.

Open Live Script

Create an empty driving scenario.

scenario = drivingScenario;

Import an ASAM 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')

Figure contains an axes object. The axes object with xlabel X (m), ylabel Y (m) contains 4 objects of type patch, line. These objects represent Driving lane, Parking lane.

Import the ASAM 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)

Figure contains an axes object. The axes object with xlabel X (m), ylabel Y (m) contains 3 objects of type patch, line.

Open Script

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;
smoothTrajectory(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

Open Live Script

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)

Open Script

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;
smoothTrajectory(v,[xEast,yNorth,zUp],speed);

while advance(scenario)
    pause(0.01)
end

This example uses:

Open Live Script

Import Zenrin Japan Map 3.0 (Itsumo NAVI API 3.0) 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('tokyoSequence.mat');
lat = data.latitude;
lon = data.longitude;

Display the route by streaming the coordinates on a geographic player. Set the zoom level to 17 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 = 17;
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 Zenrin Japan Map 3.0 (Itsumo NAVI API 3.0) road data that is nearest to the driving route into the scenario.

scenario = drivingScenario;
roadNetwork(scenario,'ZenrinJapanMap',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.

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;
smoothTrajectory(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.

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

This example uses:

Open Live Script

Import Zenrin Japan Map 3.0 (Itsumo NAVI API 3.0) road network data into a driving scenario. Select this data from a region that is centered around a specified geographic coordinate.

Define latitude and longitude coordinates corresponding to a park.

latCenter = 35.6889;
lonCenter = 139.8458;

Specify the minimum and maximum latitude and longitude coordinates for a rectangular region around the park. Display a bounding box corresponding to this region on a geographic plot.

offset = 0.0013;
minLat = latCenter - offset;
minLon = lonCenter - offset;
maxLat = latCenter + offset;
maxLon = lonCenter + offset;

figure
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,'ZenrinJapanMap',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.

figure
plot(scenario)

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

Sample of a driving lane

Border lanesLanes at the road borders

Sample of a border lane

Restricted lanesLanes reserved for high-occupancy vehicles

Sample of a restricted lane

Shoulder lanesLanes reserved for emergency stopping

Sample of a shoulder lane

Parking lanesLanes alongside driving lanes, intended for parking vehicles

Sample of a parking lane

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.

Map of an intersection with a rectangular bounding box around it. Moving clockwise from the top, the sides are labeled maxLat, maxLon, minLat, and minLon.

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.

Map of an intersection with a rectangular bounding box around it. Moving clockwise from the top, the sides are labeled maxLat, maxLon, minLat, and minLon.

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.

Map of an intersection with a rectangular bounding box around it. Moving clockwise from the top, the sides are labeled maxLat, maxLon, minLat, and minLon.

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.

Map of an intersection with a rectangular bounding box around it. Moving clockwise from the top, the sides are labeled maxLat, maxLon, minLat, and minLon.

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.

  • ASAM 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.

  • When you import one-way roads with multiple lane specifications, the function supports only those segment taper positions that match the travel direction of lane. For example, the function supports importing only right taper position for the right lanes. Left or both types of taper position are not supported for right lanes.

  • 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.

  • 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

  • Importing HERE HDLM roads with lanes of varying widths is not supported. 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. This modification to road networks can sometimes cause roads to overlap in the driving scenario.

  • Some issues with the imported roads might be due to missing or inaccurate map data in the HERE HDLM service. For example, you might see black lines where roads and junctions meet. To check where the issue stems from in the map data, use the HERE HD Live Map Viewer to view the geometry of the HERE HDLM road network. This viewer requires a valid HERE license. For more details, see the HERE Technologies website.

OpenStreetMap Import Limitations

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

  • To import complete lane-level information, the OpenStreetMap must contain the lanes and lanes:backward tags. Based on the data in the lanes and lanes:backward tags, these lane specifications are imported:

    • One-way roads are imported with the data in the lanes tag. These lanes are programmatically equivalent to lanespec(lanes).

    • Two-way roads are imported based on the data in both lanes and lanes:backward tags. These lanes are programmatically equivalent to lanespec([lanes:backward numLanesForward]), where numLanesForward = lanes - lanes:backward.

    • For roads that are not one-way without lanes:backward tag specified, number of lanes in the backward direction are imported as uint64(lanes/2). These lanes are programmatically equivalent to lanespec([uint64(lanes/2) numLanesForward]), where numLanesForward = lanes - uint64(lanes/2).

    If lanes and lanes:backward are not present in the OpenStreetMap, then 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. To prevent overlapping, ways in the OpenStreetMap file must specify the vertical stacking relationship of overlapping roads using the layer tags.

  • OpenStreetMap files containing large road networks can take a long time to load. In addition, these road networks can make some of the app options unusable. To avoid this limitation, import files that contain only an area of interest, typically smaller than 20 square kilometers.

  • 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.

Zenrin Japan Map API 3.0 (Itsumo NAVI API 3.0) Import Limitations

When you import Zenrin Japan Map API 3.0 (Itsumo NAVI API 3.0) data, the generated road network has these limitations. As a result of these limitations, the generated network might contain inaccuracies and the roads might overlap.

  • The generated road network uses road elevation data when the Zenrin Japan Map API 3.0 (Itsumo NAVI API 3.0) provides it. Otherwise, the generated network uses terrain elevation data provided by the service.

  • When the Zenrin Japan Map API 3.0 (Itsumo NAVI API 3.0) service provides information using a range, such as by specifying a road with two to three lanes or a road between 3–5.5 meters wide, the generated road network uses scalar values instead. Consider a Zenrin Japan Map API 3.0 (Itsumo NAVI API 3.0) road that has two to three lanes. The generated road network has two lanes.

  • Lanes within roads in the generated network have a uniform width. Consider a road that is 4.25 meters wide with two lanes. In the generated road network, each lane is 2.125 meters wide.

  • Where possible, the generated road network uses road names provided by the Zenrin Japan Map API 3.0 (Itsumo NAVI API 3.0) service. Otherwise, the generated road network uses default names, such as Road1 and Road2.

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.

Version History

Introduced in R2018b

See Also

Apps

Objects

Functions

Topics

External Websites

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.

2 To gain access to the Zenrin Japan Map API 3.0 (Itsumo NAVI API 3.0) service and get the required credentials (a client ID and secret key), you must enter into a separate agreement with ZENRIN DataCom CO., LTD.