hereHDLMReader

HERE HD Live Map reader

Description

Use a hereHDLMReader object to read high-definition map data for selected map tiles from the HERE HD Live Map[1] (HERE HDLM) web service, provided by HERE Technologies. HERE HDLM data provides highly detailed and accurate information about the vehicle environment, such as road and lane topology, and is suitable for developing automated driving applications.

You can select specific map tiles from which to read data or select map tiles based on the coordinates of a driving route. To read map data for tiles, use the read function and specify the reader as an input argument. For more details, see Access HERE HD Live Map Data.

Note

Use of the hereHDLMReader object requires valid HERE HDLM credentials. If you have not previously set up credentials, a dialog box prompts you to enter them. Enter the App ID and App Code that you obtained from HERE Technologies, and click OK.

Creation

Description

example

reader = hereHDLMReader(lat,lon) creates a HERE HDLM reader that can read map data for the HERE map tiles that correspond to a set of latitude and longitude coordinates. The map tiles are at a zoom level of 14.

example

reader = hereHDLMReader(tileID) creates a HERE HDLM reader that can read map data for the map tiles with the specified HERE tile IDs. These tile IDs are stored in the TileIDs property of the HERE HDLM reader.

example

reader = hereHDLMReader(___,Name,Value) sets the Configuration, WriteLocation, and CoordinateFormat properties using one or more name-value pairs. For example, hereHDLMReader(tileID,'Configuration',config) creates a reader that is configured to read map tile data from a specific HERE HDLM production catalog or catalog version, where config is a hereHDLMConfiguration object.

Input Arguments

expand all

Latitude coordinates, specified as a vector of real values in the range [–90, 90].

Use this vector, along with lon, to specify the coordinates of a driving route that you want to read map data from.

lat and lon must be the same size.

Data Types: double

Longitude coordinates, specified as a vector of real values in the range [–180, 180].

Use this vector, along with lat, to specify the coordinates of a driving route that you want to read map data from.

lat and lon must be the same size.

Data Types: double

HERE tile IDs from which to read data, specified as a vector of unsigned 32-bit integers. These tile IDs are stored in the TileIDs property of the hereHDLMReader object.

The specified map tiles must all come from the same geographic region. For a list of available regions and their corresponding values in the HERE HDLM production catalog, see the Configuration property.

If you configure the hereHDLMReader object to read data from a specific catalog using the hereHDLMConfiguration object, then all tile IDs must be found within that catalog. Otherwise, the reader object returns an error.

Example: uint32([386497368 386497369])

Data Types: uint32

Properties

expand all

This property is read-only.

HERE tile IDs from which to read data, specified as a vector of unsigned 32-bit integers. These tiles correspond to either the specified lat and lon coordinates or the specified tileID tiles.

Example: uint32([386497368 386497369])

Data Types: uint32

This property is read-only.

Map data layers available for the selected HERE tile IDs, specified as a string array of layer names. The available map layers vary depending on the geographic region.

To read data from these layers, specify these layer names as inputs to the read function.

This property is read-only.

Catalog configuration, specified as a hereHDLMConfiguration object. This configuration contains the specific HERE HDLM catalog and catalog version that the hereHDLMReader object reads data from.

If you do not specify a configuration at creation, the reader object computes the default configuration by searching the latest version of each production catalog. If all selected map tile IDs are found within a catalog, then the hereHDLMReader object is configured to read data from the latest version of that catalog.

You can specify a configuration using either the catalog name or the corresponding region name. This table shows the valid region names and their corresponding HERE HDLM production catalog names.

RegionCatalog
'Asia Pacific''here-hdmap-ext-apac-1'
'Eastern Europe''here-hdmap-ext-eeu-1'
'India''here-hdmap-ext-rn-1'
'Middle East And Africa''here-hdmap-ext-mea-1'
'North America''here-hdmap-ext-na-1'
'Oceania''here-hdmap-ext-au-1'
'South America''here-hdmap-ext-sam-1'
'Western Europe''here-hdmap-ext-weu-1'

You can set this property when you create the reader object. After you create the object, this property is read-only.

This property is read-only.

Name of folder to which HERE HDLM data is downloaded, specified as a string scalar or character vector. The specified folder must exist and have write permissions.

By default, data from the HERE HDLM web service is downloaded to a temporary file location. This temporary file location is deleted at the end of your MATLAB® session.

You can set this property when you create the reader object. After you create the object, this property is read-only.

Example: "C:\Users\myName\HERE"

Type of coordinate encoding format to apply to geographic coordinate values, specified as either 'geographic' or 'raw'.

FormatDescriptionExample
'geographic'Coordinate values are returned as (latitude, longitude) pairs with decimal degrees.[42.3743 -71.0266]
'raw'Coordinate values are returned in the default coordinate encoding format of the HERE HDLM service.int64(5978842261285240832)

Object Functions

readRead HERE HD Live Map layer data
plotPlot HERE HD Live Map layer data

Examples

collapse all

Use the HERE HD Live Map (HERE HDLM) service to read the lane topology data of a driving route and its surrounding area. Plot this data, and then stream the route on a geographic player.

Load the latitude and longitude coordinates of a driving route in Natick, Massachusetts, USA.

route = load(fullfile(matlabroot,'examples','driving','geoSequenceNatickMA.mat'));
lat = route.latitude;
lon = route.longitude;

Stream the coordinates on a geographic player.

player = geoplayer(lat(1),lon(1),'HistoryDepth',5);
plotRoute(player,lat,lon)

