wmsread

Retrieve WMS map from server

Syntax

[A,R] = wmsread(layer)

[A,R] = wmsread(layer,Name,Value,...)

[A,R] = wmsread(mapRequestURL)

[A,R,mapRequestURL] = wmsread(...)

Description

[A,R] = wmsread(layer) accesses the Internet to render and retrieve a raster map from a Web Map Service (WMS) server. The ServerURL property of the WMSLayer object, layer, specifies the server. If layer has more than one element, then the server overlays each subsequent layer on top of the base (first) layer, forming a single image. The server renders multiple layers only if all layers share the same ServerURL value.

The WMS server returns a raster map, either a color or grayscale image, in the output A. The second output, R, is a raster reference object that ties A to the EPSG:4326 geographic coordinate system. The rows of A are aligned with parallels, with even sampling in longitude. Likewise, the columns of A are aligned with meridians, with even sampling in latitude.

The geographic limits of A span the full latitude and longitude extent of layer. The wmsread function chooses the larger spatial size of A to match its larger geographic dimension. The larger spatial size is fixed at the value 512. In other words, assuming RGB output, A is 512-by-N-by-3 if the latitude extent exceeds longitude extent and N-by-512-by-3 otherwise. In both cases N <= 512. The wmsread function sets N to the integer value that provides the closest possible approximation to equal cell sizes in latitude and longitude. The map spans the full extent supported for the layer.

[A,R] = wmsread(layer,Name,Value,...) specifies parameter-value pairs that modify the request to the server. You can abbreviate parameter names, which are case-insensitive.

[A,R] = wmsread(mapRequestURL) uses the input argument mapRequestURL to define the request to the server. The mapRequestURL contains a WMS serverURL with additional WMS parameters. These WMS parameters include BBOX, GetMap and the EPSG:4326 or CRS:84 keyword. Obtain a mapRequestURL from the output of wmsread, the RequestURL property of a WMSMapRequest object, or an Internet search.

[A,R,mapRequestURL] = wmsread(...) returns a WMS GetMap request URL in the character vector mapRequestURL. You can insert the mapRequestURL into a browser to make a request to a server, which then returns the raster map. The browser opens the returned map if its mime type is understood, or saves the raster map to disk.

Examples

Read and Display Layer from NASA

Search the WMS Database for layers containing the string "bluemarble". Refine the search to include only layers from the NASA Earth Observations (NEO) WMS server. Extract the first layer.

layer = wmsfind("bluemarble");
layer = refine(layer,"neo.gsfc.nasa.gov","SearchFields","serverurl");
layer = layer(1);

Read the layer and display it on a map.

[A,R] = wmsread(layer);

axesm globe
axis off
geoshow(A,R)
title("Blue Marble")

Read and Display Orthoimage

Read and display an orthoimage of the northern section of the Golden Gate Bridge in San Francisco, California, using the USGS National Map Seamless server.

First, specify the latitude and longitude limits of the Golden Gate Bridge.

latlim = [37.78 37.84]; 
lonlim = [-122.53 -122.40];

Then, find the USGS high-resolution orthoimagery layer by reading the capabilities document from the server. The server may be busy, so try to connect multiple times.

numberOfAttempts = 5;
attempt = 0;
info = [];
serverURL = "http://basemap.nationalmap.gov/ArcGIS/services/USGSImageryOnly/MapServer/WMSServer?";
while(isempty(info))
    try
        info = wmsinfo(serverURL);
        orthoLayer = info.Layer(1);
    catch e 
        
        attempt = attempt + 1;
        if attempt > numberOfAttempts
            throw(e);
        else
            fprintf('Attempting to connect to server:\n"%s"\n', serverURL)
        end        
    end
end

Retrieve the map from the server and display it in a UTM projection.

imageLength = 1024;
[A,R] = wmsread(orthoLayer,Latlim=latlim,Lonlim=lonlim, ...
    ImageHeight=imageLength,ImageWidth=imageLength);


