Wxploop And Loopset Part 2: Display and Animation

Introduction
Opening A Wxploop Window
Creating A Simple Script
Wxploop Window
Wxploop Pixmap
Displaying An Image In A Wxploop Window
Overlays Using The Window ID
Multiple Plots In A Single Wxploop Window
Displaying Loops With Wxploop (Animation)
Some Interesting Shortcuts
Ideas To Explore Further

Overall Tutorials Table Of Contents

1. Introduction

The previous tutorial deals with opening a wxploop window and discusses how to communicate with a wxploop process using the program loopset.

This builds on the basic wxploop commands introduced in the previous tutorial, but concentrates on getting multiple plots as overlays, and in creating loops for animation. We will construct a script to run a display loop for animation. The script will use the C-Shell. A good reference for the C-Shell is:

The Unix C Shell Field Guide

Gail Anderson, Paul Anderson (1986)

Prentice Hall, Englewood Cliffs, NJ 07632

ISBN 0-13-937468-X

Before starting this tutorial, there are a few things to know. You will need to know where the data is stored at your site, and how to set your UDRESPATH environment variable. It would help to be familiar with the resources that are held in the site Wxp.res file, and in how to use the WXP Interactive Shell. Knowledge of using WXP programs from the command line will be required. Simple C-shell programming to make a script will be required along with a basic understanding of wxploop and loopset. These points are covered in previous tutorials:

If the WXP software resides on a remote machine, you should set your DISPLAY environment variable to your current terminal.

To get the most out of this tutorial, please have your user's manual on hand so that you can refer to the manual pages. As new options are introduced, we will refer to the manual pages for explanations. This process will show how information can be retrieved from the manual.

Notation: In the text below, the percent sign % refers to the system prompt. You will see a similar prompt in your working window. You should type any text following the % sign at your system prompt; you then hit return on the keyboard to enter the command. Text on the lines immediately following will show the expected response to your action. Where the next line starts with the % sign in the text below, type that line at your system prompt.

2. Opening A Wxploop Window

We will open a wxploop window using the defualt window 0, so we will not specify the option window_num. The window geometry will be 800x600+200+200 and the window title will be DEMO:

    % wxploop -batch -title DEMO -geometry 800x600+200+200 -command open

To remove the window, move the cursor into the window. While holding down the shift key on your keyboard, hit the middle mouse button. This kills the wxploop window and the wxploop process associated with it. The command entry to do the same removal is:

    % loopset k

3. Creating A Simple Script

Let's set up a script to display contoured surface temperatures over the U.S. using sfccalc. This was the basic plot we used in earlier tutorials. We will use wxpfile to find the latest data file. A copy of the script is shown below:

   #!/bin/csh -f
   #
   # demo: a script to show surface temperature contoured over the U.S.
   #       sfccalc plots the contours. wxpfile finds the latest data
   #
   set reg = us       # specify region covered by plot
   set var = st       # specify variable to plot
   
   set filename = `wxpfile -in_file cvtsfc -output file -current la`
   echo latest file is $filename
   
   sfccalc -region $reg -variable $var -name demo -message mess \
           -device d $filename &
   
   exit
   # end of script
   ####################################################################

SAVE the script as a file called demo in your home directory for now and make sure it is executable (use the chmod Unix command.)

You also need to add the following lines to your Wxp.res file in your home account (there is no need to put them in the site Wxp.res file.)

   demo.plot_type: cf
   demo.con_interval: 4
   demo.file_param: use

To run the script type:

   % demo

A contour plot of current surface temperatures over the U.S. will be displayed in a window called demo. Note: by using the name option, we are using the resources we placed in the Wxp.res file. To get rid of the display, put the cursor into the display and hit return.

4. Wxploop Window

The wxploop program is a X-windows-based program set up to animate WXP plots. A window is a rectangular area which is either displayed on the screen or iconified. When wxploop is invoked with the -command open option, a window is opened. This window has a specific X-server ID. To obtain the ID, we need to query wxploop in the following way using loopset (you will see different ID numbers):

   % wxploop -batch -command open
   % loopset query window
   14680075
   % loopset k

The ID number (14680075, above) is returned by the X-server. Your system will return a different number. If we specify the geometry of the window, the window size is returned along with the window ID:

   % wxploop -batch -geometry 800x600+200+200 -command open
   % loopset query window
   14680075:800x600

Note that loopset is sending wxploop commands to wxploop. Descriptions of wxploop commands are found in the WXP Program Reference under the section on the program wxploop.

