addToolbarMapButton

Add map button to toolbar

Since R2021b

Syntax

addToolbarMapButton(tb)

addToolbarMapButton(tb,"basemap")

addToolbarMapButton(tb,"basemap",Name=Value)

Description

addToolbarMapButton(tb) adds all map buttons to the axes toolbar tb. The axes toolbar must be in a GeographicAxes object and the GeographicAxes object must be in a figure created by using the uifigure function.

addToolbarMapButton(tb,"basemap") creates a basemap picker and adds it to the axes toolbar. Open the basemap picker by selecting Pick Basemap from the axes toolbar. The basemap picker appears near the upper-right corner of the map.

addToolbarMapButton(tb,"basemap",Name=Value) specifies basemap options using name-value arguments. For example, specify basemaps to include in the basemap picker by using the BasemapNames name-value argument.

Examples

Add and Remove Map Buttons from Toolbar

Create a figure by using the uifigure function. Place a geographic axes in the figure.

uif = uifigure;
gx = geoaxes(uif);

Create a custom axes toolbar. Add all map buttons to the toolbar.

tb = axtoolbar(gx,"default");
addToolbarMapButton(tb)

Remove all map buttons from the toolbar.

removeToolbarMapButton(tb)

Add Basemap Picker to Geographic Plot

Read latitude and longitude data from a shapefile into a table by using the readgeotable function.

T = readgeotable("tsunamis.shp",CoordinateSystemType="geographic");
lat = T.Shape.Latitude;
lon = T.Shape.Longitude;

Display the latitude and longitude data on a map. To add a basemap picker to the toolbar, you must create a figure by using the uifigure function and a geographic axes within the figure by using the geoaxes function. By default, geographic plots use the "streets-light" basemap.

uif = uifigure;
gx = geoaxes(uif);
geoscatter(gx,lat,lon,"r+")
geolimits(gx,[-25.8016 27.4532],[96.9154 166.8728])

Preserve the specified toolbar, limits, and plotted data by using the hold function.

hold(gx,"on")

Create a custom toolbar by using the axtoolbar function. Add the basemap picker to the toolbar.

tb = axtoolbar(gx,"default");
addToolbarMapButton(tb,"basemap")

Open the toolbar and select a basemap.

Add Custom Basemap to Basemap Picker

Add the OpenStreetMap© basemap to the list of basemaps available for use with mapping functions. After you add the basemap, you do not need to add it again in future sessions. The basemap picker uses the display name you specify when you add the basemap.

name = "openstreetmap";
url = "https://a.tile.openstreetmap.org/${z}/${x}/${y}.png";
copyright = char(uint8(169));
displayName = "OpenStreetMap";
attribution = copyright + "OpenStreetMap contributors";
addCustomBasemap(name,url,Attribution=attribution,DisplayName=displayName)

Read latitude and longitude data from a GPX file into a table.

T = readgeotable("sample_route.gpx");
lat = T.Shape.Latitude;
lon = T.Shape.Longitude;

Display the latitude and longitude data on a map.

uif = uifigure;
gx = geoaxes(uif);
geoplot(gx,lat,lon,LineWidth=2)
hold(gx,"on")

Add a basemap picker to the axes toolbar. Include the OpenStreetMap basemap and the high-zoom-level basemaps provided by Esri®.

tb = axtoolbar(gx,"default");
bmaps = ["openstreetmap","streets","streets-light", ...
    "streets-dark","topographic","satellite"];
addToolbarMapButton(tb,"basemap",BasemapNames=bmaps)

Open the basemap picker and select the OpenStreetMap basemap.

Add Custom Icons to Basemap Picker

By default, the basemap picker uses the Level 1, North America tile as the icon for custom basemaps. Create a basemap picker with custom icons.

Add the OpenStreetMap basemap to the list of basemaps available for use with mapping functions. After you add the basemap, you do not need to add it again in future sessions.

name = "openstreetmap"; 
url = "https://a.tile.openstreetmap.org/${z}/${x}/${y}.png";
copyright = char(uint8(169));
displayName = "OpenStreetMap";
attribution = copyright + "OpenStreetMap contributors";
addCustomBasemap(name,url,Attribution=attribution,DisplayName=displayName)

Read latitude and longitude data from a GPX file into a table.

T = readgeotable("sample_route.gpx");
lat = T.Shape.Latitude;
lon = T.Shape.Longitude;

Display the latitude and longitude data on a map.

uif = uifigure;
gx = geoaxes(uif);
geoplot(gx,lat,lon,LineWidth=2)
hold(gx,'on')

Specify the locations of the icons. For the custom basemap, use an icon that shows an area around Cape Town, South Africa. For the streets basemap, use the default icon.

osm_filename = "openstreetmap_256.png";
streets_filename = fullfile(matlabroot,"toolbox","shared","basemaps", ...
    "resources","icons","streets.png");

Create a basemap picker that includes the custom basemap, the "streets" basemap, and the custom icon.

tb = axtoolbar(gx,"default");
addToolbarMapButton(tb,"basemap",BasemapNames=["openstreetmap","streets"], ...
    BasemapIcons=[osm_filename,streets_filename])

Open the basemap picker and view the icons.

Input Arguments

tb — Axes toolbar

AxesToolbar object | array of AxesToolbar objects

Axes toolbar, specified as an AxesToolbar object or an array of AxesToolbar objects. The axes toolbar must be in a GeographicAxes object. Create the toolbar by using the axtoolbar function.

