grads-2.0.1/ 0000755 0001750 0001750 00000000000 12026403172 013741 5 ustar amckinstry amckinstry grads-2.0.1/Makefile.am 0000644 0001750 0001750 00000003561 11046315172 016005 0 ustar amckinstry amckinstry # Adding this will suppress the requirement for INSTALL, et c., files. AUTOMAKE_OPTIONS = foreign ACLOCAL_AMFLAGS = -I m4 ############################################################## # # Subdirectories with Makefiles # SUBDIRS=src EXTRA_DIST=COPYRIGHT INSTALL BINDISTFILES=COPYRIGHT INSTALL DATADISTFILES=data DOCDISTFILES=doc # Indicate that these targets are not the names of files .PHONY: nobin-dists all-dists snapshot-dist bin-dist snapshot-bin-dist \ data-dist doc-dist dist-all: dist data-dist doc-dist bin-dist: all-am $(MAKE) $(AM_MAKE_FLAGS) prefix=$(prefix)/$(distdir) install-exec; \ for file in $(BINDISTFILES) ; do \ cp -pR $$file $(distdir)/ ; \ done; \ rm -rf `find $(distdir) -name CVS`; \ $(AMTAR) chof - $(distdir) | GZIP=$(GZIP_ENV) gzip -c >$(distdir)-bin-$(host_triplet).tar.gz; \ $(am__remove_distdir) data-dist: mkdir -p $(distdir); \ for file in $(DATADISTFILES) ; do \ cp -pR $$file $(distdir)/ ; \ done; \ rm -rf `find $(distdir) -name CVS`; \ $(AMTAR) chof - $(distdir) | GZIP=$(GZIP_ENV) gzip -c >$(distdir)-data.tar.gz; \ $(am__remove_distdir) doc-dist: mkdir -p $(distdir); \ for file in $(DOCDISTFILES) ; do \ cp -pR $$file $(distdir)/ ; \ done; \ rm -rf `find $(distdir) -name CVS` $(AMTAR) chof - $(distdir) | GZIP=$(GZIP_ENV) gzip -c >$(distdir)-doc.tar.gz; \ $(am__remove_distdir) snapshot: distdir date_str=`date '+%Y%m%d-%H%M'`; \ $(AMTAR) chof - $(distdir) | GZIP=$(GZIP_ENV) gzip -c >$(distdir)-snapshot-$${date_str}.tar.gz; \ $(am__remove_distdir) bin-snapshot: all-am $(MAKE) $(AM_MAKE_FLAGS) prefix=$(prefix)/$(distdir) install-exec; \ for file in $(BINDISTFILES) ; do \ cp -pR $$file $(distdir)/ ; \ done; \ rm -rf `find $(distdir) -name CVS`; \ date_str=`date '+%Y%m%d-%H%M'`; \ $(AMTAR) chof - $(distdir) | GZIP=$(GZIP_ENV) gzip -c >$(distdir)-bin-snapshot-$${date_str}.tar.gz; \ $(am__remove_distdir) grads-2.0.1/INSTALL 0000644 0001750 0001750 00000004332 11044337100 014770 0 ustar amckinstry amckinstry GrADS - Grid Analysis and Display System Version 2.0 http://grads.iges.org/grads GrADS Executables for UNIX GrADS is distributed freely and is copyrighted under the GNU Public License. Please read the COPYRIGHT file for more complete information. For download information consult http://grads.iges.org/grads/downloads.html The executables contained in this tar file are typically placed in the directory /usr/local/bin. If you do not have write permission for your /usr/local/bin directory, you can put them in the ~/bin subdirectory of your home directory. cd /usr/local/bin gunzip tarfile.gz tar xvf tarfile After unpacking the first tar file, you should have the following executables: grads GrADS - The basic package gradsdap GrADS enabled to read data remotely via OPeNDAP gribmap Creates an index file that "maps" a GRIB data set for a GrADS descriptor file gribscan Extracts grid info from a GRIB data set grib2scan Extracts grid info from a GRIB2 data set bufrscan Reads BUFR messages and prints out ascii values gxps Converts GrADS metafiles to Postscript gxeps Converts GrADS metafiles to Encapsulated Postscript gxtran Displays metafiles stnmap Maps station data wgrib See http://www.cpc.ncep.noaa.gov/products/wesley/wgrib.html A second tar file (data.tar.Z) contains the GrADS fonts and maps data sets is also necessary and can be downloaded from http://grads.iges.org/grads/downloads.html. The contents of data.tar are typically placed in the directory /usr/local/lib/grads, the default location for these files. If you do not have write permission for /usr/local/lib/grads, you can place the files elsewhere, but you must also change the environment variable GADDIR so the GrADS executables will know where to find these files. cd dirname uncompress data.tar.Z tar xvf data.tar setenv GADDIR dirname (If dirname is not /usr/local/lib/grads) Documentation and Additional Information ---------------------------------------- Consult the GrADS homepage http://grads.iges.org/grads grads-2.0.1/bootstrap 0000755 0001750 0001750 00000000173 07701361322 015711 0 ustar amckinstry amckinstry #!/bin/sh mkdir -p etc aclocal autoheader touch config.h.in touch src/stamp-h automake -i --foreign --add-missing autoconf grads-2.0.1/doc/ 0000755 0001750 0001750 00000000000 11651523373 014517 5 ustar amckinstry amckinstry grads-2.0.1/doc/gradcomddrawrecf.html 0000644 0001750 0001750 00000000655 10243410766 020706 0 ustar amckinstry amckinstry
draw recf xlo ylo xhi yhi
Draws a filled rectangle in the area described by xlo, ylo, xhi,
yhi
. The fill color is the current line drawing attribute
color
.
grads-2.0.1/doc/advhardcopy.html 0000644 0001750 0001750 00000000212 10243410766 017701 0 ustar amckinstry amckinstry works grads-2.0.1/doc/gradcomdsetxlopts.html 0000644 0001750 0001750 00000001467 11632442207 021156 0 ustar amckinstry amckinstry
set xlopts color <thickness <size>>
Controls aspects of axis display
xlopts
controls
the X Axiscolor
Label
color (Default 1) thickness
Label
thickness (Default 3) size
Label size (Default 0.11)
grads-2.0.1/doc/gradcomdsetparea.html 0000644 0001750 0001750 00000002401 10243410766 020704 0 ustar amckinstry amckinstry
set parea xmin xmax ymin ymax
The command specifies the area for plotting contour plots, maps, or line graphs. This area does not include axis labels, titles, etc., so if you need to see those, provide for an adequate margin.
The region is specified in terms of virtual page units. By default, the virtual page is equal to the real page, so the units are approximately inches on the real page.
Maps are scaled to fit within the plotting area such that their correct aspect ratio is maintained. Thus, the map will not fill the entire plotting area except under certain lat/lon ranges. A line graph or a contour plot without a map will be scaled to fit entirely within the specified plotting area.
By default, an appropriate plotting area is chosen depending on the type of graphics output. To return to this default, enter:
set parea off
It is not appropriate to use this command to put multiple plots on one
page. It is better to use the set
vpage
command.
grads-2.0.1/doc/grib_levels.html 0000644 0001750 0001750 00000040572 10526115561 017706 0 ustar amckinstry amckinstry
TABLE 3: VERTICAL LEVELS
VALUE | DESCRIPTION | REQUIRED PARAMETERS | ABBREV. | |
0-99 | Special Codes | (See Table 3a below) | ||
100 | Isobaric level | Pressure in hPa (2 octets) | ISBL | |
101 | Layer between two isobaric levels | Pressure of top in kPa |
Pressure of bottom in kPa |
|
102 | Mean sea level | 0 | 0 | MSL |
103 | Specified altitude above MSL | Altitude in meters | GPML | |
104 | Layer between two specified altitudes above MSL | Altitude of top in hm |
Altitude of bottom in hm |
GPMY |
105 | Specified height level above ground | Height in meters | TGL | |
106 | Layer between two specified height levels above ground | Height of top in hm |
Height of bottom in hm |
HTGY |
107 | Sigma level | Sigma value in 1/10000 (2 octets) | SIGL | |
108 | Layer between two sigma levels | Sigma value at top in 1/100 |
Sigma value at bottom in 1/100 |
SIGY |
109 | Hybrid level | Level number (2 octets) | HYBL | |
110 | Layer between two hybrid levels | Level number of top | Level number of bottom | HYBY |
111 | depth below land surface | Depth in cm (2 octets) | DBLL | |
112 | Layer between two depths below land surface |
Depth of upper surface |
Depth of lower surface |
DBLY |
113 | Isentropic (theta) level | Potential temperature in K | THEL | |
114 | Layer between two isentropic levels |
475 K minus theta of top |
475 K minus theta of bottom in K | THEY |
115 | Level at specified pressure difference from ground | Pressure difference in hPa (2 octets) | SPDL | |
116 | Layer between two levels at specified pressure difference from ground | Pressure difference from ground to top in hPa | Pressure difference from ground to bottom in hPa | SPDY |
117 | Potential vorticity surface | Potential vorticity value in units of 10-6 K m2/kg s | PVL | |
119 | ETA level | ETA value in 1/1000 (2 octets) | ETAL | |
120 | Layer between two ETA levels | ETA value at top in 1/100 |
ETA value at bottom in 1/100 |
ETAY |
121 | Layer between two isobaric surfaces (high precision) | 1100 minus pressure of top in hPa |
1100 minus pressure of bottom in hPa |
IBYH |
125 | Specified height level above
ground (high precision) |
Height in cm (2 octets) | HGLH | |
128 | Layer between two sigma levels
(high precision) |
1.1 minus sigma of top in 1/1000 of sigma |
1.1 minus sigma of bottom
in 1/1000 of sigma |
SGYH |
141 | Layer between two isobaric surfaces (mixed precision) | Pressure of top in hPa | 1100 minus pressure of bottom in hPa | IBYM |
160 | Depth below sea level | Depth in m (2 octets) | DBSL | |
200 | Entire atmosphere | 0 (2 octets) | EATM | |
201 | Entire ocean | 0 (2 octets) | EOCN | |
204-244 | NCEP Special Levels & Layers | See Table 3a |
TABLE 3a: SPECIAL VERTICAL LEVELS
VALUE | DESCRIPTION | ABBREV. |
00 | Reserved | |
01 | Ground or water surface | SFC |
02 | Cloud base level | CBL |
03 | Cloud top level | CTL |
04 | Level of 0 deg (C) isotherm | 0DEG |
05 | Level of adiabatic condensation lifted from the surface | ADCL |
06 | Maximum wind level | MWSL |
07 | Tropopause | TRO |
08 | Nominal top of atmosphere | NTAT |
09 | Sea bottom | SEAB |
10-19 | Reserved | |
20 | Isothermal level (temperature in 1/100 K in octets 11 and 12) | TMPL |
21-99 | Reserved | |
204 | Highest tropospheric freezing level | HTFL |
209 | Boundary layer cloud bottom level | BCBL |
210 | Boundary layer cloud top level | BCTL |
211 | Boundary layer cloud layer | BCY |
212 | Low cloud bottom level | LCBL |
213 | Low cloud top level | LCTL |
214 | Low cloud layer | LCY |
222 | Middle cloud bottom level | MCBL |
223 | Middle cloud top level | MCTL |
224 | Middle cloud layer | MCY |
232 | High cloud bottom level | HCBL |
233 | High cloud top level | HCTL |
234 | High cloud layer | HCY |
242 | Convective cloud bottom level | CCBL |
243 | Convective cloud top level | CCTL |
244 | Convective cloud layer | CCY |
grads-2.0.1/doc/gradcomdsetxyzte.html 0000644 0001750 0001750 00000004461 11632442207 021005 0 ustar amckinstry amckinstry
set x|y|z|t|e val1 <val2>
This sets one dimension of the dimension environment using grid
coordinates. You may use whatever coordinates are convenient to you.
Issuing set lon
is equivalent to issuing set x
,
both set the x
dimension. The difference is only the units
you wish to use when entering the command.
When you enter just one value, that dimension is said to be "fixed". When you enter two values, that dimension is said to be "varying". The combination of fixed and varying dimensions defines the dimension environment.
The 'set e' command is only available in GrADS version 2.0+, when the ensemble dimension was introduced.
An important note: When you enter dimensions in grid coordinates, they are always converted to world coordinates. This conversion requires some knowledge of what scaling is in use for grid to world conversions. The scaling that is used in all cases (except one) is the scaling of the DEFAULT FILE. The exception is when you supply a dimension expression within a variable specification.
If you are setting the T or E dimension using grid coordinates, the value given in val1
or
val2
may be the word "last" to set the dimension to the max value of that grid coordinate.
set t 1
This sets time to the first time in the data set -- using
grid coordinates. T is now a fixed
dimension.
set z 1 4
This sets the vertical dimension to vary between the first and the fourth levels in the data set -- using
grid coordinates. Z is now a varying
dimension.
set t 1 last
This sets time to vary between the first and the last time in the data set -- using
grid coordinates. T is now a varying
dimension.
set e last
This sets the ensemble to the final member in the data set. E is now a fixed
dimension.
grads-2.0.1/doc/gradfuncsmth9.html 0000644 0001750 0001750 00000001761 10243410766 020165 0 ustar amckinstry amckinstry
smth9(expr)
Performs a 9 point smoothing to the gridded result of the
expr
.
grads-2.0.1/doc/font.html 0000644 0001750 0001750 00000006343 11416646527 016367 0 ustar amckinstry amckinstry
font0.dat
, font1.dat
, etc. If you create
a font6.dat
file (or 7 through
9) and put it in the same place as the other font
files, you can use that font immediately, by using the set font
command, or via font escape sequences.
The font files are in an ASCII format. Each file is 95 records in length. Each record represents a character in the font, and the records are ordered in the order of ASCII code values, starting with the blank (code value 32 decimal). So the last record represents the tilde, the 17th record the zero, etc. So when you are using the font the file represents, and enter a zero character, the character in the 17th record is plotted, whatever it may be.
Each record starts with a 3 character number. This is the number of code pairs in the record. This number is followed by the indicated number of code pairs. Each code pair is two characters. Each character represents a value, which is determined as an offset from the Capital R (decimal 82). So, if the character is Capital L, it represents a value of -6. If the character is a lower case k, it represents a value of +25.
The first code pair represents the horizontal extent of the character. So the first character of the code pair would be the minimum X, and the 2nd character the maximum X. If I remember correctly, this extent should include white space. This is followed by code pairs that represent drawing positions in X and Y, where the first character is X, and the 2nd Y. A "pen up" is indicated by the code pair " R" (blank, followed by capital R).
You can look at the existing font files for examples.
If you look at
font0.dat
, the first record represents the blank. It
thus has one code
pair, which just represents the width of the blank in
the font, thus
allocating white space when a blank is encountered. If
you look at
record 57
(which represents Cap X), you see:
6H\KFY[ RYFK[
Decoding this, you see there are 6 code pairs. The
first is the
width extent, H\
, which is -10 to 10. The next two
pairs, KFY[
,
are points -7,-12 and 7,9. So a line would be drawn
between those
two points (appropriate scaled). The next code pair
indicates pen up,
followed by YFK[
, which are 7,-12 and -7,9.
You can see the horizontal extent does not match too well with the actual character. I am not quite sure why this is, nor why the character is not centered. This is the way the fonts came, so I assume there are some font design issues involved.
If you want to design your own font, you will need to
review the
code GraDS uses to actually plot these fonts, which is
gxchpl.c
.
I determined scale factors and centering issues by trial
and error, and
these values are contained in the code.
grads-2.0.1/doc/gradfuncmaskout.html 0000644 0001750 0001750 00000003556 10243410766 020610 0 ustar amckinstry amckinstry
maskout(expr,mask)
Wherever the mask
values are less than zero, the
values in expr
are set to the missing data value.
Works with gridded or station data. Where mask
values
are positive, the expr
values are not modified. Thus
the result of maskout
is data with a possibly increased
number of missing data values. The maskout
function, in spite
of its apparant simplicity, is extremely useful.
const
function for a
description
of using maskout
to calculate the percentage of the globe
covered by precipitation.
maskout
function can be used to cause part of the
data to be ignored while doing another calculation. For example, if we
have a land-sea mask, where sea values are negative, and we want to take
some areal average of a quantity only over land:
d aave(maskout(p,mask.2),lon=0,lon=360,lat=0,lat=90)
d aave(maskout(p,mask.2(t=1)),lon=0,lon=360,lat=0,lat=90)
would probably be how Example 2 would have to be expressed in order to
work, with the local override of t=1
specified on the mask
data. See the documentation on how GrADS evaluates expressions within the
dimension environment for more information.
grads-2.0.1/doc/gradutilncdump.html 0000644 0001750 0001750 00000017642 10243410766 020436 0 ustar amckinstry amckinstry
ncdump [-c] [-h] [-v var1,...] [-b lang] [-f
lang] [-l len]
[-n name] [-d f_digits[,d_digits]]
file
Where:
-c
-h
-c
option except that the values of coordinate variables are not
included. (At most one of -c
or -h
options
may be present.)
-v var1,...,varn
-c
or -h
options, is to
include data values for all variables in the output.
-b lang
lang
begins with
C
or c
, then C language conventions will be
used (zero-based indices, last dimension varying fastest). If
lang
begins with F
or f
,
then Fortran language conventions will be used (one-based indices,
first dimension varying fastest). In either case, the data will be
presented in the same order; only the annotations will differ. This
option is useful for browsing through large volumes of
multidimensional data.
-f lang
lang
begins with C
or
c
, then C language conventions will be used (zero-based
indices, last dimension varying fastest). If lang
begins with F
or f
, then Fortran language
conventions will be used (one-based indices, first dimension varying
fastest). In either case, the data will be presented in the same
order; only the annotations will differ. This option may be useful
for piping data into other filters, since each data value appears on a
separate line, fully identified.
-l len
-n name
ncgen -b
in generating a default
netCDF file name. By default, ncdump
constructs this name
from the last component of the pathname of the input netCDF file by
stripping off any extension it has. Use the -n
option to
specify a different name. Although the output file name used by ncgen -b
can be specified, it may
be wise to have ncdump
change the default name to avoid
inadvertantly overwriting a valuable netCDF file when using
ncdump
, editing the resulting CDL file, and using ncgen -b
to generate a new netCDF
file from the edited CDL file.
-d float_digits[,double_digits]
float_digits
significant digits.
If double_digits
is also specified,
double-precision values will be displayed with that many significant
digits. If a variable has a `C_format' attribute, that overrides any
specified floating-point default. In the absence of any
-d
specifications, floating-point and double- precision
data are displayed with 7 and 15 significant digits respectively. CDL
files can be made smaller if less precision is required. If both
floating-point and double-presision precisions are specified, the two
values must appear separated by a comma (no blanks) as a single
argument to the command. If you really want every last bit of
precision from the netCDF file represented in the CDL file for all
possible floating- point values, you will have to specify this with
-d 9,17
.
ncdump
generates an ASCII representation of a specified
netCDF file on standard output. The ASCII representation is in a form
called CDL
(``network Common Data form Language'') that
can be viewed, edited, or serve as input to ncgen
. ncgen
is a companion program that
can generate a binary netCDF file from a CDL
file. Hence
ncgen
and ncdump
can be used as inverses to transform the data representation between
binary and ASCII representations. See ncgen
for a description of CDL and
netCDF representations.
ncdump
defines a default format used for each type of
netCDF data, but this can be changed if a `C_format' attribute is
defined for a netCDF variable. In this case, ncdump
will
use the `C_format' attribute to format each value. For example, if
floating-point data for the netCDF variable Z
is known to
be accurate to only three significant digits, it would be appropriate
to use the variable attribute
Z:C_format =
"%.3g"
ncdump
may also be used as a simple
browser for netCDF data files, to display the dimension names and
sizes; variable names, types, and shapes; attribute names and values;
and optionally, the values of data for all variables or selected
variables in a netCDF file.
Examples
foo.nc
:
ncdump -c foo.nc
foo.nc
, using C-style indexing for
the
annotations:
ncdump -b c foo.nc > foo.cdl
uwind
and
vwind
from
the netCDF file foo.nc
, and show the floating-point
data
with only three significant digits of precision:
ncdump -v uwind,vwind -d 3 foo.nc
omega
, using Fortran
conventions for indices, and changing the netCDF dataset name in
the resulting CDL file to omega
:
ncdump -v omega -f fortran -n omega foo.nc > Z.cdl
GrADS supports two types of data grids:
lon/lat
grids (and not necessarily regular,
e.g., gaussian);
When preprojected grids are opened in GrADS, bilinear
interpolation constants are calculated and all date are displayed
on an internal GrADS lat/lon grid defined by the
xdef
and ydef
card in the data description or .ctl
file (that's
why it takes
longer to "open" a preprojected grid data set).
It is very important to point out that the internal GrADS grid
can be any grid as it is completely independent of the
preprojected data grid. Thus, there is nothing
stopping you
displaying preprojected data on a very high res
lon/lat grid
(again, defined in the .ctl
by xdef
and ydef
). In fact, you
could create and open multiple .ctl files with different
resolutions and/or regions which pointed to the same
preprojected
data file.
When you do a display
(i.e., get a grid of data), the
preprojected data are bilinearly interpolated to
the GrADS
internal lat/lon grid. For
preprojected
scalar fields (e.g., 500
mb heights), the display is adequate and the precision of the
interpolation can be controlled by xdef
and
ydef
to define a
higher spatial resolution grid.
The big virtue of this approach is that all built in GrADS
analytic functions (e.g., aave
,
hcurl
...)
continue to work even
though the data were not originally on a lon/lat grid. The
downside is that you are not looking directly at your data on a
geographic map. However, one could always define a .ctl file
which simply opened the data file as i,j data and displayed
without the map (set
mpdraw
off). So, in my opinion, this
compromise is not that limiting even if as a modeller you wanted
to look at the grid--you just don't get the map background.
Preprojected vector fields
are a little trickier,
depending on
whether the vector is defined relative to the data grid or
relative to the Earth. For example, NMC polar stereo grids use
winds relative to the data grid and thus must be rotated to the
internal GrADS lat/lon grid (again defined in the
.ctl
file by
the xdef
and ydef
cards).
The only potential problem with working with preprojected data
(e.g., Lambert Conformal model data) is defining the projection
for GrADS. This is accomplished using a pdef
card
in the data
descriptor .ctl
file.
pdef
card
is:
pdef isize jsize projtype ipole jpole lonref gridinc
pdef 53 45 nps 27 49 -105 190.5
where,
ipole
and jpole
are the (i,j) of
the pole referenced from the lower left corner at (1,1) and gridinc
is the dx
in km.The relevant GrADS source is:
float re,xlat,wlong,r;
} else {
void w3fb04 (float alat, float along, float xmeshl, float
orient,
float *xi, float *xj) {
/*
C
C SUBPROGRAM: W3FB04 LATITUDE, LONGITUDE TO GRID
COORDINATES
C AUTHOR: MCDONELL,J.
ORG: W345 DATE: 90-06-04
C
C ABSTRACT: CONVERTS THE
COORDINATES OF A LOCATION ON EARTH FROM THE
C NATURAL
COORDINATE SYSTEM OF LATITUDE/LONGITUDE TO THE GRID (I,J)
C
COORDINATE SYSTEM OVERLAID ON A POLAR STEREOGRAPHIC MAP PRO
C
JECTION TRUE AT 60 DEGREES N OR S LATITUDE. W3FB04 IS THE
REVERSE
C OF W3FB05.
C
C PROGRAM HISTORY LOG:
C 77-05-01 J.
MCDONELL
C 89-01-10 R.E.JONES CONVERT TO MICROSOFT FORTRAN 4.1
C
90-06-04 R.E.JONES CONVERT TO SUN FORTRAN 1.3
C
93-01-26 B.
Doty converted to
C
C
C USAGE: CALL W3FB04 (ALAT,
ALONG,
XMESHL, ORIENT, XI, XJ)
C
C INPUT VARIABLES:
C
NAMES
INTERFACE DESCRIPTION OF VARIABLES AND TYPES
C ------
--------- -----------------------------------------------
C
ALAT ARG LIST LATITUDE IN DEGREES (<0 IF SH)
C ALONG
ARG
LIST WEST LONGITUDE IN DEGREES
C XMESHL ARG LIST MESH
LENGTH OF GRID IN KM AT 60 DEG LAT(<0 IF SH)
C
(190.5 LFM GRID, 381.0 NH PE GRID,-381.0 SH PE GRID)
C
ORIENT
ARG LIST ORIENTATION WEST LONGITUDE OF THE GRID
C
(105.0 LFM GRID, 80.0 NH PE GRID, 260.0 SH PE GRID)
C
C
OUTPUT VARIABLES:
C NAMES INTERFACE DESCRIPTION OF
VARIABLES
AND TYPES
C ------ ---------
-----------------------------------------------
C XI
ARG
LIST I OF THE POINT RELATIVE TO NORTH OR SOUTH POLE
C
XJ
ARG LIST J OF THE POINT RELATIVE TO NORTH OR SOUTH POLE
C
C
SUBPROGRAMS CALLED:
C NAMES
LIBRARY
C
------------------------------------------------------- --------
C COS SIN
SYSLIB
C
C REMARKS: ALL PARAMETERS IN THE CALLING
STATEMENT
MUST BE
C REAL. THE RANGE OF ALLOWABLE LATITUDES IS
FROM A
POLE TO
C 30 DEGREES INTO THE OPPOSITE HEMISPHERE.
C THE
GRID USED IN THIS SUBROUTINE HAS ITS ORIGIN (I=0,J=0)
C
AT
THE POLE IN EITHER HEMISPHERE, SO IF THE USER'S GRID HAS ITS
C
ORIGIN AT A POINT OTHER THAN THE POLE, A TRANSLATION IS NEEDED
C
TO GET I AND J. THE GRIDLINES OF I=CONSTANT ARE PARALLEL TO A
C
LONGITUDE DESIGNATED BY THE USER. THE EARTH'S RADIUS IS TAKEN
C TO BE 6371.2 KM.
C
C ATTRIBUTES:
C
LANGUAGE: SUN FORTRAN
1.4 C MACHINE: SUN SPARCSTATION 1+
C*/
static float
radpd =
0.01745329;
static float earthr = 6371.2;
re = (earthr * 1.86603) / xmeshl;
xlat
= alat * radpd;
if (xmeshl>0.0) {
wlong =
(along + 180.0 -
orient) * radpd;
r =
(re * cos(xlat)) / (1.0 +
sin(xlat));
*xi =
r * sin(wlong);
*xj = r *
cos(wlong);
re = -re;
xlat =
-xlat;
wlong = (along - orient) *
radpd;
r =
(re * cos(xlat)) / (1.0+ sin(xlat));
*xi =
r *
sin(wlong);
*xj =
-r * cos(wlong);
}
}
A typical NORAPS Lambert-Conformal grid is described below, including the C code which sets up the internal interpolation.
The .ctl
file is:
dset ^temp.grd
title NORAPS DATA TEST
undef 1e20
pdef 103 69 lcc 30 -88 51.5 34.5 20 40 -88 90000 90000
xdef 180 linear -180 1.0
ydef 100 linear -10 1.0
zdef 16 levels 1000 925 850 700 500 400 300 250 200 150 100 70
50 30 20 10
tdef 1 linear 00z1jan94 12hr
vars 1
t 16 0 temp
endvars
where,
103
= #pts in x 69
= #pts in y lcc
= Lambert-Conformal 30
= lat of ref point 88
= lon of ref point (E is positive, W is negative) 51.5
= i of ref point 34.5
= j of ref point 20
= S true lat 40
= N true lat 88
= standard lon 90000 
= dx in M 90000 
= dy in M
Otherwise, it is the same as other GrADS files.
Note - the xdef/ydef
apply to the
lon/lat
grid GrADS internally interpolates to and
can be anything...
The GrADS source which maps lon/lat
of the GrADS
internal lon/lat
grid to i,j
of the preprojected grid is:
/* Lambert Conformal conversion */
void ll2lc (float *vals, float grdlat, float grdlon,
float *grdi, float *grdj) {
/* Subroutine to convert from lat-lon to Lambert Conformal i,j.
Provided by NRL Monterey; converted to C 6/15/94.
c SUBROUTINE: ll2lc
c
c PURPOSE: To compute i- and j-coordinates of a specified
c grid given the latitude and longitude points.
c All latitudes in this routine start
c with -90.0 at the south pole and increase
c northward to +90.0 at the north pole. The
c longitudes start with 0.0 at the Greenwich
c meridian and increase to the east, so that
c 90.0 refers to 90.0E, 180.0 is the inter-
c national dateline and 270.0 is 90.0W.
c
c INPUT VARIABLES:
c
c vals+0 reflat: latitude at reference point (iref,jref)
c
c vals+1 reflon: longitude at reference point (iref,jref)
c
c vals+2 iref: i-coordinate value of reference point
c
c vals+3 jref: j-coordinate value of reference point
c
c vals+4 stdlt1: standard latitude of grid
c
c vals+5 stdlt2: second standard latitude of grid (only required
c if igrid = 2, lambert conformal)
c
c vals+6 stdlon: standard longitude of grid (longitude that
c points to the north)
c
c vals+7 delx: grid spacing of grid in x-direction
c for igrid = 1,2,3 or 4, delx must be in meters
c for igrid = 5, delx must be in degrees
c
c vals+8 dely: grid spacing (in meters) of grid in y-direction
c for igrid = 1,2,3 or 4, delx must be in meters
c for igrid = 5, dely must be in degrees
c
c grdlat: latitude of point (grdi,grdj)
c
c grdlon: longitude of point (grdi,grdj)
c
c grdi: i-co ordinate(s) that this routine will generate
c information for
c
c grdj: j-coordinate(s) that this routine will generate
c information for
c
*/
float pi, pi2, pi4, d2r, r2d, radius, omega4;
float gcon,ogcon,ahem,deg,cn1,cn2,cn3,cn4,rih,xih,yih,rrih,check;
float alnfix,alon,x,y;
pi = 4.0*atan(1.0);
pi2 = pi/2.0;
pi4 = pi/4.0;
d2r = pi/180.0;
r2d = 180.0/pi;
radius = 6371229.0;
omega4 = 4.0*pi/86400.0;
/*mf -------------- mf*/
/*case where standard lats are the same */
if(*(vals+4) == *(vals+5)) {
gcon = sin(*(vals+4)*d2r);
} else {
gcon = (log(sin((90.0-*(vals+4))*d2r))
log(sin((90.0-*(vals+5))*d2r)))
/(log(tan((90.0-*(vals+4))*0.5*d2r))
log(tan((90.0-*(vals+5))*0.5*d2r)));
}
/*mf -------------- mf*/
ogcon = 1.0/gcon;
ahem = fabs(*(vals+4))/(*(vals+4));
deg = (90.0-fabs(*(vals+4)))*d2r;
cn1 = sin(deg);
cn2 = radius*cn1*ogcon;
deg = deg*0.5;
cn3 = tan(deg);
deg = (90.0-fabs(*vals))*0.5*d2r;
cn4 = tan(deg);
rih = cn2*pow((cn4/cn3),gcon);
deg = (*(vals+1)-*(vals+6))*d2r*gcon;
xih = rih*sin(deg);
yih = -rih*cos(deg)*ahem;
deg = (90.0-grdlat*ahem)*0.5*d2r;
cn4 = tan(deg);
rrih = cn2*pow((cn4/cn3),gcon);
check = 180.0-*(vals+6);
alnfix = *(vals+6)+check;
alon = grdlon+check;
while (alon<0.0) alon = alon+360.0;
while (alon>360.0) alon = alon-360.0;
deg = (alon-alnfix)*gcon*d2r;
x = rrih*sin(deg);
y = -rrih*cos(deg)*ahem;
*grdi = *(vals+2)+(x-xih)/(*(vals+7));
*grdj = *(vals+3)+(y-yih)/(*(vals+8));
}
Wind rotation has also been added so that vector data will be properly displayed.
The pdef card for a typical eta model grid is:
pdef 181 136 eta.u -97.0 41.0 0.38888888 0.37037037
181
= #pts in x
136
= #pts in y
eta.u
= eta grid, unstaggered
-97.0
= lon of ref point (E is positive in GrADS, W
is negative)
[deg]
41.0
= lat of ref point [deg]
0.3888
= dlon [deg]
0.37037
= dlat [deg]
The source code in GrADS for the lon,lat -> i,j mapping is:
void ll2eg (int im, int jm, float *vals, float grdlon, float grdlat, float *grdi, float *grdj, float *alpha) { /* Subroutine to convert from lat-lon to NMC eta i,j. Provided by Eric Rogers NMC; converted to C 3/29/95 by Mike Fiorino. c SUBROUTINE: ll2eg c c PURPOSE: To compute i- and j-coordinates of a specified c grid given the latitude and longitude points. c All latitudes in this routine start c with -90.0 at the south pole and increase c northward to +90.0 at the north pole. The c longitudes start with 0.0 at the Greenwich c meridian and increase to the east, so that c 90.0 refers to 90.0E, 180.0 is the inter- c national dateline and 270.0 is 90.0W. c c INPUT VARIABLES: c c vals+0 tlm0d: longitude of the reference center point c c vals+1 tph0d: latitude of the reference center point c c vals+2 dlam: dlon grid increment in deg c c vals+3 dphi: dlat grid increment in deg c c c grdlat: latitude of point (grdi,grdj) c c grdlon: longitude of point (grdi,grdj) c c grdi: i-coordinate(s) that this routine will generate c information for c c grdj: j-coordinate(s) that this routine will generate c information for c */ float pi,d2r,r2d, earthr; float tlm0d,tph0d,dlam,dphi; float phi,lam,lame,lam0,phi0,lam0e,cosphi,sinphi,sinphi0,cosphi0,sinlam r,cos lamr; float x1,x,y,z,bigphi,biglam,cc,num,den,tlm,tph; int idim,jdim; pi=3.141592654; d2r=pi/180.0; r2d=1.0/d2r; earthr=6371.2; tlm0d=-*(vals+0); /* convert + W to + E, the grads standard for longitude */ tph0d=*(vals+1); dlam=(*(vals+2))*0.5; dphi=(*(vals+3))*0.5; /* grid point and center of eta grid trig */ /* convert to radians */ phi = grdlat*d2r; lam = -grdlon*d2r; /* convert + W to + E, the grads standard for longitude */ lame = (grdlon)*d2r; phi0 = tph0d*d2r; lam0 = tlm0d*d2r; lam0e = ( 360.0 + *(vals+0) )*d2r; /* cos and sin */ cosphi = cos(phi); sinphi = sin(phi); sinphi0 = sin(phi0); cosphi0 = cos(phi0); sinlamr=sin(lame-lam0e); coslamr=cos(lame-lam0e); x1 = cosphi*cos(lam-lam0); x = cosphi0*x1+sinphi0*sinphi; y = -cosphi*sin(lam-lam0); z = -sinphi0*x1+cosphi0*sinphi; /* params for wind rotation alpha */ cc=cosphi*coslamr; num=cosphi*sinlamr; den=cosphi0*cc+sinphi0*sinphi; tlm=atan2(num,den); /* parms for lat/lon -> i,j */ bigphi = atan(z/(sqrt(x*x+y*y)))*r2d; biglam = atan(y/x)*r2d; idim = im*2-1; jdim = jm*2-1 ; *grdi = (biglam/dlam)+(idim+1)*0.5; *grdj = (bigphi/dphi)+(jdim+1)*0.5; *grdi = (*grdi+1)*0.5-1; *grdj = (*grdj+1)*0.5-1; *alpha = asin( ( sinphi0*sin(tlm)) / cosphi ) ; /* printf("qqq %6.2f %6.2f %6.2f %6.2f %g %g %g %g\n", grdlon,grdlat,*grdi,*grdj,*alpha,tlm*r2d,cosphi,sinphi0); */ }
Wind rotation has not been implemented!!! Use only for scalar fields.
pdef ni nj pse slat slon polei polej dx dy sgn
ni
= # points in x
nj
= # points in y
slat
= absolute value of the standard latitude
slon
= absolute value of the standard longitude
pse
= polar stereo,
"eccentric"
polei
= x index position of the pole (where (0,0) is the
index of the first point vice the more typical (1,1) )
polej
= y index position of the pole (where (0,0) is the
index of the first point vice the more typical (1,1) )
dx
= delta x in km
dy
= delta y in km
sgn
= 1 for N polar stereo and -1
for S polar
stereo
Source code in GrADS for the lon,lat -> i,j mapping:
void ll2pse (int im, int jm, float *vals, float lon, float lat, float *grdi, float *grdj) { /* Convert from geodetic latitude and longitude to polar stereographic grid coordinates. Follows mapll by V. J. Troisi. */ /* Conventions include that slat and lat must be absolute values */ /* The hemispheres are controlled by the sgn parameter */ /* Bob Grumbine 15 April 1994. */ const rearth = 6738.273e3; const eccen2 = 0.006693883; const float pi = 3.141592654; float cdr, alat, along, e, e2; float t, x, y, rho, sl, tc, mc; float slat,slon,xorig,yorig,sgn,polei,polej,dx,dy; slat=*(vals+0); slon=*(vals+1); polei=*(vals+2); polej=*(vals+3); dx=*(vals+4)*1000; dy=*(vals+5)*1000; sgn=*(vals+6); xorig = -polei*dx; yorig = -polej*dy; /*printf("ppp %g %g %g %g %g %g %g\n",slat,slon,polei,polej,dx,dy,sgn);*/ cdr = 180./pi; alat = lat/cdr; along = lon/cdr; e2 = eccen2; e = sqrt(eccen2); if ( fabs(lat) > 90.) { *grdi = -1; *grdj = -1; return; } else { t = tan(pi/4. - alat/2.) / pow( (1.-e*sin(alat))/(1.+e*sin(alat)) , e/2.); if ( fabs(90. - slat) < 1.E-3) { rho = 2.*rearth*t/ pow( pow(1.+e,1.+e) * pow(1.-e,1.-e) , e/2.); } else { sl = slat/cdr; tc = tan(pi/4.-sl/2.) / pow( (1.-e*sin(sl))/(1.+e*sin(sl)), (e/2.) ); mc = cos(sl)/ sqrt(1.-e2*sin(sl)*sin(sl) ); rho = rearth * mc*t/tc; } x = rho*sgn*cos(sgn*(along+slon/cdr)); y = rho*sgn*sin(sgn*(along+slon/cdr)); *grdi = (x - xorig)/dx+1; *grdj = (y - yorig)/dy+1; /*printf("ppp (%g %g) (%g %g %g) %g %g\n",lat,lon,x,y,rho,*grdi,*grdj);*/ return; } }
pdef 26 16 ops 40.0 -100.0 90000.0 90000.0 14.0 9.0 180000.0
180000.0
26
= #pts in x
16
= #pts in y
ops
=
oblique polar
stereo
40.0
= lat of ref
point (14.0, 9.0)
-100.0
= lon of ref point (14.0, 9.0 (E is
positive in
GrADS, W is negative)
90000.0
= xref offset [m]
90000.0
= yref offset [m]
14.0
= i of ref point
9.0
= j of
ref
point
180000.0
= dx [m]
180000.0
= dy [m]
Wind rotation has not been implemented!!! Use only for scalar fields.
Source code in GrADS for the lon,lat -> i,j mapping:
void ll2ops(float *vals, float lni, float lti, float *grdi, float *grdj)
{
const float radius = 6371229.0 ;
const float pi = 3.141592654;
float stdlat, stdlon, xref, yref, xiref, yjref, delx , dely;
float plt,pln;
double pi180,c1,c2,c3,c4,c5,c6,arg2a,bb,plt1,alpha,
pln1,plt90,argu1,argu2;
double hsign,glor,rstdlon,glolim,facpla,x,y;
stdlat = *(vals+0);
stdlon = *(vals+1);
xref = *(vals+2);
yref = *(vals+3);
xiref = *(vals+4);
yjref = *(vals+5);
delx = *(vals+6);
dely = *(vals+7);
c1=1.0 ;
pi180 = asin(c1)/90.0;
/*
c
c set flag for n/s hemisphere and convert longitude to <0 ; 360>
interval
c
*/
if(stdlat >= 0.0) {
hsign= 1.0 ;
} else {
hsign=-1.0 ;
}
/*
c
c set flag for n/s hemisphere and convert longitude to <0 ; 360>
interval
c
*/
glor=lni ;
if(glor <= 0.0) glor=360.0+glor ;
rstdlon=stdlon;
if(rstdlon < 0.0) rstdlon=360.0+stdlon;
/*
c
c test for a n/s pole case
c
*/
if(stdlat == 90.0) {
plt=lti ;
pln=fmod(glor+270.0,360.0) ;
goto l2000;
}
if(stdlat == -90.0) {
plt=-lti ;
pln=fmod(glor+270.0,360.0) ;
goto l2000;
}
/*
c
c test for longitude on 'greenwich or date line'
c
*/
if(glor == rstdlon) {
if(lti > stdlat) {
plt=90.0-lti+stdlat;
pln=90.0;
} else {
plt=90.0-stdlat+lti;
pln=270.0;;
}
goto l2000;
}
if(fmod(glor+180.0,360.0) == rstdlon) {
plt=stdlat-90.0+lti;
if(plt < -90.0) {
plt=-180.0-plt;
pln=270.0;
} else {
pln= 90.0;
}
goto l2000;
}
/*
c
c determine longitude distance relative to rstdlon so it belongs to
c the absolute interval 0 - 180
c
*/
argu1 = glor-rstdlon;
if(argu1 > 180.0) argu1 = argu1-360.0;
if(argu1 < -180.0) argu1 = argu1+360.0;
/*
c
c 1. get the help circle bb and angle alpha (legalize arguments)
c
*/
c2=lti*pi180 ;
c3=argu1*pi180 ;
arg2a = cos(c2)*cos(c3) ;
if( -c1 > arg2a ) arg2a = -c1 ; /* arg2a = max1(arg2a,-c1) */
if( c1 < arg2a ) arg2a = c1 ; /* min1(arg2a, c1) */
bb = acos(arg2a) ;
c4=hsign*lti*pi180 ;
arg2a = sin(c4)/sin(bb) ;
if( -c1 > arg2a ) arg2a = -c1 ; /* arg2a = dmax1(arg2a,-c1) */
if( c1 < arg2a ) arg2a = c1 ; /* arg2a = dmin1(arg2a, c1) */
alpha = asin(arg2a) ;
/*
c
c 2. get plt and pln (still legalizing arguments)
c
*/
c5=stdlat*pi180 ;
c6=hsign*stdlat*pi180 ;
arg2a = cos(c5)*cos(bb) + sin(c6)*sin(c4) ;
if( -c1 > arg2a ) arg2a = -c1 ; /* arg2a = dmax1(arg2a,-c1) */
if( c1 < arg2a ) arg2a = c1 ; /* arg2a = dmin1(arg2a, c1) */
plt1 = asin(arg2a) ;
arg2a = sin(bb)*cos(alpha)/cos(plt1) ;
if( -c1 > arg2a ) arg2a = -c1 ; /* arg2a = dmax1(arg2a,-c1) */
if( c1 < arg2a ) arg2a = c1 ; /* arg2a = dmin1(arg2a, c1) */
pln1 = asin(arg2a) ;
/*
c
c test for passage of the 90 degree longitude (duallity in pln)
c get plt for which pln=90 when lti is the latitude
c
*/
arg2a = sin(c4)/sin(c6);
if( -c1 > arg2a ) arg2a = -c1 ; /* arg2a = dmax1(arg2a,-c1) */
if( c1 < arg2a ) arg2a = c1 ; /* arg2a = dmin1(arg2a, c1) */
plt90 = asin(arg2a) ;
/*
c
c get help arc bb and angle alpha
c
*/
arg2a = cos(c5)*sin(plt90) ;
if( -c1 > arg2a ) arg2a = -c1 ; /* arg2a = dmax1(arg2a,-c1) */
if( c1 < arg2a ) arg2a = c1 ; /* arg2a = dmin1(arg2a, c1) */
bb = acos(arg2a) ;
arg2a = sin(c4)/sin(bb) ;
if( -c1 > arg2a ) arg2a = -c1 ; /* arg2a = dmax1(arg2a,-c1) */
if( c1 < arg2a ) arg2a = c1 ; /* arg2a = dmin1(arg2a, c1) */
alpha = asin(arg2a) ;
/*
c
c get glolim - it is nesc. to test for the existence of solution
c
*/
argu2 = cos(c2)*cos(bb) / (1.-sin(c4)*sin(bb)*sin(alpha)) ;
if( fabs(argu2) > c1 ) {
glolim = 999.0;
} else {
glolim = acos(argu2)/pi180;
}
/*
c
c
modify (if nesc.) the pln solution
c
*/
if( ( fabs(argu1) > glolim && lti <= stdlat ) || ( lti > stdlat ) ) {
pln1 = pi180*180.0 - pln1;
}
/*
c
c the solution is symmetric so the direction must be if'ed
c
*/
if(argu1 < 0.0) {
pln1 = -pln1;
}
/*
c
c convert the radians to degrees
c
*/
plt = plt1/pi180 ;
pln = pln1/pi180 ;
/*
c
c to obtain a rotated value (ie so x-axis in pol.ste. points east)
c add 270 to longitude
c
*/
pln=fmod(pln+270.0,360.0) ;
l2000:
/*
c
c this program convert polar stereographic coordinates to x,y ditto
c longitude: 0 - 360 ; positive to the east
c latitude : -90 - 90 ; positive for northern hemisphere
c it is assumed that the x-axis point towards the east and
c corresponds to longitude = 0
c
c tsp 20/06-89
c
c constants and functions
c
*/
facpla = radius*2.0/(1.0+sin(plt*pi180))*cos(plt*pi180);
x = facpla*cos(pln*pi180) ;
y = facpla*sin(pln*pi180) ;
*grdi=(x-xref)/delx + xiref;
*grdj=(y-yref)/dely + yjref;
return;
}
u
and v
components must be 33
and 34K
(the GRIB standard)
respectively, e.g.,
u 15 33
u component of the wind at 15 pressure levels
v 15 34
v component of the wind at 15 pressure
levels
eta.u
and ops
projection are still
experimental...i,j
space, transformed
to the display device coordinates (e.g., the screen) and then
displayed. That is, the i,j of the graphic element is converted
to lat/lon
and then to x,y
on the screen via a map
projection.
GrADS currently supports four display projections
:
set mproj
nps);
set mproj
sps);
As you can probably appreciate, the i,j-to-lon/lat-to-screen x,y
for lon/lat
displays is very simple and is considerably more
complicated for N and S polar stereo
projections.
In principle, a Lambert Conformal display projection could be implemented. It just takes work and a simple user interface for setting up that display projection. Actually, the user interface (i.e., "set" calls) is the most difficult problem...
model.ctl
GrADS descriptor file (0.7 kb) model.grb
GrADS (GRIB) data file (579 kb) model.gmp
GrADS gribmap index file (4 kb)
This data file is described by the data descriptor file
model.ctl
. You may want to look at this file before
continuing. The data descriptor file describes the actual data file,
which in the case contains 5 days of global grids that are 72 x 46
elements in size.
Please download these 3 files to a local directory before proceeding.
To start up GrADS, enter:
grads
If the grads executable is not in your current directory, or if it is not in your PATH somewhere, you may need to enter the full pathname, ie:
/usr/homes/smith/grads/grads
GrADS will prompt you with a landscape vs. portrait question; just press enter. At this point a graphics output window should open on your console. You may wish to move or resize this window. Keep in mind that you will be entering GrADS commands from the window where you first started GrADS -- this window will need to be made the 'active' window and you will not want to entirely cover that window with the graphics output window.
In the text window (where you started grads from), you should now
see a prompt: ga->
You will enter GrADS commands at this
prompt and see the results displayed in the graphics output
window.
The first command you will enter is:
open model.ctl
You may want to see what is in this file, so enter:
query file
One of the available variable is called ps
, for surface pressure.
We can display this variable by entering:
d ps
d
is short for display
. You
will note that by default, GrADS
will display an X, Y plot at the first time and at the lowest
level in the data set.
Now you will enter commands to alter the dimension environment
.
The display
command (and
implicitly, the access,
operation, and
output of the data) will do things with respect to the current
dimension environment. You control the dimension environment
with the set
command:
clear
clears the displayset lon -90
sets longitude to 90 degrees Westset lat 40
sets latitude to 40 degrees Northset lev 500
sets level to 500 mbset t 1
sets time to first time stepd z
displays the variable 'z'In the above sequence of commands, we have set all four GrADS dimensions to a single value. When we set a dimension to a single value, we say that dimension is "fixed". Since all the dimensions are fixed, when we display a variable we get a single value, in this case the value at the location 90W, 40N, 500mb, and the 1st time in the data set.
If we now enter:
We have set the X dimension, or longitude, to vary. We have done this by entering two values on the set command. We now have one varying dimension (the other dimensions are still fixed), and when we display a variable we get a line graph, in this case a graph of 500mb Heights at 40N.
Now enter:
We now have two varying dimensions, so by default we get a contour plot. If we have 3 varying dimensions:
we get an animation sequence, in this case through time.
Now enter:
In this case we have set the Y (latitude) and Z (level)
dimensions to vary, so we get a vertical cross section. We have
also displayed two variables, which simply overlay each other.
You may display as many items as you desire overlaid before you
enter the clear
command.
Another example, in this case with X and T varying (Hovmoller
plot):
Now that you know how to select the portion of the data set to
view, we will move on to the topic of operations on the data.
First, set the dimension environment to an Z, Y varying one:
Now lets say that we want to see the temperature in Fahrenheit instead of Kelvin. We can do the conversion by entering:
display (t-273.16)*9/5+32
Any expression may be entered that involves the standard operators of +, -, *, and /, and which involves operands which may be constants, variables, or functions. An example involving functions:
to calculate the magnitude of the wind. A function is provided to do this calculation directly:
d mag(u,v)
Another built in function is the averaging function:
In this case we calculate the 5 day mean. We can also remove the mean from the current field:
d z - ave(z,t=1,t=5)
We can also take means over longitude to remove the zonal mean:
We can also perform time differencing:
This computes the change between the two fields over 1 day. We could have also done this calculation using an offset from the current time:
d z(t+1) - z
The complete specification of a variable name is:
name.file(dim +|-|= value, ...)
If we had two files open, perhaps one with model output, the other with analyses, we could take the difference between the two fields by entering:
display z.2 - z.1
Another built in function calculates horizontal relative vorticity via finite differencing:
Yet another function takes a mass weighted vertical integral:
Here we have calculated precipitable water in mm.
Now we will move on to the topic of controlling the graphics output. So far, we have allowed GrADS to chose a default contour interval. We can override this by:
We can also control the contour color by:
clear
set ccolor 3
d z
We can select alternate ways of displaying the data:
This is not very smooth; we can apply a cubic smoother by entering:
clear
set csmooth on
d
hcurl(u,v)
We can overlay different graphics types:
set gxout contour
set ccolor 0
set cint 30
d z
and we can annotate:
draw title 500mb Heights and
Vorticity
We can view wind vectors:
Here we are displaying two expressions, the first for the U
component of the vector; the 2nd the V component of the vector.
We can also colorize the vectors by specifying a 3rd field:
d u;v;q
or maybe:
d u;v;hcurl(u,v)
You may display pseudo vectors by displaying any field you want:
Here the U component is the wind speed; the V component is moisture.
We can also view streamlines (and colorize them):
Or we can display actual grid point values:
We may wish to alter the map background:
clear
set lon -110 -70
set lat 30 45
set mpdset nam
set digsize 0.2
set dignum 2
d u
To alter the projection:
set lon -140 -40
set lat 15 80
set mpvals -120 -75 25 65
set mproj nps
set gxout contour
set cint 30
d z
In this case, we have told grads to access and operate on data from longitude 140W to 40W, and latitude 15N to 80N. But we have told it to display a polar stereographic plot that contains the region bounded by 120W to 75W and 25N to 65N. The extra plotting area is clipped by the map projection routine.
This concludes the sample session. At this point, you may wish
to examine the data set further, or you may want to go through
the GrADS documentation and try out the other options described
there.
grads-2.0.1/doc/pagecontrol.html 0000644 0001750 0001750 00000012601 10243410766 017717 0 ustar amckinstry amckinstry
The "real" page is an 8.5x11 page in the landscape or portrait orientation. The orientation is specified when you first startup grads. The graphics output window is a representation of the real page on your computer screen. The graphics window can be any size at all. You can set the dimensions explicitly (in pixel coordinates) using the set xsize command, or you can simply resize the graphics window using your mouse. When it comes time to print the contents of the graphics window to a real page, the screen coordinates (in pixels) will be scaled so the graphics will fit in the real page in the same way they fit in the graphics window.
The "virtual" page is a page-within-a-page that fits within the limits of the real page. By default, the virtual page is the same as the real page, so that real page coordinates are exactly the same as virtual page coordinates. All graphics are drawn on the virtual page. The limits of the virtual page may be changed by using the following command:
set vpage xmin xmax ymin ymax
After entering a set
vpage
command, GrADS will return the size of the virtual
page in inches. Any arguments to graphics commands that require page
coordinates in inches are to be given in virtual page
coordinates. For example, to draw a plot in the lower left quadrant
of the real page, use the following command:
set vpage 0 5.5 0 4.25
GrADS will return the following virtual page dimensions:
Virtual page size = 11 8.5
If the virtual page has the same aspect ratio as the real page, Grads will give it the same dimensions as the real page -- in this case the virtual page is a mini version of an 11"x8.5" page. Here's another example where the virtual page is a centered square:
set vpage 4 7 2.75 5.75
GrADS will return the following virtual page dimensions:
Virtual page size = 8.5 8.5
On the real page the plot will be within a 3" square, but on the virtual page in Grads the plot will be within an 8.5" square. Remember that any arguments to graphics commands that require page coordinates in inches are to be given in virtual page coordinates.
To return to the default state where the virtual page equals the real page, enter:
It is possible to control the area within the virtual page where GrADS draws contour plots, maps, or line graphs. The command is:
set parea xmin xmax ymin ymax
This area does not include axis labels, titles, color bars, etc., so be sure to provide for adequate margins in order to see these features. Note that the plot area is specified in terms of virtual page units.
GrADS chooses an appropriate default plotting area depending on the type of graphics output. To return to this default, enter:
set parea off
Line graphs and contour plots that don't contain a map will be scaled to fill the entire plot area. Any plot that contains a map projection will be scaled to fit within the plotting area while maintaining a correct lat/lon aspect ratio. Thus, the map may not fill the entire plotting area except under certain lat/lon ranges. This feature may be turned off by setting the map projection to "scaled". See the reference page for set mproj for additional map projection options.
For drawing multi-panel plots, use set vpage
to define
several virtual pages that fit within the limits of the real page.
Virtual pages may overlap.
The sample script called
panels_demo.gs
demonstrates how to set up virtual
page coordinates for a multi-panel plot with a specified number of
rows and columns. It uses a GrADS script function
called
panels.gsf
.
If you want to place a label or some other graphic element in each panel, the position is given in virtual page coordinates. These coordinates will be the same no matter which panel you're in. This makes it easy to shift the labels in one direction or another to accomodate the graphics.
Do not use set parea
to draw multiple plots on one page. That is not what
parea
was designed for. It is far better (and easier!) to
use the set vpage
command as described above.
grads-2.0.1/doc/gradcomdenableprint.html 0000644 0001750 0001750 00000003306 11416646527 021421 0 ustar amckinstry amckinstry
enable print fname
This command opens the output file fname
that will contain the instructions in GrADS metacode format to create a hardcopy of the graphical display. Any existing contents of fname
will be lost.
The output file fname
is referred to as a GrADS metafile.
Creating a GrADS metafile for vector-graphic hardcopy involves four steps:
1. Open the metafile with the enable print
command
2. Create the graphical display that you want to print
3. Issue the print
command. For multiple images in your metafile, use clear
and then print
again.
4. Close the metafile with the disable print
command
After you have created a GrADS metafile, you can
1. convert it to postscript using the external utility gxps
2.
convert it to encapsulated postscript using gxeps
or you can
3.
display it using the external utilities gxtran
or gv32.exe
(for MS Windows)
grads-2.0.1/doc/gradcomdsettimelab.html 0000644 0001750 0001750 00000001261 10243410766 021234 0 ustar amckinstry amckinstry
set timelab on|off
This command turns on/off the display of the time label for sreen and printed output.
on
and "sticks" until reset by another
set timelab
command.
set grads
.
set parea 0.75 10.5 3.875 4.25
set grads off
set gxout tserwx
set digsiz 0.11
d wx (stid=79001)
where the grid wx
contains codes for weather symbols
grads-2.0.1/doc/gradfunccos.html 0000644 0001750 0001750 00000000555 10243410766 017705 0 ustar amckinstry amckinstry
cos(expr)
Takes the cosine of the expr
. Values are assumed to be
in radians. Works on both gridded and station data.
grads-2.0.1/doc/gradcomdsetmdlopts.html 0000644 0001750 0001750 00000000501 10243410766 021275 0 ustar amckinstry amckinstry
set mdlopts opt
opt
= noblank, blank, dig3, or nodig3
grads-2.0.1/doc/gradcomdsetarrowhead.html 0000644 0001750 0001750 00000001074 10243410766 021575 0 ustar amckinstry amckinstry
set arrowhead size
where size
is the size of the arrowhead. The default
is 0.05
. If set to 0
, no arrowhead is plotted.
If set to a negative value, the size of the arrowhead will be scaled to
the size of the arrow. The value specified will be the size when the arrow
is one inch in length.
grads-2.0.1/doc/ncdump.html 0000644 0001750 0001750 00000021523 10243410766 016673 0 ustar amckinstry amckinstry
ncdump [-c] [-h] [-v var1,...] [-b lang] [-f
lang] [-l len]
[-n name] [-d f_digits[,d_digits]]
file
Where:
-c
Show the values of
coordinate variables (variables that
are also dimensions) as well as the declarations of all
dimensions, variables, and attribute values. Data
values of non-coordinate variables are not included in
the output. This is the most suitable option to use
for a brief look at the structure and contents of a
netCDF file.
-h
Show only the
header
information in the output, that is
the declarations of dimensions, variables, and attributes but no data values for any variables. The output
is identical to using the -c
option except
that the
values of coordinate variables are not included. (At
most one of -c
or -h
options may be
present.)
-v
var1,...,varn
-c
or -h
options, is to include data values for
all variables in the output.
-b lang
lang
begins with
C
or c
, then C
language conventions will be used (zero-based indices,
last dimension varying fastest). If lang
begins
with
F
or f
, then Fortran language
conventions will be
used (one-based indices, first dimension varying
fastest). In either case, the data will be presented
in the same order; only the annotations will differ.
This option is useful for browsing through large
volumes of multidimensional data.
-f lang
lang
begins with C
or c
, then C
language conventions
will be used (zero-based indices, last dimension varying
fastest). If lang
begins with F
or
f
, then
Fortran language conventions will be used (one-based
indices, first dimension varying fastest). In either
case, the data will be presented in the same order;
only the annotations will differ. This option may be
useful for piping data into other filters, since each
data value appears on a separate line, fully
identified.
-l len
-n name
ncgen -b
in generating a default netCDF file name. By
default, ncdump
constructs this name from the
last component of the pathname of the input netCDF file by
stripping off any extension it has. Use the -n
option
to specify a different name. Although the output file
name used by ncgen -b
can be specified, it may be wise
to have ncdump
change the default name to avoid
inadvertantly overwriting a valuable netCDF file when using
ncdump
, editing the resulting CDL file, and using
ncgen
-b
to generate a new netCDF file from the edited
CDL
file.
-d float_digits[,double_digits]
float_digits
significant digits. If
double_digits
is
also specified, double-precision values will be
displayed with that many significant digits. If a
variable has a `C_format' attribute, that overrides any
specified floating-point default. In the absence of
any -d
specifications, floating-point and
double-
precision data are displayed with 7 and 15 significant
digits respectively. CDL files can be made smaller if
less precision is required. If both floating-point and
double-presision precisions are specified, the two
values must appear separated by a comma (no blanks) as
a single argument to the command. If you really want
every last bit of precision from the netCDF file
represented in the CDL file for all possible floating-
point values, you will have to specify this with -d
9,17
.ncdump
generates an ASCII representation of a
specified
netCDF file on standard output. The ASCII representation is
in a form called CDL
(``network Common Data form
Language'')
that can be viewed, edited, or serve as input to ncgen
.
ncgen
is a companion program
that can generate a binary
netCDF file from a CDL
file. Hence ncgen
and ncdump
can
be
used as inverses to transform the data representation
between binary and ASCII representations. See ncgen
for a
description of CDL and netCDF representations.
ncdump
defines a default format used for each type of
netCDF
data, but this can be changed if a `C_format' attribute is
defined for a netCDF variable. In this case, ncdump
will
use the `C_format' attribute to format each value. For example,
if floating-point data for the netCDF variable Z
is
known to be accurate to only three significant digits, it
would be appropriate to use the variable attribute
Z:C_format = "%.3g"
ncdump
may also be used as a simple browser for netCDF
data
files, to display the dimension names and sizes; variable
names, types, and shapes; attribute names and values; and
optionally, the values of data for all variables or selected
variables in a netCDF file.
foo.nc
:
ncdump -c foo.nc
foo.nc
, using C-style indexing for
the
annotations:
ncdump -b c foo.nc > foo.cdl
uwind
and
vwind
from
the netCDF file foo.nc
, and show the floating-point
data
with only three significant digits of precision:
ncdump -v uwind,vwind -d 3 foo.nc
omega
, using Fortran
conventions for indices, and changing the netCDF dataset name in
the resulting CDL file to omega
:
ncdump -v omega -f fortran -n omega foo.nc > Z.cdl
Animation
set loopdim
Sets dimension to animate
set loopincr
Sets looping increment
set looping
Turns on animation when fewer than three dimesions are varying
set dbuff
Turns on/off double buffer mode
swap
Swaps buffers when in double buffer mode
Annotation and Labeling
draw string
Draws a string anywhere on the page
draw title
Draws a title centered over a plot
set dignum
Sets the number of significant digits after the decimal point
set digsiz
Sets the size of plotted numbers
set font
Selects the font for text display
set grads
Turns on/off the GrADS logo in each plot
set string
Sets string drawing attributes
set strsiz
Sets the string character size
set timelab
Turns on/off display of the time label
set tlsupp
Suppresses the annotation of the year and/or month in date/time labels
Axis Labeling
draw xlab
Draws an X-axis label
draw ylab
Draws a Y-axis label
set vrange
Sets the range of values for Y-axis scaling
set vrange2
Sets the range of values for X-axis scaling
set xaxis
Specifies where the labeled tick marks will be placed on the X-axis
set xflip
Flips the order of the horizontal axis
set xlab
Controls the format of X-axis tick mark labels
set xlabs
Gives specific text for X-axis labels
set xlevs
Specifies each individual labeled tick mark for the X-axis
set xlint
Specifies the interval between labeled tick marks on the X-axis
set xlopts
Controls X-axis label options
set xlpos
Controls position of X-axis labels
set xyrev
Reverses the X and Y axes on a plot
set yaxis
Specifies where the labeled tick marks will be placed on the Y-axis
set yflip
Flips the order of the vertical axis
set ylab
Controls the format of Y-axis tick mark labels
set ylabs
Gives specific text for Y-axis labels
set ylevs
Specifies each individual labeled tick mark for the Y-axis
set ylint
Specifies the interval between labeled tick marks on the Y-axis
set ylopts
Controls Y-axis label options
set ylpos
Controls position of Y-axis labels
set zlog
Sets log scaling of the Z dimension
Bar Graph Options
set barbase
Sets the reference point for bar graphs
set bargap
Sets the gap between bars for bar graphs
set baropts
Specifies whether bars are outlined or filled
Color Control
set fgvals
Assigns a color to a particular value; used with 'set gxout fgrid'
set lfcols
set rbcols
Specifies a new rainbow color sequence
set rbrange
Assigns a range of values to rainbow colors
set rgb
Defines a new color
set wxcols
Controls color of weather symbols
Contour Settings
set annot
Sets color and thickness of axis border, axis labels, and tickmarks
set black
Specifies a range of values for which no contours will be drawn
set ccolor
Specifies the color of the plotted contours
set ccols
Assigns specific colors for each contour level
set cint
Sets the contour interval
set clab
Controls contour labels
set clevs
Sets specific contour levels
set clopts
Contour label options
set clskip
Sets the number of contour lines to skip when labelling
set cmax
Contours not drawn above this value
set cmin
Contours not drawn below this value
set csmooth
Interpolates the grid to a finer resolution before contouring
set cstyle
Sets the contour line style
set cterp
Turns on/off spline smoothing
set cthick
Sets contour line thickness
Display Controls
clear
Clears the display window and resets many graphics options
display
Draws a plot
reset
Returns GrADS settings to default state with some exceptions
set background
Sets background color
set clip
Sets the coordinates for clipping the plot area
set cmark
Sets the type of line marker
set display
Sets the mode of display
set frame
Draws a frame around plot borders
set gridln
Controls appearance of grid lines; used with 'set gxout grid'
set gxout
Sets a graphics output type
set line
Sets line attributes
set missconn
Connects plots lines over missing data
set parea
Specifies the area for plotting contour plots, maps, or line graphs
set vpage
Sets dimensions of the virtual page
set xsize
Resizes the graphics display window
Data and Image Output
disable fwrite
Closes output file containing gridded data
disable print
Closes output file containing images in metacode format
enable print
Opens output file containing images in metacode format
gxeps
Converts GrADS metacode format image files into postscript
gxps
Converts GrADS metacode format image files into postscript
gxtran
Displays GrADS metacode format image files
outxwd
Copies the contents of the display window into a file in XWD format
print
Copies the contents of display window to a file in a metacode format
printim
Copies the contents of display window to a file in PNG or GIF format
set fwrite
Sets filename, byte ordering, and format for data output
wi
Dumps the contents of the display window into a file in a variety of formats
Dimension Environment
set x
Specifies the X-dimension in grid coordinates
set y
Specifies the Y-dimension in grid coordinates
set z
Specifies the Z-dimension in grid coordinates
set t
Specifies the T-dimension in grid coordinates
set lon
Specifies the X-dimension in world coordinates
set lat
Specifies the Y-dimension in world coordinates
set lev
Specifies the Z-dimension in world coordinates
set time
Specifies the T-dimension in world coordinates
File Manipulation
close
Closes a GrADS data file
open
Opens a GrADS data file
reinit
Returns GrADS to its initial state
exec
Executes the list of GrADS commands contained in a file
gribmap
Creates a map of data sets in GRIB format
gribscan
Extracts grid info from data sets in GRIB format
run
Runs a GrADS script
sdfopen
Opens a COARDS-compliant NetCDF or HDF-SDS file
xdfopen
Opens a non-COARDS-compliant NetCDF or HDF-SDS file
set dfile
Changes default file
set imprun
Sets up automatic script execution before every display command
GrADS-User Interface
grads
Starts the GrADS program
help
Lists a few basic GrADS commands
query
Returns information about many aspects of the current GrADS session
quit
Quits GrADS
set datawarn
Prints "Entire Grid Undefined" in display window if all data are missing
set stat
Turns on/off printing of statistical information for each display
set warn
Turns on/off messages about the progress of certain mathematical operations
!shell
Sends a command to the shell
Graphical Elements
draw line
Draws a line
draw mark
Draws a mark
draw polyf
Draws a filled polygon
draw rec
Draws a rectangle
draw recf
Draws a filled rectangle
draw wxsym
Draws a weather symbol
Map Settings
draw map
Draws a map outline
set grid
Sets characteristics of displayed grid lines
set map
Sets map background characteristics
set mpdraw
Turns on/off drawing of map background
set mpdset
Sets the resolution of the coastal outline
set mproj
Sets current map projection
set mpt
Controls map background characteristics
set mpvals
Sets reference longitudes and latitudes for polar stereographic plots
set poli
Turns on/off the drawing of political boundaries
Station Data
collect
Saves station data in memory as a set
set mdlopts
set wxopt
Controls weather symbol output; used with 'set gxout wxsym'
set stid
Turns on/off display of the station ID next to the data values
set stnprint
Controls printing of station data values; used with 'set gxout stat'
stnmap
Writes out a hash table and/or link list information for station data
Variables
define
Creates a new GrADS variable that is loaded into memory
modify
Defines a climatological variable
set defval
Interactively modifies grid point values for 2-D defined variables
undefine
Frees the memory used by a defined variable
Vectors
set arrlab
Toggles drawing the vector arrow label
set arrowhead
Sets the size of the vector arrowhead
set arrscl
Specifies arrow length scaling
set hempref
Controls wind barb drawing conventions
set strmden
Sets density of streamlines; used with 'set gxout stream'
Widgets
draw button
Draws a button widget
redraw button
Resets a button widget on/off
draw dropmenu
Draws a dropmenu widget
set button
Specifies the color characteristics of a button widget
set dialog
Sets color properties of dialog box widgets
set dropmenu
Sets color properties of dropmenu widgets
set rband
Sets characteristics for the 'rubber band' widget
grads-2.0.1/doc/gradfuncoabin.html 0000644 0001750 0001750 00000002575 10243410766 020215 0 ustar amckinstry amckinstry
oabin (gexpr, sexpr <,-flag>)
This function bins station observations into grid cells based on their location. If more than one station is located within a grid box, the observations are averaged together to produce the analyzed value.
gexpr  
a valid grid expressionsexpr  
a valid station data expression
The optional flag
may be one of the following:
-f    
set the value to the first observation that gets binned-c    
output is the # of stations located within each grid cell
oacres
.
open grd_var.ctl open stn_var.ctl set gxout grfill d oabin(grd_var.1,stn_var.2) set gxout grid d oabin(grd_var.1,stn_var.2,-c)grads-2.0.1/doc/mathfunctions.html 0000644 0001750 0001750 00000016052 11632442207 020266 0 ustar amckinstry amckinstry
A set of math functions has been developed for use within the GrADS scripting language. Their use is somewhat self-explanatory, based on the following descriptions of the arguments and return codes.
else if (cmpwrd(name,"math_sqrt")) rc = gsfmath(pcmn,8);
else if (cmpwrd(name,"math_abs")) rc = gsfmath(pcmn,9);
rc = math_trigfunc(angle <,angle2> )
trigfunc
sin, cos, tan, asin, acos, atan, atan2,
sinh, cosh, tanh, asinh, acosh, or atanhangle
must be given in radians
angle2
(only used for atan2) rc
the result of
the trig function calculation
rc = math_format(format,num)
format
a C-language style format
statement for a floating point number, e.g. %5.2f
num
the number
to be formattedrc
the formatted
number
rc = math_nint(num)
num
a real number
in decimal formrc
num
rounded up or down to the nearest integer
rc = math_int(num)
num
a real number
in decimal formrc
the integer
part of num
not greater than num
rc = math_log(num);
num
any number
> 0rc
natural logarithm
of num
rc = math_log10(num);
num
any number
> 0.0rc
base 10 logarithm of num
rc = math_pow(num,exponent);
num
any number
exponent
any number
rc
num
raised to the power exponent
rc = math_sqrt(num)
num
any numberrc
the square root
of num
rc = math_abs(num)
num
any numberrc
the absolute
value of num
rc = math_exp(num)
num
any numberrc
the result of
the exponential function; e
raised to the power num
rc = math_fmod(num1,num2);
num1
any numbernum2
any number not
equal to zerorc
the remainder
when num1
is divided by num2
rc = math_mod(num1,num2);
num1
any numbernum2
any number not
equal to zerorc
the integer
part of the remainder when num1
is divided by num2
rc = math_strlen(string)
string
any string variablerc
the length of string
rc = valnum(string)
string
any string variablerc 0 - string
is not a number 1 -
string
is an integer 2 -
string
is not an integer
rc = wrdpos(string,int)
string
any string, usually contains more than one wordint
an integerrc
word #int
string
starts at this character #
These math functions will only work with GrADS version 1.8 (or higher).
These script records were taken from a sample script called "script_math_demo.gs".
v = 3.1456
grads-2.0.1/doc/gadoc.html 0000644 0001750 0001750 00000021127 11416646527 016473 0 ustar amckinstry amckinstry
fmt = '%-6.1f'
rc = math_format(fmt,v)
say fmt' of 'v' = 'rc
pi = 3.1415926
d2r = pi/180
angd = 45
ang = angd * d2r
cos = math_cos(ang)
say 'cos of 'angd' = 'cos
num = '3.1455'
rc = valnum(num)
if (rc = 0) ; say num' is not a number' ; endif
if (rc = 1) ; say num' is an integer' ; endif
if (rc = 2) ; say num' is not an integer' ; endif
v = 3.0
while(v < 4.0)
rc1 = math_nint(v)
rc2 = math_int(v)
print 'nint of 'v' = 'rc1' int of 'v' = 'rc2
v = v + 0.1
endwhile
pow = math_pow(2,0.5);
print '2 raised to the power 0.5 = 'pow
num = math_exp(1)
print 'exp(1) = 'num
fmod = math_fmod(5,2)
print '5 modulo 2 (the remainder when 5 is divided by 2) = 'fmod
s = 'this is a test'
rc = math_strlen(s)
print 'length of the string "'s'" = 'rc
p = 2
rc = wrdpos(s,p)
print 'word 'p' of the string "'s'" starts at character 'rc
![]() |
|
![]() |
Documentation Web Pages The html version of the GrADS documentation has become the standard base documentation for GrADS. Follow the links below to the Users Guide, an introductory tutorial session, and an alphabetical subject index. Note the documentation is covered under the same copyright as the GrADS source code. The Users Guide Tutorial
Index Download HTML Documentation Download Hard Copy Documentation
|
grads-2.0.1/doc/gradcomdswap.html 0000644 0001750 0001750 00000000367 10243410766 020063 0 ustar amckinstry amckinstry
on
This command allows the user to define a new color within GrADS. The syntax is:
set rgb color# R G B
where:
color#
is the color number; it can range from 16 to 99 (or 255 -- see Usage Note #1) R
is the Red value (0-255) G
is the Green value (0-255) B
is the Blue value 0-255)
The new color is referred to by its color#
in any GrADS command that allows specification of colors.
color#
must be a value between 16
and 99
-- 0
to 15
are
predefined.
gxps
will make use of any
new color settings although the output colors will be
printer-dependent and should be checked for the desired
rendering. When converting new color settings into grayscales, gxps
will translate the
GREEN intensity ONLY into a new greyscale value. Note that gxps
does have a predefined
mapping between color values from 0 to 15 such that the predefined rainbow sequence is rendered into a
fairly pleasing greyscale gradation; this cannot be done for newly
defined colors.
set rgb 50 200 200 200
Defines a new color number, 50
, and
assign a color to it. In this case, the color would be a light gray.
grads-2.0.1/doc/gradcomdsdfopen.html 0000644 0001750 0001750 00000011001 11436764233 020540 0 ustar amckinstry amckinstry
sdfopen filename <template #timesteps>
Opens a NetCDF or HDF-SDS format file that conforms to the COARDS conventions. The sdfopen command does not support the HDF5 format, but is does support netcdf4. The arguments and options are as follows:
filename
template
template
has a similar structure to the substitution template in a GrADS data descriptor
file. See Using Templates for details.
#timesteps
template
is invoked. The #timesteps
is the sum of the timestep
counts in all the files to be examined, not the count in any one file.
GrADS Dimension |
Acceptable Attribute Values |
X |
units: degrees_east, degree_east, degrees_E, degree_E axis: x, X |
Y |
unit: degrees_north, degree_north, degrees_N, degree_N axis: y, Y |
Z (pressure) |
units: mb, millibar, hybrid_sigma_pressure |
Z (not pressure) |
units: sigma_level, degreesk, degrees_k, level, layer, layers axis: z, Z |
T |
units: yyyymmddhhmmss, yymmddhh, or a Udunits-acceptable time unit axis: t, T |
E |
grads_dim: e axis: e, E |
xdfopen
command which requires a special descriptor file to supplement or override the metadata in the file, or use the open command with a complete descriptor file.
uwnd.1989.nc
and uwnd.1990.nc
, you could access them both as one GrADS data
set by entering:
sdfopen /data/uwnd.1989.nc uwnd.%y4.nc 730
set strmden value
specifies the streamline density, where the value is from 1
to 10. 5
is default.
grads-2.0.1/doc/gradcomdsetrbcols.html 0000644 0001750 0001750 00000002024 10243410766 021101 0 ustar amckinstry amckinstry
set rbcols color1 color2 ... colorN
This command specifies a new rainbow color sequence. The
color#
arguments may be taken from the 16 GrADS default colors or they may be new
color numbers defined via the set
rgb
command. This sequence of colors replaces the default rainbow color sequence whenever the
rainbow colors are used.
set rbcols
given without any arguments will return to
the default GrADS rainbow sequence.
set rbcols
.
Script variables are generally local to the functions (scripts) they are contained in; they exist in memory only while the function is executing. If a variable name starts with an underscore (_), then it becomes a global script variable and keeps its value throughout the execution of the main script file. The drawback to global variables was that the functions they are defined in had to be included in the main script file. With a new capability that comes with GrADS version 1.8, that is no longer the case.
Dynamic loading of script functions means that when your main script calls a function (subscript), all global variables from that function will be retained in memory and can continue to be used by main script. Commonly used functions do not have to be copied into every script that calls them.
The names of GrADS script functions may now have 16 characters and include the underscore, although they still must begin with an alphabetic character. Grads script function names are case sensitive.
Error messages will include the file name where the error ocurred -- in this case, the full path name of the file that was actually opened.
The tricks to using GrADS script functions are (1) to enable dynamic loading and (2) to teach GrADS how to find the script functions you call from your main script.
To enable the dynamic loading of script functions, put this at the top of your script:
rc = gsfallow("on")
To teach Grads how to find the script functions you call from your main script, you must first know how Grads searches for main script file names.
How GrADS searches for main script file names
Let's assume the user wants to run a script called
do_eof.gs
and gives the Grads command:
ga-> do_eof
Grads will search in the currently directory for the script name, as provided. If it doesn't find the script, it appends .gs to the script name and tries again. If the script is still not found, then the environment variable GASCRP is examined. GrADS attemps to open the script file in all the directories listed in the GASCRP variable, first with the provided name, then with the .gs appended.
If GASCRP contains "/usr/local/gradslib
/usr/homes/myhome
", then GrADS will search for the script
do_eof
in the following order:
- do_eof
- do_eof.gs
- /usr/local/gradslib/do_eof
- /usr/local/gradslib/do_eof.gs
- /usr/homes/myhome/do_eof
- /usr/homes/myhome/do_eof.gs
GrADS uses the first file it finds. Once found, the directory that contains the script file is remembered as the "main function prefix".
How GrADS searches for script function file names
Continuing with our example, let's further assume that GrADS
encounters a function in do_eof.gs
that is not included
in the stuff already loaded from the main script file. GrADS will look
for a .gsf file to load, using the following search path:
- <main-function-prefix>/<function-name>.gsf
- <main-function-prefix>/<private-paths>/<function-name>.gsf
- <GASCRP-paths>/<function-name>.gsf
The private path directory list is an optional list that
is provided via the gsfpath
function:
rc = gsfpath("dirlist")
For example, if our main script "do_eof.gs" is executed with the command:
run /usr/local/gradslib/do_eof
and this script file contains the following lines at the front:
rc = gsfallow("on")
rc = gsfpath("math1 string2")
and the script calls a function str_chop
which is not found in
the main script, then the search path would be:
draw dropmenu number xpos ypos width height text_list
Draws a drop menu with the following attributes:
number
menu number, 0 - 64xpos
x center of the menu base in page coordinates (inches)ypos
y center of the menu base in page coordinates (inches)width
width (x) of the menu base (inches)height
height (y) of the menu base (inches)text_list
the contents of the menu, seperated by vertical bars (|)
set dropmenu
command.
text_list
that will spawn a new
dropmenu should have ">num>"
appended, where
num
will be the number assigned to the spawned
dropmenu. This new dropmenu is then defined with the following syntax:
draw dropmenu num cascade new_text_list
There can be up to three levels of nested cascading dropmenus launched from the main dropmenu. The 2nd example below illustrates how to implement cascading dropmenus.
q pos
reference page have
more information on using dropmenus.
'clear' 'reset events' 'set rgb 90 100 100 100' 'set rgb 91 150 150 150' 'set rgb 92 200 200 200' 'set dropmenu 1 91 90 92 0 91 92 90 1 91 90 92 92 90 6' 'draw dropmenu 1 1 8 1.5 0.5 Select a Variable | Wind | Temperature | Height | SLP ' noselect = 1 while (noselect) 'q pos' menunum = subwrd(result,7) menuitem = subwrd(result,8) if (menunum = 1) if menuitem = 1 ; newbase = 'Variable = Wind' ; endif if menuitem = 2 ; newbase = 'Variable = Temp' ; endif if menuitem = 3 ; newbase = 'Variable = Height' ; endif if menuitem = 4 ; newbase = 'Variable = SLP' ; endif 'draw dropmenu 1 1 8 1.5 0.5 'newbase' | Wind | Temperature | Height | SLP ' noselect = 0 endif endwhile
'clear' 'reset events' 'set rgb 90 100 100 100' 'set rgb 91 150 150 150' 'set rgb 92 200 200 200' 'set button 1 91 -1 -1 1 91 90 92 12' 'draw button 1 1 8 1 0.5 quit' 'set dropmenu 1 91 -1 -1 1 91 90 92 1 91 90 92 90 92 6' 'draw dropmenu 1 1.5 7.5 2 0.5 Menu Base | Space | Earth >05> | Sun | Moon' 'draw dropmenu 5 cascade Ocean | Land | Atmosphere >11> | Biosphere' 'draw dropmenu 11 cascade Snow | Rain | Mist | Tornado ' while (1) 'q pos' say result ev = subwrd(result,6) if (ev!=3); break; endif; endwhile
Introduction to GrADS scripts
Elements of the Language:
comment
statement
assignment
say / prompt / pull
if / else / endif
while / endwhile
variables
operators
expressions
Functions
Intrinsic Functions
Commands that complement the scripting language
Widgets
Script Library
Scripting Language Reference Card
(Requires
Adobe Acrobat Reader)
Scripts offer users the facility to program GrADS operations. Although it is relatively easy for users to produce sophisticated GrADS graphics without ever writing a script, there are occasions where the programming capability makes things even easier. This section explains the general capabilities of scripts, how to run them, and suggests a strategy for users who may wish to write their own.
What scripts can do
The GrADS scripting language, used via the GrADS run
command, provides a similar
capability to the exec
command, except that scripts also have flow control, defined
variables, and access to GrADS command output. Scripts may be written
to perform a variety of functions, such as allowing a user to interact
with Grads via point and click interface, animating any desired
quantities, and annotating plots with information obtained from GrADS
query commands.
The scripting language is similar to REXX in implementation. All
variables are of type STRING. Mathematical operations are supported on
script variables. Flow control is achieved via
if/else/endif
and while/endwhile
constructs. Loop flow may be modified by the continue
or
break
commands. Strings contained in variables or
generated via an expression may be issued to GrADS as commands. The
output from those commands (i.e., the text that GrADS would have
output to the terminal) is put into a variable and made available to
the script. The language includes support for functions.
Before writing your own scripts, it is recommended that you read the rest of this section and then try to run some of the scripts in the library. Study these example scripts, referring to this page for information on syntax etc., and you will soon be equipped to write scripts of your own.
Running scripts
The command to execute a script is the
run
command:
run filename <arguments>
This command runs the script contained in the named file, which
generally has a ".gs"
tag at the end. Optional
arguments
are passed to the script as a string
variable. You may issue any GrADS command from a script, including the
run
command. When calling scripts recursively, be sure
that you can back out of the recursion and return to your main script.
Automatic script execution
You may have a simple script automatically executed before every
display
command:
set imprun script-name
This script would typically be used to set an option that by
default gets reset after each display
command, for example:
set grads off
You can issue any GrADS command from this script, but the interactions
are not always clear. For example, if you issued a display
command from this
script, you could easily enter an infinite recursion loop.
The argument to the script is the expression from the display
command.
It is convenient to put all your GrADS "utility" scripts in one
directory (e.g., /usr/local/grads/lib/scripts
).
To simplify running these scripts, GrADS first looks in the
current directory for the script and then, if it can't find it,
appends the ".gs
" extension and tries again. For example,
suppose you are working on a test script called t.gs
. You would
run it in GrADS by,
run t
If after the first two tries, the script still can't be located,
then GrADS looks in the directory defined by the environment
variable GASCRP
. In the t(csh)
, for example,
setenv GASCRP /home1/grads/lib
or in ksh
,
export GASCRP=/home1/grads/lib
Note the if the /
is not added to the end of the
directory name, it is automatically added by UNIX. However, it'll
still work if you type
setenv GASCRP /home1/grads/lib/
If the script cannot be found, then .gs
is appended and GrADS
tries yet again. Thus,
d slp
run /home1/grads/lib/cbarn.gs
simplifies to,
d slp
run cbarn
A script file is made up of records. The end of a script record is determined by either a newline character or a semicolon (where the semicolon is not contained within a constant string).
Each script record may be one of the following types:
Many of the above record types will contain expressions. Script expressions are composed of operands and operators. Operands are strings constants, variables, or function calls; operators are mathematical, logical, or concatenation operations. Further discussion of these record types and the expressions they may contain is given below.
Comments in GrADS scripts must contain an asterisk (*) in the first column.
The statement record consists only of an expression:
expression
The expression is evaluated, and the resulting string is then
submitted to GrADS as a command for execution. The script variable
rc
will contain the return code from the GrADS command
(this will always be an integer value). In addition, any text output
from GrADS in response to the command is put in the variable
result
for examination by the script. A GrADS error
resulting from an invalid command WILL NOT terminate execution of the
script.
The simplest type of expression is a string constant, which is just a character string enclosed in single or double quotes. Here's an example of simple script containing a comment plus statements comprised of string constants:
* this is a sample script
'open my_sst_dataset.ctl'
'set lat -30 30'
'set lon 90 300'
'display sst'
Assignment records are used to define variables and assign them values. The format of the assignment record is:
variable = expression
The expression is evaluated, and the result is assigned to be the value of the indicated variable. The same example from above can be rewritten to include assignment statements. Note the use of explicit and implied concatenation:
'open my_sst_dataset.ctl'
minlat = -30
maxlat = minlat + 60
minlon = 90
maxlon = 300
'set lat 'minlat%' '%maxlat
'set lon 'minlon' 'maxlon
'display sst'
To present information or questions to the GrADS user via the terminal
(standard output), use the say
or prompt
commands:
say expression
prompt expression
The result of the expression
is written to the
terminal. The prompt
command works the same way as the
say
command but does not append a carriage return. It is
possible to combine variables and string constants when writing to
standard output:
For example:
line = "Peter Pan, the flying one"
say line
say `She said it is `line
gives:
Peter Pan, the flying one
She said it is Peter Pan, the flying one
pull
To retrieve information provided by the GrADS user via the terminal
(standard input), use the pull
command:
pull variable
The script will pause for user input from the keyboard (ending with the carriage return), and then the string entered by the user is assigned to the indicated variable name. To elaborate on a previous example:
'open my_sst_dataset.ctl'
prompt 'Enter min and max latitudes: '
pull minlat maxlat
prompt 'Enter min and max longitudes: '
pull minlon maxlon
'set lat 'minlat%' '%maxlat
'set lon 'minlon' 'maxlon
'display sst'
One way to control the flow of script execution is via the if/else/endif
construct. The format is as follows:
if expression
script record
script record
.
.
else
script record
.
.
endif
The else
block is optional, but the endif
record must be present. The script records following if
expression
are executed if the expression evaluates to a string
containing the character 1. If the expression evaluates to 0, then the
script records in the if
block are not executed and the
script continues with the else
block (if it is present)
or the record following endif
. The if
expression
record must be separated from the script records
that follow it. For example, the following script record would be
invalid:
if (i = 10) j = 20
The correct syntax requires three separate script records. This is achieved by putting each record on one line:
if (i = 10)
j = 20
endif
Alternatively, the three records could be on the same line separated by a semicolon:
if (i = 10) ; j = 20 ; endif
N.B. There is no elseif
construct in GrADS.
Another method for controlling the flow of script execution is the while/endwhile
construct. The format is as follows:
while expression
script record
script record
.
.
endwhile
The script records following while expression
are
executed if the expression evaluates to a string containing the
character 1. If the expression evaluates to 0, then the script records
in the while
block are not executed and the script continues
with the record following endwhile
. The while
expression
record must be separated from the script records
that follow it.
Two additional script commands may be used to modify the
while
loop execution: break
and
continue
. Inserting the break
statement will
immediately end execution of the loop and the script will move on to
the records following endwhile
. The continue
statement will immediately end execution of the loop, but the script
will then branch immediately back to the top of the loop, and the
expression will be re-evaluated.
While loops are often used as counters. For example:
count = 1
while (count < 10)
'set t 'count
'display z'
if (rc != 0) ; break ; endif
count = count + 1
endwhile
The contents of a script variable is always a character string. However, if the contents of a variable represent a number in the correct format, certain operators may perform numeric operations on that variable, giving a string result which will also be a number.
Variable names can have from 1 to 8 characters, beginning with an alphabetic character and containing letters or numbers only. The name is case sensitive. If a variable has not yet been assigned, its value is its name.
String variables or string constants are enclosed in either single or double quotes. An example of an assignment statement that defines a string variable is as follows:
name = `Peter Pan'
name = "Peter Pan"
Numeric variables may be entered without quotes, but are still considered strings.
number = -99.99
Predefined script variables
Some variable names are predefined; it is a good idea to avoid assigning values to these variables. The following are predefined script variables -- their values will change with every execution of a GrADS command from the script:
rc
result
lat, lon, lev,
and time
are also used
as predefined variables in GrADS. Although using them within a script
is okay, in order to avoid confusion it is not recommended.
Global string variables
String variables are usually local to the functions they are contained in. Global string variables are also available. They are specified via the variable name. Any variable name starting with an underscore (_) will be assumed to be a global variable, and will keep its value throughout an entire script file. An example of an assignment statement that defines a global string variable is as follows:
_var1 = "global variable 1"
N.B. Global variables cannot be used in function headers. For example:
function dostuff(_var)
wouldn't make sense, since _var
is a global variable, and would
be invalid if it were the only argument.
Compound string variables
Compound variables are used to construct arrays in scripts. A compound variable has a variable name with segments separated by periods. For example:
varname.i.j
In this case, when the variable contents are accessed,
i
and j
will be looked up to see if they are
also variables (non-compound). If they are, the i
and
j
will be replaced by the string values of i
and j
. For example:
i = 10
j = 3
varname.i.j = 343
In the above example, the assignment is equivalent to:
varname.10.3 = 343
Note that the string values of i
and j
may
be anything, but the variable name specification in the script must
follow the rules for variable names: letters or numbers, with a
leading letter. The variable name after substitution may be any
string:
i = 'a#$xx'
varname.i = 343
The above is valid. However, we cannot refer to this variable name directly:
varname.a#$xx = 343
would be invalid.
Variable names may not be longer than 16 characters, either before or after substitution.
Note that the GrADS scripting language is not particularly efficient in handling large numbers of variables. Thus compound variables should not be used to create large arrays:
i = 1
while (i < 10000)
   var.i = i
   i = i + 1
endwhile
The above loop will create 10000 distinct variable names. Such a large number of variables in the variable chain will slow the script down a lot.
The following operators are implemented in the scripting language:
|
logical OR &
logical AND !
unary NOT -
unary minus =
equal !=
not equal >
greater than >=
greater than or equal <
less than <=
less than or equal %
concatenation +
addition -
subtraction *
multiplication /
divisionThe following operators will perform a numeric operation if the operands are numeric:
=, !=, >, >=, <, <=, +, -, *, /
If any of the following operations are attempted with non-numeric operands, an error will result:
+, -, *, /
Arithmetical operations are done in floating point. If the result is
integral, the result string will be an integer. Logical operations
will give a character 0
(zero) if the result is FALSE,
and a character 1
(one) if the result is TRUE.
Script expressions consist of any combination of operands, operators, and parentheses. Operands may be string constants, variables, or function calls. The precedence of the operators is:
-, ! (Unary)
/, *
+, -
%
=, !=, >, >=, <, <=
&
|
Within the same precedence level, operations are performed left to right. Parentheses modify the order of operation according to standard convention.
All script expressions, including all function calls, etc. are evaluated and the resulting string is what gets executed as a command. For example:
var1 = -1 ; var2 = 10
if (var1*var2 < 10 & var1 > 0)
say 'both statements are true'
else
say 'it is not the case that both statements are true'
endif
For the expression following if
, both sides of the
logical operation must be evaluated before the entire expression can
be simplified into a true or false result. In this case, the
subexpression on the left is true, but the subexpression on the left
is not, so the whole expressions resolves to 0 (zero) and the script
will print:
it is not the case that both statements are true
Concatenation
In some espressions, the concatenation operator may be implied. The %
operator may be omitted whenever the two operands are a string
constant and a variable name. With implied concatentation, intervening
blanks will be ignored.
For example, the following expressions have the same effect:
'set lat 'minlat%' '%maxlat
uses the concatenation operator % 'set lat 'minlat' 'maxlat
concatenation is implied
Assuming two previous statements, minlat = -30
and
maxlat = 30
, the resulting expression would be:
'set lat -30 30'
Keep in mind the order of precedence when using the concatenation operator.
Function calls take the form of:
name(arg,arg,arg,...)
where the function name follows the same rules as for variable names, and the arguments may be any expression. Functions may either be contained within the script file itself, or the may be intrinsic functions. Functions contained within other script files are not supported as yet (other script files may be executed via the GrADS run command).
In either case, functions are invoked as a script expression is being evaluated. Script functions always have a single string result, but may have one or more string arguments. Functions are invoked by:
name(arg,arg,arg...)
If the function has no arguments, you must still provide the parentheses:
name()
You may provide your own functions from within your script file
by using the function
definition record:
function name(variable, variable, ...)
To return from a function, use the return
command:
return expression
The expression
is optional; if not provided, a NULL string will
be returned. (A null string is: '') The result of the function
is the result of the expression specified on the return command.
When a function is invoked, the arguments are evaluated, then flow of control is transferred to the function. The variables contained in the list within the function definition record are initialized to the values of the passed arguments. If too few arguments where passed for the variables specified, the trailing variables are uninitialized. If too many arguments are passed, the extra arguments are discarded.
You may modify the variables from the function definition record without modifying the variables from the calling routine.
Scope of variables is normally local to the function, but can be global.
When a script file is first invoked (via the run
command),
execution starts at the beginning of the file. A function
definition record may optionally be provided at the beginning.
If it is, it should specify one variable name. This variable
will be initialized to any run
command options. If no options
were given, the variable will be initialized to NULL.
strlen (string)
string
.
sublin (string, n)
This function gets a single line from a string containing several
lines. The result is the nth
line of
string
. If the string has too few lines, the
result is NULL. n
must be an integer.
subwrd (string, n)
This functions gets a single word from a string.
The result is the nth
word of string
.
If the string is too short, the result is NULL.
n
must be an integer.
substr (string, start, length)
This function gets part of a string.
The sub-string of string
starting at location
start
for length length
will be returned.
If the string is too short, the result will be short or NULL.
start
and length
must be integers.
read (filename)
This functions reads individual records from file filename
.
Repeated calls must be made to read consecutive records. The result is
a string containing two lines: the first line is the return code, the
2nd line is the record read from the file. The record may be a maximum
of 80 characters. Use the sublin
function to separate the
result. Return codes are:
0 -
ok 1 -
open error 2 -
end of file 8 -
file open for write 9 -
I/O error
write (filename, record <, append>)
This functions writes records to output file filename
.
On the first call to write for a particular file, the file is opened
in write mode. This will destroy an existing file! If you use the
optional append flag, the file will be opened in append mode, and all
writes will be appended to the end of the file. Return codes are:
0
- ok 1
- open error 8
- file open for read
close (name)
This function closes the named file. This must be done if you wish to
read from a file you have been writing to. This can also be used to
rewind a file. Return codes are:
0
- ok 1
- file not open
There are some GrADS commands that, although not designed exclusively for scripts, are most useful in script applications. These include:
To see the list of available options, issue the query
command by itself. A
description of the query
options that are most useful for script applications follows.
q define
--
Lists all defined variables
q defval ival
jval
-- Gives defined grid value at ival, jval
To interactively modify grid point values for a defined
variable, q defval
can be used in conjunction with set defval
. For example, the
code shown below queries the value of sst at gridpoint(i,j), then
tests to see if the value is less than -1.6, and if it is, sets the
sst to a bad value.
'q defval sst 'i' 'j
val = subwrd(result,3)
if (val < -1.6)
  'set defval sst 'i' 'j' 'bad_value
endif
q dims
--
Gives the current dimension environment
q file
n
-- Gives info on file number n
q files
--
Lists open files
q fwrite
--
Gives the name of the file used for fwrite operations
q gxinfo
--
Lists graphics settings
This option is handy when trying to find the plot area. The output
from q gxinfo
might
look like this:
Last Graphic = Line
Page Size = 11 by 8.5
X Limits = 2 to 10.5
Y Limits = 0.75 to 7.75
Xaxis = Lon Yaxis = Val
Mproj = 2
The first line indicates that the output is a line plot. The second line
gives the page dimensions -- in this case GrADS is in landscape
mode. The third and fourth lines give the x and y boundaries of the
plot. In this case the plot has 1-inch margins in the x direction and
0.75-inch margins in the y direction. The fifth line tells what kind
of axes you have, and the sixth line identifies the map projection:
1
Scaled (no preservation of aspect ratio)2
Latlon (2-D horizontal fields) 3
Northern polar stereographic 4
Southern polar stereographic 5
Robinson (lon range must be -180 to
180 and lat range must be -90 to 90)
q pos
-- Waits for mouse click, returns position
q shades
-- Gives colors and levels of shaded contours
q time
- gives time range of current open file
q transform coord1 coord2
-- Coordinate transformations
where transform
is one of:
xy2w
XY coords to world coords
xy2gr
XY coords to grid coords
w2xy
world coords to XY coords
w2gr
world coords to grid coords
gr2w
grid coords to world coords
gr2xy
grid coords to XY coords
XY coords are inches on the page (screen) where the page is 11x8.5 inches or 8.5x11 inches, depending on how GrADS was started.
World coords are lat, lon, lev, time or val, depending on what the dimension environment is when the grid was displayed. Note that time is displayed (and must be specified) in GrADS absolute date/time format. val is the value coordinate for a 1-D plot (linegraph).
Grid coordinates are the i,j indices the grid being displayed. For station data sets, grid and world coordinates are equivalent except for the time dimension. Note that if you display a grid from a 'wrapped' data set, the grid numbers may be out of range of the actual file grid numbers. (A 'wrapped' data set is a data set that covers the earth in the longitude direction. Wrapping takes place automatically). The conversions are done consistently, but you may want to be sure you can handle the wrapping case if your data set is global.
N.B. Coordinate transform queries are only valid after something has been displayed, and the transformations apply only to the most recent item that has been displayed.
When using the graphics output type set gxout findstn
, three
arguments must be provided with the display
command. The
first argument is a station data expression. The 2nd and 3rd arguments
are the X and Y screen coordinates of the of the desired search
location. GrADS will find the station closest to the specified X and
Y position, and print its stid, lon, and lat. This graphics output
type should only be used when X and Y are the varying dimensions and
AFTER a regular display command (that results in graphics output) is
entered.
set dbuff on|off
This command sets double buffer mode on
or
off
. This allows animation to be controlled from a
script. The clear
command also sets double buffer mode off
.
swap
Swaps buffers, when double buffer mode is on
. If double
buffer mode is off
, this command has no effect.
The usual usage of these commands would be:
set dbuff on
start looping
   display something
   swap
endloop
set dbuff off
GrADS has the capability to implement a graphical user interface. This interface is used to draw widgets (buttons and pull down menus) that allow a "point and click" interface between the Grads user and the scripting language.
Here is a sample from a script illustrating how to draw a button:
set rgb 90 100 100 100 set rgb 91 50 50 50 set rgb 92 200 200 200 set button 2 90 91 92 3 90 92 91 6 draw button 1 5.5 1 2 0.5 This is a Button
The reference pages for set
button
and draw
button
contain information on how to specify the button
characteristics and position.
A button's initial "state" is ON
. If a user clicks on a
button following a q pos
command, then the button state will switch from ON (1)
to
OFF (0)
. A second q
pos
followed by a mouse click on the button will return it
to the ON
state. The button state may also be changed
with the redraw
button
command.
The output from the q pos
command
is what makes the button widgets so useful. Here is a template of what
q pos
returns after a mouse click
on a button:
Position = xpos ypos mousebutton widgetclass buttonnumber buttonstate
where:
xpos, ypos    
- coordinates of the mouse click in virtual page units mousebutton   
- either 1, 2, or 3 for the left, center, or right mouse button widgetclass   
- 1 is the widget class number for buttons buttonnumber  
- the number assigned to the button when it was originally drawn buttonstate   
- either 0 (meaning "off") or 1 (meaning "on")
If the user did not click on a button, then widgetclass
will be 0 and there will be no output for
buttonnumber
or buttonstate
.
As with button widgets, dropmenus provide a "point-and-click"
interface between scripts and the GrADS user. The reference pages for
set dropmenu
and
draw dropmenu
contain information on how to specify the dropmenu characteristics and
position.
The output from q pos
after a click on a dropmenu is similar to that described above for
buttons. Here is a template of what is returned by q pos
after a mouse click
on a dropmenu:
Position = xpos ypos mousebutton widgetclass menunumber inum
where:
xpos, ypos    
- coordinates of the mouse click in the menu base in virtual page units mousebutton   
- either 1, 2, or 3 for the left, center, or right mouse button widgetclass   
- 3 is the widget class number for dropmenus menunumber    
- the number assigned to the dropmenu when it was originally drawn inum          
- the menu item number selected from the menu list
If no menu item is selected, then menunumber
and inum
will
both be -1.
Here is a script sample illustrating how to use a dropmenu:
'reset events' 'set rgb 90 100 100 100' 'set rgb 91 150 150 150' 'set rgb 92 200 200 200' 'set dropmenu 1 91 90 92 0 91 90 92 1 91 90 92 90 92 6' 'draw dropmenu 1 1 8 1.5 0.5 Select a Variable | Wind | Temperature | Height | SLP ' noselect = 1 while (noselect) 'q pos' menunum = subwrd(result,7) menuitem = subwrd(result,8) if (menunum = 1) if menuitem = 1 ; newbase = 'Variable = Wind' ; endif if menuitem = 2 ; newbase = 'Variable = Temp' ; endif if menuitem = 3 ; newbase = 'Variable = Height' ; endif if menuitem = 4 ; newbase = 'Variable = SLP' ; endif 'draw dropmenu 1 1 8 1.5 0.5 'newbase' | Wind | Temperature | Height | SLP ' noselect = 0 endif endwhile
Here is another script sample illustrating how to use cascading dropmenus:
'clear' 'set rgb 90 100 100 100' 'set rgb 91 150 150 150' 'set rgb 92 200 200 200' 'set button 1 91 -1 -1 1 91 90 92 12' 'draw button 1 1 8 1 0.5 quit' 'set dropmenu 1 91 -1 -1 1 91 90 92 1 91 90 92 90 92 6' 'draw dropmenu 1 1.5 7.5 2 0.5 Menu Base | Space | Earth >05> | Sun | Moon' 'draw dropmenu 5 cascade Ocean | Land | Atmosphere >11> | Biosphere' 'draw dropmenu 11 cascade Snow | Rain | Mist | Tornado ' while (1) 'q pos' say result ev = subwrd(result,6) if (ev!=3); break; endif; endwhile
It is left to the GrADS script writer (that means you!) to run the demo and
interpret the output of q pos
when clicking on all the options in the cascade of dropmenus.
GrADS has a widget type called rband
for rubber banding. There
are two rband
modes: box
and line
.
To set up the rband
widget, use the following command:
set rband num mode x1 y1 x2 y2
where:
num
- widget numbermode
- may be either box
or line
x1
- lowest X point where the widget will be active (in virtual page units)y1
- lowest Y point where the widget will be active (in virtual page units)x2
- highest X point where the widget will be active (in virtual page units)y2
- highest Y point where the widget will be active (in virtual page units)
In box
mode, as the user clicks and drags the mouse in
the active rband area a box is drawn with one corner located at the
initial click and the opposite corner located at the release point. In
line
mode, a line is drawn between these two points.
For example, suppose you want to set up a
box
rubber band widget in the plot region only.
First, execute q gxinfo
to get the X and Y limits of the plot area. The result from q gxinfo
might look like
this:
Last Graphic = Line Page Size = 11 by 8.5 X Limits = 2 to 10.5 Y Limits = 0.75 to 7.75 Xaxis = Lon Yaxis = Val Mproj = 2
Second, set up the widget with set rband
using the dimensions
grabbed from the result of q gxinfo
:
xlims = sublin(result,3) ylims = sublin(result,4) x1 = subwrd(xlims,4) x2 = subwrd(xlims,6) y1 = subwrd(ylims,4) y2 = subwrd(ylims,6) 'set rband 21 box 'x1' 'y1' 'x2' 'y2
Finally, use q pos
to activate the widget.
ga-> q pos
This freezes the system until the user clicks, drags, and then releases the mouse somewhere within the active rband area. Here is a template for the output you would get from GrADS after a mouse click and drag in the rband area:
Position = xpos1 ypos1 mousebutton widgetclass widgetnumber xpos2 ypos2
where:
xpos1, ypos1   
- coordinates of the initial mouse click in virtual page units mousebutton    
- either 1, 2, or 3 for the left, center, or right mouse button widgetclass    
- 2 is the widget class number for rbands widgetnumber   
- the number assigned to the
rband widget when it was set up xpos2, ypos2   
- coordinates of the mouse release point in virtual page units
The page coordinates can be then be used to draw a box (or a line)
where the user specified, or parsed and used in the coordinate
transform q xy2w
to
recover the lat/lon region selected by the user.