garp.run.README BE SURE TO READ THE FILE garp1.04.newfeat.README to learn about the new features in GARP version 1.04. ---------------------------------------------------------------------- This is the second general release of GARP, version 1.04 GARP (GEMPAK Analysis and Rendering Program) is an X Windows/Motif software application designed by the COMET Computer Systems Development Group for the display and analysis of meteorological data sets. COMET has contributed the GARP software to the SOO/SAC community. Please remember, the GARP software is intended to be used as a tool for your research and training programs. This software and the data products that you can create using this software can not be considered operational. ---------------------------------------------------------------------- Before running GARP on your SAC, you must install it. For installation instructions, please see the file README/garp.install.README. After installing GARP, here's how to run it. Starting GARP: ------------- Start GARP from NTL: % ntl & and press the GARP (blue) button. Note, since GARP does not have a error message dialog box (yet), it's best to start NTL from an xterm or hpterm, rather than from a Motif Workspace Menu. This will allow you to position the xterm or hpterm so that you can see the GARP & GEMPAK messages while you are running GARP. Running GARP: ------------ Here's a brief introduction to the features of GARP. The description below will be clearer if you run GARP while you read through the rest of this document. Layout: ------ The GARP user interface consists of a large black display window. Along the top, there is a Menu Bar with pull-down menus. Beneath the Menu Bar there is a series of icons representing different data & graphic types. The last icon is a "Reset" button. Next to the icons, there is the Speed Control slider and the Image Fade slider. These are followed by the looping controls (loop forward, loop backward, rock, step forward, stop, step back). Along the bottom of the display window, there is a clock, and after you've loaded a graphic, there is a dynamic readout of the pixel indeces, the lat/lon, and image data values. Menu Bar: -------- The menu bar pull-down menus offer the following features: File: "Save" allows you to save the current graphics as GIF files. "Quit" allows you to quit GARP. View: Contains menu items for selecting particular data types. This provides an alternate means of performing actions if the icons have been turned off. Area: "Area" allows you to set one of the predefined graphics areas. The DEFAULT area is determined by the data type. For satellite and radar imagery, it is determined by the image. For model, surface and upper air data, it is the continental US. Areas are defined in the $GARPHOME/config/Garp_defaults configuration file and can be changed by the user. The "DEFINE" area can be used to specify in detail the projection and geographic area for the plot using GEMPAK terminology for PROJ and GAREA. "PREVIOUS" takes you back to the previous area used. In addition, you may zoom in on any graphic by drawing a rubber band box with the mouse (position the mouse in the upper left corner of the desired area, press the left mouse button and hold it, drag the mouse to the lower right corner of the area and release the button). Use the Area->DEFAULT to return to the full area. Note that when you zoom on an image or surface/upper air data graphic, GARP will go back to the data file and extract more data (if available) to re-draw the graphic. Time: "Time" allows you to set the time to be the current time, or some previous time. This option is used for simulating the passage of time in case study exercises in the COMET classroom. In the field, you should always use the "Real Time" option (the default). Option: "Tools" allows you to set the size, filtering, and width of the symbols and text in the drawing window. Currently, the default values of these parameters are hard coded and can not be configured by the user. User configuration will be added in later versions of GARP. "Animation" allows you to control animations in more detail. Frame editing, and dwell settings for loops can be controlled from here. "Enhancements" allows you to set the color enhancement table for imagery. The defaults are defined in the GEMPAK table file $GEMTBL/sat/imgtyp.tbl. If you choose to change a default in this table, you will change the default for all NAWIPS applications You may also fade the image (to make overlayed graphics more visible), and roll the color bar. The "Invert" button will invert the color table. The "Equalize" function has not yet been implemented. "Background" loads topographic image files to be used for plot backgrounds. These are image files, so you cannot load them with other images. "Overlay-->Station" and "Overlay-->Radar Range" allows you to overlay various types of station ID's and Radar Range Rings on the graphic. In GARP 1.0.4, you may now add your own station lists to this option. Preferences--> Display Window: "Pixel Value" allows you to turn on or off the display of the the pixel values for imagery. If you turn this "on" after images have been loaded, you will have to reload the images for the pixel values to display. "Cursor Tracking" allows you to turn on or off the cursor tracking information in the status bar. "Plot Fills Window Area" causes the plot to fill as much of the screen as possible. Otherwise, some plots may have portions clipped on the sides, top or bottom. Deselecting "Show cons" and "Show Status Bar" will remove the Icon and Status bars from the GARP window. This will give you a slightly larger graphics window. Icons: ----- There are 10 icons beneath the Menu Bar. Each icon represents a different data type or graphic type, except the last two which allow clearing and reset. Not all icons have been implemented yet. GARP allows you to freely combine data of different types (i.e. satellite & model data, or radar & obs data, etc.) within the constraints of GEMPAK. Notice that as you pass the mouse over the icons, a window appears to tell you what the data or graphic type is. When loading multiple frames into a loop, you may interrupt the loading by clicking on the CLEAR or RESET icons. Radar and Satellite Data: Display of satellite and radar imagery. Same as NSAT. The default number of satellite images to load is hard coded into GARP. You can change the images to select by clicking on the file name with your mouse. To select a single image, click once. To select multiple images in sequence, click and hold the mouse button as you slide up or down the list. To select multiple images out of sequence, press the CTRL key and click on each image to load. Surface Observational Data: Surface data plotted in a standard surface chart. Surface METAR's, mesonet, and ship/buoy data are now supported. The standard METAR's are available from "synoptic", mesonet from "mesonet", and ship and buoy from ship/buoy. You can select/deselect which data is plotted by clicking on the Station Layout button. The default uses one color for all data; the multi-color button activates multiple colors. All the available dates/times from the data files are listed in the scroll window. Select the date/times with the mouse. Profiler Data: Profiler data from individual sites can be plotted as a time series over some time interval, usually 24 hours. (Note that SOO's may not have access to this data type.) Upper Air Data: Upper air observational data plotted in a standard upper air chart. You can select/deselect what data is plotted by clicking on the Station Layout button. You can change the level by clicking on the Pressure Level button. All the available dates/times from the data files are listed in the scroll window. Select the date/times with the mouse. Gridded Data: Gridded data plotted with contours or vectors (barbs or arrows). GARP can display gridded data from a number of models, this is defined in the $GARPHOME/config/Garp_defaults file. There are five coordinate systems that grids can be displayed on. The level can be chosen by either pressing the Level button, or by typing in the level (or levels in the case of a layer quantity). The date/times/forecast hours listed in the scroll window are extracted from each data file. As a result, you may notice an extra second or two processing time. To get specific information about the available times, levels, and fields in a given grid file, press the Info button. This window will allow you to open a grid file and get a GDINFO summary of the available grids in the file. The "Scalar:" and "Vector:" buttons allow grouping of FDF's from which to choose. The scrolling windows contain some pre-defined functions for plotting gridded data. You may select any of these functions, and the GEMPAK GFUNC or GVECT specification will appear in the input window below the scroll windows. These functions are defined in "FDF"'s (Function Definition Files), which are text files stored in the $GARPHOME/fdf/ directory tree. Please see the section "Defining FDF's" below for more information about creating your own FDF's. In addition to the pre-defined functions, you may type in ANY valid GEMPAK GFUNC or GVECT in the input window. Inline parameters (^ @ %) are accepted. Please see "phelp gfunc" for more information. Note that if you are manually inputting a GFUNC or GVECT specification, you must select Scalar or Vector, as appropriate. For more user control over the way your contour/vector plot looks, click on the More button. This will allow you to specify contour lines or color fill; what type of line or list of colors to use; how often to label the contour lines; the contour interval, min, & max; whether H/L symbols are plotted; and for vectors whether wind barbs or arrows are used. Please note that the Field Description box may give valuable information on how a specific pre-defined function is used. Finally, in order to plot a gridded data graphic, you must be sure to select the date/time(s), the level, and a scalar or vector function. If you forget any of these your graphic will not plot. Some FDF's include the definition for the level. In these cases, any value in the Level box is ignored. Press the Display or the Display & Close button to draw the graphics. The Clear icon will interrupt the drawing. Cross Section Data: Much of the cross section dialog is the same as the plan view model grid display. The main difference is that you must specify the cross section end points in the form STN1>STN2 or LAT;LON1>LAT;LON2. Model/Grid Time Height: The model time height window looks much like the Cross Section dialog box. You can only choose one model run per loop. Model/Grid Vertical Profile Data: The model vertical profile looks similar to the upper air vertical profile dialog box. Please note, when drawing a skew-T diagram (the default), you may not change the functions plotted. The temperature and dewpoint data will automatically be drawn. Clear: Clear the window. This icon will clear the drawing window of all frames. You may also use the Clear icon to interrupt the loading of any loop. Note, the Clear button will NOT reset the graphics area (GAREA), so if you have zoomed or changed the default area, your graphic will stay that way. Reset: Reset the window and the graphics area. This icon will clear the drawing window of all frames and it will also reset the GAREA to the DEFAULT value. You may also use the Reset icon to interrupt the loading of any loop. Combining Data Types in GARP: ---------------------------- GARP allows you to easily combine data of different types within the constraints of the underlying GEMPAK software. Data is overlayed by default. You must manually clear the frames with the Clear icon if you do not want an overlay. Currently, GARP will only allow you to clear the entire graphic. In future versions of GARP, the ability to lift off individual graphics from an overlay will be implemented. Currently, GARP has some automatic time matching across data types. For example, if you choose to plot a 5 hour series of satellite images and then choose to overlay surface observations on top of the satellite images, the obs date/times which correspond to the selected satellite images will be pre-selected for you. You are free to change the date/times selected, if you choose. Please note that automatic time matching has not been implemented for all data type or date/time combinations. This functionality will be added to future release of GARP. Please note that currently, GARP will NOT allow you to combine multiple images. (For example, a satellite image and a radar image, or an IR and a VIS satellite image.) This functionality will be added to future releases of GARP. Also note that if you try to load an image or set of images when you already have images loaded, then this is interpreted as a RESET before GARP loads the new images. GARP Information & Error Messages: --------------------------------- It's important that you position the xterm or hpterm so that you can read the GEMPAK and GARP messages. Currently, GARP does not have a message dialog box, so the xterm or hpterm is the only way you can see the messages. If GARP does not display a requested graphic, you should check the xterm or hpterm for a GEMPAK error message. This is particularly helpful when plotting gridded data using GFUNC and GVECT specifications. Defining FDF's: -------------- The FDF (Function Definition File) is a simple text file which defines a GFUNC or GVECT specification. You can easily create FDF's for your favorite simple or complex diagnostic functions. All the FDF's for plan view graphics are stored in the $(GARPHOME)/fdf/scalar and $(GARPHOME)/fdf/vector directories. Cross section FDFs are stored in the $(GARPHOME)/fdf/xsscalar and $(GARPHOME)/fdf/xsvector directories. Vertical profile (scalar & vector) FDFs are stored in $(GARPHOME)/fdf/vpscalar and $(GARPHOME)/fdf/vpvector. Time Height cross section FDFs are stored in $(GARPHOME)/fdf/thscalar and $(GARPHOME)/fdf/thvector. These directories are defined in the config/Garp_defaults file. FDF's are further grouped into sections below each of these directories, to provide better FDF organization. For example, FDF's are groupled into 3 groups under fdf/scalar: general, convective and winter, to allow one to group particular FDFs into seasonal groups. Users can create other groupings and populate them with their own FDF's if desired. For example, you could create a group of FDFs that only apply to the Eta model. Then, you would create an "eta" subdirectory in fdf/scalar/ and store the Eta-specific FDFs there. Note, each additional group must be listed in the $GARPHOME/config/Garp_defaults file in the xxxChapter keys (ScalarChapter, VectorChapter, etc.). The FDF format allows you to specify a simple GFUNC or GVECT, or you can make a complete specification, including most of the GEMPAK variables. For a sample FDF, please see the $(GARPHOME)/fdf/ directories. For a blank FDF template, please see the file valid_fdf_keys, in the $(GARPHOME)/fdf/ directory, and here, in this directory. Lines beginning with a "!" are comments. The required variables are indicated. The optional variables may be specified, or left blank. GEMPAK will use default values for blank variables. The file name you choose for the FDF will be the name that appears in the "Scalar Field" or "Vector Field" scroll window in the Gridded Data or Cross Section selection window. The addition of FDF's is dynamic, so you can add new FDF's to GARP at any time. To create a new FDF, I suggest that you copy an existing FDF, and make the necessary changes to the required and/or optional variables. You must also choose an appropriate file name. You must put the file in the appropriate directory ($GARPHOME/fdf/scalar/*, $GARPHOME/fdf/vector/*, $GARPHOME/fdf/xsscalar/* $GARPHOME/fdf/xsvector/*), and it is ready to be used. Sometimes, functions can be used in both plan projection and cross section graphics. If this is the case, I recomment that you put the FDF in the $GARPHOME/fdf/scalar directory, and create a link to the $GARPHOME/fdf/xsscalar directory. For example, if I create an FDF called "Temp_K" and placed it in the $GARPHOME/fdf/scalar/general directory, I can use the following command to create a link in the $GARPHOME/dfd/xsscalar/general directory: ln -s $GARPHOME/fdf/scalar/general/Temp_K $GARPHOME/fdf/xsscalar/general/Temp_K You can contribute any FDF's you have written to the directory contrib/fdf/ on the SAC FTP server. As FDF's are written at COMET, they will be added to this directory as well (and to subsequent releases of GARP). The only requirements for a contributed FDF are that you include your name in a comment line, and that you check to be sure no other FDF on the contrib/fdf/ directory has the same name. (If there is an FDF of the same name, make a simple change to your file name). __________________________________________________________________ Peggy Bruehl National SAC Coordinator - NWS peggy@comet.ucar.edu COMET/UCAR PO Box 3000 (303) 497-8356 Boulder, CO 80307-3000 SOO/SAC Home Page: http://www.comet.ucar.edu/pub_html/sac_html/index.html ------------------------------------------------------------------