This page describes how to use NCL scripts to create plots of WRF data that can be displayed in VAPOR scenes. Cindy Bruyere has provided an NCL library (WRFUserARW.ncl) and numerous scripts to facilitate plotting WRF data with NCL. These scripts (which we shall call WRF-NCL scripts) can be modified to produce geo-referenced TIFF files (geotiffs), which can be read by VAPOR. Many example scripts are found at http://www.mmm.ucar.edu/wrf/OnLineTutorial/Graphics/NCL/NCL_examples.htm . For more information about these scripts refer to the NCL WRF documentation.
To illustrate these methods, there is an on-line tutorial on the VAPOR website, entitled “Using NCL with VAPOR to Visualize WRF-ARW data.” That document shows in detail how three different NCL scripts can be converted to geotiffs and displayed in VAPOR.
The conversion process involves modifying a WRF-NCL script to generate a geo-referenced TIFF (geoTiff) file of the plots, which can then be incorporated into a VAPOR visualization session. The process generally involves making minor modifications at three key points in the script: after opening the NCL 'workstation', after creating the plot that is to be captured, and before exiting the script. There are two additional constraints: the workstation type must be postscript, and frame-advance between plots must be explicitly managed.
Note that you should only produce one plot for each time step of the data. If your NCL script produces multiple plots for each time step, it should be modified to only produce one of the plots at each time step. You can visualize multiple images in the vapor scene at the same time step; however, these images need to be in different geoTiff files. To visualize multiple plots per time step, you can make multiple geoTiffs, by using several NCL scripts, one for each of the different plots.
When the NCL plots are horizontal, mapped to the WRF domain, then the resulting geoTiff images will be aligned to match the geo-referencing when shown in VAPOR. However, if the plot is vertical, it will not be geo-referenced, and it must be aligned in the VAPOR GUI 2DData panel by the user to correctly fit in the coordinates of the domain.
Four sample NCL scripts are provided in the VAPOR distribution, in the directory $VAPOR_HOME/share/examples/NCL. (On Mac these are found in $VAPOR_HOME/Contents/SharedSupport/examples/NCL). These scripts are wrf_cloud.ncl, wrf_EtaLevels.ncl, wrf_pv.ncl and wrf_surface.ncl, and are modifications of scripts of the same names provided on the NCL-WRF example web page noted above. To use these scripts, you will need to edit them, to change the names of the wrf output files that are specified in the scripts.
Note that for wrf2geotiff.ncl to work correctly, you must have the file “.hluresfile” in your Unix home directory. A sample file is at http://www.ncl.ucar.edu/Document/Graphics/hlures.shtml .
Overview:
A typical WRF-NCL script for plotting WRF data is of the general form:
; load supporting libraries
load "..."
; open WRF files...
...
; open workstation
wks = gsn_open_wks("ps", "wrfPlot")
; set up resources, generate contours, etc.
...
; overlay the plot on a map
plot = wrf_map_overlay(wrfFile, wks, (/contour/), pltres, mapres)
It is also common to see the plot-generation code segment inside a loop over time or over a collection of files:
; loop over each timestamp do i=0, numTimes-1
...
plot = wrf_map_overlays(......)
end do
Modifying scripts for geotiff output:
The script below shows the previous example template, modified to generate a geotiff file; the new lines of code are shown in color. The key points to note are: i) inclusion of the wrf2geotiff library, ii) opening the geotiff output process, iii) setting resources for explicit frame advance, iv) writing each plot to the geotiff output process, and v) closing the geotiff output process. Note that in opening the geotiff output process, an opaque variable is created that should be passed to other calls to the wrf2geotiff library. The full wrf2geotiff library and the meaning of parameters passed to the functions follows below.
; load supporting libraries
load "..."
; NOTE 1: On Windows, the file wrf2geotiff.ncl is located in
; $VAPOR_HOME/share/examples/NCL/.
; However, if the path to $VAPOR_HOME contains blank characters,
; you should copy the file wrf2geotiff.ncl to another directory
; and load it from that directory in the load statement below.
; NCL will not correctly handle blanks in directory names.
; NOTE 2: On Mac, the file wrf2geotiff.ncl is located in
; $VAPOR_HOME/Contents/SharedSupport/examples/NCL, which is by default at
; /Applications/VAPOR/VAPOR.app/Contents/SharedSupport/examples/NCL
;
; load the wrf2geotiff library:
load "$VAPOR_HOME/share/examples/NCL/wrf2geotiff.ncl"
; open WRF files... ...
; open workstation
wks = gsn_open_wks("ps", "wrfPlot")
; following must be performed once, after opening a workstation but before plots are generated.
; It creates an opaque object that is passed to other wrf2geotiff functions.
wrf2gtiff = wrf2geotiff_open(wks)
...
; IMPORTANT! You must explicitly manage frame-advance.
; Here we modify the resource that gets passed to wrf_map_overlays below
pltres = True
pltres@FramePlot = False ; we'll make frame advance below
; loop over each timestamp
do i=0, numTimes-1
...
plot = wrf_map_overlays(......)
; write the plot just created and advance the frame...
wrf2geotiff_write(wrf2gtiff, wrfFile, times(it), wks, plot, True)
frame(wks) ; frame-advance
end do
; close the geotiff file...
wrf2geotiff(wrf2gtiff, wks)
The wrf2geotiff library:
wrf2geotiff_open(wks):
Called once to open a geotiff file for writing. The name of the geotiff file will be the same as the output file of the workstation, except with a suffix of .gtif.
Parameters:
wks the workstation object
Returns: An opaque object that is passed to subsequent wrf2geotiff functions.
wrf2geotiff_write(wrf2gtif, wrfFile, timeStamp, wks, plotObject, cropped):
Called for each plot that is to be written to the geotiff file.
Parameters:
wrf2gtif: the opaque object created by the call to wrf2geotiff_open()
wrfFile: the WRF input file used to generate the plot; used here to extract georeferencing information
timeStamp: a timestamp string, typically obtained from the WRF file.
wks: the workstation object
plotObject: the plot object to be written
cropped: a boolean indicating whether the plot should be cropped at the plot frame. Setting this to false causes the plot and its surrounding labeling/annotations to be written into the geotiff.
Returns: Nothing
wrf2geotiff_close(wrf2gtiff, wks):
Called once after all output has been written to workstation. This call has the side-effect of closing and flushing all pending operations on the workstation, such that any subsequent attempts to use the workstation will be undefined.
Parameters:
wrf2gtif the opaque object created by the call to wrf2geotiff_open()
wks the workstation object
Returns: Nothing
Advanced functions:
wrf2geotiff_setOutputScale(wrf2gtif, scaleFactor):
By default, images in the geotiff are of the same size, in pixels, as the postscript page when rasterized. This function can be used to scale the images to something smaller or larger. Applies to the entire collection of plots, and if called more than once, the scaleFactor of the last plot is what is used.
Parameters:
wrf2gtif: the opaque object created by the call to wrf2geotiff_open()
scaleFactor: a multiplier for the image size
Returns: Nothing
wrf2geotiff_disableGeoTags(wrf2gtif, scaleFactor):
Vapor automatically positions geotiff images into a scene. But it can also allow a user to interactively position images that are not georeferenced. In particular, plots of WRF data that are vertical cross-sections have nonsensical geo-coordinates (a non-zero area is required). Calling this function prevents geotiff tags from being written to the tiff file. As the timestamps are still written into the tiff file, the user can place the image interactively and Vapor can animate it through time.
Parameters: wrf2gtif: the opaque object created by the call to wrf2geotiff_open()
Returns: Nothing
Usage Notes:
required external programs: psplit, convert, tiff2geotiff
These external programs must be available and visible via the user's PATH environment variable. psplit is distributed with NCL, and tiff2geotiff is part of the VAPOR distribution. convert is part of the ImageMagick suite of image processing tools, which is commonly part of most Linux distributions, and is freely downloadable from the Web.
Space requirements:
The conversion to geotiff creates various intermediate files. These are written to the /tmp directory, and they are generally removed after use. Depending upon the size of the resultant geotiff, a fair amount of temporary disk space can be required. Experiments with Hurricane Ike simulation data have resulted in geotiffs of several hundred megabytes, for an image composed of 100+ frames/timesteps. The amount of required temporary space is comparable to the size of the resultant geotiff file.
Future Plans:
Ultimately it is preferable to generate geotiff output directly from NCL. Efforts are currently underway in NCL's development that will facilitate this. Such a capability will eliminate much, if not the entire requirement to modify scripts in the manner described herein.
