Many georeferenced images (satellite images, maps, etc.) can be obtained from Web mapping services and then used in a VAPOR scene to enhance geospatial understanding of the scene. A few such images are preloaded in VAPOR and are available in the Image tab. VAPOR also provides an application "getWMSImage.sh" that can be used to retrieve such images from Web mapping services.
getWMSImage.sh is a command-line tool for obtaining geo-referenced imagery from the Internet for use as base-map reference in VAPOR visualizations. It is implemented as a bash-shell script, and as such only operates in Unix environments (e.g. Linux, Mac OSX, Cygwin on Windows). The script is bundled with the VAPOR distribution, and makes use of tiff2geotiff, described in the next section. It is thus imperative that the VAPOR environment variables are correctly set by sourcing vapor-setup.csh or vapor-setup.sh in the shell in which you run this script. The Unix utilities wget or curl are also required, as is the convert utility from Imagemagick for some types of maps1. Imagemagick is needed when a particular WMS server does not support "tiff" image format, including all the map-types available in the default mode, except BMNG and Landsat. Note that you must have write-access to the current directory where temporary files will be downloaded from the WMS.
The script operates in either a default mode, or an expert mode. The default mode is intended to assist most users in acquiring typical base-map imagery. One chooses from a small set of predefined map-types, which includes NASA Blue Marble and Landsat imagery, maps of political boundaries, rivers, etc. For users who are knowledgeable on Web Mapping Services (WMS), expert mode can be used to acquire arbitrary imagery from any WMS-compliant server.
In either mode, one must first determine the latitude and longitude extents that are needed. Usually you will want to choose these large enough to contain the domain or all domains (with a moving nest) in the WRF dataset. There are several ways of determining these extents. One way is to look at the output of wrfvdfcreate. This output includes the min/max longitude and latitude at the corners of the data. This will usually be sufficient when the WRF is not near the north or south pole. If the WRF domain is a polar stereo projection that contains the north or south pole, then the rectangle should go from longitude -180 to longitude +180, and latitude range should include the polar latitude (+90 or -90). Another way to determine the extents is to load the data into the vaporgui application, and visualize the 2D WRF variables XLAT and XLON in the 2D visualizer. You can click on the image to find the value of these variables, and thereby determine what latitude and longitude values to include in the retrieved data.
Default Mode:
In default mode, the user chooses a base-map from a small set of predetermined map types. The script is invoked on the command-line as:
getWMSImage.sh {optional parameters} minLon minLat maxLon maxLat
where minLon, minLat, maxLon, maxLat are the bounding box values for the area-of-interest, in units of decimal degrees. Longitudinal values must be in the range [-180...180], while latitudinal values should range from [-90...89.9999]. By default, the requested map will be for NASA Blue Marble at an image size of 1024x768 pixels, downloaded to a file named "BMNG.tiff". Several optional command-line switches can override the default behavior:
-m map_name Where map_name is one of the following (case-sensitive):
-r xres yres
Change the map resolution; default is 1048x768
-o imageFileName
Change the name of the resulting filename; default is map_name.tiff
-t Requests a transparent background
Expert Mode:
Expert mode is intended for using the script to fetch an image from any OGC-compliant WMS server. As such, one must be highly knowledgeable about WMS technology and protocol. Generally this means knowing how to acquire and interpret the so-called "GetCapabilities" document from a server, from which to determine the URL for a "GetMap" request, the layer names that are available, and the image-formats the server supports. Details of this are beyond the scope of this document; consult the WMS specification at the Open Geospatial Consortium's website (http://www.opengeospatial.org/standards/wms).
Expert mode adds the following command-line options to those of the default mode; the first three options are to be used in lieu of the -m map_name option:
-s URL
The URL of the WMS service
-l layername
The name of the requested layer
-f format
The format for the requested image, as advertised by the server
-o imageFilename
Change the name of the requested image file; default is layername.tiff
-z Requests that the resultant image should be compressed
-d Debug mode; does not delete temporary/intermediate files
Examples:
To request an image of US counties for the US (latitudes 25 to 50, longitudes -125 to -64) issue the command:
getWMSImage.sh –m USCounties -125 25 -64 50
It is worth noting that the predefined map-types in the default mode are effectively implemented via expert-mode parameters, and thus provide examples of expert mode use. For example, the map-type UScounties is a request to a USGS site, for two specific layers (states and county boundaries; ordering is important), of an image-format supported by that site. A comparable request on the command-line, using expert options, would look like:
getWMSImage.sh -s \ http://imsref.cr.usgs.gov:80/wmsconnector/com.esri.wms.Esrimap/USGS_EDC_...\ -l ATLAS_STATES_150,ATLAS_COUNTIES_2000 -f image/png -o UScounties.tiff -125 25 -64 50
