Main Content

wmmarker

Display geographic marker on web map

Description

wmmarker(lat,lon) displays a marker overlay at the points specified by lat and lon on the current web map. If there is no current web map, wmmarker creates one. wmmarker centers the map so that all vector overlays on the web map are visible. A marker is also called a map pin.

example

wmmarker(P) displays a marker overlay based on the vector geographic features stored in P. Each element of P defines one marker overlay.

example

wmmarker(wm,___) displays the overlay in the web map specified by the web map handle, wm.

wmmarker(__,Name,Value) specifies name-value pairs that set additional display properties. Parameter names can be abbreviated and are case-insensitive.

example

h = wmmarker(___) returns a handle to the overlay.

Examples

collapse all

Display a marker at the location of London, England. There is no current web map, so the wmmarker function creates one.

lat = 51.5187666404504;
lon = -0.130003487285315;
wmmarker(lat,lon)

wmmarker adds the marker name to the list of overlays in the Layer Manager. The default name is Marker Overlay 1.

Layer Manager with options for base layers and overlay layers

Read the coordinates and names of locations in Boston, MA, as a geospatial table.

P = readgeotable("boston_placenames.gpx");

Display the data as markers on a web map. Specify the feature names and overlay names using name-value arguments. The wmmarker function creates a new web map when there is no current web map.

wmmarker(P,"FeatureName",P.Name,"OverlayName","Boston Placenames")

Click on a marker to see information about the feature, including its name.

Define a location. For this example, specify the coordinates of MathWorks®.

lat =  42.299827;
lon = -71.350273;

Specify a name and text to display in the description balloon. This code makes the MathWorks URL a link.

name = 'MathWorks';
description = sprintf(...
  '%s<br>%s</br><br>%s</br>',...
  '3 Apple Hill Drive', 'Natick, MA. 01760', ...
  '<a href="https://www.mathworks.com" target="_blank">https://www.mathworks.com</a>');

Specify a custom icon for the marker.

iconDir = fullfile(matlabroot,'toolbox','matlab','icons');
iconFilename = fullfile(iconDir,'matlabicon.gif');

Display the marker on the web map by using wmmarker. Specify the Description, FeatureName, Icon, and OverlayName name-value pairs. Note the custom icon. Display the text you included by clicking on the marker. Note the HTML formatting in the description.

wmmarker(lat,lon,'Description',description, ...
                 'FeatureName',name, ... 
                 'Icon',iconFilename, ... 
                 'OverlayName',name)

Import a shapefile representing tsunami events reported over several decades, tagged geographically by source location.

GT = readgeotable("tsunamis.shp","CoordinateSystemType","geographic");

Create an attribute specification for use in the feature balloons. Modify the specification so that it defines a table of values, including year, cause, country, location, and maximum height. The attribute specification defines the format of the expected value for each field.

attribspec = makeattribspec(GT);

desiredAttributes = ...
       {'Max_Height','Cause','Year','Location','Country'};
allAttributes = fieldnames(attribspec);
attributes = setdiff(allAttributes,desiredAttributes);
attribspec = rmfield(attribspec,attributes);
attribspec.Max_Height.AttributeLabel = "<b>Maximum Height</b>";
attribspec.Max_Height.Format = "%.1f Meters";
attribspec.Cause.AttributeLabel = "<b>Cause</b>";
attribspec.Year.AttributeLabel = "<b>Year</b>";
attribspec.Year.Format = "%.0f";
attribspec.Location.AttributeLabel = "<b>Location</b>";
attribspec.Country.AttributeLabel = "<b>Country</b>";

Create a web map with a base layer containing ocean details. Add the marker overlay. Display the table data you specified in the attribute specification by selecting a marker.

webmap("ocean basemap");
wmmarker(GT,"Description",attribspec,... 
	     "OverlayName","Tsunami Events")
wmzoom(2)

World map with red markers that represent tsunami events. A balloon displays information about one of the markers.

Input Arguments

collapse all

Latitudes of points, specified as a matrix.

Data Types: single | double

Longitudes of points, specified as a matrix.

Data Types: single | double

Geographic features, specified as one of the following:

Web map, specified as a web map handle.1

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.

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

Example: wmmarker(lat,lon,'Autofit',true)

Overlay visibility, specified as the comma-separated pair consisting of 'Autofit' and the logical flag true or false, or the numeric value 1 or 0. If true or 1, wmmarker adjusts the spatial extent of the map to ensure that all the vector overlays on the map are visible. If false, wmmarker does not adjust the spatial extent when the overlay is added to the map.

