addCustomBasemap

Add custom basemap

Syntax

addCustomBasemap(basemapName,URL)

addCustomBasemap(basemapName,wmsLayer)

addCustomBasemap(basemapName,wmsGetMapRequestURL)

addCustomBasemap(basemapName,mbtilesFilename)

addCustomBasemap(basemapName,A,R)

addCustomBasemap(___,Name=Value)

Description

Add Basemap from Web Source

addCustomBasemap(basemapName,URL) adds a custom basemap to the list of basemaps available for use with mapping functions. This syntax adds the basemap from a parameterized URL. basemapName is the name you choose to call the custom basemap.

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.

Added basemaps remain available for use in future MATLAB^® sessions.

addCustomBasemap(basemapName,wmsLayer) adds a custom basemap from a Web Map Service (WMS) layer. (since R2024b)

addCustomBasemap(basemapName,wmsGetMapRequestURL) adds a custom basemap from a URL containing a WMS GetMap request. (since R2024b)

Add Basemap from File, Image, or Data Grid

addCustomBasemap(basemapName,mbtilesFilename) adds a custom basemap from 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. (since R2022a)

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

addCustomBasemap(basemapName,A,R) adds a custom basemap from a georeferenced image or data grid. Specify the image or data grid using an array and a raster reference object. The input image or data grid must be referenced to Earth. (since R2024b)

Additional Options

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 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)

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 Vector Basemap from Esri

Display data on a vector 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])

Add Basemap from Image

Since R2024b

Read a GeoTIFF file containing imagery of Boston into the workspace as an array and a map cells reference object. The array is a grid of cells referenced to projected coordinates.

[A,R] = readgeoraster("boston.tif");

Add a custom basemap from the array and reference object. The addCustomBasemap function issues a warning because the array and reference object do not specify global data for zoom level 0.

addCustomBasemap("bostonBasemap",A,R)

Warning: File does not contain global data for zoom level 0.

Create a map using the limits of the imagery. Calculate the latitude and longitude limits by unprojecting the xy-limits that are stored in the reference object.

xlimits = R.XWorldLimits;
ylimits = R.YWorldLimits;
projcrs = R.ProjectedCRS;
[latlim,lonlim] = projinv(projcrs,xlimits,ylimits);

figure
geolimits(latlim,lonlim)

Change the basemap to the custom basemap. The black background indicates areas where the basemap tile contains no data.

geobasemap bostonBasemap

Add Basemap from Quantitative Data

Since R2024b

To add a custom basemap with full-color tiles from quantitative data, you must first convert the data to an indexed image and a colormap, and then convert the indexed image and colormap to an RGB image.

Search the Web Map Service (WMS) Database for a layer containing terrain elevation data from the WMS server hosted by MathWorks®. The elevation data is derived from GMTED2010.

layers = wmsfind("mathworks",SearchField="serverurl");
elevation = refine(layers,"elevation");

Read global elevation data from the server. Specify the raster size as 2048-by-4096, and specify the format as BIL. The wmsread function represents the data using an array and a geographic cells reference object.

[Z,R] = wmsread(elevation,Latlim=[-90 90],Lonlim=[-180 180], ...
    ImageHeight=2048,ImageWidth=4096,ImageFormat="image/bil");

Convert the elevation data to an indexed image and a colormap. An indexed image is an array of integers, where each integer maps to a row of the colormap. Each row of the colormap is an RGB triplet that specifies the red, green, and blue components of a color.

• Prepare to visualize the water areas in blue by setting elevations at or below sea level (Z <= 0) to a value below sea level.

• Specify the number of colors to include in the colormap as 256.

• Create a colormap that is appropriate for elevation data.

• Rescale the elevation data to the interval [0, 255].

• Create the indexed image by converting the rescaled elevation data to an array of 16-bit unsigned integers. Note that the largest value of the unsigned integer type must be greater than the number of colors in the colormap.

% create colormap
Z(Z <= 0) = -1;
numColors = 256;
cmap = demcmap(Z,numColors);

% create indexed image
X = rescale(Z,0,numColors-1);
X = uint16(X);

Convert the indexed image to an RGB image of 8-bit unsigned integers.

rgb = ind2rgb8(X,cmap);

Add a custom basemap from the RGB image and reference object. Specify an attribution for the basemap by using the Attribution name-value argument.

addCustomBasemap("gmted2010",rgb,R,Attribution="US Geological Survey")