The window number and the server ID number are not the same. As we didn't specify the window_num parameter, the window defaults to number 0. The ID reply is the X-server window 14680075 and it's size is 800x600 when the geometry option is set. Each wxploop window will have a specific X-server ID. Remember that each invocation of wxploop will have only one window (and hence ID) for that window. We can have more than one wxploop operating if we use the window_num option. For example, type:

   % wxploop -window_num 4 -batch -geometry 800x600+200+200 -command open

Now get the ID of window 4 by typing:

   % loopset -window_num 4 query window
   15728651:800x600

We see that window 4 has a server ID 15728651 (and the first window had an ID 14680075). We can get rid of the windows by typing the following:

   % loopset k
   % loopset -window_num 4 k

5. Wxploop Pixmap

A pixmap is an allocated space in memory in which data can be stored. A pixmap is just like a window, but several pixmaps can be opened (up to 32 per window.) The number of windows will depend on the number of X-server processes allowed on your system. Each pixmap can be copied into a window. Sequencing through these pixmaps will give the sense of animation. The faster the X-server, the better the animation due to faster sequencing. Let's take a look at pixmaps. Open a window again and check it's ID by typing:

   % wxploop -batch -geometry 800x600+200+200 -command open
   % loopset query window
   14680075:800x600

Now, let's do a pixmap query by typing:

   % loopset query pixmap
   Invalid query command

An error occurs because pixmaps are numbered as they are created, starting at pixmap 0. The open command only opens a window. Thus the correct command line should specify the pixmap number as well:

   % loopset query pixmap 0
   0:800x600

No pixmap exists yet, hence the ID of 0. loopset is sending wxploop commands to wxploop. Now create two consecutive pixmaps in the following manner:

   % loopset create 
   Created pixmap 0
   % loopset create 
   Created pixmap 1

We can now do a pixmap ID query by typing:

   % loopset query pixmap 0
   14680080:800x600
   % loopset query pixmap 1
   14680081:800x600

Thus, we see that as we create consecutive pixmaps, we create new X-server ID's associated with each pixmap. In a script, we can program a loop to create a number of pixmaps. This technique is the basic idea of many of the sample animation scripts that come with the WXP distribution.

And how does the animation work?

Well, go to the wxploop window we created. You will notice that the cursor symbol (when placed in the demo window) is no longer a solid circle. It is now two arrows forming a circle. Press the middle mouse button and you will see the symbol change to a solid circle. Press again and the circular-arrows symbol is back. The circular-arrows symbol means wxploop is looping through pixmaps, the two pixmaps we've created. As yet nothing is drawn in them, so all we get is black window.

TO REMOVE THE WINDOW, type:

    % loopset k

6. Displaying An Image In A Wxploop Window

We shall now put an image into a wxploop window. We will use the wxploop window ID for now; we will use pixmap ID's later when we discuss setting up animation loops. We will use the sfccalc command we used in previous tutorials in the demo script we created:

   sfccalc -region $reg -variable $var -file_param use -message mess \
           -device d $filename &

So how can we put this plot into a wxploop window?

The solution is to use the device option. In earlier tutorials, we had this option set to d for display, but there is also the entry w for specifying a window. In the Program Reference section on sfccalc, the following entry occurs for the device option:

   -device device[,name]
           d   Display where name is the X-server (optional)
           w   Window where name is [X-server ID] ====NOTE!
           p   printer or postscript
           q   plotter

The X-server ID can relate to a window or to a pixmap as we saw above. So let's adapt the demo script. Here is the new script, the changes are discussed after it. Save this as a new demo, or edit the old demo to reflect the changes:

   #!/bin/csh -f
   #
   # demo: a script to show surface temperature contoured over the U.S.
   #       sfccalc plots the contours. wxpfile finds the latest data
   #
   # As before:
   set reg = us       # specify region covered by plot
   set var = st       # specify variable to plot
   set filename = `wxpfile -in_file cvtsfc -output file -current la`
   echo latest file is $filename
   
   # Add in lines to start up wxploop and get the window ID
   #
   wxploop -batch -title DEMO -geometry 800x600+200+200 -command open
   set winID = `loopset query window`
   
   sfccalc -region $reg -variable $var -name demo -message mess \
           -device w,,$winID $filename
   
   exit
   # end of script
   #################################################################

To run the script, type:

   % demo

Points about the script:

