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.

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.

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, where 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 USGS layers based on region of interest. 
caLayers = wmsfind('usgs*california', ... 
  'SearchField', 'serverurl', ... 
  'Latlim', latlim, 'Lonlim', lonlim); 

% Refine the search to include only the San Franciso layers. 
% Remove layers that contain metadata or footprint information. 
caLayers = caLayers.refine('SanFranciscoCA'); 
removeNames = {'footprint', 'metadata'}; 
layerNames = {caLayers.LayerName}; 
index = true(1, numel(layerNames)); 
for k=1:numel(removeNames) 
    tf = regexpi({caLayers.LayerName}, removeNames{k}); 
    index = index | cellfun(@isempty, tf); 
end 
orthoLayers = caLayers(index); 

% Obtain the image. 
imageLength = 1024; 
[A, R] = wmsread(orthoLayers, 'Latlim', latlim, 'Lonlim', lonlim, ... 
    'ImageHeight', imageLength, 'ImageWidth', imageLength); 

% Display the orthoimage 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})

Read and display a single sequence image from the MODIS instruments on the Aqua and Terra satellites that shows hurricane Katrina on August 29, 2005:

% Find the hurricane Katrina sequence layer.
katrina = wmsfind('Hurricane Katrina (Sequence)');
katrina = wmsupdate(katrina(1));

% The Dimension.Extent field shows a sequence delimited 
% by commas. The sequence starts on August 24 and ends 
% on August 31. The commas start at August 25 and end
% after August 30. Select the sequence corresponding to 
% August 29.
commas = strfind(',', katrina.Details.Dimension.Extent);
extent = katrina.Details.Dimension.Extent;
sequence = extent(commas(end-2)+1:commas(end-1)-1);

% Obtain the time, latitude, and longitude limits
% from the values in the sequence. Split the sequence 
% into a cell array of values by first finding
% all values between and including the parentheses,
% then remove the parentheses and split the values.
pat = '[(-.\d)]';
r = regexp(sequence, pat);
values = sequence(r);
values = strrep(values, '(', ' ');
values = strrep(values, ')', ' ');
values = regexp(values, '\s', 'split');
values = values(~cellfun('isempty', values));
time = values{1};
xmin = values{2};
ymin = values{3};
xmax = values{4};
ymax = values{5};

% Define latitude and longitude limits from the information
% in the sequence. The layer's geographic extent is assigned 
% for the combined set of sequences. The requested map cannot
% be a subset of the layer's bounding box. In this rare case, 
% set the layer's limits using the limits of the sequence.
latlim = [str2double(ymin) str2double(ymax)];
lonlim = [str2double(xmin) str2double(xmax)];
katrina.Latlim = latlim;
katrina.Lonlim = lonlim;

% Read and display the sequence map.
[A,R] = wmsread(katrina, 'SampleDimension', ...
   {katrina.Details.Dimension.Name, sequence});
figure
usamap(katrina.Latlim,katrina.Lonlim);
geoshow(A,R)
coast = load('coast');
plotm(coast.lat, coast.long)
title({katrina.LayerTitle, time})

Search MATLAB Documentation
R2012a Documentation → Mapping Toolbox
View documentation for other releases	Learn more about Mapping Toolbox