geoplayer

Visualize streaming geographic map data

Description

A geoplayer object is a geographic player that displays the streaming coordinates of a driving route on a map.

• To display the driving route of a vehicle, use the plotRoute function.

• To display the position of a vehicle as it drives along a route, use the plotPosition function.

• To change the underlying map, or basemap, of the geoplayer object, update the Basemap property of the object. For more information, see Custom Basemaps.

Creation

Syntax

player = geoplayer(latCenter,lonCenter)

player = geoplayer(latCenter,lonCenter,zoomLevel)

player = geoplayer(___,Name,Value)

Description

player = geoplayer(latCenter,lonCenter) creates a geographic player, centered at latitude coordinate latCenter and longitude coordinate lonCenter.

player = geoplayer(latCenter,lonCenter,zoomLevel) creates a geographic player with a map magnification specified by zoomLevel.

player = geoplayer(___,Name,Value) sets properties using one or more name-value pairs, in addition to specifying input arguments from previous syntaxes. For example, geoplayer(45,0,'HistoryDepth',5) creates a geographic player centered at the latitude-longitude coordinate (45, 0), and sets the HistoryDepth property such that the player displays the five previous geographic coordinates.

Input Arguments

latCenter — Latitude coordinate

real scalar in the range (–90, 90)

Latitude coordinate at which the geographic player is centered, specified as a real scalar in the range (–90, 90).

Data Types: single | double

lonCenter — Longitude coordinate

real scalar in the range [–180, 180]

Longitude coordinate at which the geographic player is centered, specified as a real scalar in the range [–180, 180].

Data Types: single | double

zoomLevel — Magnification

15 | integer in the range [0, 25]

Magnification of the geographic player, specified as an integer in the range [0, 25]. This magnification occurs on a logarithmic scale with base 2. Increasing zoomLevel by one doubles the map scale.

Properties

HistoryDepth — Number of previous geographic coordinates to display

0 (default) | nonnegative integer | Inf

Number of previous geographic coordinates to display, specified as a nonnegative integer or Inf. A value of 0 displays only the current geographic coordinates. A value of Inf displays all geographic coordinates previously plotted using the plotPosition function.

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

HistoryStyle — Style of displayed geographic coordinates

'point' (default) | 'line'

Style of displayed geographic coordinates, specified as one of these values:

• 'point' — Display the coordinates as discrete, unconnected points.

• 'line' — Display the coordinates as a single connected line.

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

Basemap — Map on which to plot data

'streets' (default) | 'darkwater' | 'grayterrain' | 'grayland' | 'colorterrain' | ...

Map on which to plot data, specified as one of the basemap names in this table, 'none', or a custom basemap defined using the addCustomBasemap function. For more information on adding custom basemaps, see Custom Basemaps. For examples on how to add custom basemaps, see Display Data on OpenStreetMap Basemap and Display Map Data on HERE Basemap.

	'streets' (default) Street map data composed of geographic map tiles using the World Street Map provided by Esri®. For more information about the map, see World Street Map on the Esri ArcGIS website. Hosted by Esri.		'darkwater' Land areas: light-to-moderate gray Ocean and water areas: darker gray Hosted by MathWorks® and derived from public domain data.
	'grayterrain' Worldwide terrain depicted monochromatically in shades of gray, combining shaded relief that emphasizes both high mountains and the micro terrain found in lowlands. Hosted by MathWorks.		'grayland' Land areas: light-to-moderate gray land Ocean and water areas: white Hosted by MathWorks.
	'colorterrain' Shaded relief map blended with a land cover palette. Humid lowlands are green and arid lowlands brown. Hosted by MathWorks.		'bluegreen' Land areas: light green Ocean and water areas: light blue Hosted by MathWorks.
	'landcover' Satellite-derived land cover data and shaded relief presented with a light, natural palette suitable for making thematic and reference maps (includes ocean-bottom relief). Hosted by MathWorks.	N/A	'none' Geographic axes plots your data with latitude-longitude grid, ticks, and labels but does not include a map.

By default, access to basemaps requires an Internet connection. The exception is the 'darkwater' basemap, which is installed with MATLAB^®.

If you do not have consistent access to the Internet, you can download the basemaps hosted by MathWorks onto your local system. For more information about downloading basemaps, see Access Basemaps in MATLAB (MATLAB). You cannot download basemaps hosted by Esri.

Example: player = geoplayer(latCenter,lonCenter,'Basemap','darkwater')

Example: player.Basemap = 'darkwater'

Data Types: char | string

Parent — Parent axes of geographic player

Figure graphics object | Panel graphics object

Parent axes of the geographic player, specified as a Figure graphics object or Panel graphics object. If you do not specify Parent, then geoplayer creates the geographic player in a new figure.

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

Axes — Axes used by geographic player

GeographicAxes object

Axes used by geographic player, specified as a GeographicAxes object. Use this axes to customize the map that the geographic player displays. For an example, see Customize Geographic Axes. For details on the properties that you can customize, see GeographicAxes Properties.

Object Functions

plotPosition	Display current position in geoplayer figure
plotRoute	Display continuous route in geoplayer figure
reset	Remove all existing plots from geoplayer figure
show	Make geoplayer figure visible
hide	Make geoplayer figure invisible
isOpen	Return true if geoplayer figure is visible

Examples