axesm("utm",Zone=utmzone(latlim, lonlim), ...
    MapLatlimit=latlim,MapLonlimit=lonlim,Geoid=wgs84Ellipsoid)
geoshow(A,R)
axis off
title("San Francisco")
subtitle("Northern Section of Golden Gate Bridge")

Read and Display Composite of Sea Surface Temperature

Read and display a global composite of sea surface temperature based on NOAA Coral Reef Watch data.

First, search the WMS Database for layers containing the word "coastwatch". Refine the search to find layers with the data set ID "NOAA_DHW/".

coastwatch = wmsfind("coastwatch","SearchField","serverurl");
layers = refine(coastwatch,"NOAA_DHW/","Searchfield","serverurl");

Refine the search again to find layers with coastline boundaries, nation boundaries, state boundaries, and sea surface temperatures.

layers = [refine(layers,"coastlines"); ...
    refine(layers,"nations"); refine(layers,"states"); ...
    refine(layers,"dhw_5km:CRW_SST","MatchType","exact")];

Read data from the layers for March 1, 2023.

time = "2023-03-01T12:00:00Z";
[A,R] = wmsread(layers,"Time",time);

Display the data on a map.

axesm("pcarree","Maplonlimit", [0 360], ...
                "PLabelLocation",45, ...
                "MLabelLocation",90, ...
                "MLabelParallel", -90, ...
                "MeridianLabel", "on", ...
                "ParallelLabel","on");
geoshow(A,R)

layerTitle = string(layers(end).LayerTitle);
layerTitle = textwrap(layerTitle,65);
layerTitle = [layerTitle; string(time)];
title(layerTitle,"Interpreter","none")

Customize Map Appearance

The wmsread function enables you to set optional parameters such as the image height, image width, and background color. For this example, customize the map by specifying an image resolution and background color.

Search the WMS Database for a layer containing terrain elevation data from the WMS server hosted by MathWorks®. The default background color defines the ocean and is white.

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

Define a background color by specifying the red, green, and blue levels. Specify the cell size as 0.5 degrees.

oceanColor = [0 170 255];
cellSize = 0.5;

Read an image from the layer as an array and a geographic cells reference object. Specify the background color and resolution using name-value arguments.

[A,R] = wmsread(elevation,"BackgroundColor",oceanColor, ...
    "CellSize",cellSize);

Display the image on a map and add a title. Remove the labels and the graticule lines.

worldmap world
geoshow(A,R)
title(elevation.LayerTitle)

gridm off
mlabel off
plabel off

Input Arguments

layer — Information about the layer you are retrieving

WMSLayer object

Information about the layer you are retrieving, specified as a WMSLayer object.

Example: [A,R] = wmsread(layers(1));

mapRequestURL — WMS GetMap request URL

character vector

WMS GetMap request URL, specified as a character vector.

Example: [A,R] = wmsread(mapURL);

Data Types: 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.

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

Example: [A,R] = wmsread(layers(1),'latlim',[40 50]);

latlim — Latitude limits of the output image in degrees

[] (default) | two-element vector

Latitude limits of the output image in degrees, specified as a two-element vector of the form [southern_limit northern_limit]. The limit values must be ascending. By default, 'Latlim' is empty, and wmsread uses the full extent in latitude of layer. If Layer.Details.Attributes.NoSubsets is true, 'Latlim' may not be modified.

Example: [A,R] = wmsread(layers(1),'latlim',[40 50]);

Data Types: double

lonlim — Longitude limits of the output image in degrees

[] (default) | two-element vector

Longitude limits of the output image in degrees, specified as a two-element vector in the form [western_limit eastern_limit]. The limit values must be ascending. By default, 'Lonlim' is empty and the full extent in longitude of layer is used. If Layer.Details.Attributes.NoSubsets is true, you cannot modify 'Lonlim'

Example: [A,R] = wmsread(layers(1),'lonlim',[40 50]);

