addCustomBasemap

Add custom basemap

Syntax

addCustomBasemap(basemapName,URL)

addCustomBasemap(basemapName,mbtilesFilename)

addCustomBasemap(___,Name,Value)

Description

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 several types of map displays, for example, geographic axes created using the geoaxes function, geographic globes created using the geoglobe function, and web maps created using the webmap function.

addCustomBasemap(basemapName,mbtilesFilename) adds the custom basemap specified by mbtilesFilename, an MBTiles file containing raster or vector map tiles. You can use the basemap in future MATLAB sessions, provided the MBTiles file is still on the same path as when you add it.

Web maps do not support custom basemaps created from MBTiles files.

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

Examples

Add Basemap from OpenStreetMap

Display point locations on a geographic bubble chart using a basemap from OpenStreetMap®.

Specify values for these arguments:

• A name that identifies the custom basemap.

• The URL of the map tiles. For load balancing, this provider has three servers you can use (a, b, and c).

• An attribution that gives credit to the provider of the map tiles. When you plot data, this attribution appears at the bottom of the map. Map tile providers can define specific requirements for the attribution.

basemapName = "openstreetmap";
url = "a.tile.openstreetmap.org/${z}/${x}/${y}.png"; 
copyright = char(uint8(169));
attribution = copyright + "OpenStreetMap contributors";

Add the custom basemap to the list of basemaps available for use with mapping functions.

addCustomBasemap(basemapName,url,"Attribution",attribution)

Specify the latitude and longitude coordinates of several point locations. Then, plot the coordinates using a geographic bubble chart.

lat = [42.3501 42.3515 42.3598 42.3584 42.3529];
lon = [-71.0870 -71.0926 -71.0662 -71.0598 -71.0662];

gb = geobubble(lat,lon,"Basemap",basemapName);
gb.BubbleWidthRange = 25;
gb.MapLayout = "maximized";
gb.ZoomLevel = 14;

Add Basemap from Esri

Display data on a basemap hosted by Esri®.

Add the basemap to the list of basemaps available for use with mapping functions. For this example, add the basemap using the map tiles URL and style URL for National Geographic Style [1].

basemapName1 = "natgeostyle";
url = "https://basemaps.arcgis.com/arcgis/rest/services/World_Basemap_v2/VectorTileServer/tile/${z}/${x}/${y}.pbf";
style = "https://www.arcgis.com/sharing/rest/content/items/3d1a30626bbc46c582f148b9252676ce/resources/styles/root.json?f=pjson";
addCustomBasemap(basemapName1,url,Style=style)

Import a GPX file that contains the path of a glider. Extract the latitude coordinates, longitude coordinates, and elevations.

trk = readgeotable("sample_mixed.gpx","Layer","track_points");
lat = trk.Shape.Latitude;
lon = trk.Shape.Longitude;
h = trk.Elevation;

Display the path in 2-D using the National Geographic Style basemap.

geoplot(lat,lon,"m",LineWidth=2)
geobasemap(basemapName1)

You can also customize the appearance of the basemap by using a predefined style. For example, add another basemap using the same map tiles URL and a predefined topographic style.

basemapName2 = "topostyle";
addCustomBasemap(basemapName2,url,Style="topographic")

Display the path in 3-D using the new basemap.

uif = uifigure;
g = geoglobe(uif,Basemap=basemapName2);
geoplot3(g,lat,lon,h,"m",LineWidth=2)

[1] "National Geographic Style - Overview." ArcGIS Online. Accessed December 8, 2022. https://www.arcgis.com/home/item.html?id=3d1a30626bbc46c582f148b9252676ce.

Add Basemap from MBTiles File

Creating custom basemaps from MBTiles files is useful when you do not have internet access.

MBTiles files can contain raster or vector map tiles. Raster map tiles are useful for displaying satellite imagery and orthoimagery. Vector map tiles enable you to customize the appearance of the basemap and typically include higher zoom levels than raster map tiles. If you do not know whether your MBTiles file contains raster or vector map tiles, check with your data provider.

Raster MBTiles File

Create a basemap from an MBTiles file containing raster map tiles. Mapping Toolbox includes a raster MBTiles file, usgsimagery.mbtiles, with low-resolution USGS imagery.

