addCustomBasemap

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

Specify values for these arguments:

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;

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

Specify values for these arguments:

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)

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:

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)

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:

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

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.

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.

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

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

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

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

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

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

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.

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

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.

Get a list of 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.

info = wmsinfo("https://wms.gebco.net/mapserv?");
layers = info.Layer;
iceTopoLayer = refine(layers,"GEBCO_LATEST_2_sub_ice_topo")

iceTopoLayer = 
  WMSLayer

  Properties:
           Index: 1
     ServerTitle: 'This is a WMS for the GEBCO global bathymetric grid'
       ServerURL: 'https://wms.gebco.net/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)

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)

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.