Data Types: double

ImageHeight — Desired height of the raster map in pixels

scalar, positive, integer-valued number

Desired height of the raster map in pixels, specified as a scalar, positive, integer-valued number. ImageHeight cannot exceed 8192. If layer.Details.Attributes.FixedHeight contains a positive number, you cannot modify 'ImageHeight'.

Example: [A,R] = wmsread(layers(1),'ImageHeight',40);

Data Types: double

ImageWidth — Desired width of the raster map in pixels

scalar, positive, integer-valued number

Desired width of the raster map in pixels, specified as a scalar, positive, integer-valued number. ImageWidth cannot exceed 8192. If Layer.Details.Attributes.FixedWidth contains a positive number, you cannot modify 'ImageWidth'.

Example: [A,R] = wmsread(layers(1),'ImageWidth',100);

Data Types: double

CellSize — Target size of the output pixels (raster cells) in degrees

scalar or two-element vector

Target size of the output pixels (raster cells) in degrees, specified as a scalar or two-element vector. If you specify a scalar, the value applies to both height and width dimensions. If you specify a vector, use the form [height width]. The wmsread function issues an error if you specify both CellSize and ImageHeight or ImageWidth. The output raster map must not exceed a size of [8192,8192].

Example: [A,R] = wmsread(layers(1),'Cellsize',5);

Data Types: double

RelTolCellSize — Relative tolerance for 'CellSize'

.001 (default) | scalar or two-element vector

Relative tolerance for 'CellSize', specified as a scalar or two-element vector. If you specify a scalar, the value applies to both height and width dimensions. If you specify a vector, the tolerances appear in the order [height width].

Example: [A,R] = wmsread(layers(1),'RelTolCellsize',[4 5]);

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

ImageFormat — Desired format to use in rendering the map as an image

first available format in the Layer.Details.ImageFormats cell array (default) | character vector

Desired format to use in rendering the map as an image, specified as one of the following character vectors. If specified, the format must match an entry in the Layer.Details.ImageFormats cell array. If not specified, the format defaults to the first available format in the supported format list.

Value	Description
'image/jpeg'	JPEG
'image/gif'	GIF
'image/png'	PNG
'image/tiff'	TIFF
'image/geotiff'	GeoTIFF
'image/geotiff8'	GeoTIFF8
'image/tiff8'	TIFF8
'image/png8'	PNG8
'image/bil'	Band Interleaved by Line (BIL) format. When you specify the 'image/bil' format, wmsread returns A as a two-dimensional array with a class type of int16 or int32.

Example: [A,R] = wmsread(layers(1),'ImageFormat','image/png');

Data Types: char

StyleName — Style to use when rendering the image

'' (default) | character vector | cell array of character vectors

Style to use when rendering the image, specified as a character vector or cell array of character vectors. The StyleName must be a valid entry in the Layer.Details.Style.Name field. If you request multiple layers, each with a different style, then StyleName must be a cell array of character vectors.

Example: [A,R] = wmsread(layer(1),'StyleName','style');

Data Types: char | cell

Transparent — Pixel transparency

false (default) | true

Pixel transparency, specified as a logical value, true or false. When you set Transparent to true, pixel transparency is enabled, meaning all pixels not representing features or data values are set to a transparent value. When you set Transparent to false, non-data pixels are set to the value of the background color.

Example: [A,R] = wmsread(layers(1),'Transparent',true);

Data Types: logical

BackgroundColor — Color used for background (nondata) pixels of the map

[255,255,255] (default) | three-element vector

Color used for background (nondata) pixels of the map, specified as a three-element vector.

Example: [A,R] = wmsread(layers(1),'BackgroundColor',[0,0,255]);

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

Elevation — Desired elevation extent of the requested map

character vector