Add the USGS Imagery basemap to the list of basemaps available for use with mapping functions. The addCustomBasemap function uses the attribution and maximum zoom level contained in the file.

basemap1 = "usgsimagery";
mbtilesFilename1 = "usgsimagery.mbtiles";
addCustomBasemap(basemap1,mbtilesFilename1)

Read worldwide land areas into the workspace as a geospatial table. Create a subtable containing only Australia.

GT = readgeotable("landareas.shp");
australia = GT(GT.Name == "Australia",:);

Display the outline of Australia over the USGS Imagery basemap.

figure
geoplot(australia,"LineWidth",2,"FaceColor","none")
geobasemap usgsimagery

Vector MBTiles File

(Since R2023a)

Create a basemap from an MBTiles file containing vector map tiles. Mapping Toolbox includes a vector MBTiles file, naturalearth.mbtiles, with low-zoom levels of region and land boundaries.

Add the Natural Earth basemap to the list of basemaps available for use with mapping functions. Specify the appearance of the basemap, including the colors and fonts, using a predefined style.

basemap2 = "naturalearth";
mbtilesFilename2 = "naturalearth.mbtiles";
style = "streets";
addCustomBasemap(basemap2,mbtilesFilename2,Style=style)

Create a map using the Natural Earth basemap. Zoom into a region including the northeast United States.

figure
geobasemap naturalearth
geolimits([38.6 47.8],[-81.4 -65.4])

Compare Vector and Raster Basemap Tiles

Starting in R2023a, you can add custom basemaps using vector map tiles hosted by Esri. Vector map tiles enable you to customize the appearance of the basemap and typically include higher zoom levels than raster map tiles. This example creates vector and raster versions of similar Esri basemaps and compares the map tiles at different zoom levels.

Specify the maximum zoom level to use for the custom basemaps.

maxzoom = 20;

Add a custom basemap using the map tiles URL for Streets [1]. This basemap uses vector map tiles.

basemapName1 = "streetsvector";
url1 = "https://basemaps.arcgis.com/arcgis/rest/services/World_Basemap_v2/VectorTileServer/tile/${z}/${x}/${y}.pbf";
addCustomBasemap(basemapName1,url1,Style="streets",MaxZoomLevel=maxzoom)

Add the custom basemap using the map tiles URL for World Street Map [2]. This basemap uses raster map tiles.

basemapName2 = "streetsraster";
url2 = "https://services.arcgisonline.com/arcgis/rest/services/World_Street_Map/MapServer/tile/${z}/${y}/${x}.png";
attribution = "Esri, HERE, Garmin, (c) OpenStreetMap contributors, and the GIS user community";
addCustomBasemap(basemapName2,url2,Attribution=attribution,MaxZoomLevel=maxzoom)

Create two maps in a tiled chart layout. Place the vector basemap in the left tile and the raster basemap in the right tile. Center both maps on the Statue of Liberty in New York City.

f = figure(Position=[500 500 1000 500]);
center = [40.689125327367890 -74.044492429136966];
initialzoom = 14;

t = tiledlayout(1,2);
gx1 = geoaxes(t,Basemap=basemapName1,MapCenter=center,ZoomLevel=initialzoom);
title("Vector Basemap")
subtitle("Zoom Level " + initialzoom)

gx2 = geoaxes(t,Basemap=basemapName2,MapCenter=center,ZoomLevel=initialzoom);
gx2.Layout.Tile = 2;
title("Raster Basemap")
subtitle("Zoom Level " + initialzoom)

Use a loop to view the basemap at increasing zoom levels. Unlike the vector basemap at this location, the raster basemap does not contain data at zoom level 20.

for zoom = initialzoom:0.5:maxzoom
    gx1.ZoomLevel = zoom;
    gx2.ZoomLevel = zoom;

    subtitle(gx1,"Zoom Level " + zoom)
    subtitle(gx2,"Zoom Level " + zoom)

    drawnow
    pause(0.75)
end

[1] "Streets - Overview." ArcGIS Online. Accessed December 7, 2022. https://www.arcgis.com/home/item.html?id=de26a3cf4cc9451298ea173c4b324736.

[2] "World Street Map - Overview." ArcGIS Online. Accessed December 7, 2022. https://www.arcgis.com/home/item.html?id=3b93337983e9436f8db950e38a8629af.

