addCustomBasemap

Add custom basemap

Description

example

addCustomBasemap(basemapName,URL) adds the custom basemap specified by URL to the list of basemaps available for use with mapping functions. basemapName is the name you choose to call the custom basemap. Added basemaps remain available for use in future MATLAB® sessions.

You can use custom basemaps with the webmap function and with MATLAB geographic axes and charts.

example

addCustomBasemap(___,Name,Value) specifies name-value pairs that set additional parameters of the basemap.

Examples

collapse all

Add a custom basemap and plot the path of a glider on it.

Read glider path data into the workspace.

trk = gpxread('sample_mixed.gpx','FeatureType','track');

Define the name that you will use to specify your custom basemap.

name = 'opentopomap';

Specify the website that provides the map data. The first character of the URL indicates which server to use to get the data. For load balancing, the provider has three servers that you can use: a, b, or c.

url = 'a.tile.opentopomap.org';

Create an attribution to display on the map that gives credit to the provider of the map data. Web map providers might define specific requirements for the attribution.

copyright = char(uint8(169));
attribution = [ ...
      "map data:  " + copyright + "OpenStreetMap contributors,SRTM", ...
      "map style: " + copyright + "OpenTopoMap (CC-BY-SA)"];

Define the name that will appear in the Layer Manager to represent your custom basemap.

displayName = 'Open Topo Map';

Add the custom basemap to the list of basemap layers available.

addCustomBasemap(name,url,'Attribution',attribution,'DisplayName',displayName)

Open a web map, specifying your custom basemap by the name you defined.

webmap opentopomap

Plot the glider path track on the basemap, specifying the width of the line used to represent the track.

wmline(trk,'LineWidth',2)

Specify a custom basemap and then use bubbles to show the locations of locations on the basemap.

Define the name that you will use to specify your custom basemap.

name = 'openstreetmap';

Specify the website that provides the map data. The first character of the URL indicates which server to use to get the data. For load balancing, the provider has three servers that you can use: a, b, or c.

url = 'a.tile.openstreetmap.org';

Create an attribution to display on the map that gives credit to the provider of the map data. Web map providers might define specific requirements for the attribution.

copyright = char(uint8(169));
attribution = copyright + "OpenStreetMap contributors";

Define the name that will appear in the Layer Manager to represent your custom basemap.

displayName = 'Open Street Map';

Add the custom basemap to the list of basemap layers available.

addCustomBasemap(name,url,'Attribution',attribution,'DisplayName',displayName)

Plot the locations over the map using a geographic bubble chart. You can specify your custom basemap when you create the geographic bubble chart.

pts = gpxread('boston_placenames');
gb = geobubble(pts.Latitude,pts.Longitude,'Basemap','openstreetmap');
gb.BubbleWidthRange = 25;
gb.MapLayout = 'maximized';
gb.ZoomLevel = 14;

Plot the glider path data over a variety of maps available from the USGS National Map site. This can be a good way to view the maps available from a site and determine which map provides the best background for your data.

View glider path on basemaps from the USGS National Map. Construct basemap URLs by replacing BASEMAP with the name of the USGS basemap.

Read in the glider path track data.

trk = gpxread('sample_mixed','FeatureType','track');

Specify the custom basemap URL. The USGS National Map supports several tiled web maps. For this example, insert the word "BASEMAP" into the URL string. In this way, you can replace the word BASEMAP with the name of one of the maps supported by the USGS National Map.

baseURL = "https://basemap.nationalmap.gov/ArcGIS/rest/services";
usgsURL = baseURL + "/BASEMAP/MapServer/tile/${z}/${y}/${x}";

Specify a list of the names of USGS basemaps that you want to use. These names will be inserted into the URL in place of "BASEMAP".

basemaps = ["USGSImageryOnly" "USGSImageryTopo" ...
       "USGSTopo" "USGSShadedReliefOnly" "USGSHydroCached"];

Specify a list of display names that you can use with each map. Use display names that are the same as those used by webmap so that webmap does not contain duplicate maps.

displayNames = ["USGS Imagery" "USGS Topographic Imagery" ...
       "USGS Shaded Topographic Map" "USGS Shaded Relief" ...
       "USGS Hydrography"];
maxZoomLevel = 16;

Create a map attribution to give credit to the provider of the map data.

attribution = 'Credit: U.S. Geological Survey';

Create a loop in which you use each basemap with the geoplot function, plotting the glider data on each of the USGS basemaps.

for k =1:length(basemaps)
   basemap = basemaps(k);
   name = lower(basemap);
   url = replace(usgsURL,"BASEMAP",basemap);
   displayName = displayNames(k);
   addCustomBasemap(name,url,'Attribution',attribution, ...
         'DisplayName',displayName,'MaxZoomLevel',maxZoomLevel)
   figure
   geoplot(trk.Latitude,trk.Longitude,'r','LineWidth',5);
   geobasemap(basemap)
   title(displayName)
end

Input Arguments

collapse all

Name used to identify basemap programmatically, specified as a string scalar or character vector.

Example: 'openstreetmap'

Data Types: string | char

Parameterized map URL, specified as a string scalar or character vector. A parameterized URL is an index of the map tiles, formatted as ${z}/${x}/${y}.png or {z}/{x}/{y}.png, where:

  • ${z} or {z} is the tile zoom level.

  • ${x} or {x} is the tile column index.

  • ${y} or {y} is the tile row index.

Example: 'https://hostname/${z}/${x}/${y}.png'

Data Types: string | char

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: addCustomBasemap(basemapName,URL,'Attribution',attribution)

Attribution of custom basemap, specified as the comma-separated pair consisting of 'Attribution' and a string scalar, string array, character vector, or cell array of character vectors. If the host is 'localhost', or if URL contains only IP numbers, specify an empty value (''). To create a multiline attribution, specify a string array or nonscalar cell array of character vectors.

If you do not specify an attribution, the default attribution is 'Tiles courtesy of DOMAIN_NAME_OF_URL', where the addCustomBasemap function obtains the domain name from the URL input argument.

Example: 'Credit: U.S. Geological Survey'

Data Types: string | char | cell

Display name of the custom basemap, specified as the comma-separated pair consisting of 'DisplayName' and a string scalar or character vector.

The webmap function uses this name in the Layer Manager.

Example: 'OpenStreetMap'

Data Types: string | char

Maximum zoom level of the basemap, specified as the comma-separated pair consisting of 'MaxZoomLevel' and an integer in the range [0, 25].

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Map is deployable using MATLAB Compiler, specified as the comma-separated pair consisting of 'IsDeployable' and false or true.

If you are deploying a map application and want users to have access to the added basemap, set 'IsDeployable' to true. For more information about deployment, see Tips.

Data Types: logical

Tips

  • You can find tiled web maps from various vendors, such as OpenStreetMap®, the USGS National Map, Mapbox, DigitalGlobe, Esri® ArcGIS Online, the Geospatial Information Authority of Japan (GSI), and HERE Technologies. Abide by the map vendors terms-of-service agreement and include accurate attribution with the maps you use.

  • To use a custom basemap in a deployed application, when you call addCustomBasemap, you must set the value of the 'IsDeployable' name-value pair to true. You must set this name-value pair whether you call addCustomBasemap in your application or outside of your application.

  • To access a list of available basemaps, press Tab before specifying the basemap in your plotting function.

Introduced in R2018b