for idx = 1:length(lat)
    plotPosition(player,lat(idx),lon(idx))
end

Create a HERE HDLM reader from the route coordinates. If you have not previously set up HERE HDLM credentials, a dialog box prompts you to enter them. The reader contains map data for the two map tiles that the route crosses.

reader = hereHDLMReader(lat,lon);

Read lane topology data from the LaneTopology layer of the map tiles. Plot the lane topology.

laneTopology = read(reader,'LaneTopology');
plot(laneTopology)

Overlay the route data on the plot.

hold on
geoplot(lat,lon,'bo-','DisplayName','Route');
hold off

Overlay the lane topology data on the geographic player. Stream the route again.

plot(laneTopology,'Axes',player.Axes)
for idx = 1:length(lat)
    plotPosition(player,lat(idx),lon(idx))
end

Use the HERE HD Live Map (HERE HDLM) web service to read 3-D lane geometry data from a map tile. Then, plot the data on an OpenStreetMap® basemap.

Create a HERE HDLM reader for a map tile ID representing an area of Berlin, Germany. If you have not previously set up HERE HDLM credentials, a dialog box prompts you to enter them.

tileID = uint32(377894435);
reader = hereHDLMReader(tileID);

Add the OpenStreetMap basemap to the list of basemaps available for use with the HERE HDLM service. After you add the basemap, you do not need to add it again in future sessions.

name = 'openstreetmap';
url = 'https://a.tile.openstreetmap.org/${z}/${x}/${y}.png';
copyright = char(uint8(169));
attribution = copyright + "OpenStreetMap contributors";
addCustomBasemap(name,url,'Attribution',attribution)

Read 3-D lane geometry data from the LaneGeometryPolyline layer of the map tile. Plot the lane geometry on the openstreetmap basemap.

laneGeometryPolyline = read(reader,'LaneGeometryPolyline');
gx = plot(laneGeometryPolyline);
geobasemap(gx,'openstreetmap')

Zoom in on the central coordinate of the map tile.

latcenter = laneGeometryPolyline.TileCenterHere3dCoordinate.Here2dCoordinate(1);
loncenter = laneGeometryPolyline.TileCenterHere3dCoordinate.Here2dCoordinate(2);

offset = 0.001;
latlim = [latcenter-offset,latcenter+offset];
lonlim = [loncenter-offset,loncenter+offset];

geolimits(latlim,lonlim)

Use the HERE HD Live Map (HERE HDLM) web service to read the topology geometry data from a map tile. Use this data to find the shortest path between two nodes within the map tile.

Define a HERE tile ID for an area of Stockholm, Sweden.

tileID = uint32(378373553);

Create a HERE HDLM reader for the tile ID. Configure the reader to search for the tile in only the Western Europe catalog. If you have not previously set up HERE HDLM credentials, a dialog box prompts you to enter them. The reader contains map data for the specified map tile.

config = hereHDLMConfiguration('Western Europe');
reader = hereHDLMReader(tileID,'Configuration',config);

Read the link definitions from the TopologyGeometry layer of the map tile. The returned layer object contains the specified LinksStartingInTile field and the required map tile fields, such as the tile ID. The other fields are empty. Your map data and catalog version might differ from the ones shown here.

topology = read(reader,'TopologyGeometry','LinksStartingInTile')
topology = 
  TopologyGeometry with properties:

   Data:
                    HereTileId: 378373553
          IntersectingLinkRefs: []
           LinksStartingInTile: [1240×1 struct]
                   NodesInTile: []
    TileCenterHere2dCoordinate: [59.3372 18.0505]

   Metadata:
                       Catalog: 'here-hdmap-ext-weu-1'
                CatalogVersion: 3117

  Use plot to visualize TopologyGeometry data.

Find the start and end nodes for each link in the LinksStartingInTile field.

startNodes = [topology.LinksStartingInTile.StartNodeId];
endNodesRef = [topology.LinksStartingInTile.EndNodeRef];
endNodes = [endNodesRef.NodeId];

Find the length of each link in meters.

linkLengths = [topology.LinksStartingInTile.LinkLengthMeters];

Create an undirected graph for the links in the map tile.

G = graph(string(startNodes),string(endNodes),double(linkLengths));
H = plot(G,'Layout','force');
title('Undirected Graph')

Specify a start and end node to find the shortest path between them. Use the first and last node in the graph as the start and end nodes, respectively. Overlay the nodes on the graph.

startNode = G.Nodes.Name(1);
endNode = G.Nodes.Name(end);

highlight(H,[startNode endNode],'NodeColor','red','MarkerSize',6)
title('Undirected Graph - Start and End Nodes')

Find the shortest path between the two nodes. Plot the path.

path = shortestpath(G,startNode,endNode);
highlight(H,path,'EdgeColor','red','LineWidth',2);
title('Undirected Graph - Shortest Path')

Limitations

  • hereHDLMReader objects do not work on Linux machines.

  • The HERE HDLM web service determines the geographic coverage of the map data. Map data is not available for all locations.

Tips

  • To speed up the performance of the reader, when creating the reader, specify a hereHDLMConfiguration object for the Configuration property. This object configures the reader to search for the selected map tiles from only a specific geographic region. If you do not specify a configuration object when you create the reader, the reader searches for the map tiles across all geographic regions.

  • To save HERE HDLM credentials between MATLAB sessions, select the corresponding option in the HERE HD Live Map Credentials dialog box. To manage HERE HDLM credentials, use the hereHDLMCredentials function.

Introduced in R2019a


[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 (app_id and app_code) for using the HERE Service.