Add Basemap from USGS National Map

Display the route of a glider in 2-D and 3-D using a topographic basemap from the USGS National Map.

Specify values for these arguments:

• A name that identifies the custom basemap.

• The URL for the map tiles. This URL includes the URL of the National Map ArcGIS REST Services Directory and the path to the map tiles from the USGS Topo basemap service.

• An attribution that gives credit to the provider of the map tiles. When you plot data, this attribution appears at the bottom of the map. Map tile providers can define specific requirements for the attribution.

basemapName = "usgstopo";
url = "https://basemap.nationalmap.gov/ArcGIS/rest/services/USGSTopo/MapServer/tile/${z}/${y}/${x}/png";
att = "Credit: US Geological Survey";

Add the basemap to the list of basemaps available for use with mapping functions.

addCustomBasemap(basemapName,url,"Attribution",att)

Import a GPX file that contains the path of a glider. Extract the latitude coordinates, longitude coordinates, and elevations.

trk = readgeotable("sample_mixed.gpx","Layer","track_points");
lat = trk.Shape.Latitude;
lon = trk.Shape.Longitude;
h = trk.Elevation;

Display the path in 2-D using the USGS Topo basemap.

geoplot(lat,lon,"r","LineWidth",2)
geobasemap(basemapName)

Display the path in 3-D using a geographic globe and the same basemap. By default, the view is directly above the path. Tilt the view by holding Ctrl and dragging.

uif = uifigure;
g = geoglobe(uif,"Basemap","usgstopo");
geoplot3(g,lat,lon,h,"r","LineWidth",2)

Add Several Basemaps from USGS National Map

Plot the path of a glider over a variety of basemaps that are available from the USGS National Map site. Viewing data over several maps can help you determine which map provides the best background.

This example adds each basemap using a loop. Prepare to add the basemaps by specifying these arguments:

• The URL of the map tiles. The USGS National Map supports several tiled web maps. For this example, insert the word BASEMAP into the URL string. The loop replaces the word BASEMAP with the names of the maps supported by the USGS National Map.

• The names of USGS basemaps. The loop inserts these names into the URL in place of BASEMAP.

• The display names to use for each basemap. For this example, use display names that match the names used by the webmap function, so that webmap does not contain duplicate maps.

• An attribution that gives credit to the provider of the map tiles. When you plot data, this attribution appears at the bottom of the map. Map tile providers can define specific requirements for the attribution.

• The maximum zoom level for the basemaps.

baseURL = "https://basemap.nationalmap.gov/ArcGIS/rest/services";
usgsURL = baseURL + "/BASEMAP/MapServer/tile/${z}/${y}/${x}/png";
basemapNames = ["USGSImageryOnly" "USGSImageryTopo" "USGSTopo" "USGSHydroCached"];
displayNames = ["USGS Imagery" "USGS Topographic Imagery" "USGS Shaded Topographic Map" "USGS Hydrography"];
attribution = "Credit: U.S. Geological Survey";
maxZoomLevel = 16;

Import a GPX file that contains the path of a glider.

GT = readgeotable("sample_mixed.gpx","Layer","tracks");

Use a loop to add each basemap and display the glider path over each basemap.

for k =1:length(basemapNames)
   basemap = basemapNames(k);
   name = lower(basemap);
   url = replace(usgsURL,"BASEMAP",basemap);
   displayName = displayNames(k);
   
   addCustomBasemap(name,url,"Attribution",attribution, ...
         "DisplayName",displayName,"MaxZoomLevel",maxZoomLevel)

   figure
   geobasemap(basemap)
   geoplot(GT,"r","LineWidth",5);
   title(displayName)
end

Add Basemap from OpenTopoMap

Display the route of a glider on a web map using a basemap from OpenTopoMap.

Specify values for these arguments:

• A name that identifies the custom basemap.

• The URL of the map tiles. For load balancing, this provider has three servers you can use (a, b, and c).

• An attribution that gives credit to the provider of the map tiles. When you plot data, this attribution appears at the bottom of the map. Map tile providers can define specific requirements for the attribution.

• The name that appears in the Layer Manager tab of the web map.

