WXP - The Weather Processor

Version 6

What is WXP 6?

WXP version 6 is a complete rewrite of WXP in C++ converting the WXP library into a set of objects (almost 300). In additiona, WXP 6 can be used by accessing the API from C++, Perl and Python.

What is different in WXP 6

There are a lot of differences in WXP but many of the core items work very close to their WXP 4 and 5 equivalents.

WXP 6 is not interactive. There are no menus and prompts to set parameters when you run the programs. It's the equivalent of running WXP 5 in batch mode. This minimizes command lines when in a lot of cases the defaults can be used. There are interactive features in the graphical interface through the Figure object which is used by most graphics programs.
WXP 6 has no shell program and utility programs like wchill and stdatms will not be part of the package.
WXP 6 programs are named for the objects they invoke. So "sfcplot" invokes the "SfcPlot" object. This cleans up the naming of programs. Also, there is no need for a "sfcwx" and "sfccalc" in WXP 6. The "-pl" will turn on contouring if needed. WXP 6 eliminates overlays in programs. So "sfcplot" will not plot fronts (see frontplot) and "radplot" will not plot watches (see watchplot). Overlays are now done with the "plot" and "figure" programs (see below).
The use of resources is essentially the same as in WXP 5 with the following augmentations:

The default name for the resource file is "wxp.cfg" but ".wxpdef" and "Wxp.res" can also be used.
There are default locations for the resource file. If you put the resource file in "/home/wxp/etc" or in "/usr/local/wxp/etc", WXP 6 will find the resource file without having to set the "wxpdefault" environment variable.
There are user defined resources. In WXP 5, only those predefined in the resource list were available. These predefined resources had command line shorthands and environment variables defined. In WXP 6, user defined resources can be specified in the resource file and on the command line (in API as well). Some resources like color resources can be specified with "res=new_resrc" and that value can be specified as "prog.new_resrc: value" in the resource file or as "-new_resrc=value" on the command line. This also works in the name conventions with the "%{new_resrc}" specification.
The path resources now allow multiple directories separated by ":". WXP 6 will search each directory in order to find the file. So you could specify

*data_path: /mnt/noaaport/nwstg/data:/home/wxp/nwstg/data

and if there was no file available in the first directory, it would search the second and so on to find a file. The first directory is always used for output.
The "V6" condition can be used in the resource file to isolate WXP 6 resources. Just put a "IF V6" line before the WXP 6 resources, then and "ELSE" and the WXP 5 resources and an "END". This uses the same conditional processing in WXP 5 but V6 is a special condition for V6 parameters.
There are a lot of new resources available, many of which were only available with the plot_param in WXP 5. Also several color resources such as color_wx and color_wind are now ignored.

Database files:

Map files - WXP 6 finally use the lat/lon range parameters in the map files. This speeds up map plotting by not plotting map segments not in the domain.
Map Database files - The map database file (.mdb) lists a description of each element in the map file such as the bounding states or the name of a river, highway or national park. The index integer at the end of the header line of the map file is now used as an index into a map database file. The DLG maps are being updated to use this feature.
Map Lists - WXP 6 will sense if a map list is specified on the "-mf" parameter if the file has a ".mpl" extension. There is no need for "fi:maplistfile" any more.
Color Table files - WXP 6 ignore any leading color index value. However color names must be unique.
Color Fill files - WXP 6 add the "@description" and "@value" parameters. The "@description" replaces the enhancement name in the ".enh" files. The "@value" line specifies that the indices listed in the file are values. In WXP 5, you had to specify "c-5" for a temperature value in an enhancement file. This replaces that feature forcing satellite enhancements to treat the line "-40:lgreen" as -40C. The eliminates the need for the ".enh" files.

Variable files - WXP 6 has several changes to the variable files. First the menu flag value can only be a 0 or 1. There are no options for menus. Also, parameters inside the [] must be separated by ",". So a WXP 5 line:

