This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English version of the page.

Note: This page has been translated by MathWorks. Click here to see
To view all translated materials including this page, select Country from the country navigator on the bottom of this page.

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.

example

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

example

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

expand all

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

Data Types: single | double

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

Data Types: single | double

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

expand all

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.

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.

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.

'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 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 used by geographic player, specified as a GeographicAxes object. Use this axes to customize the map that the geographic player displays. For more details, see GeographicAxes Properties.

Object Functions

plotPositionDisplay current position in geoplayer figure
plotRouteDisplay continuous route in geoplayer figure
resetRemove all existing plots from geoplayer figure
showMake geoplayer figure visible
hideMake geoplayer figure invisible
isOpenReturn true if geoplayer figure is visible

Examples

collapse all

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

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 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 = 'http://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 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 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

expand all

Tips

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

Introduced in R2018a