You can add only one of each type of map button to the axes toolbar. Adding a new button replaces any existing icons of the same type.

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: addToolbarMapButton(tb,"basemap",BasemapNames=["streets","satellite"],NumColumns=1) specifies a basemap picker with one column and the "streets" and "satellite" basemaps.

BasemapNames — Basemaps to include in basemap picker

string array | cell array of character vectors

Basemaps to include in the basemap picker, specified as a string array or a cell array of character vectors. You can specify the basemaps shown in the table and basemaps added using the addCustomBasemap function. Five basemaps in the table are high-zoom-level maps hosted by Esri^®. The other six basemaps are tiled data sets created using Natural Earth. By default, the basemap picker includes all available basemaps, including custom basemaps, except "none".

	"streets-light" (default) Map designed to provide geographic context while highlighting user data on a light background. Hosted by Esri.		"streets-dark" Map designed to provide geographic context while highlighting user data on a dark background. Hosted by Esri.
	"streets" General-purpose road map that emphasizes accurate, legible styling of roads and transit networks. Hosted by Esri.		"satellite" Full global basemap composed of high-resolution satellite imagery. Hosted by Esri.
	"topographic" General-purpose map with styling to depict topographic features. Hosted by Esri.		"landcover" Map that combines satellite-derived land cover data, shaded relief, and ocean-bottom relief. The light, natural palette is suitable for thematic and reference maps. Created using Natural Earth.
	"colorterrain" Shaded relief map blended with a land cover palette. Humid lowlands are green and arid lowlands are brown. Created using Natural Earth.		"grayterrain" Terrain map in shades of gray. Shaded relief emphasizes both high mountains and micro-terrain found in lowlands. Created using Natural Earth.
	"bluegreen" Two-tone, land-ocean map with light green land areas and light blue water areas. Created using Natural Earth.		"grayland" Two-tone, land-ocean map with gray land areas and white water areas. Created using Natural Earth.
	"darkwater" Two-tone, land-ocean map with light gray land areas and dark gray water areas. This basemap is installed with MATLAB®. Created using Natural Earth.	N/A	"none" Blank background that plots your data with a latitude-longitude grid, ticks, and labels.

All basemaps except "darkwater" require Internet access. The "darkwater" basemap is included with MATLAB.

If you do not have consistent access to the Internet, you can download the basemaps created using Natural Earth onto your local system by using the Add-On Explorer. The five high-zoom-level maps are not available for download. For more information about downloading basemaps and changing the default basemap on your local system, see Access Basemaps for Geographic Axes and Charts.

The basemaps hosted by Esri update periodically. As a result, you might see differences in your visualizations over time.

Alignment of boundaries and region labels are a presentation of the feature provided by the data vendors and do not imply endorsement by MathWorks^®.

If you specify any combination of BasemapNames, DisplayNames, and BasemapIcons, they must all be the same size. The elements of BasemapNames correspond with the elements of DisplayNames and BasemapIcons.

Example: BasemapNames=["streets","satellite"]

Data Types: char | string

DisplayNames — Basemap labels

string array | cell array of character vectors

Basemap labels, specified as a string array or a cell array of character vectors. When a label is longer than the width of a column, MATLAB breaks the label into separate lines so that each line fits within the width of the column, and avoids breaking words when possible. Basemap labels display up to three lines. MATLAB truncates labels that are longer than three lines.

The default display name for each basemap is:

• "satellite" — Satellite

• "streets" — Streets

• "streets-dark" — Streets (dark)

• "streets-light" — Streets (light)

• "topographic" — Topographic

• "darkwater" — Dark Water

• "bluegreen" — Blue Green

• "grayterrain" — Gray Terrain

• "colorterrain" — Color Terrain

• "landcover" — Land Cover

• "none" — none

• Custom basemap — Display name specified by the addCustomBasemap function. If you do not specify a display name when you add the custom basemap, then the basemap picker uses the basemap name.

Create a basemap picker with no display names by specifying DisplayNames as "".

If you specify any combination of BasemapNames, DisplayNames, and BasemapIcons, they must all be the same size. The elements of DisplayNames correspond with the elements of BasemapNames and BasemapIcons.

Example: DisplayNames=["Road Map","Satellite Imagery"]

Data Types: char | string

BasemapIcons — Icon file names

string array | cell array of character vectors

Icon file names, specified as a string array or a cell array of character vectors. Supported image formats include JPEG, PNG, GIF, and SVG.

Specify file names based on the locations of your files.

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

• If a 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.png" or "dataDir\myFile.png".

The default basemap icons are in the folder matlabroot/toolbox/shared/basemaps/resources/icons. When you add a custom basemap using the addCustomBasemap function, the default icon is the Level 1, North America tile.

When an icon has a side length greater than 80 pixels, MATLAB scales the icon to fit.

Create a basemap picker with no icon images by specifying BasemapIcons as "". In this case, the icons display the basemap names instead of images.

If you specify any combination of BasemapNames, DisplayNames, and BasemapIcons, they must all be the same size. The elements of BasemapIcons correspond with the elements of BasemapNames and DisplayNames.

Example: BasemapIcons=["myIcon1.png","myIcon2.png"]

Data Types: char | string

NumColumns — Number of basemap picker columns

2 (default) | positive integer

Number of basemap picker columns, specified as a positive integer.

Example: NumColumns=3

Data Types: single | double

Limitations

• When the Scrollable property of the figure is true, the basemap picker may not appear, or may appear in a different location than the upper-right corner.

Version History

Introduced in R2021b