Animate Sequence of Latitude and Longitude Coordinates

Load a sequence of latitude and longitude coordinates.

data = load('geoSequence.mat');

Create a geographic player and configure it to display all points in its history.

zoomLevel = 17;
player = geoplayer(data.latitude(1),data.longitude(1),zoomLevel,'HistoryDepth',Inf);

Display the sequence of coordinates.

  for i = 1:length(data.latitude)
      plotPosition(player,data.latitude(i),data.longitude(i));
      pause(0.01)
  end

View Position of Vehicle Along Route

Load a sequence of latitude and longitude coordinates.

data = load('geoRoute.mat');

Create a geographic player and set the zoom level to 12. Compared to the default zoom level, this zoom level zooms the map out by a factor of 8.

player = geoplayer(data.latitude(1),data.longitude(1),12);

Display the full route.

plotRoute(player,data.latitude,data.longitude);

Display the coordinates in a sequence. The circle marker indicates the current position.

for i = 1:length(data.latitude)
    plotPosition(player,data.latitude(i),data.longitude(i));
    pause(0.05)
end

Display Data on OpenStreetMap Basemap

This example shows how to display a driving route and vehicle positions on an OpenStreetMap® basemap.

Add the OpenStreetMap basemap to the list of basemaps available for use with the geoplayer object. 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)

Load a sequence of latitude and longitude coordinates.

data = load('geoRoute.mat');

Create a geographic player. Center the geographic player on the first position of the driving route and set the zoom level to 12.

zoomLevel = 12;
player = geoplayer(data.latitude(1),data.longitude(1),zoomLevel);

Display the full route.

plotRoute(player,data.latitude,data.longitude);

By default, the geographic player uses the World Street Map basemap ('streets') provided by Esri®. Update the geographic player to use the added OpenStreetMap basemap instead.

player.Basemap = 'openstreetmap';

Display the route again.

plotRoute(player,data.latitude,data.longitude);

Display the positions of the vehicle in a sequence.

for i = 1:length(data.latitude)
   plotPosition(player,data.latitude(i),data.longitude(i))
end

Display Map Data on HERE Basemap

Display a driving route on a basemap provided by HERE Technologies. To use this example, you must have a valid license from HERE Technologies.

Specify the basemap name and map URL.

name = 'herestreets';
url  = ['https://2.base.maps.cit.api.here.com/maptile/2.1/maptile/', ...
        'newest/normal.day/${z}/${x}/${y}/256/png?app_id=%s&app_code=%s'];

Maps from HERE Technologies require a valid license. Create a dialog box. In the dialog box, enter the App ID and App Code corresponding to your HERE license.

prompt = {'HERE App ID:','HERE App Code:'};
title = 'HERE Tokens';
dims = [1 40]; % Text edit field height and width
hereTokens = inputdlg(prompt,title,dims);

If the license is valid, specify the HERE credentials and a custom attribution, load coordinate data, and display the coordinates on the HERE basemap using a geoplayer object. If the license is not valid, display an error message.

if ~isempty(hereTokens)
        
    % Add HERE basemap with custom attribution.
    url = sprintf(url,hereTokens{1},hereTokens{2});
    copyrightSymbol = char(169); % Alt code
    attribution = [copyrightSymbol,' ',datestr(now,'yyyy'),' HERE'];
    addCustomBasemap(name,url,'Attribution',attribution);

    % Load sample lat,lon coordinates.
    data = load('geoSequence.mat');

    % Create geoplayer with HERE basemap.
    player = geoplayer(data.latitude(1),data.longitude(1), ...
        'Basemap','herestreets','HistoryDepth',Inf);
 
    % Display the coordinates in a sequence.
    for i = 1:length(data.latitude)
        plotPosition(player,data.latitude(i),data.longitude(i));
    end

else
    error('You must enter valid credentials to access maps from HERE Technologies');
end

Customize Geographic Axes

Customize the geographic axes of a geoplayer object by adding a custom line between route endpoints.

Load a driving route and vehicle positions along that route.

data = load('geoRoute.mat');

Create a geographic player that is centered on the first position of the vehicle.

zoomLevel = 10;
player = geoplayer(data.latitude(1),data.longitude(1),zoomLevel);

Display the full route.

plotRoute(player,data.latitude,data.longitude);

Display positions of the vehicle along the route.

for i = 1:length(data.latitude)
    plotPosition(player,data.latitude(i),data.longitude(i))
end

Customize the geographic axes by adding a line between the two endpoints of the route.

geoplot(player.Axes,[data.latitude(1) data.latitude(end)], ...
    [data.longitude(1) data.longitude(end)],'g-*')

Limitations

• Geographic map tiles are not available for all locations.

More About

Custom Basemaps

The geoplayer object can use custom basemaps from providers such as HERE Technologies and OpenStreetMap^®.

To make a custom basemap available for use with the geoplayer object, use the addCustomBasemap function. After you add a custom basemap, it remains available for use in future MATLAB sessions, until you remove the basemap by using the removeCustomBasemap function.

To display streaming coordinates on a custom basemap, specify the name of the basemap in the Basemap property of the geoplayer object.

Note

For some custom basemaps, access to the map servers requires a valid license from the map provider.

Tips

• When the geoplayer object plots a position that is outside the current view of the map, the object automatically scrolls the map.