1.: We start a wxploop window (wxploop command line using open.) We then query the window to get the X-server-window ID and assign it to the variable winID. We are using the default wxploop window number 0 as window_num is not specified.
2.: We use sfccalc to produce a contour of surface temperatures for the U.S. The file used is found with wxpfile and assigned to the variable filename. We have set the message option to mess (echo status.) The -name demo option finds other resources for sfccalc from the Wxp.res files. We set the resources earlier. NOTE: we do not have to put the sfccalc process into the background (no & sign) when plotting to a wxploop process.
3.: We have changed the device option of sfccalc to read; where winID is the variable to which we assigned the window ID. In the line above, I omit the X-server-machine name as I have already set my DISPLAY environment variable to specify my terminal. To see this better, we can make the line read:; You need to replace saturn with the name of the terminal you are putting the display on. While working on saturn, if I now specified the sfccalc device output to go to jupiter, I'd write the option as; and get an error message returned when I try to run demo:; You can use loopset k to remove the wxploop window to allow you to run demo again. This error message is returned because the wxploop window is on saturn with the given ID and then sfccalc tries to draw on jupiter to a window with that same ID which of course doesn't exist. In the script, no server is specified, as everything happens on saturn.

REMOVE THE WINDOW BY TYPING:

   % loopset k

7. Overlays Using The Window ID

The script has the basic requirements for setting up overlays.

How?

Well, let's just add a few lines to the script demo and change the variable var. Either edit your demo script to reflect this script, or save the following as script demo:

   #!/bin/csh -f
   #
   # demo: a script to show surface temperature contoured over the U.S.
   #       sfccalc plots the contours. wxpfile finds the latest data
   #
   # As before but moving var:
   set reg = us       # specify region covered by plot
   
   set filename = `wxpfile -in_file cvtsfc -output file -current la`
   echo latest file is $filename
   
   # Add in lines to start up wxploop and get the window ID
   #
   wxploop -batch -title DEMO -geometry 800x600+200+200 -command open
   set winID = `loopset query window`
   
   # We've moved the var variable down
   #
   set var = st       # specify variable to plot = temperature
   
   sfccalc -region $reg -variable $var -name demo -message mess \
           -device w,,$winID $filename 
   
   # and now repeat the var variable, but set to a new spec. wv
   #
   set var = wv       # specify variable to plot = wind vectors
   
   sfccalc -region $reg -variable $var -name demo -message mess \
           -draw data -device w,,$winID $filename 
   
   exit
   # end of script
   ################################################################

Now, run the script.

Points about the script:

1.: We've added a second sfccalc command line that writes to the same winID. However, this second sfccalc has variable var set for wind vectors wv.
2.: Notice that the second invocation of sfccalc (for vectors) has the option -data draw. This means the wind barbs will be drawn, but no title will be written as it would overwrite the previous title specifying temperature contours.
3.: In a similar way, other data can be overlayed on the display.

We can change the window bar title to reflect the details of the window contents. To change the title of the window from DEMO to Temps_and_Wind, we type the following from the system prompt:

   % loopset set name Temps_and_Wind

This renames the title bar. This line can be placed in the script at a line after the wxploop command line. DO NOT USE MORE THAN 30 CHARACTERS FOR THE TITLE STRING. The underscore is required to keep the name as one string.

REMOVE THE WINDOW BY TYPING:

   % loopset k

8. Multiple Plots In A Single Wxploop Window

Another feature uses geometry options again. We specified for the demo script that the wxploop window location be 800x600+200+200 on the workstation. Once the window is open, we let programs write to the window (as with sfccalc in script demo.) We can use the geometry option on the WXP program command line, with sfccalc in demo, to place the program plots AT DIFFERENT LOCATIONS IN ONE WXPloop WINDOW.

Below is the new demo script showing this. Edit your current copy of demo, or save the following into a new demo:

   #!/bin/csh -f
   #
   # demo: a script to show surface temperature contoured over the U.S.
   #       sfccalc plots the contours. wxpfile finds the latest data
   #
   set reg = us       # specify region covered by plot
   
   set filename = `wxpfile -in_file cvtsfc -output file -current la`
   echo latest file is $filename
   
   # Add in lines to start up wxploop and get the window ID
   #
   wxploop -batch -title DEMO -geometry 800x600+200+200 -command open
   set winID = `loopset query window`
   
   set var = st       # specify variable to plot = temperature
   #
   # add -geometry to sfccalc routines and take out -draw option 
   #
   sfccalc -region $reg -variable $var -name demo -message mess \
           -geometry 400x300+0+0 -device w,,$winID $filename 
   
   set var = wv       # specify variable to plot = wind vectors
   sfccalc -region $reg -variable $var -name demo -message mess \
           -geometry 400x300+400+300 -device w,,$winID $filename 
   
   exit
   # end of script
   ################################################################

To run the script, type:

   % demo

Points about the script:

1.: We removed the draw option of the wave vector plot (second sfccalc) so the title will appear.
2.: This example shows how we can size the sfccalc plots to fit WITHIN the wxploop window.

The use of geometry should be considered carefully. As pointed out in tutorial tut8_wxploop, geometries set in resources called by a program that writes it's output to a wxploop window can cause errors by putting plots at the wrong point WITHIN the wxploop window.

