WXP version 5
User's Guide

Scripting, Overlays and Animations

The resource interface to WXP makes it ideal for use within scripts.  There are three main uses of the command line interface: generating overlays and loops, generating GIF images and Graphical User Interfaces (GUIs).

Overlays and Loops

Using Individual Programs
Most WXP programs can produce overlays and loops just as long as it is from the same data type.  In other words, a surface plotting program can plot temperatures and overlay a contour of pressure as well as loop them over several hours.

   sfcwx -cu=la -re=mw -va="temp,pres[:ln:in=4:co=lred]" -nh=-5 -de=d
sfcover.gif (19356 bytes)

The variable setting of "-va=temp,pres[:ln:in=4:co=lred]" first plots temperature and then overlays a line contour of pressure in light red at an interval of 4 mb.  The num_hour setting "-nh=-5" will generate a loop of 6 images containing the latest hour and the previous 5 hours.

Using wxploop and loopset
The surface plotting program cannot overlay a surface contour on a satellite picture. In order to do this, wxploop must be used. This can be done manually using wxploop, xsat, and sfccalc but it is easier to write it into a script. Wxploop acts as a canvas to accept graphics commands from xsat and sfccalc. When wxploop is run in batch mode, the window ID information is written to standard output which is then captured in the wxpdevice environment variable for use by the WXP graphics programs. In most cases, WXP graphics are non-destructive. This means a data plot or line contour will overlay on a satellite image or contour plot easily (see image below). If the overlay is a color fill contour plot or satellite image, it will cover the underlying image. For a satellite image, there is the ability to specify an overlay (-pp=over) along with an appropriate enhancement scheme which blacks out parts of the image that are supposed to be transparent. The xsat program uses the color "black" as a transparent color. For color fill contours, there are fill patterns which allow the background to show through. There is the ability to turn off certain color levels by specifying "off" for a color fill color. For overlay maps, again, there is a transparent color which defaults to black. Also, it is critical to control plot labels. The text above and below the plot will overlap making them impossible to read so the draw resource must be used to toggle text labels off. To tailor plot labels, use the label resource or mapplt.

#! /bin/csh -f
# Set up device to hold output of wxploop which is window ID
setenv wxpdevice w,,`wxploop -wn=-1 -ba -ti=overlay -ct=sat.clr,wxp.clr`
# Run xsat to display satellite data
xsat -cu=la -if=sat_ir -re=us
# Run sfccalc to overlay contours.  Notice the use of draw (dr) set to data
# so that only the contours are displayed.  Notice the use of color_cont (coco)
# to change the color of the line contours to light red
sfccalc -cu=la -re=us -va=pres -in=2 -pl=ln -dr=data -coco=lred -pp=gridx2 -oa=4,8
satover.gif (118799 bytes)      

Another method is to save the window information to a file. The window number in wxploop is actually a filename. Then the window information part of the device resource is the same filename. This is useful for Windows users since Win32 prevents use of standard output.

#! /bin/csh -f
# Save window ID to file /tmp/win
wxploop -wn=/tmp/win -ba -ti=overlay -ct=sat.clr,wxp.clr
setenv wxpdevice w,,/tmp/win
# Run xsat to display satellite data
xsat -cu=la -if=sat_ir -re=us
# Run sfccalc to overlay contours.  Notice the use of draw (dr) set to data
# so that only the contours are displayed.  Notice the use of color_cont (coco)
# to change the color of the line contours to light red
sfccalc -cu=la -re=us -va=pres -in=2 -pl=ln -dr=data -coco=lred -pp=gridx2 \
  -oa=4,8

To create a loop, put a loop into the script. There are some other changes to be made. First, the frames in the loop (called pixmaps) need to be created. This uses the loopset command to communicate with wxploop through a message queue. Creating a message queue adds some overhead into the script. Wxploop won't run if the message queue exists. To solve this problem, "loopset -wn=1 clean" could be run to delete the queue or "loopset alloc" could be run to return the first available message queue. When wxploop terminates, the queue is deleted but sometimes wxploop terminates abnormally leaving the queue.

The next item is to run loopset to create the pixmap and return the window information as before. Once the pixmap is created, it becomes the canvas that the graphics programs use. Wxploop then loops through each of the pixmap to create the loop.

NOTE: Queues are not implemented in Windows/Win32.