basemapName = "opentopomap"; 
url = "a.tile.opentopomap.org/${z}/${x}/${y}.png"; 
copyright = char(uint8(169));
attribution = [ ...
      "map data:  " + copyright + "OpenStreetMap contributors,SRTM", ...
      "map style: " + copyright + "OpenTopoMap (CC-BY-SA)"]; 
displayName = "Open Topo Map";

Add the custom basemap to the list of basemaps available for use with mapping functions.

addCustomBasemap(basemapName,url,"Attribution",attribution, ...
                          "DisplayName",displayName)

Open a web map that uses the OpenTopoMap basemap. Then, read glider data into the workspace and plot it over the basemap.

webmap(basemapName)
trk = readgeotable("sample_mixed.gpx","Layer","tracks");
wmline(trk,"LineWidth",2)

Input Arguments

basemapName — Name used to identify basemap programmatically

string scalar | character vector

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

Example: 'openstreetmap'

Data Types: string | char

URL — Parameterized map URL

string scalar | character vector

Parameterized map URL, specified as a string scalar or character vector.

The parameterized map URL typically includes:

• The URL of the basemap tiles.

• An index of the map tiles, formatted as ${z}/${x}/${y} or ${z}/${y}/${z}, where z is the tile zoom level, x is the tile column index, and y is the tile row index.

• The file format of the map tiles. The addCustomBasemap function can read tiles in image formats supported by the imread function and tiles in PBF format (requires Mapping Toolbox™) when the map tiles are hosted by Esri^®. Depending on the data provider, map tiles are available in different file formats.

The way you structure this argument can depend on the data provider. For more information about how to structure a URL, see Examples or ask your data provider.

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

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

Data Types: string | char

mbtilesFilename — Name of MBTiles file

character vector | string scalar

Name of an MBTiles file containing raster or vector map tiles, specified as a character vector or string scalar. You must include the extension .mbtiles. The way you specify mbtilesFilename depends on the location of your file.

• If the file is in your current folder or in a folder on the MATLAB path, then specify the name of the file, such as "myFile.mbtiles".

• If the file is not in the current folder or in a folder on the MATLAB path, then specify the full or relative path name, such as "C:/myfolder/myFile.mbtiles" or "dataDir/myFile.mbtiles".

Data Types: char | string

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: addCustomBasemap(basemapName,URL,Attribution="My attribution") specifies the attribution for the custom basemap.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: addCustomBasemap(basemapName,URL,"Attribution","My attribution") specifies the attribution for the custom basemap.

Attribution — Attribution of custom basemap

string scalar | string array | character vector | cell array of character vectors

Attribution of the custom basemap, specified as a string scalar, string array, character vector, or cell array of character vectors. To create a multiline attribution, specify a string array or a nonscalar cell array of character vectors.

When you create a custom basemap from a URL, the default attribution is 'Tiles courtesy of DOMAIN_NAME_OF_URL', where DOMAIN_NAME_OF_URL is the domain name from the URL input argument. If the host is 'localhost', or if URL contains only IP numbers, specify the attribution as an empty string ("").

When you create a custom basemap from an MBTiles file with an attribution in the metadata, the addCustomBasemap function gets the attribution from the file. If the file does not contain an attribution, the default attribution is an empty string.

When you add a basemap from vector map tiles hosted by Esri, the addCustomBasemap function ignores this argument and uses an attribution based on the location and zoom level.

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

Data Types: string | char | cell

Style — Style of vector basemap

"auto" (default) | "streets-light" | "streets-dark" | "streets" | "topographic" | name of JSON file | URL | ...

Style of the vector basemap, specified as a predefined style, the name of a JSON file, or a URL. The appearance of the basemap, such as the line colors and font names, depends on the style you specify when you add the basemap.

This table lists the predefined style options. The predefined style options do not require internet access.

Value	Sample Image	Value	Description
"streets-light" — Provides geographic context while highlighting user data on a light background.		"streets-dark" — Provides geographic context while highlighting user data on a dark background.
"streets" — Emphasizes roads and transit networks.		"topographic" — Emphasizes topographic features.
"openstreetmap" — Uses colors based on OpenStreetMap®.		"bluegreen" — Uses light green for land areas and light blue for water areas.
"grayland" — Uses gray for land areas and white for water areas.		"darkwater" — Uses light gray for land areas and dark gray for water areas.