Create a geographic globe that uses the custom basemap. Position the camera above South America.

uif = uifigure;
g = geoglobe(uif,Basemap="gmted2010");

campos(g,-18,-62)

Add Basemap from WMS Layer

Since R2024b

A WMS server provides images of publicly accessible geospatial information from web-based sources. For introductory information about WMS servers, see Basic Workflow for Creating WMS Maps.

Search the WMS Database for layers from the GEBCO WMS server. Refine the list to include the "GEBCO_LATEST_2_sub_ice_topo" layer, which contains color-shaded elevation and under-ice topography for the globe. Synchronize the layer with the WMS server.

layers = wmsfind("gebco.net",SearchField="serverurl");
iceTopoLayer = refine(layers,"GEBCO_LATEST_2_sub_ice_topo");
iceTopoLayer = wmsupdate(iceTopoLayer)

iceTopoLayer = 
  WMSLayer

  Properties:
           Index: 1
     ServerTitle: 'This is a WMS for the GEBCO global bathymetric grid'
       ServerURL: 'https://www.gebco.net/data_and_products/gebco_web_services/web_map_service/mapserv?'
      LayerTitle: 'GEBCO Grid colour-shaded for elevation including under ice topography'
       LayerName: 'GEBCO_LATEST_2_sub_ice_topo'
          Latlim: [-90.0000 90.0000]
          Lonlim: [-180.0000 360.0000]
        Abstract: 'GEBCO_LATEST_2_sub_ice_topo'
CoordRefSysCodes: {'EPSG:4326'}
         Details: [1x1 struct]

  Methods

Valid WMS layers have longitude limits in the range [–180, 180] or [0, 360]. Specify valid longitude limits for the layer by changing the Lonlim property.

iceTopoLayer.Lonlim = [-180 180];

Add a custom basemap using the WMS layer. Specify an attribution by using the Attribution name-value argument and the title of the layer.

attribution = iceTopoLayer.LayerTitle;
addCustomBasemap("gebcoIceTopo",iceTopoLayer,Attribution=attribution) 

Create a geographic globe that uses the custom basemap. Position the camera above Europe.

uif = uifigure;
g = geoglobe(uif,Basemap="gebcoIceTopo");

campos(g,33,8,4e6)
campitch(g,-70)

Add Basemap from WMS GetMap Request URL

Since R2024b

A WMS server provides images of publicly accessible geospatial information from web-based sources. A WMS GetMap request enables you to read an image with the specified geographic limits at a specified time. For more information about WMS GetMap requests, see Modify Your Map Request.

Search the WMS Database for layers from the NASA Earth Observations (NEO) WMS server. Refine the list to include the "MOD_LSTD_M" layer, which contains daytime land surface temperatures. Synchronize the layer with the WMS server.

layers = wmsfind("neo.gsfc.nasa.gov",SearchFields="ServerURL");
tempLayers = refine(layers,"land surface temperature");
tempDayLayer = refine(tempLayers,"MOD_LSTD_M");
tempDayLayer = wmsupdate(tempDayLayer);

Create a WMS map request from the layer. Request data from June 1, 2024 by updating the Time property of the map request.

mapRequest = WMSMapRequest(tempDayLayer);
mapRequest.Time = "2024-06-01";

Get the WMS GetMap request URL from the map request. Then, add a custom basemap using the URL. Specify an attribution by using the Attribution name-value argument and the title of the server.

url2024 = mapRequest.RequestURL;
attribution = tempDayLayer.ServerTitle;
addCustomBasemap("landTempJune2024",url2024,Attribution=attribution)

Display the basemap in a geographic axes object by using the geobasemap function. Add a title and subtitle using the title of the layer and the time stored in the map request, respectively.

figure
geobasemap landTempJune2024

t = tempDayLayer.LayerTitle;
title(t)
subtitle(mapRequest.Time)

Add a second basemap using temperatures from January 1, 2001. Update the Time property of the map request, get the updated WMS GetMap request URL, and add the basemap using the updated URL.

mapRequest.Time = "2001-01-01";
url2000 = mapRequest.RequestURL;
addCustomBasemap("temperatureJan2001",url2000,Attribution=attribution)

Display the second basemap in a new geographic axes object.

figure
geobasemap temperatureJan2001
title(t)
subtitle(mapRequest.Time)

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.

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

wmsLayer — WMS layer

WMSLayer object | array of WMSLayer objects

Since R2024b