ONE MORE THING: We've been writing to the X-server ID for the wxploop window. If we now create a pixmap with the following command (with the wxploop display still up):

   % loopset create
   Created pixmap 0

the wxploop window goes black as a blank pixmap has overwritten the data we put in the window.

REMOVE THE WINDOW BY TYPING:

   % loopset k

9. Displaying Loops With Wxploop (Animation)

Wxploop brings the ability to animate displays. To do this, we need to use pixmaps. To review, a pixmap is an allocated space in memory in which data can be stored. It is just like a window, but several pixmaps can be opened (up to 64 per window.) Each pixmap can then be copied into the window. Sequencing through these pixmaps will give the sense of animation. The faster the X-server, the better the animation due to faster sequencing. We'll open a window and create a few pixmaps by typing:

   % wxploop -batch -geometry 800x600+200+200 -command open
   % loopset create
   Created pixmap 0

   % loopset create
   Created pixmap 1

   % loopset query pixmap 0
   14680080:800x600

   % loopset query pixmap 1
   14680081:800x600

We created pixmaps and then queried wxploop for their ID's. Another way to get the ID and create the pixmap at the same time is to type:

    % loopset create pix
    14680082:800x600

which returns an ID. Loopset is using wxploop commands.

But which pixmap is this now? We have 0 and 1, so let's query wxploop:

    % loopset query last 
    2

which means pixmap 2 was the last one created. And how many pixmaps are there now? Type:

    % loopset query number
    3

There are three, pixmaps 0, 1, and 2. And if we look at the wxploop window, the circular-arrows indicate wxploop is looping through the three pixmaps. The window is black because the three pixmaps don't have images in them yet. Terminate the window by typing:

    % loopset k

We use the pixmap ID to specify the X-server ID in the -device w,,pixID option of wxp program command lines. Either edit your current script to reflect the changes below, or create a new one.

   #!/bin/csh -f
   #
   # demo: a script to show surface temperature contoured over the U.S.
   #       sfccalc plots the contours. wxpfile finds the latest data
   #
   set reg = us # specify region covered by plot
   
   # Open a wxploop window
   #
   wxploop -title DEMO -batch -geometry 800x600+200+200 -command open
   
   # Loop through 4 hours of data and display
   #
   foreach hour (1 2 3 4)
   
      set filename = `wxpfile -in_file cvtsfc -output file -current $hour`
      echo latest file is $filename
   
      set pixID = `loopset create pix`
   
      set var = st # specify variable to plot
      sfccalc -region $reg -variable $var -name demo -message mess \
              -device w,,$pixID $filename
   
   end
   
   loopset set name Temperature_Loop
   
   exit
   #
   # end script
   ##################################################################

To run the script, type:

   % demo

Points about the script:

1.: We first set up the wxploop window.
2.: We set up a loop using the foreach construct of C-shell:; to allow us to get four hours of data consecutively and display them. The foreach variable is the hour to which the list 1 2 3 4 will be assigned, one at each pass through the loop (four passes in all.)
3.: The wxpfile option current now has $hour as it's value. This means at each pass through the loop, we will find the file from that many hours ago (1 hour ago, 2 hours ago, 3 hours ago, then 4 hours ago). Wxpfile is called within the loop.
4.: We create pixmaps using the loopset create pix command and assign the output of this command to the variable pixID using the construct:
5.: We have the sfccalc program with -name demo to get the resources from the Wxp.res file. The device option has the pixID variable assigned so that at each invocation of sfccalc, the display will go to the current pixmap.
6.: We rename the window bar to reflect the loop contents.

10. Some Interesting Shortcuts

With the loop running demo, let's look at some ways of controlling the looping.

1.: To toggle the display from looping to stop, put the cursor in the window and press the middle mouse button.
2.: With the loop stopped, press the left mouse button a few times. We step back through the loop.
3.: With the loop stopped, press the right mouse button a few times. We step forward through the loop.
4.: With the cursor in the wxploop window, hold down the shift key and press the middle mouse button. This kills the loop.

11. Ideas To Explore Further

And so we have created a simple animation loop. It can very easily be expanded upon by increasing the number of hours; changing the variable; or changing the region looked at. We can even change the program (and wxpfile file-type looked for) to see other data such as upper-air data.

With an understanding of this simple example, more complex analyses become possible.

Overlays can be done to a pixmap as well, in the same manner as we did with the window earlier, by specifying the same pixmap ID for more than one command (such as sfccalc.) Thus overlay plots can be animated as well.

xsat can be used to write to pixmaps so that satellite images can be looped (up to 64 images.)

For further information about WXP from Unidata, email support@unidata.ucar.edu
Last updated by Mike Wright on July 25, 1994