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 ¹ (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 Read and Visualize 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 Access Key ID and Access Key Secret that you obtained from HERE Technologies, and click OK.

Creation

Syntax

reader = hereHDLMReader(lat,lon)

reader = hereHDLMReader(tileID)

reader = hereHDLMReader(___,Name,Value)

Description

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.

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.

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

lat — Latitude coordinates

vector of real values in the range [–90, 90]

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

lon — Longitude coordinates

vector of real values in the range [–180, 180]

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

tileID — HERE tile IDs

vector of unsigned 32-bit integers

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 HERE HDLM production catalog.

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

TileIDs — HERE tile IDs

vector of unsigned 32-bit integers

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

Layers — Map data layers

string array

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.

Configuration — Catalog configuration

hereHDLMConfiguration object

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 set this property when you create the reader object. After you create the object, this property is read-only.

WriteLocation — Folder name of downloaded map data

tempdir (temporary directory) (default) | string scalar | character vector

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"

CoordinateFormat — Type of coordinate encoding format

'geographic' (default) | 'raw'

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

Format	Description	Example
'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

read	Read HERE HD Live Map layer data
plot	Plot HERE HD Live Map layer data

Examples

Plot and Stream Lane Topology Data from Driving Route

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('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

Plot 2-D Lane Geometry on Custom Basemap

Use the HERE HD Live Map (HERE HDLM) web service to read 3-D lane geometry data from a map tile. Then, plot the 2-D part of 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 2-D part of 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)

Find Shortest Path Between Two Nodes

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("hrn:here:data::olp-here-had:here-hdlm-protobuf-weu-2");
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: [1269×1 struct]
                   NodesInTile: []
    TileCenterHere2dCoordinate: [59.3372 18.0505]

   Metadata:
                       Catalog: 'hrn:here:data::olp-here-had:here-hdlm-protobuf-weu-2'
                CatalogVersion: 21501

  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

• 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 only a specific HERE HD Live Map production catalog. If you do not specify a configuration object when you create the reader, the reader searches for the map tiles across all catalogs.

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

Version History

Introduced in R2019a