depict Weather_Depiction     le=sfc :sfc:depict{\
                                         fr         [:cf:lab=0:cof=depict.cfl],\
                                         map        [co=red],\
                                         cldcv      [:cloud],\
                                         cldcl      [:data:lc],\
                                         wx         [:wx:cl]}

would be this in WXP 6:

depict Weather_Depiction     1 :sfc:depict{\
                                         fr         [,cf,lab=0,cof=depict.cfl],\
                                         map        [co=red],\
                                         cldcv      [,cloud,co=white],\
                                         cldcl      [,data,lc,co=white],\
                                         wx         [,wx,cl,co=yellow]}

Font lists - WXP 6 allows for scalable X11 fonts. To specify scalable, surround the size parameter with {}. The number inside the braces will be the default size. If you specify -cot=white:hi=.5, it will scale the fonts.
```
helv    #-adobe-helvetica-bold-r-normal-*-{24}-*-*-*-*-*-*-*
```

Name Conventions:

Convention tags can be added to the end of the naming convention line.
```
grib_nam      %M/%y%m%d%6h_nam.grb       %M/%y%m%d%6h_nam.hdr      grib min=420
sat_ir_ec     %S/%y%m%d%h%15n_geci11.sat -                     850000,giniz min=45
nids          %{nids_path}/%i/%y%m%d%h%n_%e.nid   -                nids min=12
```
So the line goes: tag, name convention, header file convention, file type, parameter. By specifying the file type here, it eliminates the need to use the "-in" parameter since WXP 6 will know what type of file to use based on the name convention. The type can be prepended by a minimum size for latest file consideration (for backward compatibility with WXP 5). The parameter section adds other information to be used by WXP 6. The "min=420" tells WXP 6 that you have to go back at least 420 minutes (7 hours) to consider a file current. This is used by programs to match times in overlays (see below).
The name convention allows user defined resources to be specified:
```
nldn          %{nldn_path}/%y%m%d%h%n.nldn  -   noaa
```
This means the user defined path can be listed in the resource file as "*nldn_path" or on the command line as "-nldn_path". This eliminates the need for weird paths such as "watch_path".
Multiple paths can be specified:
```
*model_path: /mnt/noaaport/nwstg/model:/mnt/noaaport/nwstg2/model:/home/wxp/nwstg/model
```
The paths will be searched in order to find an available file. The first path is always used for output files.

Plot Domains:

Ellipsoidal earth can be specified:
```
sat:e:0:-75::1:,0.5,-74.9,1024,1024,0.1266,0.147
```
The ":e" specifies to use an ellipsoidal earth rather than spherical.
Angular projections can be specified. If the 4th parameter to the satellite projection is "1", then the projection plane is radians rather than X/Y. This is needed for certain satellite projections.
There is no need to put "id:" before a station identifier. WXP 6 will sense if a 4 letter station identifier is being specified "-pd=KORD,.4".

Image changes

Valued images - WXP 6 adds a set of values to images. In WXP 5, images had pixel values (0-255). In WXP 6 values can be applied to each pixel value. This is used for IR temperatures in satellite images and dBZ values on radar mosaics. This means color_fill parameters can be based on the values in the image and not pixel values (nice for radar mosaics... see @values in color_fill).
Cutoff values in image file - In WXP 5, cutoff values had to be specified in xsat to prevent unwanted interpixel interpolation (see winter mosaics). In WXP 6, the cutoff values can be put into the image file, eliminating the need to specify (or guess) the cutoff values on the command line.
Georeferenced images - WXP 6 will interpret comments in the GIF and PNG files. To georeference an image, add a WXP plot domain specification into the comments of the image. For example "pd=ll,0,0,360,180,1,1". You can enter this in an image manipulation program such as Gimp. The nx,ny parameteres MUST specify the image size in pixels (width,height). So in this example, the image was 360x180 pixels. What this does is allow the user to create a generic background map and include it in the plot. One way of doing this is with the map_file resource:
```
sfcplot -pd=ne -mf=-us_relief1.gif,wxp.map
```
This tells WXP6 to plot a US relief map as a background. If the image is georeferenced, WXP 6 will automatically remap the image to the plot domain. This eliminates creating tons of background maps.
Model masking - WXP 6 allows satellite images to be masked by a forecast model output:
```
satplot -mm=ruc,init:2m_ag:temp:C,-10
```
The first parameter is the model to use. The second parameter is the field to use as the mask grid. The last parameter is a fudge factor to be applied to the grid before masking. The satellite image MUST be valued for this to work. GINI images from NOAAPORT are valued by default. The satplot program will allow the user to apply a calibration to the image if one is not directly determined from the input image.