WMS layer, specified as a WMSLayer object or an array of WMSLayer objects.

The WMS layers must satisfy these requirements:

• The layers must be associated with the same WMS server. For an array of layers, you can query the URLs of unique WMS servers by using the servers function.

• The WMS server associated with the layers must support HTTPS.

• The layers must support one of these coordinate reference systems (CRSs). You can find the CRSs that a layer supports by querying the CoordRefSysCodes property of the WMSLayer object.

  • The WGS 84 geographic CRS, which the CoordRefSysCodes property stores as 'EPSG:4326' or 'CRS:84'.

  • A Web Mercator projected CRS, which the CoordRefSysCodes property stores as 'EPSG:3857', 'EPSG:900913', or 'EPSG:102113'.

• The layers must support an image format. You can determine the formats that a layer supports by querying the ImageFormats field of the structure contained within the Details property of the WMSLayer object.

Adding a custom basemap from WMS layers has these limitations:

• The addCustomBasemap function does not support layers from wms.mathworks.com.

• The addCustomBasemap function does not support layers with fixed height or fixed width attributes. You can determine if a layer has fixed width or fixed height attributes by querying the FixedWidth or FixedHeight field of the structure contained within the Details property of the WMSLayer object.

• Geographic globes do not support custom basemaps created from layers that read data from redirected servers.

wmsGetMapRequestURL — URL that contains WMS GetMap request

string scalar | character vector

Since R2024b

URL that contains a WMS GetMap request, specified as a string scalar or character vector. You can get the URL by querying the RequestURL property of a WMSMapRequest object.

The URL must satisfy these requirements:

• The URL must include the transfer protocol. Only https is supported.

• The URL must specify one of these coordinate reference systems (CRSs).

  • The WGS 84 geographic CRS, which the URL indicates as EPSG:4326 or CRS:84.

  • A Web Mercator projected CRS, which the URL indicates as EPSG:3857, EPSG:900913, or EPSG:102113.

• The URL must specify an image format, such as image/jpeg.

Adding a custom basemap from a URL that contains a WMS GetMap request has these limitations:

• The addCustomBasemap function does not support requests from wms.mathworks.com.

• The addCustomBasemap function does not support requests with fixed height or fixed width attributes. To determine if a request has fixed height or fixed width attributes, convert the URL to a WMSLayer object. Then, query the FixedWidth or FixedHeight fields of the structure contained within the Details property of the WMSLayer object. For more information about converting a URL to a WMSLayer object, see Create WMS Layer from WMS GetMap Request URL on the WMSLayer reference page.

• Geographic globes do not support requests that read data from redirected servers.

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

When data stored in the MBTiles file does not fill the extent of a basemap tile, the basemap displays the missing data in the tile using black or blue colors.

You can create MBTiles files from a georeferenced image or data grid by using the mbtileswrite function. (since R2024b)

Data Types: char | string

A — Georeferenced image or data grid

M-by-N numeric or logical matrix | M-by-N-by-3 numeric array

Since R2024b

Georeferenced image or data grid, specified as an M-by-N numeric or logical matrix or an M-by-N-by-3 numeric array.

Some data types and values of M and N cause the addCustomBasemap function to issue a warning:

• When A has a data type other than uint8, the function issues a warning and adds the basemap using the uint8 data type.

• When M and N are less than 256, the function issues a warning and adds the basemap by resizing the array so that either M or N is greater than or equal to 256.

R — Spatial reference for A

GeographicCellsReference object | GeographicPostingsReference object | MapCellsReference object | MapPostingsReference object

Since R2024b

Spatial reference for A, specified as a GeographicCellsReference, GeographicPostingsReference, MapCellsReference, or MapPostingsReference object.

The addCustomBasemap function adds the basemap using the CRS that is stored in R.

• When R is a GeographicCellsReference or GeographicPostingsReference object and the GeographicCRS property of the object is empty, the function writes the MBTiles file using the WGS 84 geographic CRS, which has the EPSG code 4326.

• When R is a MapCellsReference or MapPostingsReference object, the ProjectedCRS property of the object must not be empty. The projected CRS must be suitable for reprojection to the WGS 84 / Pseudo-Mercator projected CRS, which has the EPSG code 3857.

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

R2024b: Add custom basemaps from images or data grids

Add basemaps from georeferenced images or from georeferenced data grids.

R2024b: Add custom basemaps from WMS data

Add basemaps from WMS layers and from URLs containing WMS GetMap requests.

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.