Desired elevation extent of the requested map, specified as a character vector. The layer must contain elevation data, which is indicated by the 'Name' field of the Layer.Details.Dimension structure. The 'Name' field must contain the value 'elevation'. The 'Extent' field of the Layer.Details.Dimension structure determines the permissible range of values for the parameter.

Example: [A,R] = wmsread(layer(1),'Elevation','test');

Data Types: char

Time — Desired time extent of the requested map

character vector | numeric date number

Desired time extent of the requested map, specified as a character vector or numeric date number. The layer must contain data with a time extent, which is indicated by the 'Name' field of the Layer.Details.Dimension structure. The 'Name' field must contain the value 'time'. The 'Extent' field of the Layer.Details.Dimension structure determines the permissible range of values for the parameter. For more information about setting this parameter, see the Time property of the WMSMapRequest object.

Example: [A,R] = wmsread(layer(1),'Time','June 15, 2015');

Data Types: double | char

SampleDimension — Name of sample dimension

two-element cell array of character vectors

Name of dimension, specified as a two-element cell array of character vectors, other than 'time' or 'elevation' and its character vector value. The layer must contain data with a sample dimension extent, which is indicated by the 'Name' field of the Layer.Details.Dimension structure. The 'Name' field must contain the value of the first element of 'SampleDimension'. The 'Extent' field of the Layer.Details.Dimension structure determines the permissible range of values for the second element of 'SampleDimension'.

Example: [A,R] = wmsread(layer(1),'SampleDimension',{'sample','test'});

Data Types: cell

TimeoutInSeconds — Number of seconds to elapse before issuing a server time-out

60 (default) | scalar integer

Number of seconds to elapse before issuing a server time-out, specified as a scalar integer. If you set the value to 0, wmsread ignores the time-out mechanism.

Example: [A,R] = wmsread(layers(1),'TimeoutInSeconds',80);

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

Output Arguments

A — Color or grayscale image

real, nonsparse, 2-D matrix

Color or grayscale image, returned as a real, nonsparse, 2-D matrix.

R — Geographic raster reference object

map.rasterref.GeographicCellsReference object

Geographic raster reference object, returned as a map.rasterref.GeographicCellsReference object. A raster referencing object ties the image A to the EPSG:4326 geographic coordinate system.

mapRequestURL — WMS GetMap request URL

character vector

WMS GetMap request URL, returned as a character vector.

More About

EPSG: 4326 Coordinate Reference System

The EPSG:4326 coordinate reference system is based on the WGS84 (1984 World Geodetic System) datum. Latitude and longitude are in degrees and longitude is referenced to the Greenwich Meridian.

Tips

• Establish an Internet connection to use wmsread. Periodically, the WMS server is unavailable. Retrieving the map can take several minutes. wmsread communicates with the server using a WebMapServer object representing a WMS server. The object acts as a proxy to a WMS server and resides physically on the client side. The object retrieves the map from the server. The object automatically times-out after 60 seconds if a connection is not made to the server.

• To specify a proxy server to connect to the Internet, select File > Preferences > Web and enter your proxy information. Use this feature if you have a firewall.

• wmsread supports reading data in WMS versions 1.0.0, 1.1.1, and 1.3.0. For version 1.3.0 only, the WMS specification states, "EPSG:4326 refers to WGS 84 geographic latitude, then longitude. That is, in this CRS the x-axis corresponds to latitude, and the y-axis to longitude." Most servers provide data in this manner; however, some servers conform to version 1.1.1, where the x-axis corresponds to longitude and the y-axis to latitude.

  wmsread attempts to validate whether a server is confirming to the specification. It checks the EPSG:4326 bounding box, and if the XLim values exceeds the range of latitude, then the axes are swapped to conform to version 1.1.1 rather than 1.3.0. If wmsread does not detect that the XLim values exceed the range of latitude and you notice that the latitude and longitude limits are reversed, then you need to swap them. You can either modify the bbox parameters in the mapRequestURL or modify the Latlim and Lonlim parameter values, if permissible.

Version History

Introduced before R2006a