The default is "auto", which chooses a style based on the MATLAB theme. When you select the light theme, "auto" uses the "streets-light" style. When you select the dark theme, "auto" uses the "streets-dark" style.

When you use a predefined style and specify the map tiles using an MBTiles file, the addCustomBasemap function creates a JSON file with the style information and places the file in the same folder as the MBTiles file. You can use the JSON file to customize the appearance of the predefined basemap. For more information, see Customize Appearance of Vector Basemaps.

When you specify the name of a JSON file, you must include the extension .json. The way you specify the file depends on the location of the file.

• If the file is in your current folder or in a folder on the MATLAB path, then specify the name of the file, such as "myFile.json".

• If the file is not in the current folder or in a folder on the MATLAB path, then specify the full or relative path name, such as "C:/myfolder/myFile.json" or "dataDir/myFile.json".

JSON files can require internet access, for example, when the file specifies fonts or icons that are stored on a web server. When the file includes references to web servers, the paths must be full paths (not relative paths).

Style Limitations

• The predefined styles use a font supported only in English locales.

• Styles specified using URLs must include the transfer protocol. Only https is supported.

• Styles specified using URLs and JSON files can contain attributes that the addCustomBasemap function does not support. These unsupported attributes can affect the appearance of the basemap or can cause the function to issue an error.

• The addCustomBasemap function creates the custom basemap by matching layers contained in the map tiles with layer IDs specified by the style. If the function fails to match a layer with a layer ID, then the basemap displays the geometry of the layer (such as polygon edges and lines) and does not display other aspects of the layer (such as points and text).

• Styles specified using URLs or JSON files from Esri can cause basemaps on globe viewers to appear in unexpected blue colors. These colors appear because the style specifies some layers as semitransparent instead of completely opaque. Within a JSON file, you can make layers completely opaque by changing values of the "fill-opacity" properties to 1. After you update the JSON file, you must add the custom basemap again.

Data Types: char | string

DisplayName — Display name of custom basemap

string scalar | character vector

Display name of the custom basemap, specified as a string scalar or character vector.

The webmap function uses this name in the Layer Manager. The addToolbarMapButton function uses this name in the basemap picker.

Example: "OpenStreetMap"

Data Types: string | char

MaxZoomLevel — Maximum zoom level of basemap

18 (default) | integer in range [0, 25]

Maximum zoom level of the basemap, specified as an integer in the range [0, 25].

When you create a custom basemap from an MBTiles file with the maximum zoom level in the metadata, the addCustomBasemap gets the maximum zoom level from the file.

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

IsDeployable — Map is deployable using MATLAB Compiler™

false or 0 (default) | true or 1

Map is deployable using MATLAB Compiler, specified as a numeric or logical 0 (false) or 1 (true).

To deploy a map application that uses a custom basemap, set IsDeployable to true. If you create the custom basemap from an MBTiles file, then you must include the file in the deployed application package, unless you deploy the application to the same computer you used to compile the application or if the file is on a network file system that the application can access from a different computer. You must set this argument whether you use the addCustomBasemap function in your application or outside your application.

Data Types: logical

Limitations

• When you add a custom basemap from vector map tiles, text that crosses tile boundaries can appear clipped.

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 access a list of available basemaps, press Tab before specifying the basemap in your plotting function. This image shows a sample list of available basemaps, including several custom basemaps from the USGS National Map.

  

Version History

Introduced in R2018b

R2023a: Add custom basemaps from vector basemaps hosted by Esri and from MBTiles files containing vector data

Add vector basemaps from these sources:

• Vector basemaps hosted by Esri. Specify the basemap using a URL.

• MBTiles files containing vector map tiles.

Specify the appearance of vector basemaps using the Style name-value argument.

Mapping Toolbox includes an MBTiles file, naturalearth.mbtiles, with low-zoom levels of region and land boundaries.¹ The file was created using data from Natural Earth.

R2022a: Add custom basemaps from MBTiles files

Add a custom basemap from an MBTiles file containing raster map tiles. Creating custom basemaps from MBTiles files is useful when you do not have internet access. Mapping Toolbox includes an MBTiles file with low-resolution USGS imagery called usgsimagery.mbtiles.