#! /bin/csh -f
# Set up device to hold output of wxploop which is window ID
wxploop -wn=1 -ba -ti=overlay -ct=sat.clr,wxp.clr
# Loop over hours
foreach hour ( 6 5 4 3 2 1 0 )
   setenv wxpdevice w,,`loopset -wn=1 cr pix`
# Run xsat to display satellite data
   xsat -cu=$hour -if=sat_ir -re=us
# Run sfccalc to overlay contours.  Notice the use of draw (dr) set to data
# so that only the contours are displayed.  Notice the use of color_cont (coco)
# to change the color of the line contours to light red
   sfccalc -cu=$hour -re=us -va=pres -in=2 -pl=ln -dr=data -coco=lred \
      -pp=gridx2 -oa=4,8
end

Using wxploop in Windows/Win32
This is possible but not easy to implement. First, Win32 eliminates standard output so the window information must be written to a file. Also, queues are not implemented in Win32 so this eliminates the ability to use loopset to tell wxploop to create a new pixmap. Third, graphics programs are automatically backgrounded in batch files so xsat and sfccalc would run simultaneously and the resulting product would be unusable. A possible solution is to put a sleep command in the batch file to slow down the process. Another solution is to use a different shell like Korn shell which is available from some software vendors.

#! /bin/ksh -f
# Save window ID to file
wxploop -wn=/tmp/win -ba -ti=loop -ct=sat.clr,wxp.clr
setenv wxpdevice w,,/tmp/win
for hour in 6 5 4 3 2 1 0 ; do
# Display satellite data, use new window command to create new pixmap
   xsat -cu=la -if=sat_ir -re=us -pp=new
# Run sfccalc to overlay contours.  Notice the use of draw (dr) set to data
# so that only the contours are displayed.  Notice the use of color_cont (coco)
# to change the color of the line contours to light red
   sfccalc -cu=la -re=us -va=pres -in=2 -pl=ln -dr=data -coco=lred -pp=gridx2 \
     -oa=4,8
done

Complicated Overlays
These overlay scripts can be rather complicated overlaying more than just two products. This requires more annotation and control over the output. First, common resource values should be set as environment variables. This gives the script a single point to change these parameters and also reduces what is needed on the command line of each program. Second, labels need to be generated using wxpfile to describe the plotted data. Once specialized labels are set, only the data needs to be plotted "-dr=data" from each graphics program. The map is generated at the appropriate time with mapplt. Once the plot is done, mapplt is called to put the specialized labels on the plot.

#! /bin/csh -f
# Preset common resources
setenv wxpgeometry 900x650
setenv wxpcurrent la
setenv wxpmessage print
setenv wxpregion us
# Open up a WXPloop window with size 900x650, title it SFC_Map,
# lock in colors from wxpcolor, and setup the return key to close the window 
# WXPloop returns the window ID which is set to the dev shell variable
setenv wxpdevice w,,`wxploop -ba -wn=-1 -ct=sat.clr,wxp.clr -ti=SFC_Map`
# Generate a label for the plot with wxpfile
set label=`wxpfile -if=sfc_cvt -ou=date`
# Generate a label for the frontal data based on the latest front file time
set frtlabel=`wxpfile -if=frt_dat -ou=hour`
# Plot a IR satellite picture
xsat -dr=data -if=sat_ir
# Plot a stippled radar summary
rad -dr=sum -pp=bar,fill:1 -va=sum -com=red 
# Overlay a map
mapplt -dr=map
# Plot the fronts using sfcwx and adjust the colors
sfcwx -if=front -dr=data -cofr=lblue:w3,lred:w3,lblue,lred,lmagenta
# Plot isobars with twice the gridpoints for a smoother plot, used priority 3
# stations and filter/smoothing parameter of 5, radius of influence of 7, no
# contour labels
sfccalc -pr=3 -oa=4,8 -dr=data -va=pres -coco=blue -pp=gridx2,lab:0 -in=4 -pl=ln
# Plot surface data for priority 1 stations
sfcwx -dr=data -pr=1 -va=all 
# Use mapplt to plot labels on map
mapplt -dr=text "uc:Surface data plot for $label" "lr:Fronts at $frtlabel"
satsfcmap.gif (223615 bytes)

The keys to a good overlay plot is to:

Generating GIF Images

A nice feature of WXP is the integrated GIF file generator.  If a image dump is needed from an overlay graphic, it can be accomplish by one of two methods:

mapplt -dr=text -pp=gif:sfc_map.gif \
   "uc:Surface data plot for $label" "lr:Fronts at $frtlabel"

This can be used to dump GIF files from programs not in a script.

wxploop -ba -ge=900x650 -ct=wxp.clr -ti=SFC_Map
set pixid=`loopset -me=print cr pix`
# Graphics commands
...
# Direct wxploop to save window to file
loopset save 0 sfc_map.gif
# Close the window
loopset kill

It is possible for a single script to generate more than one image. This is preferred since the overhead of starting and stopping wxploop can be expensive. At the end of each plot, the window/pixmap must be cleared so that the next image can be generated.

wxploop -ba -wn=/tmp/win
setenv wxpdevice w,,/tmp/win
# Graphics commands
…
progx -pp=gif:plot1.gif 
prog1 -pp=clear
# Graphics commands
…
progx -pp=gif:plotx.gif,kill
setenv wxpwindow_num xx
wxploop -ba -ge=900x650 -ct=wxp.clr -ti=SFC_Map
set pixid=`loopset que win`
# Graphics commands
…
loopset save 0 plot1.gif
loopset clear
# Graphics commands
…
loopset save 0 plotx.gif
loopset kill

Automating GIF Generation

These scripts can now be run automatically using cron to generate images for local use of for a web server. Here are some recommendations:

Create a list of scripts and add them to the cronfile:

35 * * * * /home/wxp/scripts/sfc_map

Use of Scripting with Graphical User Interfaces

Even though WXP does not come with a graphical user interface (GUI), its command line and scripting capabilities makes it ideal to link with an external GUI.  Many GUI programs such as Tcl/Tk are capable of generating command lines that can be used by WXP.   Obviously, the number of options that WXP has would make it difficult to ideally use WXP from a GUI, a GUI can be used to quickly test various options to tailor a plot.   The resulting command line or script can be saved to a file for future use. 

Scripting and Postscript Overlay

The Postscript interface allows overlays for printing output by using the append option to the postscript device specification. In general, any overlay product can be printed by replacing the window device parameters with an appropriate append print option. Here is a sample script:

#! /bin/csh -f
# Set up device for Postscript append, remove file first
rm wxp.ps
# Run sfcwx to display surface data
sfcwx -cu -re=mw -va=all -de=p,+wxp.ps
# Run sfccalc to overlay contours.
sfccalc -cu -re=mw -va=st -in=5 -pl=ln -dr=data -coco=lblue -de=p,+wxp.ps
# Run pscat to place header and trailer info on file and send to printer
pscat wxp.ps

The append option for Postscript will eliminate the header (setup and macro definition) and trailer (showpage).  Postscript then allows the second program to overlay its graphics upon the first programs graphics.  The pscat program is used to put the header and trailer on the file making it ready for printing.  If the wxpps_print environment variable is set, the output can be spooled directly to the printer:

   setenv wxpps_print '|lp -dps'

Scripting and HPGL Overlay

The HPGL interface is nearly identical to that of the postscript interface except it produces PCL5 output compatible with most modern HP laserprinters and plotters.  This is especially handy for printing to HP's wide bed plotters (2x3 foot output).  Here is a sample script:

#! /bin/csh -f
# Set up device for HPGL append, remove file first
rm wxp.hpgl
# Run sfcwx to display surface data
sfcwx -cu -re=mw -va=all -de=h,+wxp.hpgl
# Run sfccalc to overlay contours.
sfccalc -cu -re=mw -va=st -in=5 -pl=ln -dr=data -coco=lblue -de=h,+wxp.hpgl
# Run pscat to place header and trailer info on file and send to printer
hpglcat wxp.hpgl

The append option for HPGL will eliminate the header (setup and macro definition) and trailer (reset).  The hpglcat program is used to put the header and trailer on the file making it ready for printing.  If the wxphp_out environment variable is set, the output can be spooled directly to the printer:

   setenv wxphp_out '|lp -dhp'

Looping using animated GIFs

When developing a loop for a web server, it is possible to take pregenerated GIF images and concatenate them together.  This can be done with the gifcat program:

gifcat -s -o eta_pres_loop.gif \
   eta_pres_init.gif eta_pres_6h.gif eta_pres_12h.gif eta_pres_18h.gif \
   eta_pres_24h.gif eta_pres_30h.gif eta_pres_36h.gif eta_pres_42h.gif \
   eta_pres_48h.gif 

Last updated July 21, 1998