Data Plotting

Data information labels will have brackets for units "Temperature [F]". This is one simple way to tell this is a WXP 6 plot.
There is no rubber band zoom. Using "Alt-z" will do a 2x zoom at the cursor. A "Alt-Z" (alt shift Z) will do an unzoom at the cursor location. A "Alt-u" will go back to the original plot domain.
There is a pan feature using "Alt-p".
To save a GIF image, use "Alt-s". To save a PNG file, use "Alt-S".

Overlays and Looping - The awkward wxploop program in WXP 5 has been replaced by two programs: plot and figure. The plot program is really aimed at generating plots for web sites. It has limited interactive features but adds functionality on the command line to tailor plot output. The figure program is set up to act much like WXP 5 programs with looping, interaction, etc. Both program have intelligence to anchor time for each overlay. The time is determined from the first available plot and then that time is used to select data for the other plots in the overlay. The default is to use the file that matches the time given to it but the "min=" option can be added to the name convention file to search back a specific number of minutes to find a matching time.
API - The key addition to WXP in version 6 is access to the underlying library. WXP 6 was written in C++ with everything contained in objects rather than library routines. Most of the WXP objects and methods within those objects are accessible from both Perl and Python interfaces.

From Perl:

# Import WXP module
use WXP;

# Initialize WXP
WXP::Prog::readResrcFile( "script" );

# Create and initialize an object
$domain = new WXP::Domain;
$sat = new WXP::SatPlot( "nc=sat_ir_nc,ct=sat.clr,cof=0-50" );
$dplot = new WXP::DatumPlot;
$date = new WXP::Date;
$grid = new WXP::Grid;

# Use a static library
WXP::DomainTool::decode( $domain, "us" );

# Draw something
$plot = new WXP::Plot;
$plot->setDomain( $domain );
$sat->draw( $plot );
$plot->setLineColor( "red" );
$plot->drawLine( 10, 25, 15, 40 );

# Use WXP constants
$dplot->draw( $plot, 40, -75, WXP::Datum::MARK, "+", "co=lcyan" );

From Python:
```
# Import WXP module
import WXP

# Initialize WXP
WXP.Prog.readResrcFile( "script" )

# Create and initialize an object
domain = WXP.Domain()
sat = WXP.SatPlot( "nc=sat_ir_nc,ct=sat.clr,cof=0-50" )
dplot = WXP.DatumPlot()
date = WXP.Date()
grid = WXP.Grid()

# Use a static library
WXP.DomainTool.decode( domain, "us" )

# Draw something
plot = WXP.Plot()
plot.setDomain( domain )
sat.draw( plot )
plot.setLineColor( "red" )
plot.drawLine( 10, 25, 15, 40 )

# Use WXP constants
dplot.draw( plot, 40, -75, WXP.Datum.MARK, "+", "co=lcyan" )
```
The advantage of the API is that you can create objects and work with them independent of a WXP program. This give you more flexibility than just using a program. For example, you can read in a grid from a forecast model and do a set of post processing on it. If this were done in a script using a WXP program, the grid would have to be read in each time. Also, the API gives you more access to graphical functions for annotating plots. It gives you the ability to conditionally generate plots based on the availability of data above and beyond the capabilities of a program.