Documentation

wmsread

Retrieve WMS map from server

Syntax

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

Description

example

[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 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,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.

Examples

collapse all

Read and Display a Blue Marble Next Generation Layer from NASA

Read NASA layer and display it.

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

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://raster.nationalmap.gov/arcgis/services/Orthoimagery/USGS_EROS_Ortho/ImageServer/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 and display it in a UTM projection.

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

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 Global Monthly Composite of Sea Surface Temperature

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})

Input Arguments

collapse all

layer — Information about the layer you are retrievingWMSLayer object

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

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

mapRequestURL — WMS GetMap request URLcharacter string

WMS GetMap request URL, specified as a character string.

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

Data Types: char

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.

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 pixelsscalar, 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 pixelsscalar, 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 degreesscalar 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 imagefirst available format in the in the Layer.Details.ImageFormats cell array (default) | string

Desired format to use in rendering the map as an image, specified as one of the following strings. 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. .

StringDescription
'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) | string | cell array of strings

Style to use when rendering the image, specified as a string or cell array of strings. 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.

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

Data Types: char | cell

'Transparent' — Pixel transparencyfalse (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 mapstring

Desired elevation extent of the requested map, specified as a string. 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 mapstring | numeric date number

Desired time extent of the requested map, specified as a string 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 WMSMapRequest.Time property reference page.

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

Data Types: double | char

'SampleDimension' — Name of sample dimensiontwo-element cell array of strings

Name of dimension, specified as a two-element cell array of strings, 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'.

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

Data Types: cell

'TimeoutInSeconds' — Number of seconds to elapse before issuing a server time-out60 (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

collapse all

A — Color or grayscale imagereal, nonsparse, 2-D matrix

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

R — Geographic raster reference objectmap.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 URLcharacter string

WMS GetMap request URL, returned as a character string.

More About

collapse 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.

Introduced before R2006a

Was this topic helpful?