Main Content

wmsupdate

Synchronize WMSLayer object with server

    Description

    updatedLayers = wmsupdate(layers) synchronizes the properties of the WMSLayer objects in layers with values from their associated WMS server and returns the updated layers in updatedLayers. The function removes layers that are not available on the server. This syntax requires all specified layers to be associated with the same WMS server.

    The wmsupdate function requires an internet connection. WMS servers can periodically be unavailable. Synchronizing layers with a server can take several minutes.

    example

    [updatedLayers,index] = wmsupdate(layers) additionally returns a logical array whose elements are 1 (true) when the corresponding layer in layers is available on the server. This syntax requires all specified layers to be associated with the same WMS server.

    [___] = wmsupdate(layers,Name,Value) specifies options for synchronizing layers with their WMS server. For example, "AllowMultipleServers",true enables the function to synchronize layers that are associated with different WMS servers.

    example

    Examples

    collapse all

    Search the WMS Database for specific layers from the NASA Goddard Space Flight Center DAAC servers. Then, synchronize the properties of the layers with values from the servers. Enable the function to synchronize layers that are associated with different servers.

    layers = wmsfind("disc1.gsfc.nasa.gov","SearchField","serverurl");
    updatedLayers = wmsupdate(layers,"AllowMultipleServers",true);

    When you synchronize WMS layers with their associated WMS server, the function populates the Abstract, CoordRefSysCodes, and Details properties of the WMSLayer objects. You can use the additional information to refine your search.

    Find all layers in the WMS Database with the title "Global Sea Surface Temperature". Determine the number of unique servers by using the servers function.

    layers = wmsfind("Global Sea Surface Temperature","SearchField","LayerTitle");
    servers(layers)
    ans = 1×1 cell array
        {'https://svs.gsfc.nasa.gov/cgi-bin/wms?'}
    
    

    Synchronize the layers with the server. View the abstract, coordinate reference system code, and details of the first layer.

    updatedLayers = wmsupdate(layers);
    updatedLayers(1).Abstract
    ans = 
        'The temperature of the surface of the world's oceans provides a clear indication of the state of the Earth's climate and weather.  The AMSR-E instrument on the Aqua satellite measures the temperature of the top 1 millimeter of the ocean every day, even through the clouds.  In this visualization sequence covering the period from June, 2002, to September, 2003, the most obvious effects are the north-south movement of warm regions across the equator due to the seasonal movement of the sun and the seasonal advance and retreat of the sea ice near the North and South poles.  It is also possible to see the Gulf Stream, the warm river of water that parallels the east coast of the United States before heading towards northern Europe, in this data.  Around January 1, 2003, a cooler than normal region of the ocean appears just to the west of Peru as part of a La Nina and flows westward, driven by the trade winds.  The waves that appear on the edges of this cooler area are called tropical instability waves and can also be seen in the equatorial Atlantic Ocean about the same time.
         
         Additional Credit:
         B>Please give credit for this item to:</b><br />'
    
    
    updatedLayers(1).CoordRefSysCodes
    ans = 1×1 cell array
        {'CRS:84'}
    
    
    updatedLayers(1).Details
    ans = struct with fields:
         MetadataURL: 'http://svs.gsfc.nasa.gov/vis/a000000/a002900/a002905/a002905.fgdc'
          Attributes: [1×1 struct]
         BoundingBox: [1×1 struct]
           Dimension: [1×1 struct]
        ImageFormats: {'image/png'}
         ScaleLimits: [1×1 struct]
               Style: [1×2 struct]
             Version: '1.3.0'
    
    

    Refine the search to include only layers with abstracts that contain "El Nino".

    el_nino = refine(layers,"El Nino","SearchFields","abstract");

    Search the WMS Database for layers from the NASA Goddard Space Flight Center SVS Image Server. Synchronize the properties of the layers with values from the server. Then, refine the search to find layers containing the term "blue marble".

    layers = wmsfind("svs.gsfc.nasa.gov","SearchField","serverurl");
    updatedLayers = wmsupdate(layers);
    blueMarble = refine(updatedLayers,"blue marble","SearchField","abstract");

    Refine the search again to find the first layer with a title containing the term "512".

    blueMarble512 = refine(blueMarble,"*512");
    blueMarble512 = blueMarble512(1);

    Display the layer on a world map. Remove the parallel and meridian labels.

    [A,R] = wmsread(blueMarble512);
    worldmap world
    geoshow(A,R)
    title(blueMarble512.LayerTitle)
    plabel off
    mlabel off

    Synchronizing layers from multiple servers can take a long time. You can avoid synchronizing layers multiple times by saving updated layers to a MAT file.

    Search the WMS Database for server URLs that contain "noaa". Refine the search to include only layers with information about oceans.

    layers = wmsfind("noaa","SearchFields","ServerURL");
    layers = refine(layers,"ocean");

    Synchronize the layers. The code might take several minutes to run because it is synchronizing layers that are associated with multiple servers.

    updatedLayers = wmsupdate(layers,"AllowMultipleServers",true);

    Save the layers to a MAT file called oceanLayers.

    save("oceanLayers","updatedLayers")

    Loading the MAT file enables you to refine your search and read a map without updating the layers again.

    Note that servers change, so the layers contained in the MAT file might become out-of-date.

    Input Arguments

    collapse all

    WMS layers, specified as an array of WMSLayer objects.

    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: wmsupdate(layers,"AllowMultipleServers",true) enables the function to synchronize layers that are associated with different WMS servers.

    Time out connection duration in seconds, specified as a nonnegative integer. The value is the number of seconds to wait to receive a response from the server. To deactivate the time out mechanism, specify this argument as 0.

    Layers can be associated with multiple servers, specified as a numeric or logical 1 (true) or 0 (false).

    • false specifies that all layers in layers must be from the same server.

    • true specifies that the layers in layers can be associated with different servers. This option makes a request to each unique server, which can take several minutes to finish.

    Output Arguments

    collapse all

    Synchronized layers, returned as an array of WMSLayer objects.

    In addition to synchronizing the properties of the WMSLayer objects with the server, the wmsupdate function populates the Abstract, CoordRefSysCodes, and Details properties of the objects.

    The wmsupdate function removes layers that are not available on the server. Except for deleted layers, updatedLayers preserves the order of layers in layers.

    The size of updatedLayers matches the size of layers(index).

    Indicator for available layers, returned as a logical array. The size of index matches the size of layers.

    • A logical 1 (true) indicates that the corresponding layer is available on the server.

    • A logical 0 (false) indicates that the corresponding layer is not available on the server.

    Data Types: logical

    Version History

    Introduced in R2009b