The ActiveGEM package is currently under development at the University at Albany (SUNY) and at McGill University. The goal of the project is to fill the gap between the GEMPAK package and research users using current interfacing technology. The primary language of ActiveGEM is perl/Tk, a modular extension of the perl programming language developed by Nick Ing-Simmons and available on the CPAN servers and mirrors.
ActiveGEM is licensed open source software hosted by SourceForge.net, and is subject to the terms and conditions of its copyright (see section Copying Conditions). Although its target audience is the meteorological community, suggestions for extensions of the package to address the needs of other groups is always welcome.
As noted in the licensing and copying agreement (see section Copying Conditions) we encourage all users of this software to become developers and to contribute to the evolution of ActiveGEM. Please share any interfaces that you develop and bug fixes that you implement so that others may benefit from your efforts.
This Quick Start portion of the ActiveGEM manual provides a basic set of instructions for installing and running some of the ActiveGEM utilities. It represents by no means a comprehensive list of the functionality of the various components of the ActiveGEM package. For full instructions, the user is encouraged to read the detailed sections of the manual before beginning to work extensively with ActiveGEM.
Before installing the ActiveGEM package, make sure that you have an up-to-date version of Perl5 (versions 5.6 and newer are preferred) and that the Perl/Tk module is installed and functional. For a description of Perl and Perl module installation, see the CPAN site at www.cpan.org. You will also need a FORTRAN compiler. Although FORTRAN90 is preferred, FORTRAN77 is also supported by the limited FORTRAN utilities of the ActiveGEM package. A fully-functional, up-to-date version of the GEMPAK libraries is also required for ActiveGEM installation. ActiveGEM is known to work for GEMPAK versions 5.6 and newer, although a high degree of backwards-compatibility is likely.
Once these components are running on your system, and you have downloaded
and unpacked your ActiveGEM distribution
(`gunzip -c ActiveGEM-x.x.x.tar.gz | tar -xvf -`),
enter the top level directory and run the configuration
script (`./configure`). Note that there are many possible command-line
options and environment variables for the configuration script, the most
common of which is the --prefix option which allows the user to assign
an installation path. Run `./configure --help` for a full list of options.
If you have an older version of the ActiveGEM package installed on your
system, be sure to run `make uninstall` in the old source directories
before attempting to upgrade.
After successfully configuring the package for your system (you should
watch the output from the configure script as it runs to be sure that it
produces no warnings or errors), you can build and install the package
simply by typing `make all; make install`. This will be reasonably quick
(depending on your machine) so be sure to follow the output and check
that all of the components compile and install correctly. Once you have
installed the package components, make sure that your executable destination
path (bin) is in your path and you will be ready to get started with
the ActiveGEM package.
Once the ActiveGEM package is properly installed on your system, you
will be able to run the plotGEM GEMPAK plotting interface. This is
the first application in the ActiveGEM package, and provides a user-friendly
graphical interface for the GEMPAK plotting utilities including
plan, cross-sectional, and profile plotting. To get started, type
plotGEM on the command line to start the interface. After loading, you
will be presented with the main notebook window of plotGEM. The following
instructions are highly simplified, and reflect only the simplest application
of the plotGEM interface. In-depth instructions and tips are found in the
remainder of this manual.
To select an input GEMPAK file for plotting, click on the Browse
button on the right hand side of the screen (or use the -file command-line
option - run `plotGEM -h` for a list of options). Select a data file from the
browser, and click on Accept to import the file name to plotGEM. If this
is the only data file that you wish to load, then press the Load button
on the main window, and wait while the file is loaded by plotGEM. Once the
load operation is complete, a "Field Selection Window" will open, providing a list
of the fields available in the requested file. Use the left mouse button to
highlight the field of choice, then press the Generate Plan Plot button
in the top right-hand corner of the main window. Wait for a few seconds as
GEMPAK works its magic, and you should be rewarded with an X-window
showing the requested field. Note that the default map is for the United States
(where else?), so you will wind up with a blank map if you do not have any data
covering that area.
You can customize your plot by selecting the "Scalar Field" tab in the notebook on the main window. This page allows you to add colours, change contour properties and intervals, and pretty much anything else that GEMPAK is capable of. For more information on the other plotting functions available to you with plotGEM, please browse the remainder of this manual.
The ActiveGEM package consists of a set of perl/Tk programs and modules which provide a graphical user environment for interaction with GEMPAK functions. Additionally, small Fortran90 and Fortran77 utilities are provided to enhance the error-tracking abilities of the ActiveGEM software. The primary functions of the ActiveGEM interfaces are to provide a high level of easily-accessible flexibility to the user, and to parse the user's input into appropriate options strings for the GEMPAK text interface. The GEMPAK text interface is addressed automatically by the ActiveGEM utilities, thereby completing the graphical abstraction layer for the user.
As with all open source software in the development phase, there will inevitably be bugs in the interface which will become apparent as more users attempt to use ActiveGEM for more complex tasks. With the help of the user and developer community, these errors will be corrected over time, and will result in a set of stable, relatively bug-free GUIs. Continued development of the GEMPAK package will also lead to incompatibilities in spite of the developers' best attempts to foresee them. Continued error and fix reporting on the part of the users is essential for the success of any open source software.
As a graphical interface overlay, the ActiveGEM package does not itself do any data handling. The data formatting limitations of ActiveGEM are therefore identical to those of GEMPAK and can be found in the GEMPAK software documentation for gridded, station and image files.
The plotGEM utility is the ActiveGEM GUI for the GEMPAK plotting functions. The plotGEM implementation for version 1.7.0 provides access to the 2D plan plotting, cross-sectional, and profiling capabilities of GEMPAK
The plotGEM GUI is notebook-based, with six main (tabbed)
pages: See section File I/O Notebook Page, See section Scalar Field Page, See section Vector Field Page,
and See section Script Overrides Page. Each of these pages will be
explained in greater detail in later portions of this chapter.
In addition to the notebook, a menu bar across the top of the
window provides file functions, map options, and advanced
options. The file functions (including Save, Save As, Load,
and Quit) allowing the user to save or load the session at any
point. The smooth quitting option runs a GEMPAK cleanup
script, and is the suggested method of terminating the interface.
The map options provide the user with both simple and advanced
map setup capabilities including area, projection, and colour
options. The advanced options menu item allows the user to control output
devices, superpositions, and to define additional data sources.
The Generate Plot button on the right side of the menu
bar generates output from the GUI and calls the appropriate
GEMPAK plotting function. In superposition mode, a second
button appears on the menu bar, allowing the user to Submit
the plotted fields to the final output one at a time. Deactivating
superposition destroys this Submit button.
The file input/output page of the plotGEM interface is the
place for user handling of the gridded input files and the
output image files. To open a single file for plotting, simply
enter the file name in the Input File slot and press
the Load button. The file name will appear as an
active input file, and a few seconds (depending on the file size)
will pass while the file is scanned by the Fortran loader. A
field selection window is opened automatically upon file
loading, and will be described later in this section. To open
multiple input files for plotting, use the Push and Pop
buttons to enter a stack of input file names in the active input
file list before pressing the Load button. Alternatively,
you can use the standard UNIX wildcards (* and ?) to
load sets of files simultaneously.
The output file or window name is also defined on this
notebook page. The default value is GEMPAK, which corresponds
to the GEMPAK defaults for the X-windows device. This
name is given to all output image files produced by ActiveGEM
and GEMPAK. This entry must not reference a subdirectory of the
local directory (for example, if a GEMPAK directory exists locally,
then the default will fail on plot execution). This entry
should be modified to reflect the type of output being generated.
For example, if the GIF generation device is being used
to produce GIF images, then the output file can be changed
to someFileName.gif, for any convenient file name.
The field selection window displays a listing of the fields
available in the active input file(s) under a series of descriptive
headings. Fields can be selected either by using the drop-down
menus above the column headers, or by left-clicking over the
field of choice in the display window. At the top of the
selector, the user has choices between Scalar Field and
Vector Field options (the default is scalar). As well,
function or vector entries can be made manually in the entry
boxes provided.
For example, to plot wind vectors, the Vector Field
button should be highlighted at the top of the field selection
window. This tells plotGEM to produce a vector expression. Next
the desired expression is entered into the box to the left of
the Vector Function label (this expression would be WND
in our example. To ensure that the date and levelling information
is set correctly for this field, it is probably a good idea to select
one of the function's components (say, UREL) from the display
window. This could equally be accomplished using the pull-down
menus at the top of the display window, but the former method is
by far the safer of the two. Either double-clicking the left mouse
button over the highlighted field, or pressing the Generate
button on the main window will result in a wind vector plot. The
same can be done for scalar fields, with the function defined
in the entry box beside the Scalar Function label and the
Scalar Field button activated.
Help menus are provided to assist users in writing their own
functions, and Long function inputs are available for the
writing of extended compund functions. Also available in the window
generated by pressing the Long buttons are the function
expansion descriptions. By default, plotGEM expands the date, level,
and coordinate for each variable in each function. This is a desirable
quality since it allows for plotting and computation involving multiple
times and levels; however, it can also result in long input lines for
the GEMPAK applications, some of which are very restrictive
on input line length. plotGEM will attempt to warn users of very
long lines. If you see such a warning, removing some of the expansions
using the options in the Long window is the best place to start
for reducing the line length. Of course, resetting the maximum input
line length parameter in GEMPAK and recompiling the package
is another (permanent) answer if you have that kind of control. A
description of this procedure is provided in the pop-up window as
a user note.
Three different types of plots can be plotted with plotGEM:
2D plan maps, 2D vertical cross-sections, and profiles. The default
plotting mode is Plan Plot, which is displayed on the
Generate button in the top right-hand corner of the
display. To access either of the other plotting modes, use the
Type menu to highlight the desired mode. Once the
new mode is selected, the Generate widget will be modified
to reflect the new plot type. For example, if you choose the
Profile selection in the Type menu, then the
Generate button changes to read Generate Profile.
No settings or options are lost during the plot type changes,
so even if you forget to switch until you have everything else
set up, you will not have to redo any of your work.
Plot type switching while in superposition mode (discussed
individually in each of the following subsections, and activated
from the Options menu) is not allowed for obvious reasons.
An attempt to switch during superpositions will be trapped and
the user will be warned of his/her indiscretion.
The scalar field page of the plotGEM notebook contains
the line and colour filling display options. For a simple line
plot, use either the old or the new Contour choices
across the top of the page. To create a colour plot, select
one of the Fill options. Note that any or all of the
four plotting options can be selected for any given plot.
The line properties option section contains a set of reasonable
defaults which will generally serve to provide a first look at
any dataset. Both label and line characteristics are set in this
section. The colour properties selection region is somewhat
more complex, with two primary modes of operation. The first
(default) produces a range of colours with appropriate
gradation. The second, more involved, mode involves the
specification of individual fill/dash values, and is accessible
through a separate window (activated once the
Choose Fill/Dash Values button is pressed). Note that this
mode requires the specification of a semicolon-separated list of
individual contour levels in the Levels entry of this
region. The button with an ! (exclamation mark) to the right of
the Levels entry is useful in conjuction with the colour
level specifications (see section Adding Colours and Colour Bars to Plots). It propagates the
colour Levels to the line Levels.
Once the user is satisfied with the selections on this
page, he/she uses the Generate Plot button on the menu bar
to create the desired plot. After changes to any of the
values on this page, the Generate Plot button must be
pressed to display the new plot.
The vector field page of the plotGEM notebook contains the vector (or barb) and reference vector display options. Default behavior is to plot wind barbs at every gridpoint, which is desirable only as a first guess.
The properties of the vector display are set in the top region of the
page. Colour, size, type, and vector units can be changed quickly
by modifying the appropriate entries. As well, the handling of
stations (gridpoints) with calm winds is set in this selection
area. If the vectors (barbs) appear to densely in the output, then
set the Skip Points entries to non-zero values to plot
vectors (barbs) only every n gridpoints.
The reference vector properties, displayed only when the
vector option is chosen in the vector properties region,
are set in the bottom half of the page. The location of the
reference vector takes the form of semicolon-separated x;y
coordinates, where 0;0 is the bottom-left corner of the
page and 1;1 is the top right corner. Note that the
use of Hardware Font for text is preferable on most
systems.
All options for the plot domains and map setup are contained within the
entries under the Map menu at the top of the main window. The
map description is of course only meaningful in plan plotting mode
(see section Changing Plot Types), and is necessarily ignored in both
cross-sectional and profile plotting modes. The map domain may be
selected using either the Quick Area selection list or the
Advanced Map and Area Settings window. The quick list provides
an easy way to look at data for different domains around the world
without having to worry about specific grid specifications. The
map settings window, however, provides complete access to the
map projections and definitions available in GEMPAK.
General map attributes including map colour, line-style, and
projection, are set in the Map Plotting region of the
map settings window (note that Defining Angles are used
only for some of the more advanced map projects - please refer
to the GEMPAK users guide for more details). The
map domain is defined in the Domain Description region
of the window, where one of six selections can be made. The
Native Data Grid domain displays the actual domain of the
gridded input dataset. The Native Image Map specifies that
all fields are to be plotted on the domain of the satellite or
radar image provided (see section Using Satellite and Radar Image Backgrounds) if this option is
selected and no image is provided, then the Geographical
specification (described below) is used by default.
The Lat/Long specification allows
the user to accurately define the corners of the region to be
plotted. The default Geographical specification permits
for the quick definition of a map centered on a particular area,
as does the Station specification. The Zoom
definition allows for the "zooming" of the current map to a
user-defined region.
In general, the best way to zoom the
map is to select the Choose New Area button before
selecting the Graphical specification. This is because
you will only be able to select a subregion from the currently
active area, which is defined by the settings snapshot at the
time that the Choose New Area button is activated. If you
select the Graphical specification first, then you will
only be able to choose a new area from your previously-zoomed
region, which is likely not intention but may be considered a feature.
Instead, leave the
domain description at its current value (whatever that is) and
select the Choose New Area button to get more
predictable behavior. Zooming out returns the map settings
to the last selected non-zooming projection.
The plotting of the latitude/longitude reference lines is
defined in the Lat/Long Plotting region of the page (the
colour of these lines may also be set directly from the Map
menu), and
specific options are set in the Miscellaneous Options
region. The extent of the plan map on the page may be set
in the latter region.
Additional map details may defined in the Miscellaneous Options
section of the window. By default, only the base map is
loaded, which contains information about coastal and major political
boundaries. To add details such as lakes, rivers, and roads,
select and add additional maps to the listing in this section. Several
detailed maps are available through the pull-down menu, and others
may be accessed by either entering the full path name of the
map file into the Custom Map entry, or by selecting existing
maps from the GEMPAK database using the Browse
button. Each time a map is to be added to the current plot from the
text entry the Add button must be selected (this is done automatically
for the pull-dowm menu options). To remove a map from the
current plot, simply highlight the plot name, and activate the
Remove button to remove it from the list. Only maps which
are on the list will be used in plotting the current panel.
The cross-section plotting page gives the user access to many of the common options
employed uniquely during the plotting of cross-sectional views. The top panel
on the page allows the user to define the transect path in one of four ways:
using latitude/longitude specifications of the endpoints, using gridpoint entries for the
endpoints, using station specifiers at the endpoints, or performing a graphical
definition. The first three of these options are fairly simple, but the
fourth (graphical definition of the transect) is the most powerful. Activating
the Choose button will produce a new plot window (called CursorChooseWindow
no matter what entry you have on the File I/O page) showing the plan view
of your grid area. If the plotted region does not contain the area you're interested in,
then try resetting the map options (using the Map menu item) before hitting
the Choose button again. Once the plan map has been plotted, simply click
and drag the transect of your choice using the left mouse button. The next time the
Generate Cross-section button (on the top menu bar) is pressed,
the desired cross-section will be plotted on the main output window. Note that the
CursorChooseWindow will not close, but you can drag it out of the way - this
feature will optimize your next selection process.
The Axis Formatting panel provides control over the size, extent, and position
of the vertical coordinate and the plot. For the cross-section, both skew-T
Axis Types are invalid, since they are reserved for profile plotting, to be
described in the next section. For control over the contour properties (for example,
whether to use fill colours or not) and vector properties, use the Scalar Field
and Vector Field pages. Similarly, title and colour bar plotting and description is
accomplished using the appropriate entries from the Options menu at the top of
the page.
Due to GEMPAK limitations, superposition in cross-section
mode can be accomplished only for one scalar field and one
vector field. If you wish to overlay multiple scalar (or vector)
fields, you must use the Overlay option under the
Options menu. More information can be found in
See section Plotting Multiple Fields with plotGEM.
Profile plotting with plotGEM is accomplished using the options provided
on the Profile page of the main notebook. As for the
Cross-section page, the top panel provides entries for the
location of the profile in latitude/longitude coordinates, grid
coordinates, or as a station identifier. The profile location
can also be chosen graphically in a manner very similar to that
described in the previous section. Activating the Choose
button will create a separate map window (entitled
CursorChooseWindow) containing a plan plot of the selected
field(s). Choosing a location on the map window is as simple
as single-clicking the mouse button on the desired point. The
next time that the Generate Profile button is pressed
(this button is on the right-hand side of the menu row), the
profile at the defined location will appear on the main window.
Axis formatting for profile plots is similar to that for the
cross-sections as described in the previous section. The extents
and details of each of the ordinate and abscissa axes can be
set directly on the Profile page, as can the properties
of the plot window. A More button to the right of the
bound and interval entries allows for further description of the
particulars of the axis labelling properties.
Simple frame characteristics can be easily set in the
Profile Appearance panel. For skew-T plotting options, and additional
options for other plot types, a Background/Markers button on the right-hand
side of the Axis Formatting panel generates a separate entry
window which allows for detailed definition of the plot properties.
Superposition of profiles is not allowed in the current implementation.
Instead, the Overlay button in the Options menu
must be activated for multiple profiles to be shown on the
same window. More information can be found in See section Plotting Multiple Fields with plotGEM.
Surface data can be plotted by only in Plan Plot form
(see section Changing Plot Types) since soundings or cross-sections of surface data
would have no real meaning. The controlling window for plotting
surface data can be accessed through `Data'=>`Station Data'.
The Station Data Handling window provides full control over
the plotting of surface observational data. By default, no station
information is plotted and the Station Data File entry is
blank. To plot station data, simply provide the name of a valid
surface data file in this entry and the date of the observing time
in the Obs Year/Month/Day/Hour/Min entries at the bottom
of the window.
The other options on the Station Data Handling page control
the information plotted and its attributes. The details of the text and
symbol characters are defined at the top of the window. In the
middle of the window is a selection box that allows for the quick
user-definition of the data to be plotted at the station location. When
any of the buttons are selected (their configuration representing that
of the final product), a Station Parameter Selection window
for the requested slot appears. The entry and its individual attributes
may be defined here (note that all symbol sizes and widths can also be
set for all parameters using the Reset Symbol Sizes button).
Because surface data plotting is handled separately from contouring in GEMPAK, `Options'=>`Overlay' mode must be used to add surface data to plots (see section Plotting Multiple Fields with plotGEM). Moreover, if multiple sets of surface observations are to be plotted (for example, separate surface stations and ship/buoy observations), then `Overlay' must be used since there is no `Superposition' facility in the underlying GEMPAK application. The simple rule is that whenever producing surface observational plots, use `Overlay'.
Satellite and radar images (properly-formatted, see the GEMPAK
documentation for details) can be used as backgrounds by GEMPAK
by defining the name of the image file through
`Data'=>`Additional Data Sources'. The Enhanced Data Handling
window permits the user-definition of the background image file (either satellite
or radar) and provides access to the full range of enhancement tables. Note
that the map projection is automatically changed to a satellite view if
a Satellite Input File is defined and the checkbutton beside it is
active (the default). The grid area of the plot remains defined as before
on the new projection; however, the user can also specify that the full domain
of the image is to be shown using the Native Image Map button
in the Advanced Map Options window (accessible through
`Map'=>`Advanced Map Area and Settings'
(see section Selecting Map Settings).
All of the lines plotted on GEMPAK maps allow for the definition
of specific line colours. Each of these is reflected in plotGEM with
a pull-down menu of the available colour options. All scalar plots in
GEMPAK (see section Scalar Field Page) can also be shaded/coloured
using the Fill option on the main notebook's scalar field page.
With fill selected (and defined by either the default Colour Range,
Fixed Range, or Colour Value list - these options are
described in greater detail below), a colour bar is easily added to the
plot using `Options'=>`Colour Bars' (under the
Options menu at the top of the main window). A popup window
will allow you to set the properties of the colour bar in your
current plot. Note that default is for the colour bar not
to be displayed, so the first step in the definition of the colour
bar is to select the Show Colour Bar option at the top of the
colour bar window.
The positioning of the colour bar is somewhat tricky, but will be
familiar to GEMPAK users. The bar location is defined in the
view coordinates (x[0,1],y[0,1]), separated by a semicolon. For
example, an entry of .9;.2 would position the Anchor of the
colour bar 90% of the width from the left edge, and 20% of the height
from the bottom of the plot. The anchor is set using the pull-down
menu directly to the right of the bar location entry [default lower-left (LL)].
The anchor is basically the position of the entered location relative to the
colour bar itself. If the default lower-left is retained in this case
the example, then the lower-left corner of the colour bar will be
positioned at (.9,.2). Of course, this will create a colour bar that
extends well to the right of the plot window, so the Orientation
of the colour bar may be changed to "Vertical". Control of the colour
labels (along the colour bar) is also provided in this region of the
colour bar window. Text attributes for the colour bar are defined
in the separate Text Settings region.
There are three options for colour filling in on the Scalar Field
notebook page. The default (Colour Range) allows the user to
define a range of colour with which to fill the map as GEMPAK
finds appropriate. This setting can be refined using the Interval,
Minimum, and Maximum settings in the same section; however,
the start and end field values of the colour range are still chosen based
on the field itself. This can be a problem in time series generation where
it is preferrable that all colour ranges be the same.
For this purpose
the Fixed Range colour style should be chosen, which allows for
a quick-and-easy definition of the field values (levels) to shade based
on the user-supplied (mandatory) Minimum and Maximum values.
This fill style works best with the Auto Fill Interval enabled.
If numerous colours are used, the length of the Levels line may
exceed the recommended value. If this is the case, plotGEM will warn you
of the possible problem, and offer to attempt to resolve it. Unless you
are very sure of your custom GEMPAK build, you would be well
advised to allow plotGEM to give you a hand in reducing the line length;
otherwise, some of the higher colour levels will likely be lost. Note
that increasing the Fix Skip value is an effective way of
thinning the colour list and reducing the line length, although it also
reduces the (colour) smoothness of the final product. Note that
contours can be added to each colour level using the ! (exclamation mark)
button in the Line Properties section of the page.
The Colour Values fill option allows for precise user
control over the colour and fill type for specific levels. Each level
given in the Levels list is treated separately in this fill
mode, and both colour and fill values are provided by the user once
the Choose Fill/Dash Values button is activated. Note that
this pop-up window is one of the few in plotGEM that must
be closed for changes within it to take effect.
The default colourmap in plotGEM mirrors that of GEMPAK so that
users familiar with the GEMPAK colour naming scheme feel
more comfortable with the initial values. However, one of the primary
advantages of plotGEM is that the selection of multiple colour maps
is a very simple procedure. Activating the `Options'=>`Colour Mapping'
menu item results in the generation of a pop-up window that allows the
user to quickly define both the background colour and the overall
colour map to be applied to the current plot. By default, the
Use Default checkbutton is selected for the background colour,
which means that all graphical plots will be generated with a black
background, except for PostScript file, which have a white background.
De-activating this checkbutton will override all default backgrounds,
including those for the PostScript driver. Note that this is not
the best way to invert the image from white-on-black to black-on-white.
The `Options'=>`Negative' option is provided to assist
with the production of negative prints (see below).
Changing the General Colour Map results in changes to all of the
colour options available in plotGEM. It may also produce changes in
some of the current settings as the new colour map is queried for your
setup. For example, if you have the line colour set to green
in the default default colour map, and change to the rainbow
colour map, you will notice that the line colour has been reset to
redorange1. If you change back to the default map,
the line colour will change back to green. This remapping is performed
numerically in that the colours are mapped in the order in which they
appear in each map. Although most of the standard colours map predictably
from one colour scheme to another, it is probably safer to set the
colour map before proceeding too far with the production of the plot.
The application of non-default colour maps will allow you to make
images with smooth colour gradations across the range of your data
using either the Colour Range or Fixed Range options on
the Scalar Field page (see section Scalar Field Page).
All colour maps contain both colour and black-and-white mappings.
The latter can be selected using the `Options'=>`Output Colours'
Greyscale option. With Greyscale activated, all plots
are generated using grey gradations instead of colours. In general,
these gradations go from light to dark, or vice versa. There is
no uniform attempt to maintain the intensity of the colours from
Full Colour to Greyscale since many of the maps would
result in a set of uniform, or indistinguishable, greys. Note that
all of the colour options in plotGEM are updated to greys once
Greyscale is selected. There is currently no Monochrome
implementation in plotGEM, although the Monchrome option will
be passed to the called GEMPAK application upon request.
For publication-type images, it is also sometimes useful to produce image types (other than postscript) on white backgrounds instead of the default black (for example, for import to FrameMaker software). (The postscript driver does this automatically so that your sysadmin doesn't have to replace printer toner every hour or two.) This can be achieved in plotGEM through the selection of the `Negative' option from the `Options' menu. All white/vanilla lines in the standard white-on-black mode will be converted to black lines, and the background will be switched from dark to light. Note that all other colours remain unaffected by the negative mode switch. Because this mode requires that an extra command be executed in the GEMPAK output buffer, generation of the images may be a bit slower. It is therefore advisable to build the plot using standard white-on-black mode in the X-Window, and to make activate negative plotting only as the final step.
The script overrides page of the plotGEM notebook provides the
highest level of flexibility for the experienced GEMPAK user.
A complete set of option types is provided, each of which can
be set manually and selected to override any values generated
by plotGEM at execution time. Note that only those filled
entries whose options are highlighted (by clicking on the selection
box next to the entry) will be used to override the plotGEM
values. A full set of overrides (inactive) containing a snapshot of the
current settings is generated each time that the Generate Plot
button is pressed. Similarly, the Generate Overrides button
can be used to produce overrides without re-plotting.
A dynamically-generated help index can be accessed using the
Help button. Complete information on each of the entries is
provided so that the user can quickly and easily set the override
values of his/her choosing. Keep in mind that almost all of the
options available
to the user are included on the other pages and windows of plotGEM.
The overrides page should be used as a last resort only, since
error checking is necessarily virtually nonexistent for the
user-specified entries. To remove a user override, simply de-select
the appropriate option button, and press Generate Overrides to
accept the current plotGEM values.
Saving and loading of the full set of plot values (everything that
you can see in plotGEM) is accomplished using the Save,
Save As, and Load options of the File menu. Selecting
either the Save As or Load option opens a file browser
from which to choose the desired save/load file. If a save file has
already been selected, then Save simply replaces its current
contents with a snapshot of the plotGEM options. Once you have created
a complicated plot that suits your needs, it is a very good idea to
save the plotGEM settings just in case you need to reproduce it quickly.
Loading and running a previously-saved set of plot settings should
result in a plot identical to the one generated the first time, provided
that the datafiles are still present and unchanged.
As the ActiveGEM package goes through upgrades, an internal plotGEM version number is incremented. This version information is also stored in the saved files, so that the software knows, at load time, how old the information in the save file is expected to be. If plotGEM detects an save file written by an older version of the software, it will warn the user as to the severity of the possible conflict. As much as possible, wrappers are written to implement the loading of files written by older versions; however, keep in mind that any options implemented between the versions will be set to their (usually very reasonable) default values.
In an effort to permit simple organization of the saved files, the ActiveGEM programs recognize the ACTIVESAVE environment variable as pointing to the users's storage directory. Each time a file selection menu appears (for saving and loading), it will default to this directory. In this way, it is simple for the user to keep all of his/her settings in the same location for easier recovery at a later time. If the ACTIVESAVE variable is unset, then the file browser will default to the current directory.
Although plotGEM provides a wide range of functionality for the user,
there will undoubtedly be times when advanced users wish to make use
of GEMPAK scripts directly (remembering that within plotGEM
there are both Scripting Override options (see section Script Overrides Page) and
`Data'=>`Multiple Times' capabilities). If this is
the case, then the GEMPAK script used by plotGEM to generate
the most recent output can be produced using the `File'=>`Export'
option. Upon export selection, the user is prompted for a script file
name: the script will be generated into this file. The generated script
comes plug-and-play, but may require the user to apply user-executable
attributes, in an effort to maintain platform independence. Once executable,
the script may be run simply by typing its name on the command line to
reproduce the latest output of plotGEM. Due to plotGEM internal usage
of the gpend GEMPAK buffer-clearing utility, it is
advisable to quit plotGEM before running the exported script.
Especially for graphical devices (X-windows), however, this is not
necessary. It is for the user to remember to run the gpend
utility to generate hard-copy output as necessary.
Plotting multiple fields on a single map with plotGEM is accomplished primarily through
the use of the `Superposition' option. In plan plotting mode, simply
activate the `Options'=>`Superposition' button to begin the
process of developing a multiple-field graphic. In superposition mode, a second button and
(red) menu set appears next to the Generate Plan Plot button. This Submit
button and menu allows you to add and remove superposition layers to your plot.
To generate the first superposition layer, select the desired field from the
field selection window, and give it the attributes that you would like this field
to have. Once you are happy with the result (you can generate the map as many
times as you want), press the Submit button to store the first layer into
memory. The second layer of the plot now becomes available for you to manipulate.
You may (and probably will want to) choose a different field to plot with entirely
different attributes. Each time that you press the Generate Plan Plot
button, both layers are replotted; however, only the attributes of the active layer
(now the second layer) may be modified. In this way, any number of fields may
be superposed upon each other.
If, after submitting a field, you realize that you have made a mistake on one of the layers underneath it (anything but the active field), you can select the `Withdraw' option from the red `Superposition' menu. This will withdraw the currently-active field, and make the previously-submitted field active. You can withdraw as many times as necessary to get back to the field you wish to modify. In the default memory mode, a withdrawn field is purged from memory and must be reconstructed manually; however, enhanced handling of fields is possible using the plotGEM data manager (see section Using the plotGEM Data Manager).
In cross-section and profile plotting modes, internal GEMPAK limitations limit the usefulness of the `Superposition' option. On cross-sections, only one scalar field and one vector field may be overlaid, and profile plots do not support superposition at all. A work-around is provided using the `Options'=>`Overlay' button instead of superposition. In overlay mode, a separate button and (red) menu appear, with the current layer number displayed on the button. In terms of end-user functionality, this mode is very much like superposition, as layers may be added and removed using either the button or the special menu; however, output file sizes are increased dramatically in overlay mode since all background lines are replotted for each layer. For this reason, the use of overlay mode for superposing fields should be limited to applications in cross-section and profile plotting modes only. In plan plotting, all field layers should be added using superposition.
If multiple layer plots of surface observational data are required (or if station data is to be layerd onto another field), the the only option for creating the layers is `Options'=>`Overlay'. Applying `Superposition' in this case will not work since there is no support for station plotting in the gridded data programs of GEMPAK and there is no superposition ability in the package's surface mapping utilities.
Multi-panel plots are easily generated using the plotGEM interface. To select
a panel region, use the window produced by activating `Options'=>`Multi-Panel'
to highlight the desired layout and panel. Note that the active panel displays
the word Active once selected. Once a panel is selected, all plotting
occurs in that region until a new panel selection is set (note that the default
is an active 1-panel plot). Within each panel, plotting is exactly the same
as for a 1-panel plot. Fields may be superposed to generate multi-field
plots, colours may be added, colour bars and titles may be defined, et cetera.
Once the active panel displays the desired fields, activate `Options'=>`Overlay' mode and add the layer by pressing the newly-generated button (or by selecting the `Add Layer' option from the special menu). This will save the current panel and allow you to begin processing the next one. Back in the Multi-Panel window, select another panel for plotting, and begin to construct the fields for the new plot. Each time you generate the plot, all of the fields and panels will be replotted, but only the top layer will be active for modification. In this way, any number of panels may be added to a plot; however, only a limited number of layout options are available in the Multi-Panel window. Others must be added using Script Overrides (see section Script Overrides Page).
As for superposition mode, layers added in overlay mode may be removed if changes are required in a layer (panel) that has already been added. Under the special overlay (red) menu, select the `Remove Layer' option to remove the active layer and activate the next-most-recently submitted panel. This process may continue until you reach the layer in which changes are required. Again, the plotGEM data manager (see section Using the plotGEM Data Manager) will come in useful when changes are to be made in a deeply-layered panel.
The plotGEM data manager is a system which allows for the recovery of removed fields. It is useful in both `Superposition' and `Overlay' modes, or with a combination of the two (for example, a multi-panel plan plot with multiple fields in each panel). The data manager is always active in the background of the application, but only intervenes when the `Data'=>`Data Manager' button is selected. While the Data Manager is active, no new fields may be submitted or overlaid. However, any atribute of any previously-submitted or overlaid field may be changed. This makes the Data Manager a powerful tool when modifications are required for deeply-layered plots.
For example, suppose that superposition mode is used to generate two layers on a plan plot, the first of which has colour but no colour bar. After submitting the first layer and modifying the second to his/her liking, the user decides that a colour bar would be pretty (after all, isn't that what science is all about?). The user selects `Data'=>`Data Manager' to help with this modification. A window appears, showing the currently-submitted fields (two, in this case) in the order in which they were submitted. Either double-clicking on the desired field, or selecting the field and activating the `Modify' button will activate the field in question. All of the fields attributes are now modifiable in the usual plotGEM windows. Once the colour bar has been added, the user simply presses the `Exit' button on the Data Manager popup window (or de-select the `Data'=>`Memory Manager' menu entry) to continue editing the top level field.
In fact, a the development of a basic layout may prove to be the easiest way to begin a complex plot. Arrange fields into panels using superposition (on the same panel) and overlays (for different panels), all with the default colour and line settings. Once the desired layout is obtained, the Data Manager can be used to apply settings to the individual fields. Note that new fields cannot be added with the Data Manager active, and that all superposition and overlay options are deactivated once the manager is invoked. Of course, more fields can be added (or fields removed) once the Data Manager is turned off.
If multiple fields appear the same in the abbreviated field summary presented by the Data Manager in the popup window, additional details can be obtained by highlighting a field and pressing the `Details' button. This pops a separate window to provide additional information about the selected field.
The GEMPAK output shell is simply a window on the Shell notebook
page that displays the runtime output from the GEMPAK applications
executed by plotGEM. Instead of writing to the STDOUT of the shell from which the plotGEM
application was launched, the output from GEMPAK children is redirected
to this notebook page, allowing for quick reference to any informational, warning,
or error messages that the applications return. The output shell window is not
interactive, so no input is allowed in the output shell buffer. The the Shell
notebook page will be most useful when the plot generated by plotGEM and GEMPAK
fails to display the requested field.
This section contains a list of frequently asked questions about the plotGEM utility. If you are having trouble, and are unable to find answers in this list, feel free to post questions to the plotGEM mailing lists on the package distribution page (http://sourceforge.net/projects/activegem).
plotGEM -v. In this case, the
utility is not started, but the version information is printed to STDOUT.
plotGEM -h at the prompt. The utility will
not be started, but a list of valid options will be printed to STDOUT.
cannot open fileA+fileB, then chances are that
you'll have to apply the appropriate patch (provided with the
activeGEM distribution) before continuing. For more information on
how to install patches, see section Patches for GEMPAK Distribution. The appropriate patch
in this case is the activeGEM-multiFile.patch patch.
! character. Options are multiple
instances of GEMPAK scripts. More simply, any time that you want to put
multiple fields on the same map, you should use `Superposition', and any time that
you want to put multiple maps on a single layout, use the `Overlay' option. The
rules are somewhat different if you are in either the `Cross-Section' or the
`Profile' plotting modes due to various internal GEMPAK limitations.
In `Cross-Section' mode, only a single scalar and a single vector field may be
superposed; however, any number of fields may be overlaid. The situation is even
more dire in `Profile' mode, where no superposition is allowed (plotGEM will
warn you about this) but again many fields may be overlaid. Also, the plotting
and layering of station data on a `Plan Plot' field requires the use of
`Overlay' because a different GEMPAK application is invoked to accomplish
the station data plotting tasks. These are not
good enough reasons to always use `Overlay' instead of `Superposition' since
the overwriting of backgrounds in `Overlay' mode can lead to huge
output files which will make you very unpopular with anyone sharing a printer with you.
For more information on this topic, please see section Plotting Multiple Fields with plotGEM and
see section Plotting Multiple Panels with plotGEM.
Fixed Range colour option with a large range and
many colours, you may have hit the limit of the GEMPAK line
length (typically around 128). The plotGEM utility will warn you about
the long line, and will attempt to trim it on request (by reducing the
precision of the increment); however, extensions beyond the 128-letter
boundary may occur. In this case, it will be necessary to apply one
of the patches [see section Patches for GEMPAK Distribution]. Specifically, the
activeGEM-lineLength.patch patch will allow you to extend the line
to your heart's content (up to 512 characters). For more information on
installing the patches, please refer to the appropriate section.
The plotGEM GEMPAK plotting graphical interface is the only application packaged with version 1.7.0 of ActiveGEM. However, several activeGEM-oriented GEMPAK patches are included to enhance the performance of gempak in specific cirucmstances.
The GEMPAK patches are contained in the patches/GEMPAK
subdirectory of the ActiveGEM distribution. They are not automatically
installed at build-time since their application will depend on the
needs of the user, the GEMPAK version in use, and the
permissions required for GEMPAK configuration. All of the
patches in the activeGEM distribution are applied in the same way. First,
copy the patch (activeGEM-foo.patch where foo represents the
patch name) to the top-level directory of the GEMPAK distribution
(you may need special priviliges to do this). (The top-level directory
of the GEMPAK distribution is the one that contains the
Gemenviron setup script.) Then, enter the following commands (again
replacing foo with the name of the patch):
patch -p 0 -b -z .orig <$GEMPAK/../activeGEM-foo.patch make distclean make all >&make.out make install >&install.out
If you wish to apply multiple patches, then repeat the first (patching) step of this sequence for each patch before rebuliding the GEMPAK distribution. This will save you from rebuilding GEMPAK multiple times. A list of available patches, along with a brief description of each, is provided here.
activeGEM-lineLength.patch : This patch increases the allowable
line-length for input arguments to GEMPAK variables. This
is useful if you find that your colour ranges are being truncated
below the maximum value, and arises from the fact that there are several
places in the GEMPAK code where the maximum line length is
set to 128 characters (don't be fooled, it isn't only in GEMPRM.PRM).
If you have missing colours at either the top or the bottom of your
colour range, this patch is for you. The activeGEM-lineLength.patch
patch was created for GEMPAK version 5.7.2p2, but should
work with many recent GEMPAK releases.
activeGEM-multiFile.patch : This patch allows the user to
read from multiple files for plotting. If you ever want to open
multiple input files in activeGEM, then you will need to apply this
patch to GEMPAK. If you do not have this patch
installed and attempt to open multiple files, you will get
GEMPAK errors that warn of things like
cannot find fileA+fileB. The activeGEM-multiFile.patch
patch was created for GEMPAK version 5.7.2p2, but should
work with many recent GEMPAK releases. Note that there
seems to be a deficiency in GEMPAK at the root of this
problem; hopefully new releases of the GEMPAK package
will not require this hack. Try loading multiple files before
blindly applying this patch.
Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:
Copyright (C) year your name. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''.
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the "with...Texts." line with this:
with the Invariant Sections being list their titles, with
the Front-Cover Texts being list, and with the Back-Cover Texts
being list.
If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.
If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.
Jump to: a - c - d - e - f - g - i - l - m - o - p - q - s - t - u - v
This document was generated on 25 January 2005 using texi2html 1.56k.