Main Content

addCustomBasemap

Add custom basemap

collapse all in page

Syntax

addCustomBasemap(basemapName,URL)
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.

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

example

Examples

collapse all

Open Live Script

Add a custom basemap to view locations on an OpenTopoMap® basemap, then remove the custom basemap.

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 that you can use (a, b, or 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.

  • A display name for the custom basemap. This name appears in the Imagery tab of Site Viewer.

name = "opentopomap";
url = "a.tile.opentopomap.org/${z}/${x}/${y}.png";
attribution = "©OpenStreetMap contributors";
displayName = "Open Topo Map";

Use addCustomBasemap to load the custom basemap, and then create a Site Viewer that uses the custom basemap.

addCustomBasemap(name,url,Attribution=attribution,DisplayName=displayName)
viewer = siteviewer(Basemap=name);

Site Viewer with the OpenTopoMap basemap

After you add a custom basemap, the custom map is available in new Site Viewer windows. Note the Open Topo Map basemap icon in the Imagery tab.

siteviewer;

A new Site Viewer. The Imagery tab shows a selection of basemaps, including the OpenTopoMap basemap..

Use removeCustomBasemap to remove the custom basemap. Then, open a new Site Viewer. Note the Open Topo Map basemap option is no longer available in the Imagery tab.

removeCustomBasemap(name)
siteviewer;

The Imagery tab in a new Site Viewer. The tab does not show the OpenTopoMap basemap.

Input Arguments

collapse all

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

Example: "opentopomap"

Data Types: string | char

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

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

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

Data Types: string | char | cell

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

Example: "OpenTopoMap"

Data Types: string | char

Maximum zoom level of the basemap, specified as 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 a numeric or logical 0 (false) or 1 (true).

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.

  • Mapping Toolbox enables additional strategies for adding custom basemaps. For example, you can add custom basemaps from vector basemaps hosted by Esri, from MBTiles files, or from georeferenced images. Several of these strategies do not require internet access. For more information, see addCustomBasemap (Mapping Toolbox) and Use Basemaps in Offline Environments (Mapping Toolbox).

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

    Plotting function in MATLAB with list of available basemaps to select from

Version History

Introduced in R2019b

See Also

| | | (Mapping Toolbox) | (Mapping Toolbox)

Topics