Overlay visibility, specified as a scalar logical or numeric value true (1) or false (0).

  • If true, wmmarker adjusts the spatial extent of the map to ensure that all the vector overlays on the map are visible.

  • If false, wmmarker does not adjust the spatial extent when the overlay is added to the map.

Data Types: double | logical

Description of feature, specified as the comma-separated pair consisting of 'Description' and a character vector, cell array of character vectors, or scalar structure. The description defines the content that wmmarker displays in the feature’s description balloon which appears when a user clicks on the feature in the web map. Description elements can be either plain text or HTML markup. When you specify an attribute spec, the display in the balloon for the attribute fields of P are modified according to the specification. The default value is an empty character vector (''). If the value is a structure, the attribute spec is applied to the attributes of each feature of P and ignored with lat and lon input.

  • If the value is a cell array it is either scalar or the same length as P, or lat and lon, and specifies the description for each marker.

  • If the value is a structure, the attribute spec is applied to the attributes of each feature of P and ignored with lat and lon input.

Data Types: char | struct | cell

Name of overlay layer, specified as the comma-separated pair consisting of 'OverlayName' and a character vector. wmmarker inserts the name in the Layer Manager under the Overlays item. The Layer Manager is the tool that appears on the right side of the web map frame. The default name is 'Marker Overlay N' where N is the number assigned to this overlay.

Data Types: char

Name of feature, specified as the comma-separated pair consisting of 'FeatureName' and a character vector or cell array of character vectors. The name appears in the feature's balloon when a user clicks on the feature in the web map. The default value is 'OverlayName : Point K', where OverlayName is the name of the overlay and K is the number assigned to a particular point. If the value is a character vector, wmmarker applies it to all features. If the value is a cell array, it must be a scalar or an array with the same length as P or lat and lon.

Data Types: char | cell

File name of custom icon for a marker, specified as the comma-separated pair consisting of 'Icon' and a character vector or cell array of character vectors. If the icon file name is not in the current folder, or in a folder on the MATLAB® path, specify a full or relative path name. If you specify an Internet URL it must include the protocol type. If the icon file name is not specified, the default icon is displayed. For best results when you want to view a non-default icon, specify a PNG file containing image data with an alpha mask.

  • If the value is a character vector, wmmarker applies the value to all markers.

  • If you specify a cell array, it must be the same length as P, or lat and lon, and specifies the icon for each marker.

Data Types: char | cell

Scaling factor for icon, specified as the comma-separated pair consisting of 'IconScale' and a positive numeric scalar or vector.

  • If the value is a scalar, the value is applied to all icons.

  • If the value is a vector, it must specify a value for each icon, and it must be the same length as lat and lon or P.

Data Types: double

Icon color, specified as the comma-separated pair consisting of 'Color' and one of these options.

  • A color name such as 'red' or a short name such as 'r'.

  • An RGB triplet, which is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1]; for example, [0.4 0.6 0.7].

  • A cell array of color names such as {'red','green','blue'} or {'r','g','b'}.

  • A string vector of color names such as ["red" "green" "blue"] or ["r" "g" "b"].

  • A matrix of RGB triplets, which is a three-column matrix in which each row is an RGB triplet.

The way you specify the color depends on the desired color scheme.

  • To apply the same color to all icons, specify a single color name or RGB triplet.

  • To apply a different color to each icon, specify a cell array of color names, a string vector of color names, or a matrix of RGB triplets. The number of colors and RGB triplets must match the length of lat and lon or P.

If you specify a custom icon file, then the wmmarker function ignores this argument.

This table contains the color names and equivalent RGB triplets for some common colors.

Color NameShort NameRGB TripletAppearance
"red""r"[1 0 0]

Sample of the color red

"green""g"[0 1 0]

Sample of the color green

"blue""b"[0 0 1]

Sample of the color blue

"cyan" "c"[0 1 1]

Sample of the color cyan

"magenta""m"[1 0 1]

Sample of the color magenta

"yellow""y"[1 1 0]

Sample of the color yellow

"black""k"[0 0 0]

Sample of the color black

"white""w"[1 1 1]

Sample of the color white

Data Types: char | string | cell | double

Transparency of marker, specified as the comma-separated pair consisting of 'Alpha' and a numeric scalar or vector. If you specify a vector, it must include a value for each marker, that is, the vector must be the same length as P. The default value, 1, means that the marker is fully opaque.

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

Output Arguments

collapse all

Marker overlay, returned as a handle to a marker overlay object.

Version History

Introduced in R2013b

expand all


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