This tutorial explains how to use the WMS (Web Map Service) client within Metview.
Please note that this tutorial requires Metview version 4.0.5 or later. |
First start Metview; at ECMWF, the command to use is metview (see Metview at ECMWF for details of Metview versions). You should see the main Metview desktop popping up.
You will create some icons yourself, but some are supplied for you. If you are at ECMWF then you can copy the icons from the command line like this:
cp -R /home/graphics/cgx/tutorials/wms_tutorial $HOME/metview |
Otherwise, please download the following file:
and save it in your $HOME/metview directory. You should see it appear on your main Metview desktop, from where you can right-click on it, then choose execute to extract the files.
You should now see a wms_tutorial folder which contains the solutions and also some additional icons required by these exercises. You will work in the wms_tutorial folder so open it up. You should see the following contents:
Please note that because the WMS client requires internet access you might need to configure your network proxy settings in Metview. This can be done by selecting ‘Preferences’ from the menu in the toolbar of the Metview Desktop.
Please be aware that this tutorial is strongly dependent on the availability of the selected WMS services and that of the network itself. Therefore it cannot be guaranteed that the exercises will work for you. Should you experience any WMS service related problems throughout the tutorial, you can still try out the icons provided in the ‘examples’ folder to see how the WMS client is working in Metview. |
A Web Map Service (WMS) is a standard protocol for serving geo-referenced map images over the internet that are generated by a map server. The specification was developed and first published by the Open Geospatial Consortium (OGC). WMS provides a way for different organisations to share graphical maps over the internet through specially constructed URLs.
A key concept of WMS is that of a layer representing a basic unit of geographical information that a WMS client can request as a map image from a WMS server. |
In the WMS transaction the client sends (HTTP) requests to the server which on return sends back the requested information to the client. The WMS standard defines several request types, two of which have to be supported by any WMS servers:
The Metview WMS client can perform both of these request types enabling users to perform the following actions:
The WMS standard defines different versions. Metview supports all the versions commonly used to date: 1.0, 1.1, 1.1.1 and 1.3.0.
For further information on WMS standards please turn to the official documents available at the OGC web site:
http://www.opengeospatial.org/standards
In this exercise we will build a WMS GetMap request for a Sea Surface Temperature layer from the NASA Earth Observations WMS server and visualise the resulting image in Metview.
WMS requests in Metview can be defined and executed by the WMS Client icon. You can find this icon in the icon drawer.
Create a new WMS Client icon in your ‘wms_tutorial’ folder (by dragging it into the folder). Rename it ‘NASA’ and open its editor (double-click or right-click,
Type in the following web address into the URL bar at the top of the interface:
http://neowms.sci.gsfc.nasa.gov/wms/wms
Now we will send the GetCapabilities request to this server by clicking on the button in the toolbar (hitting enter in the URL bar results in the same action).
This operation can take a while depending on the network traffic and the server load. If the server does not seem to reply the request can be interrupted any time by clicking on the button in the toolbar.
Please note that there is a log panel at the bottom of the editor displaying detailed information about the request sent to the server and indicates its status, as well. This panel can be hidden or shown by the toggle button in the toolbar. The statusbar, at the bottom of the interface, briefly indicates the status of the current operation.
If the GetCapabilities request was successful the editor is populated with the replied data.
The WMS client analyses the returned GetCapabilities document and displays the layers ( tab) and supported file formats ( combo box in the toolbar) on the left hand side. Formats that cannot be visualised in Metview are greyed out in the list.
The complete GetCapabilities document is shown on the right ( tab. This is intended for more expert users and can be used to debug GetCapabilities documents. The service provider’s meta-data ( tab) is also displayed on the right hand side.
Now browse the layer tree on the left hand side and select the sub-layer called
Sea Surface Temperature 1981-2006 (1 month - AVHRR) |
Then switch to the tab on the right hand side of the editor. This tab shows the properties of the selected layer. At first what you can see here is the meta-data:
On top of the meta-data various user-configurable map image generation parameters are shown here:
Now we will specify the date and time for our Sea Surface Temperature layer. Click on the tab on left hand side of the editor. This shows the user-settable layer properties. We already know CRS and Style from the previous step. On top of these we can see Time here. If we click on the extension button next to the label the available values will be listed.
Time is a predefined dimension in the WMS standards. Dimensions are optional layer properties and we will see how to work with them in Part 3 of this tutorial. At present it is enough to select the default value by clicking on item Default in the list.
Having specified the time we can generate a preview for the selected layer. Click on the button in the layer tab. Now Metview builds and sends a GetMap request to the server to acquire a map image for the layer using the specified CRS, style and time.
At the same time another request is sent to the server to generate a legend image for the given style (if it is available). Just like in the case of the GetCapabilities request, the requests sent to the server can be seen in the log panel area. When the server replies for these requests the resulting images are displayed in the tab.
Please note that the WMS client always uses the maximum bounding box of the given CRS to generate the preview image.
One of the main purposes of the WMS client editor is to automatically generate a GetMap request that, in the end, can be visualised in Metview. This GetMap request is kept continuously updated as we change our layer settings in the interface. To see this request just click on the tab in the right hand side of the editor.
If we are satisfied with our request we can save it by clicking on the button at the bottom left corner of the editor. With this action the GetMap request we generated together with some meta-data will be stored in our WMS Client icon. Please note that by closing the interface without clicking on we will lose all the settings we have made!
Save your settings (if you have not done so) then right-click on the icon and select . This will execute the GetMap request and visualise the resulting image in a Metview Display Window.
You can see here a similar image to the preview but this time it is overlaid with the Metview coastlines. By clicking on the ‘NASA’ layer in the tab (on the right hand side of the plot window) you will see the meta-data associated with the visualised WMS layer and the legend, as well.
Remarks:
To overlay a WMS map image with any other data just drag the icons representing the data into the plot. There are two icons prepared for you in the folder to try this out: the ‘coastlines_grey’ Coastlines icon and the ‘mslp’ GRIB icon. Simply drag them into the Display Window and see how the plot has been changed.
In the previous exercise we selected only one date for our Sea Surface Temperature layer. Now we will take a step forward and select multiple dates to generate a series of map images that can be visualised as an animation in Metview. We will continue to work in folder ‘wms_tutorial’.
The generation of multiple map images relies on the concept of WMS dimensions. Dimensions are optional layer attributes allowing the specification of date, time, elevation and other custom parameters. There are two predefined dimensions in the WMS standards: Time and Elevation. On top of these, layers can have other custom dimensions each starting with a DIM_ prefix (e.g. DIM_RUN, DIM_FORECAST).
Dimensions have a special role for the Metview WMS client: if multiple values are selected for a given dimension the client will generate a separate GetMap request, and thus, a separate map image for each of them. The result is a series of map images defining the animation frames for Metview.
Duplicate your ‘NASA’ WMS Client icon and rename the duplicate ‘NASA loop’. Edit it and select the tab on the left hand side. This panel lists all the dimensions of the selected layer. Here we can only see dimension Time because only this dimension is defined for the layer. Now click on the extension button next to the Time label to see all the possible values. What you can see here is as follows (apart from the default value):
1981-09-01/2006-12-01/P1M |
This expression defines a range of time values based on a special encoding (this is the extension of the ISO8601 standard). This expression reads as: dates from 1981-09-01 to 2006-12-01 by a one month step.
Now we will specify every month in 2006 to generate twelve map images for our animation. First we need to clear the current selection (by clicking on the clear button to the right of the text input area) and then type in the following text:
2006-01-01/2006-01-12/P1M |
Having done this the interface should look like as follows:
As mentioned above, by specifying twelve dates we generated twelve individual GetMap requests. To inspect these requests click on the tab in the right hand side of the editor.
We can see here that the requests are almost identical and the only difference is that Time is varying from one request to the other. Please note that for the sake of better readability the dimensions (in our case it is only Time) are always highlighted in a different colour (orange) to the other parameters in this list.
Save your settings (if you have not done so) then right-click on the icon and select . This will execute all the GetMap requests and visualise the resulting images in a Metview Display Window.
The plot looks like much the same as in Part 2 but since we have more than one image we can navigate through them by using the animation buttons in the toolbar or the in tab (on the right hand side of the window).
The list in the tab shows you the values of a set of meta-data keys for each animation frame (i.e. for each image). To see the key names just put the cursor into the column headings. The keys used here are basically GRIB API keys but WMS parameters are mapped to them (see the table below for details).
Frame keys can be grouped into ‘key profiles’. At the bottom of the tab there is a combo box to switch between the existing key profiles. To manage the key profiles (e.g. to add your own profiles) please try the Key profile manager dialog that can be launched by the button with a spanner icon next to the key profile selector combo box.
Remarks:
Layer name | shortName |
Date part of dimension TIME | date, dataDate, time.dataDate |
Time part of dimension TIME | time, dataTime, time.DataTime |
Date part of dimension DIM_RUN | date, dataDate, time.dataDate |
Date part of dimension DIM_RUN | time, dataTime, time.DataTime |
Dimension DIM_FORECAST | step, stepRange, time.stepRange |
Dimension ELEVATION | level, vertical.level |
The WMS client’s user interface offers two WMS request editing modes: an interactive and a plain mode. So far we have used the interactive mode and it provided us with a high-level user interface to set the parameters and build the request automatically whenever it is possible. However, occasionally there might be a need for changing some request parameters manually and this is exactly what the plain editing mode can be used for.
In folder ‘wms_tutorial’ duplicate your ‘NASA’ WMS Client icon and rename the duplicate ‘NASA plain’. Edit it and find the combo box in the bottom left corner of the user interface.
Now select option “Plain” from the combo box to enter the plain editing mode. You should see the following user interface:
The editable WMS request parameters are listed on the left hand side of the interface. Whenever you edit a parameter the WMS request displayed on the right hand side of the interface is immediately updated.
To demonstrate the editor’s capabilities we will change parameter Time by adding an another date to it. Now change parameter Time and type in the following text into its editor:
2006-11-01,2006-12-01 |
From Part 3 we know that the date we added (November 2006) is a valid date. We also know that Time is a WMS dimension so the specification of multiple values results in multiple map images. Thus you have just defined two WMS requests (i.e. two animation frames for Metview) as shown below:
Save your settings then right-click on the icon and select to see if your changes are really working. Having finished the visualisation close the icon editor.
Remarks:
Imagine a situation when you have an existing WMS request (as a text string) that you would like to visualise in Metview. The easiest way of doing it is to import the request into the WMS client as it will be demonstrated in this exercise.
In your 'wms_tutorial' folder you will find a Notes icon called ‘NASA topography request’. This icon contains a GetMap request to access a topography layer from the same NASA server as we used in the previous exercises. To see the request just open the icon’s editor (double-click or right-click,
Create a new WMS Client icon. Rename it ‘NASA topography’ and open its editor. Select ‘Import’ from the menu in the menu bar to start up the Import dialog. Now open your ‘NASA topography request’ icon’s editor (if you have not done so) then copy and paste the request into the Import dialog.
Having finished it just press the button to populate the WMS client user interface with the request parameters. Now preview the selected layer and visualise it (after saving the settings) then close the editor.
Remarks:
In this example we will write the macro equivalent of the exercise we solved in Part 2 to visualise our Sea Surface Temperature WMS layer with a Metview macro. We will work in folder 'wms_tutorial' again.
The implementation of WMS visualisation in Metview macro follows the same principles as in the interactive mode. In macro we work with the macro command equivalent of the WMS Client icon which is called wmsclient.
The quickest way to generate a macro is to simply save a visualisation on screen as a Macro icon. Visualise your ‘NASA’ WMS Client icon, drop the ‘coaslines_grey’ and ‘mslp’ icons into the plot and click on the macro icon in the tool bar of the Display Window.
Now a new Macro icon called 'MacroFrameworkN' is generated in your folder. Right-click this icon. Now you should see your original plot reproduced.
Please note that this macro is to be used primarily as a framework. Depending on the complexity of the plot macros generated in this way may not work as expected and in such cases you may need to fine-tune them manually. So, we will use an alternative way and write our macro in the macro editor.
Since we already have all the icons for our example we will not write the macro from scratch but instead we drop the icons into the Macro editor and just re-edit the automatically generated code.
Create a new Macro icon (it can be found in the icon drawer) and rename it 'step1'. When you open the Macro editor (right-click ) you can see that the first line contains #Metview Macro. Having this special comment in the first line helps Metview to identify the file as a macro, so we want to keep this comment in the first line.
Now position the cursor in the editor a few lines below the line of #Metview Macro. By doing so we specified the position where the icon-drop generated code will be placed. Then drop your 'NASA' WMS Client icon into the Macro editor. You should see something like this (after removing the comment lines starting with # Importing):
#Metview Macro
nasa = wmsclient(
server :"http://neowms.sci.gsfc.nasa.gov...",
version : "Default",
request : "http://neowms.sci.gsfc...",
extra_getcap_par : "",
extra_getmap_par : "",
http_user : "",
http_password : "",
layer_title : "Sea Surface Temperature …",
layer_description : "Sea surface …",
service_title : "NASA Earth …",
layer_legend : "http://neo.sci...",
time_dimensions : "TIME"
) |
You only have to add the following command to the macro to plot the result:
plot(nasa) |
Now, if you execute this macro (right-click or click on the button in the Macro editor) you should see a Display Window popping up with your WMS image.
Duplicate the 'step1' Macro icon (right-click and rename the duplicate 'step2'. In this step we will add our ‘coastlines_grey’ and ‘mslp’ icons to the macro.
Position the cursor above the plot command in the Macro editor and drop your 'coastlines_grey' icon into it. Repeat this with the 'mslp ' icon. Then modify the plot command by adding these new arguments after the nasa variable:
plot(nasa,coastlines_grey,mslp) |
Now, if you run this macro you should see your modified plot in the Display Window.