Documentation Center

  • Trial Software
  • Product Updates

wmsread

Retrieve WMS map from server

Syntax

[A,R] = wmsread(layer)
[A,R] = wmsread(mapRequestURL)
[A,R] = wmsread(layer,Name,Value,...)
[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, a referencing matrix R, 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(mapRequestURL) uses the input argument mapRequestURL to define the request to the server. The mapRequestURL string contains a WMS serverURL with additional WMS parameters. The URL string includes the WMS parameters BBOX and 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] = 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,mapRequestURL] = wmsread(...) returns a WMS GetMap request URL in the string 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.

Input Arguments

layer

WMSLayer object that contains information about the layer you are retrieving, such as the server URL. layer must contain either the string 'EPSG:4326' or 'CRS:84' in the CoordRefSysCodes property.

mapRequestURL

String that defines the request to the server.

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

'Latlim'

Two-element vector that specifies the latitude limits of the output image in the form [southern_limit northern_limit]. The limits are in degrees and must be ascending. By default, 'Latlim' is empty, and the full extent in latitude of layer is used. If Layer.Details.Attributes.NoSubsets is true, then 'Latlim' may not be modified.

'Lonlim'

Two-element vector that specifies the longitude limits of the output image in the form [western_limit eastern_limit]. The limits are in degrees and 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, then 'Lonlim' may not be modified.

'ImageHeight'

Scalar, positive, integer-valued number that specifies the desired height of the raster map in pixels. ImageHeight cannot exceed 8192. If layer.Details.Attributes.
FixedHeight
contains a positive number, then you cannot modify 'ImageHeight'.

'ImageWidth'

Scalar, positive, integer-valued number that specifies the desired width of the raster map in pixels. ImageWidth cannot exceed 8192. If Layer.Details.Attributes.FixedWidth contains a positive number, then you cannot modify 'ImageWidth'.

'CellSize'

Scalar or two-element vector that specifies the target size of the output pixels (raster cells) in units of degrees. 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].

'RelTolCellSize'

Scalar or two-element vector that specifies the relative tolerance for 'CellSize'. If you specify a scalar, the value applies to both height and width dimensions. If you specify a vector, the tolerance appears in the order [height width].

Default: .001

'ImageFormat'

String that specifies the desired image format for use in rendering the map as an image. If specified, the format must match an entry in the Layer.Details.ImageFormats cell array and must match one of the following supported formats: 'image/jpeg', 'image/gif', 'image/png', 'image/tiff', 'image/geotiff', 'image/geotiff8', 'image/tiff8', 'image/png8', 'image/bil'. If not specified, the format defaults to the first available format in the supported format list. When the 'image/bil' format is specified, A is returned as a two-dimensional array with a class type of int16 or int32.

'StyleName'

String or cell array of strings that specifies the style to use when rendering the image. By default, the style is set to the empty string. 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 strings.

'Transparent'

Logical that specifies if transparency is enabled. When you set Transparent to true, 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.

Default: false

'BackgroundColor'

Three-element vector that specifies the color of the background (nondata) pixels of the map.

Default: [255,255,255]

'Elevation'

String that indicates the desired elevation extent of the requested map. 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.

'Time'

String or numeric date number that indicates the desired time extent of the requested map. 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 WMSMapRequest.Time property reference page.

'SampleDimension'

Two-element cell array of strings that indicates the name of a sample dimension (other than 'time' or 'elevation') and its string 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'.

'TimeoutInSeconds'

Integer-valued, scalar double that indicates the number of seconds to elapse before a server time-out is issued. A value of 0 causes the time-out mechanism to be ignored.

Default: 60 seconds

Output Arguments

A

Color or grayscale image.

R

Referencing matrix that ties A to the EPSG:4326 geographic coordinate system.

mapRequestURL

String that lists a WMS GetMap request URL.

Definitions

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.

Examples

Read and display a Blue Marble Next Generation layer from NASA:

nasa = wmsfind('nasa', 'SearchField', 'serverurl');
layer = nasa.refine('bluemarbleng', ...
   'SearchField', 'layername', 'MatchType', 'exact');
[A, R] = wmsread(layer(1));
figure
axesm globe
axis off
geoshow(A, R)
title('Blue Marble')

 

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.

Define region of interest.

latlim = [37.824928  37.829598];
lonlim = [-122.482373 -122.47768];

Find the USGS high-resolution ortho-imagery layer. The USGS National Map provides ortho-imagery from various regions of the United States. One method to obtain the high-resolution ortho-imagery layer is to obtain the capabilities document from the server. The ortho-imagery layer is the only layer from this server. Use multiple attempts to connect to the server in case it is busy.

numberOfAttempts = 5;
attempt = 0;
info = [];
serverURL = 'http://isse.cr.usgs.gov/arcgis/services/Orthoimagery/USGS_EDC_Ortho_HRO/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

Obtain the image.

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

% Display the ortho-image in a UTM projection.
figure
axesm('utm', 'Zone', utmzone(latlim, lonlim), ...
    'MapLatlimit', latlim, 'MapLonlimit', lonlim, ...
    'Geoid', wgs84Ellipsoid)
geoshow(A,R)
axis off
title({'San Francisco','Northern Section of Golden Gate Bridge'})

 

Read and display a global monthly composite of sea surface temperature for April 16, 2010 based on data from the AMSR-E sensor on board the Aqua satellite. Include the coastline, landmask, and nation layers.

coastwatch = wmsfind('coastwatch', 'SearchField', 'serverurl');
layers = coastwatch.refine('erdAAsstamday', ...
   'Searchfield','serverurl');
time = '2010-04-16T00:00:00Z';
[A, R] = wmsread(layers(end:-1:1), 'Time', time);
figure
axesm('pcarree', 'Maplonlimit', [0, 360], ...
   'PLabelLocation', 45, 'MLabelLocation', 90, ...
   'MLabelParallel', -90, 'MeridianLabel', 'on', ...
   'ParallelLabel', 'on');
geoshow(A, R);
title({layers(end).LayerTitle, time})

More About

expand all

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 handle object representing a WMS server. The handle object acts as a proxy to a WMS server and resides physically on the client side. The handle object retrieves the map from the server. The handle 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.

See Also

| | | | |

Was this topic helpful?