packages icon

				Vis5D Version 5.1


1. OVERVIEW OF Vis5D

     Vis5D is a	software system	for visualizing	data made by numerical weather
models and similar sources.  Vis5D works on data in the	form of	a five-
dimensional rectangle.	That is, the data are real numbers at each point of a
"grid" which spans three space dimensions, one time dimension and a dimension
for enumerating	multiple physical variables.  Of course, Vis5D works perfectly
well on	data sets with only one	variable, one time step	(i.e. no time dynamics)
or one vertical	level.	However, your data grids should	have at	least two rows
and columns.

     The major new feature of Vis5D version 5.1	is support for comparing
multiple data sets.  This extra	data can be incorporated at run-time as	a list
of *.v5d files or imported at anytime after Vis5D is running.  Data can	be
overlaid in the	same 3-D display and/or	viewed side-by-side spread sheet style.
Data sets that are overlaid are	aligned	in space and time.  In the spread sheet
style, multiple	displays can be	linked.	 Once linked, the time steps from all
data sets are merged and the controls of the linked displays are synchronized.

     The Vis5D system includes the vis5d visualization program,	several	programs
for managing and analyzing five-dimensional data grids,	and instructions and
sample source code for converting your data into its file format.  We have
included the Vis5D source code so you can modify it or write new programs.  We
have also included sample data sets from the LAMPS model and from Bob
Schlesinger's thunderstorm model, so you can work through our examples.

     Vis5D version 1.0 was written by Bill Hibbard and Dave Santek of the
University of Wisconsin	Space Science and Engineering Center, supported	by the
NASA Marshall Space Flight Center, and by Marie-Francoise Voidrot-Martinez of
the French Meteorology Office.	Later version enhancements were	written	by Bill
Hibbard, Brian Paul, Johan Kellum, and Andre Battaiola.	 Dave Kamins and Jeff
Vroom of Stellar Computer, Inc.	provided substantial help and advice in	using
the Stellar software libraries.	 Simon Baas and	Hans de	Jong of	the Netherlands
ported Vis5D to	HP workstations.  Pratish Shah of Kubota Inc. ported Vis5D to
the Kubota Alpha/Denali	workstation.  Mike Stroyan of Hewlett Packard added PEX
support.

     Vis5D is offered under the	terms of the GNU General Public	License, which
you can	find in	the file "NOTICE".  As the notice states, there	is no warranty
for the	Vis5D system, but we would be interested in hearing about your questions
and problems.  You can join the	Vis5D mailing list by sending email to
majordomo@ssec.wisc.edu	with:

subscribe vis5d-list

as the first line of the message body (not the subject line).  You can also send
questions to Bill Hibbard (whibbard@macc.wisc.edu) and Johan Kellum
(johan@ssec.wisc.edu).	Our postal address is:

     Space Science and Engineering Center
     University	of Wisconsin - Madison
     1225 West Dayton Street
     Madison, WI  53706


This document is the complete guide for	using Vis5D.  It is available in
PostScript or ASCII.

Contents:
     Section 1 Overview
     Section 2 System requirements and installation
     Section 3 Putting your data into Vis5D
     Section 4 McIDAS files
     Section 5 Vis5D utilities
     Section 6 Using vis5d to visualize	your data
     Section 7 The v5dimport utility
     Section 8 Sample data sets
     Section 9 Version history


1.1 Vis5D Documentation	on the World Wide Web

The Vis5D Home Page is available on the	World Wide Web page at URL:

     http://www.ssec.wisc.edu/~billh/vis5d.html

This is	linked to another Web document that describes how to use Vis5D files as
a World	Wide Web medium	for exchanging model output, at	URL:

     http://www.ssec.wisc.edu/~billh/view5d.html

There is a Web document	describing the Vis5D API (Application Programmer
Interface), intented to	help system developers use Vis5D as a visualization
subsystem of other systems, at URL:

     http://www.ssec.wisc.edu/~billh/api.html

There is a Web document	describing the Vis5D Tcl scripting interface at	URL:

     http://www.ssec.wisc.edu/~billh/script.html

Copies of the api.html and script.html files are included with the Vis5D ftp
distribution.


2. SYSTEM REQUIREMENTS AND INSTALLATION

     In	the following sections we describe the hardware	and software required to
run Vis5D and detail how to install Vis5D on your system.


2.1 System Requirements

Vis5D currently	works with the following systems.  In all cases, at least 32MB
of RAM is recommended and at least an 8-bit color display are required:

     1.	Silicon	Graphics workstations:
	  IRIX version 4.0.1 or	higher.
	  Multiple processors are used when present.
	  IrisGL is not	supported.

     2.	IBM RS/6000 workstations:
	  Model	320H or	higher
	  AIX version 3	or later
	  3-D graphics hardware	is supported through OpenGL

     3.	HP series 7000 or 9000 workstations:
	  HP-UX	A.09.01	or later
	  PEX optional

     4.	Sun Sparc workstations:
	  SunOS	5.x or later

	  ** IMPORTANT NOTE FOR	SunOS 5	USERS **
	  SunOS	5.x users:  The	X shared memory	extension may not work
	  correctly.  If Vis5D prints an error message to the effect of	"Shared
	  memory error"	then you'll have to append the following three lines to
	  the end of your /etc/system file then	reboot:
	       set shmsys:shminfo_shmmax = 0x2000000
	       set shmsys:shminfo_shmmni = 0x1000
	       set shmsys:shminfo_shmseg = 0x100

     5.	DEC Alpha workstations:
	  OSF/1	V1.3 or	later
	  Kubota Denali	Graphics hardware supported with KWS V1.3.3 or later and
	       NPGL Run-time license.

	  ** IMPORTANT NOTE FOR	OSF USERS **
	  you need to run 'limit stacksize 32m'	before you run Vis5D

     6.	IBM PC compatibles with	Linux:
	  75MHz	Pentium	CPU or faster recommended
	  Linux	1.0 or later
	  XFree86 (X window system) must be installed


Note that on systems which don't have 3-D graphics hardware or OpenGL, all 3-D
rendering is done in software using Mesa (an OpenGL work-alike).  Be aware that
software rendering is rather slow.  3-D	graphics hardware is recommended.

     If	you would like to port Vis5D to	a new graphics system or workstation
read the "PORTING" file	which gives more information.  If you succeed, please
inform us so that we may add your work to the distribution.


2.2 Installing Vis5D

     Vis5D is obtained via anonymous ftp.

Here are the installation instructions:

     1.	Go to the directory in which you want Vis5D installed:
	  % cd /usr/mydir

	  NOTE:	 The installation of Vis5D will	result in a new	subdirectory
	  named	"vis5d-5.1/" being created in the current directory.

	  NOTE:	 Be sure that you have write permission	in this	directory.  If
	  you do not, you should become	superuser before proceeding.  When
	  finished installing Vis5D be sure to set the file ownership and
	  permissions accordingly.

     2.	Start ftp:
	  % ftp	iris.ssec.wisc.edu
	  or
	  % ftp	144.92.108.63

     3.	Login as anonymous and send your email address as the password:
	  Name:	anonymous
	  Password: email-address

     4.	Go to the pub/vis5d directory:
	  ftp> cd pub/vis5d-5.1

     5.	Transfer files in binary mode:
	  ftp> binary

     6.	Get the	Vis5D archive file:
	  ftp> get vis5d-5.1.tar.Z

     7.	Get the	optional sample	data archive file:
	  The vis5d-data.tar.Z file contains topography, map outlines and sample
	  data sets.  If you've	used Vis5D in the past you can should already
	  have these files and can move	them into your new "vis5d-5.1"
	  directory.

	  ftp> get vis5d-data.tar.Z

     8.	Exit ftp:
	  ftp> bye

     9.	Uncompress and un-tar the archive file:
	  % uncompress vis5d-5.1.tar.Z
	  % tar	-xvf vis5d-5.1.tar

     10. Change	to the newly created vis5d directory:
	  % cd vis5d-5.1

     11. Optionally uncompress and untar the data file:
	  % mv ../vis5d-data.tar.Z .
	  % uncompress vis5d-data.tar.Z
	  % tar	-xvf vis5d-data.tar

     12. Run make:
	  % make

	  Make will print a list of systems supported for Vis5D.  Look for yours
	  on the list and type the appropriate make command.  For example,
	  suppose you have an IBM RS/6000 without OpenGL and 3-D graphics
	  hardware.  You should	type:

	  % make ibm-x

	  Vis5D	and its	utility	programs will now be compiled.	If you do not
	  have C and/or	FORTRAN	compilers on your system, this step will fail
	  with an error	message	such as	"cc: Command not found." or "f77:
	  Command not found."  In this case you	will have to get the appropriate
	  archive of executable	programs:

	  a. List the "viewer" files.  These files are archives	which contain
	   vis5d exectuables for common	Unix systems:
	       ftp> dir	*viewer*
	  b. Make sure you're still in the vis5d-5.1 directory and download the
	     viewer file for your operating system (xxx):
	       ftp> get	vis5d.xxx.viewer.tar.Z
	  c. Exit ftp:
	       ftp> bye
	  d. Uncompress	and un-tar the archive:
	       % uncompress vis5d.xxx.viewer.tar.Z
	       % tar -xvf vis5d.xxx.viewer.tar

     13. Test Vis5D:
	  % ./vis5d LAMPS.v5d

	  NOTE:	 To quit, click	on the "EXIT" widget button.

     14. You may delete	the .tar files if desired.



2.3 Manifest

     When you are finished installing Vis5D you	should have a directory	named
"vis5d-5.1" which contains the following files and subdirectories:

     README	    this documentation file in ASCII
     README.ps	    this documentation file in PostScript
     NOTICE	    the	GNU general public license (copyright)
     PORTING	    an ASCII document with notes on porting Vis5D
     LAMPS.v5d	    Sample LAMPS data set
     SCHL.v5d	    Sample data	set:  Bob Schlesinger's	thunderstorm model
     OUTLSUPW	    World continental map lines	file
     OUTLUSAL	    Low	resolution map of US with state	boundaries
     OUTLUSAM	    Medium resolution map of US	with state boundaries
     EARTH.TOPO	    Earth topography file
     api.html	    documentation file for the API between Vis5D and its user
     interface
     script.html    documentation file for Vis5D scripting language
     *.tcl	    example scripts
     vis5d	    this is the	vis5d visualization program
     v5dappend	    utility to join v5d	files together
     v5dinfo	    utility to see summary of a	v5d file
     v5dstats	    utility to see statistics of a v5d file
     v5dedit	    utility to edit the	header of a v5d	file
     v5dimport	    utility to convert,	resample, and reduce v5d files
     gr3d_to_v5d    utility to convert a McIDAS	GR3D file to v5d format
     comp_to_v5d    utility to convert (a) comp5d file(s) to v5d format
     listfonts	    utility to list fonts available on SGI systems for IRIS GL
     src/	    source code	for vis5d
     util/	    source code	for the	Vis5D utilities
     lui5/	    source code	for LUI	user interface library
     Mesa/	    source code	for the	Mesa 3-D graphics library
     import/	    source code	for the	v5dimport program
     userfuncs/	    directory of user-written analysis functions
     contrib/	    software contributed by Vis5D users
     convert/	    source code	for sample data	conversion programs
     user_data/	    sample code	for user supplied data formats



2.4 Customizing

     After installation	and testing you	may want to customize the vis5d	program
by editing the src/vis5d.h file:

     1.	   The visualization program vis5d assumes your	system has 32 megabytes
      of memory.  Although you can override this when you invoke vis5d,	it may
      be convenient to change the default if your system has more than 32MB.
      The default number of megabytes is defined by the	value of MBS in	the
      src/vis5d.h include file.

     2.	   There are two ways to specify a different topography	and/or map
      file. One	way is to edit src/vis5d.h and change the values for TOPOFILE
      and/or MAPFILE.  For example, if you move	the map	and topography files to
      /usr/local/bin, you would	specify	"/usr/local/data/EARTH.TOPO" and
      "/usr/local/data/OUTLUSAM" respectively. The other way is	press the
      'DISPLAY'	button on the main contral panel, then press the 'Options'
      button found above each display menu.  The 'toponame' and/or 'mapname'
      fields can be changed accordingly.

     When finished changing the	src/vis5d.h file you must recompile the	programs
by repeating installation step 12 above.

     If	Vis5D is going to be used by multiple users on your system you may
want to	move the vis5d executables and data files to a common directory
tree such as /usr/local:
     % mv vis5d	/usr/local/bin
     % mv v5d* /usr/local/bin
     % mv OUTL*	/usr/local/data
     % mv EARTH.TOPO /usr/local/data
then change change the vis5d.h file as described above to indicate where
the map	and topography files are stored.



3. PUTTING YOUR	DATA INTO Vis5D

     Vis5D works with data organized as	a 5-D rectangle.  The first 3 dimensions
are spatial:  rows, columns, and levels	(or latitutude,	longitude, and height).
The 4th	dimension is time.  The	5th dimension is the enumeration of multiple
physical variables such	as temperature,	pressure, water	content, etc.

     In	addition to the	data itself, there are a number	of parameters needed to
describe a Vis5D dataset:  the sizes of	the five dimensions (number of rows,
columns, levels, timesteps, and	variables), geographic position	and orientation
of the data (map projection), the names	of the variables, the actual times and
dates associated with each timestep, etc.

     The vis5d visualization program accepts two standard file formats:	 v5d
files and comp5d files.	 Both store 3-D	data in	a compressed format which vis5d
can use	quickly	and efficiently.  Comp5d files are those which were produced by
the comp5d program in previous versions	of Vis5D.  The v5d file	format is the
new, and prefered, file	format used in version 4.0 and later of	 Vis5D.	 It is
intended to be a replacement for the comp5d format because it more flexible and
may be extended	in the future.

     Vis5d can also accept a user defined file format.	A user can create a new
file format and	the functions to read this format.  See	section	3.4 below.

     To	view your data with vis5d you will typically write a conversion	program
to convert your	data files to v5d format.  To help you do this we've included
four sample conversion programs	to guide you.  Basically, you just add the
instructions to	read your file format, we provide the instructions to write the
v5d file.  See section 3.1 below.

     If	you have used Vis5D in the past, you may continue to convert your data
to McIDAS format and use comp5d	to make	a compressed file.  However, to	take
full advantage of the new map projections and vertical coordinate system in
version	4.0 and	higher,	you should write a new conversion program to make v5d
files.

     Another option for	getting	your data into Vis5D is	the v5dimport utility.
v5dimport is a new program for file conversion,	combining, and resampling.  It
reads a	number of different file formats and can be extended to	read new
formats.  See section 7	for more details.


3.1 Converting Your Data to v5d	Format

     Files in the v5d format are created with functions	from the v5d library.
We've included four sample conversion programs which outline how to make a v5d
file.  They are	located	in the convert/	subdirectory.  You can choose which one
to use as a template for your data converter:

     foo_to_v5d.f   A Fortran program which assumes a rectangular lat/lon
		    map	projection and equally spaced linear vertical
		    coordinate system.

     foo2_to_v5d.f  A Fortran program which allows any map projection and
		    vertical coordinate	system as well as a different
		    number of vertical levels for each variable.

     foo_to_v5d.c   A C	program	which assumes a	rectangular lat/lon map
		    projection and equally spaced linear vertical
		    coordinate system.

     foo2_to_v5d.c  A C	program	which allows any map projection	and
		    vertical coordinate	system as well as a different
		    number of vertical levels for each variable.


     In	any case, each conversion program uses three functions to write	the v5d
file: v5dCreate	(or v5dCreateSimple), v5dWrite,	and v5dClose.  v5dCreateSimple
is used	to create v5d files which only specify the most	basic parameters.
v5dCreate allows more complicated parameters.  There are versions of these
functions for C	and Fortran programs.

     Here are the descriptions of the v5dCreate	and v5dCreateSimple functions in
a format similar to man	page documentation.  C programmers should note that in
the argument descriptions we describe arrays by	FORTRAN	convention, i.e. A(1) is
the first element of A whereas in C this would be A[0].


Fortran-callable functions:
     integer function v5dcreatesimple( name, numtimes, numvars,nr, nc, nl,
			      varname, timestamp, datestamp, northlat, latinc,
			      westlon, loninc, bottomhgt, hgtinc )
     character*	(*) name
     integer numtimes
     integer numvars
     integer nr
     integer nc
     integer nl
     character*10 varname(MAXVARS)
     integer timestamp(*)
     integer datestamp(*)
     real northlat
     real latinc
     real westlon
     real loninc
     real bottomhgt
     real hgtinc

     integer function v5dcreate( name, numtimes, numvars, nr, nc, nl, varname,
			      timestamp, datestamp, compress, projection,
			      proj_args, vertical, vert_args )
     character*	(*) name
     integer numtimes, numvars
     integer nr
     integer nc
     integer nl(*)
     character*10 varname(MAXVARS)
     integer timestamp(*)
     integer datestamp(*)
     integer compress
     integer projection
     real proj_args(*)
     integer vertical
     real vert_args(*)



C-callable functions:
     int v5dCreateSimple( name,	numtimes, numvars, nr, nc, nl, varname,
			      timestamp, datestamp, northlat, latinc, westlon,
			      loninc, bottomhgt, hgtinc	)
     char *name;
     int numtimes;
     int numvars;
     int nr, nc, nl;
     char varname[MAXVARS][10];
     int timestamp[], datestamp[];
     float northlat, latinc;
     float westlon, loninc;
     float bottomhgt, hgtinc;

     int v5dCreate( name, numtimes, numvars, nr, nc, nl, varname, timestamp,
			      datestamp, compress, projection, proj_args,
			      vertical,	vert_args )
     char *name;
     int numtimes, numvars;
     int nr, nc, nl[];
     char varname[MAXVARS][10];
     int timestamp[], datestamp[];
     int compress;
     int projection;
     float proj_args[];
     int vertical;
     float vert_args[];

Arguments used by v5dCreate and	v5dCreateSimple:
     name	 The name of the v5d file to create
     numtimes	 Number	of timesteps (at least 1)
     numvars	 Number	of variables (at least 1)
     nr		 Number	of rows	in all 3-D grids (at least 2)
     nc		 Number	of columns in all 3-D grids (at	least 2)
     varname	 Array of variable names:
		      varname(1) = name	of first variable
		      varname(2) = name	of second variable
		      ...
		      varname(numvars) = name of last variable
     timestamp	 Array of time labels for the timesteps	in HHMMSS format:
		      timestamp(1) = time of first timestep
		      timestamp(2) = time of second timestep
		      ...
		      timestamp(numtimes) = time of last timestep
     datestamp	 Array of date labels for the timesteps	in YYDDD format
		      datestamp(1) = date of first timestep
		      datestamp(2) = date of second timestep
		      ...
		      datestamp(numtimes) = date of last timestep


Arguments used only by v5dCreateSimple:
     nl		 Number	of levels in all 3-D grids (at least 1)
     northlat	 Latitude of northern edge of box in degrees
     latinc	 Increment between rows	in degrees  (positive)
     westlon	 Longitude of western edge of box in degrees (positive West
     longitude)
     loninc	 Increment between columns in degrees  (positive)
     bottomhgt	 Bottom	boundary of box	in km
     hgtinc	 Increment between levels in km	(positive)

Arguments used only by v5dCreate:
     nl		 Number	of levels in the 3-D grids per variable:
		      nl(1) = number of	levels for first variable
		      nl(2) = number of	levels for second variable
		      ...  = ...
		      nl(numvars) = number of levels for last variable
     compress	 Compression mode (1, 2	or 4 bytes per grid point)
     projection	 Indicates type	of map projection:
		      0	= linear, rectangular, generic units
		      1	= linear, rectangular, cylindrical-equidistant
		      2	= Lambert Conformal
		      3	= Stereographic
		      4	= Rotated
                      5 = Mercator
     proj_args	 Projection arguments:
		      if projection=0 then
			   proj_args(1)	= North	boundary of 3-D	box
			   proj_args(2)	= West boundary	of 3-D box
			   proj_args(3)	= Increment between rows
			    proj_args(4) = Increment between columns
		      else if projection=1 then
			   proj_args(1)	= North	Latitude bound of 3-D box
			   proj_args(2)	= West Longitude bound of 3-D box
			   proj_args(3)	= Increment between rows in degrees
			   proj_args(4)	= Increment between cols in degrees
		       else if projection=2 then
			   proj_args(1)	= Standard Latitude 1
			   proj_args(2)	= Standard Latitude 2
			   proj_args(3)	= Row of North/South pole
			   proj_args(4)	= Column of North/South	pole
			   proj_args(5)	= Longitude parallel to	columns
			   proj_args(6)	= Increment between columns in km
		      else if projection=3 then
			   proj_args(1)	= Latitude of center (degrees)
			   proj_args(2)	= Longitude of center (degrees)
			   proj_args(3)	= Row of center	of projection
			   proj_args(4)	= Column of center of projection
			   proj_args(5)	= Spacing between columns at center
		      else if projection=4 then
			   proj_args(1)	= North	boundary on rotated sphere
			   proj_args(2)	= West boundary	on rotated sphere
			   proj_args(3)	= Increment between rows
			    proj_args(4) = Increment between columns
			   proj_args(5)	= Earth	Latitude corresponding to (0,0)
			   proj_args(6)	= Earth	Longitude corresponding	to
		      (0,0)
			   proj_args(7)	= Rotation angle
                      else if projection=5 then
                           proj_args(1) = Latitude of center of projection
                           proj_args(2) = Longitude of center of projection
                           proj_args(3) = Row Increment in Kilometers
                           proj_args(4) = Column Increment in Kilometers
		      endif
     vertical	 Indicates type	of vertical coordinate system:
		      0	= equally spaced levels	in generic units
		      1	= equally spaced levels	in km
		      2	= unequally spaced levels in km
		      3	= unequally spaced levels in mb
     vert_args	 Vertical coordinate system arguments:
		      if vertical=0 then
			   vert_args(1)	= height of bottom level
			   vert_args(2)	= spacing between levels
		      else if vertical=1 then
			   vert_args(1)	= height of bottom level in km
			   vert_args(2)	= spacing between levels in km
		      else if vertical=2 then
			   vert_args(1)	= height (km) of grid level 1 (bottom)
			   vert_args(2)	= height (km) of grid level 2
			   ...
			 vert_args(N) =	height (km) of grid level N (top) where
				N is the maximum value in the nl array.
		      else if vertical=3 then
			   vert_args(1)	= pressure (mb)	of grid	level 1
		      (bottom)
			   vert_args(2)	= pressure (mb)	of grid	level 2
			   ...
			 vert_args(N) =	pressure (mb) of grid level N (top)
				where N	is the maximum value in	the nl array.
		      endif


The v5dWrite function is used to write a single	3-D grid of data to a v5d file.
The grid is identified by a timestep and physical variable number.  Here is the
synopsis of v5dWrite:

Fortran-callable function:
     integer function v5dwrite(	time, var, data	)
     integer time
     integer var
     real data(*)

C-callable function:
     int v5dWrite( time, var, data )
     int time;
     int var;
     float data[];

Arguments descriptions:
     time      A timestep number in the	range [1..numtimes]
     var       A variable number in the	range [1..numvars]
     data      3-D array of grid values; number	of values = nr*nc*nl(var)
	       ordered as data[row+nr*(col+nc*lev)] where row increases	from
	       North to	South, col increases from West to East,	and lev
	       increases from bottom to	top


The v5dClose function closes the v5d file after	the last grid has been written.
No arguments are needed.  Here is the synpsis of v5dClose:

Fortran-callable function:
     integer function v5dclose

C-callable function:
     int v5dClose()


Each of	the create functions returns 1 when successful and 0 when an error
occurs.

     Looking at	any of the example data	conversion programs, you'll see	that
there are variables which directly correspond to the arguments to
v5dCreate/v5dCreateSimple.  It is up to	you to initialize these	variables.  For
example, you'll	have to	assign to numtimes the number of timesteps in your
dataset, assign	to numvars the number of variables in your dataset, etc.  After
you've initialized all these variables,	the v5dCreate (or v5dCreateSimple) call
will create the	v5d file.  If you've failed to initialize any of the variables
you will see an	appropriate error message.

     Next, the conversion program will enter a nested loop inside of which you
must insert the	code to	read your data for the appropriate time	step and
physical variable number.  Read	your data into the array specified.  The
v5dWrite call will then	compress and write the data to the v5d file.  Finally,
the v5dClose function will be called after all the data	has been written.

     After you've written and compiled your file converter, you	should test it
with one of your data files then check that it worked by running the v5dinfo and
v5dstats utility programs on the v5d file.  If everything looks	OK, try	running
vis5d.

     Here is an	example	of typical values that might be	assigned to each
variable if one	were using the foo_to_v5d.f program:

     Assignment		 Comments
     numtimes =	5	 5 time	steps
     numvars = 4	 4 physical variables
     nr	= 30		 30 rows in each 3-D grid
     nc	= 40		 40 columns in each 3-D	grid
     nl	= 20		 20 levels in each 3-D grid
     varname(1)	= "U"	 U (east/west) wind component
     varname(2)	= "V"	 V (north/south) wind component
     varname(3)	= "T"	 Temperature
     varname(4)	= "P"	 Pressure
     timestamp(1) = 140000    2:00:00 pm
     timestamp(2) = 141500    2:15:00 pm
     timestamp(3) = 143000    2:30:00 pm
     timestamp(4) = 144500    2:45:00 pm
     timestamp(5) = 150000    3:00:00 pm
     datestamp(1) = 94036     36th day of 1994 (February 5)
     datestamp(2) = 94036     "
     datestamp(3) = 94036     "
     datestamp(4) = 94036     "
     datestamp(5) = 94036     "
     northlat =	60.0	 Northern boundary of box is at	30 degrees latitude
     latinc = 1.0	 There is 1 degree of latitude between each of the 30
     rows
     westlon = 100.0	 Western boundary of 3-D box is	at 100 degrees longitude
     loninc = 0.5	 0.5 degree of longitude between each of the 40	columns
     bottomhgt = 0.0	 Bottom	of box is at 0km (sea level)
     hgtinc = 1.0	 1 km between each of the 20 grid levels (top at 19.0km)


     The product of the	number of rows,	columns, levels, timesteps, and
variables is the total number of data points.  In this example:	 30*40*20*5*4 =
480,000.  A real dataset may be	100 rows by 100	columns	by 20 levels, have 50
timesteps, and 10 variables for	a total	of 100,000,000 data points.

     The difference between the	foo_to_v5d program (which uses v5dCreateSimple),
and the	foo2_to_v5d program (which uses	v5dCreate), is the later allows	you to
specify	any map	projection, vertical coordinate	system,	a different number of
grid levels for	each physical variable,	and to control data compression.  To
specify	a map projection, you must set the value of projection to 0,1,2	or 3 to
indicate which projection, then	specify	the projection-dependent parameters in
the proj_args arrray.  Specifying the vertical coordinate system is done
similarly.

     It	is sometimes useful to specify a different number of grid levels for
each variable.	For example, suppose most of your variables have 30 grid levels
but a some variables have fewer	grid levels, perhaps only one.	Prior to version
4.0 of Vis5D, you would	have had to fill in the	extra levels with redundant,
missing	or dummy data values.  With the	v5dCreate function you can specify how
many grid levels are present for each individual physical variable with	the nl
array parameter.  Be aware that	the amount of data passed to the v5dWrite call
will depend on which variable you're writing.  For example, if your grid has C
columns	and R rows then	the number of values in	the data array passed to
v5dWrite for variable V	must equal C*R*nl(V).

     By	default, the bottom-most grid level of each variable is	displayed at the
bottom of the 3-D box; each grid extends upward	for how	ever many levels are
present.  Sometimes, however, the bottom-most grid level of a particular
variable should	be positioned higher up.  An example of	this is	a combined
ocean/atmosphere dataset.  There may be	a total	of 18 grid levels:  the	bottom 8
grid levels being ocean	data and the top 10 grid levels	being atmospheric data.
In this	case, the bottom of the	atmospheric data should	be offset or shifted
upward by 8 grid levels.

     Elaborating on the	ocean/atmosphere example, suppose we have 2 ocean
variables named	S (salinity) and T (temperature) and 2 atmosphere variables
named P	(pressure) and T1 (temperature).  There	are 8 layers of	ocean data and
10 layers of atmospheric data.	Here is	a summary showing how the lowlev array
is the solution	to this	situation:





     varnum varname(varnum)	   nl(varnum)	  lowlev(varnum)
       1       S	  8	     0
       2       T	  8	     0
       3       P	  10	     8
       4       T1	  10	     8


The lowlev array is not	specified in the v5dCreate function because it was
developed after	the v5dCreate function was well	established.  Instead, the new
v5dSetLowLev function is called	with the lowlev	array.	This separate function
was added to extend the	functionality of v5dCreate without changing its	calling
sequence.  Here	is the synopsis	of v5dSetLowLev:

Fortran-callable function:
     integer function v5dsetlowlev( lowlev )
     integer lowlev(*)

C-callable function:
     int v5dSetLowLev( lowlev )
     int lowlev[];

Argument description:
     lowlev	 Specifies the vertical	offset,	in grid	levels,	for each
     variable.
		      lowlev(1)	= offset for first variable
		      lowlev(2)	= offset for second variable
		      ...  = ...
		      lowlev(numvars) =	offset for last	variable

v5dSetLowLev may be called at any point	between	v5dCreate and v5dClose.


     The v5dCreate and v5dcreate functions allow you to	control	how the	grid
data are compressed.  The default is for grid values to	be linearly scaled to
one byte integers.  This works very well for most data sets, since the scaling
factors	are chosen independently for each combination of time step, variable and
vertical level.	 Furthermore, the compression to one byte per grid point enables
Vis5D's	high degree of interactivity, since compression	allows entire data sets
to be resident in memory.  However, the	compress argument of the v5dCreate and
v5dcreate functions lets you pick whether grid point values are	scaled to 1-byte
integers, scaled to 2-byte integers, or	left as	4-byte floating	point values (no
compression).  We recommend that you try compression to	1-byte integers	first,
and only use 2 or 4 bytes if you have precision	problems at 1-byte.

     Vis5D version 4.2 and later allow you to specify the physical units for
each variable in your dataset.	The v5dSetUnits() function takes two arguments:
a variable number and a	units character	string.	 If the	first variable in your
file is	P and the units	are millibars then you can specify that	with:

     C:	 v5dSetUnits( 1, "millibars" )
     Fortran: call v5dsetunits(	1, "millibars" )

The units will be displayed by the v5dinfo program and in Vis5D	when using the
probe.

     To	compile	your program which uses	v5dCreate, v5dWrite, and v5dClose you
must link with the src/v5d.o and src/binio.o files.  See the makefiles in the
convert/ directory for examples.

     Finally, if your data is generated	by an atmospheric or oceanic model, you
may want to consider modifying your model to generate v5d files	directly using
the v5dCreate, v5dWrite, and v5dClose functions.  Look at the sample data
conversion programs for	ideas.


3.2 Map	Projections and	Vertical Coordinate Systems

     Version 4.0 of Vis5D added	support	for new	map projections	and vertical
coordinate systems.  When we use the term map projection, we're	referring to the
relationship between the rows and columns of data in the 3-D grid to the
latitude/longitude of the earth.  The term vertical coordinate system refers to
the relationship between the vertical levels of	data in	the 3-D	grid to	altitude
in the atmosphere (or depth in the ocean).

Vis5D 5.1 supports the following map projections:

(0) Generic rectilinear:  this is a linear, regularly-spaced coordinate	system
     with no implied units.  This system is useful when	your data is not related
     to	earth science (computational fluid dynamics for	example.)  North/south
     coordinates increase upward and east/west coordinates increase to the left.
     The projection is defined by four parameters:

     NorthBound	 Northern boundary of 3-D box
     WestBound	 Western boundary of 3-D box
     RowInc	 Increment (spacing) between grid columns
     ColInc	 Increment (spacing) between grid rows

     Example:  Suppose your 3-D	grid has 80 rows and 60	columns	and NorthBound =
	  100.0	meters,	WestBound = 50.0 meters, RowInc	= 0.5 meters, and ColInc
	  = 0.5	meters,	then:

	  the south boundary will be at	60.5 meters.  i.e. southbound =
	       NorthBound - (RowInc * (rows-1))
	  and the east boundary	will be	at 20.5	meters.	 i.e. eastbound	=
	       WestBound - (ColInc * (columns-1))



(1) Rectilinear	lat/lon	(cylindrical equidistant):  this is the	rectangular
     latitude/longitude	coordinate system used in previous versions of Vis5D.
     Latitude increases	to the North (upward in	the graphical display) and
     longitude increases to the	West (leftward in the graphical	display;
     positive west latitude).  The projection is defined by four parameters:

     NorthBound	 Northern boundary of 3-D box in degrees of latitude in	the
		 range [-90S,90N].
     WestBound	 Western boundary of 3-D box in	degrees	of longitude in	the
		 range [-180E,180W].
     RowInc	 Increment (spacing) between grid rows in degrees of latitude
		 greater than zero.
     ColInc	 Increment (spacing) between grid columns in degrees of
		 longitude greater than	zero.

     Example:  If your 3-D grid	has 30 rows and	60 columns and if NorthBound =
	  70.0,	WestBound = 140.0, RowInc = 1.0, and ColInc = 0.5, then:

	  the south boundary will be at	41 degrees latitude.  i.e. (NorthBound -
	       RowInc *	(rows-1))
	  and the east boundary	will be	at 110.5 degrees longitude. i.e.
	       (WestBound - ColInc * (columns-1))


(2) Lambert conformal:	a conic	projection defined by the following six
parameters:

     Lat1, Lat2	    First and second standard latitudes	in the range [-90S,90N].
		    Lat1 and Lat2 define where the imaginary cone intersects the
		    sphere of the Earth.  Lat1 and Lat2	must have the same sign,
		    that is, they must both be positive	or both	negative.  Also,
		    Lat1 must be greater than or equal to Lat2.
     PoleRow, PoleCol	 These parameters indicate the position	of the north or
		    south pole with respect to the 3-D grid coordinate system.
		    These values may be	outside	the 3-D	grid.  If Lat1 and Lat2
		    are	positive, the north pole is assumed, else, the south
		    pole is assumed.
     CentLon	    Central longitude:	this parameter indicates which Earth
		    longitude is to be parallel	to the 3-D grid	columns.
     ColInc	    Increment (spacing)	between	grid columns at	the central
		    longitude and standard latitudes, in km.  This parameter
		    controls the scale of the projection.

     Example 1:	 Suppose your 3-D grid has 35 rows and 40 columns and you want a
     Lambert conformal projection of the United	States centered	over Wisconsin:
	  Lat1 = 70.0
	  Lat2 = 20.0
	  PoleRow = -35.0
	  PoleCol = 20.0
	  Central Longitude = 90.0
	  ColInc = 100.0

     Example 2:	 Suppose your 3-D grid has 35 rows and 40 columns and you want a
     Lambert conformal projection over Australia:
	  Lat1 = -20.0
	  Lat2 = -70.0
	  PoleRow = 60.0
	  PoleCol = 20.0
	  Central Longitude = -130.0
	  ColInc = 200.0

     Note:  Beware that	when the pole is visible in a Lambert conformal
     projection, there is usually a wedge-shaped region	(with its apex at the
     pole) which is undefined (i.e. Longitude is >180 AND <-180).  In this
     region, there will	be no map lines	and the	topography will	be incorrect.


(3) Azimuthal Stereographic: an	aximuthal stereographic	projection defined by
five parameters:

     CentLat, CentLon	 Latitude and longitude	of the center of projection.
		    The	apex of	the imaginary cone will	be over	this coordinate.
     CentRow, CentCol	 Row and column	of the center of projection.  The grid
		    row	and column indicated will be at	the center of the
		    projection.	 These values may be outside the 3-D box.
     ColInc	    Increment (spacing)	between	grid columns in	km at the center
		    of the projection.	This parameter controls	the scale of the
		    projection.

     Example:  Suppose your 3-D	grid has 40 rows and 40	columns	and want an
     azimuthal stereographic projection	centered over of the north pole:
	  CentLat = 90.0
	  CentLon = 0.0
	  CentRow = 20.0
	  CentCol = 20.0
	  ColInc = 200.0


(4) Rotated rectilinear	lat/lon:  this is the rectangular latitude/longitude
     coordinate	system on a sphere rotated with	respect	to the Earth's natural
     latitude/longitude.  North/south coordinates increase upward on the rotated
     sphere and	east/west coordinates increase leftward	on the rotated sphere.
     The projection is defined by seven	parameters:

     NorthBound	    Northern boundary of 3-D box in degrees of latitude	in the
		    range [-90S,90N].
     WestBound	    Western boundary of	3-D box	in degrees of longitude	in the
		    range [-180E,180W].
     RowInc	    Increment (spacing)	between	grid rows in degrees of	latitude
		    greater than zero.
     ColInc	    Increment (spacing)	between	grid columns in	degrees	of
		    longitude greater than zero.
     CentLat, CentLon	 Latitude and longitude	on Earth corresponding to
		    Latitude/Longitude = (0,0) on the rotated sphere.
     Rotation	    Clockwise angle of rotation	of rotated sphere about	its
		    (0,0) point.

     Example:  Over small regions the Earth is nearly flat and we can exploit
     this to create nearly square grids	for small scale	models.	 We can	generate
     a nearly square grid of 41	rows by	41 columns over	a small	region over
     Wisconsin with:
	  NorthBound = 2.0
	  WestBound = 2.0
	  RowInc = 0.1
	  ColInc = 0.1
	  CentLat = 43.0
	  CentLon = 90.0
	  Rotation = 0.0

(5) Mercator: this is a conformal cylindrical coordinate system.  It is best used
      for applications limited to the equitorial regions.

      CenterLat     Latitude of the center of the projection in degrees. Range
                    of [-90S,90N].
      CenterLon     Longitude of the center of the projection in degrees. Range
                    of [-180E,180W].
      RowIncKm      Increment (spacing) between grid rows in Kilometers.
      ColIncKm      Increment (spacing) between grid columns in Kilometers.


Vis5D 5.1 supports the following vertical coordinate systems:

(0) Equally spaced, generic units:  this is a linear vertical coordinate system
     in	which levels in	the 3-D	grid are equally spaced.  No specific units are
     implied.  The coordinate system is	defined	by two parameters:

     BottomBound Bottom	boundary boundary of 3-D box.
     LevInc	 Increment(spacing) between grid levels.

     Example:  Suppose your 3-D	grid has 20 levels and you want	the bottom
     boundary to be 0.0	meters and you want .1 meters between levels.  Then:
	  BottomBound =	0.0
	  LevInc = 0.1


(1) Equally spaced, kilometers:	 this is a linear vertical coordinate system
     used in previous versions of Vis5D.  Grid levels are equally spaced.  The
     coordinate	system is defined by two parameters:

     BottomBound Bottom	boundary of 3-D	box in km.
     LevInc	 Increment (spacing) between grid levels in km greater than
     zero.

     Example:  Suppose your 3-D	grid has 20 levels and you want	.5 kilometers
     between grid levels.  Then:
	  BottomBound =	0.0
	  LevInc = 0.5


(2) Unequally spaced, kilometers:  this	is a linear vertical coordinate	system
     in	which grid levels can be unequally spaced.  The	coordinate system is
     defined by	an array of N height parameters	where N	is the number of levels
     in	the 3-D	grids.	If the number of grid levels is	different for each
     variable, N is the	maximum	number of grid levels.

     Height(1)	 Height	of first (bottom) grid level in	km
     Height(2)	 Height	of second grid level in	km
     ...	 ...
     Height(N)	 Height	of Nth (top) grid level	in km

     Note that the Height values must increase with N.

     Example:  Suppose your 3-D	grids have 10 levels and you want the grid
     levels to be more closely spaced near the bottom than near	the top.  Then:
	  Height(1) = 0.0
	  Height(2) = 0.1
	  Height(3) = 0.2
	  Height(4) = 0.3
	  Height(5) = 0.4
	  Height(6) = 0.6
	  Height(7) = 0.8
	  Height(8) = 1.0
	  Height(9) = 1.3
	  Height(10) = 1.6


It is also possible to display the vertical axis on a logarithmic scale.  This
is done	with the -log  command line option when	you start vis5d.  In this case,
the vertical axis is logarithmic with respect to height	but linear with	respect
to pressure.  The relationship between height (H) and pressure (P) is:

	  P = 1012.5 * e^( H / -7.2 )	     (^	denotes	exponentiation)

	  H = -7.2 * Ln( P / 1012.5 )	     (Ln denotes natural log)

The constants 1012.5 and -7.2 are just defaults	which can be overriden when you
specify	the -log option.  See section 6.1 for details.

(3) Unequally spaced, millibars:  this is a linear vertical coordinate system in
     which grid	levels can be unequally	spaced.	 The coordinate	system is
     defined by	an array of N pressure parameters where	N is the number	of
     levels in the 3-D grids.  If the number of	grid levels is different for
     each variable, N is the maximum number of grid levels.

     Pressure(1) Pressure of first (bottom) grid level in km
     Pressure(2) Pressure of second grid level in km
     ...	 ...
     Pressure(N) Pressure of Nth (top) grid level in km

     Note that the Pressure values must	decrease with N.

For the	purposes of calculating	wind trajectories, Vis5D assumes the
relationship between height (H)	and pressure (P) is:

	  P = 1012.5 * e^( H / -7.2 )	     (^	denotes	exponentiation)

	  H = -7.2 * Ln( P / 1012.5 )	     (Ln denotes natural log)



     Only the v5d file format is capable of storing the	new map	projection and
vertical coordinate system information.	 When a	v5d file is read into vis5d this
information is used to setup the topography, map lines,	and compute wind
trajectories.

     The vis5d program also supports two other display projections:  spherical
and cylindrical.  Instead of drawing a rectangular 3-D box, these projections
will actually warp the 3-D box into a spherical	or cylincrical shape.  These
projections are	used by	specifying the -projection option with the value
spherical or cylindrical; they are not specified in the	v5d file.  The spherical
option can be used to display your data	on a 3-D globe.	 The cylindrical option
can be used to display your data on a flat, round topography.  It's probably
best to	just experiment	with these options using the LAMPS dataset for example.
See the	section	on vis5d's command line	options	for more information.


3.3 Special Variables and Data Values

     Analysis and visualization	of wind	information is an important part of
Vis5D.	Specifically, the vis5d	program	looks to see if	your data set contains
variables named	U, V and W.  If	present, they are assumed to be	the three
components of wind vectors and are used	to display trajectory tracings and wind
slices.

     The U wind	component is parallel to rows, with positive U values pointing
toward increasing column numbers (i.e.,	positive eastward in a cylindrical
equidistant map	projection).  The V wind component is parallel to columns, with
positive V values pointing toward decreasing row numbers (i.e.,	positive
northwardward in a cylindrical equidistant map projection).  Positive W	values
are upward, negative W is downward.  The units for U, V	and W are assumed to be
meters per second except when a	generic	map projection or vertical coordinate
system is used.	 In that case, the units are in	X per second where X is	the
units used to specify the northbound, westbound, rowinc, and colinc parameters.

     If	you do not like	to use U, V, and W for wind vector components you can
either specify other wind variable names on the	vis5d command line or enter them
while running vis5d.

     Strictly speaking,	U, V and W do not have to represent wind motion.  They
can be used to represent any flow field	such as	ocean currents.	 However, you
may want to scale U, V,	and W by some constant for visualization purposes.

     Vis5D allows any grid data	value to be undefined or 'missing'.  For
example, datasets based	on observations	are often incomplete or	contain
erroneous values.  In your data	conversion program you can indicate a grid value
is missing by assigning	it a value greater than	1.0e30.	 Missing data in vis5d
will show up as	holes in isosurfaces and contour slices	and as black regions in
colored	slices.	 The data probe	will report missing values as 'Missing'.


3.4 User Defined File Formats

     This section is intended for experienced programmers.  In order to	allow
the reading
of a different file format the functions in /vis5d-5.1/src/user_data.c must be
changed.  There
are two	functions in user_data.c which need to be changed, user_data_get_header
and user_data_get_grid.	 There is currently sample code	in both	of these
functions to use as a template to create a new data file format.  The sample
code reads the sample user data	in /vis5d-5.1/user_data	.

     A user can	also define new	topography and map file	formats.  In order to
read a new topography file format the function user_data_get_topo must be
changed, and for a new map file	format the function user_data_get_map must be
changed.  Both of these	functions are also found in /vis5d-5.1/src/user_data.c
and they both have sample code.

     In	order to invoke	the reading of new file	format for data, topography or
map files the command line option '-userdata' followed by a 'G'	 (for grid
data), 'M' (for	map data) and/or 'T' (for topography data).  For example to use
the sample code	in user_data.c to read grid data and topography	data, the
following line would be	used:
     vis5d user_data/ETA.dat -user_data	GT -topo user_data/ETA_TOPO.dat



4. McIDAS 3D GRID DATA FILES

     In	previous versions of Vis5D, it was standard practice to	put one's data
into a McIDAS GR3D file, then compress it with comp5d prior to using vis5d.
While directly converting to the v5d format is prefered, we still include this
information on the McIDAS format.  If you don't	want to	put your data into
McIDAS files, you may skip to section 5	now.

     WE	RECOMMEND AGAINST THIS WAY OF GETTING YOUR DATA	INTO VIS5D - INSTEAD USE
THE TECHNIQUES DESCRIBED IN SECTION 3 OF THIS DOCUMENT.

     A McIDAS GR3D file	contains a sequence of 3-D grids of data.  The three-
dimensional grids are organized	into short sequences to	enumerate the values of
multiple physical variables at a single	time.  The short sequences of physical
variables are repeated into a longer sequence which steps through many time
steps.	These files have a names of the	form GR3Dnnnn where nnnn is a 4-digit
number between	0001 and 9999.	The McIDAS utility programs then refer to files
only by	a number (1 through 9999).

     A 3D grid file contains a directory entry for each	3D grid, which describes
the size and geographic	location of the	grid, and the date, time and name of
physical variable of the data in the grid array.  A five-dimensional data set
consists of a sequence of 3D grids in a	3D grid	file, all with the same	size and
geographic locations.  The grid	sequence repeats the same short	sequence of
physical variables stepping forward through time.  For example,	the grid
sequence from a	weather	model could be:

		      PHYSICAL
   GRID		      VARIABLE
  NUMBER  DATE	TIME	NAME
     1	 88035 000000	 U
     2	 88035 000000	 V
     3	 88035 000000	 W
     4	 88035 000000	 T
     5	 88035 000000	 P
     6	 88035 010000	 U
     7	 88035 010000	 V
     8	 88035 010000	 W
     9	 88035 010000	 T
    10	 88035 010000	 P
    11	 88035 020000	 U
    12	 88035 020000	 V
    13	 88035 020000	 W
    14	 88035 020000	 T
    15	 88035 020000	 P

     This data set consists of 3 time steps of 5 physical variables.  The
physical variables are the U, V	and W components of the	wind vector, the
temperature T and the pressure P.  The date is February	4, 1988	and the	time
steps are midnight, 1 AM and 2 AM.  Dates are in YYDDD format and times	are in
HHMMSS format as described earlier.


4.1 Putting Your Data Into a McIDAS 3D Grid File

     The following sample program creates a 3D grid file and fills its 3D grids
with data for a	five-dimensional data set.  This program can be	found in the
file sample.F, it's makefile is	sample.m.  The easiest way to read your	data
into a 3D grid file is to alter	the sample.F program.  The subroutines it calls
are all	in the libmain.a library, and their source is in the src subdirectory.
Here is	a listing of sample.F:

  1 C THE MAIN PROGRAM OF YOUR CONVERSION PROGRAM MUST
  2 C BE NAMED SUBROUTINE MAIN0
  3 C
  4	  SUBROUTINE MAIN0
  5 C
  6 C THE NEXT TWO COMMENTS ARE	PRINTED	BY THE 'help sample' COMMAND
  7 C ?	SAMPLE program to convert data to 3D grid files
  8 C ?	sample gridf#
  9 C
 10 C DIMENSIONS OF 3D GRID
 11 C NOTE NLATS AND NLONS MUST	BOTH BE	LESS THAN OR EQUAL TO 150
 12 C NLATS, NLONS AND NHGTS MUST ALL BE AT LEAST 2
 13	  PARAMETER (NLATS=31,NLONS=51,NHGTS=16)
 14 C
 15 C NUMBER OF	PHYSICAL VARIABLES AND NUMBER OF TIME STEPS
 16 C NOTE EITHER OR BOTH MAY BE EQUAL TO 1.  THAT IS, Vis5D DOES
 17 C NOT FORCE	YOU TO HAVE MULTIPLE VARIABLES OR TIME DYNAMICS.
 18	  PARAMETER (NVARS=5,NTIMES=100)
 19 C
 20 C ARRAY FOR	3D GRID	DATA
 21	  REAL*4 G(NLATS, NLONS, NHGTS)
 22 C ARRAYS FOR GRID FILE ID AND GRID DIRECTORY
 23	  INTEGER ID(8), IDIR(64)
 24 C ARRAY FOR	VARIABLE NAMES
 25	  CHARACTER*4 CNAME(5)
 26 C
 27 C LATITUDE,	LONGITUDE AND HEIGHT BOUNDS FOR	SPATIAL	GRID
 28	  DATA XLATS/20.0/,XLATN/50.0/
 29	  DATA XLONE/70.0/,XLONW/120.0/
 30	  DATA XHGTB/0.0/,XHGTT/15.0/
 31 C
 32 C STARTING DATE IN YYDDD AND TIME IN HHMMSS
 33	  DATA JDAY/88035/,JTIME/020000/
 34 C TIME STEP	IN HHMMSS
 35	  DATA JSTEP/000100/
 36 C
 37 C NAMES OF THE FIVE	PHYSICAL VARIABLES
 38	  DATA CNAME/'U	  ', 'V	  ', 'W	  ', 'T	  ', 'P	  '/
 39 C INITIALIZE GRID DIRECTORY	TO ZEROS
 40	  DATA IDIR/64*0/
 41 C
 42 C READ GRID	FILE NUMBER FROM COMMAND LINE.	IPP WILL
 43 C CONVERT THE PARAMETER # 1	TO AN INTEGER, WITH A DEFAULT
 44 C VALUE OF 0.
 45	  IGRIDF=IPP(1,0)
 46 C IF ILLEGAL GRID FILE NUMBER, PRINT ERROR MESSAGE AND RETURN
 47	  IF(IGRIDF .LT. 1 .OR.	IGRIDF .GT. 9999) THEN
 48	    CALL EDEST('BAD GRID FILE NUMBER ',IGRIDF)
 49	    CALL EDEST('MUST BE	BETWEEN	1 AND 9999 ',0)
 50	    RETURN
 51	  ENDIF
 52 C
 53 C CALCULATE	GRID INTERVALS
 54	  XLATIN=(XLATN-XLATS)/(NLATS-1)
 55	  XLONIN=(XLONW-XLONE)/(NLONS-1)
 56	  XHGTIN=(XHGTT-XHGTB)/(NHGTS-1)
 57 C
 58 C DATE AND TIME FOR	FIRST TIME STEP
 59 C IDAYS CONVERTS YYDDD FORMAT TO DAYS SINCE	JAN. 1,	1900
 60	  IDAY=IDAYS(JDAY)
 61 C ISECS CONVERTS HHMMSS FORMAT TO SECONDS SINCE MIDNIGHT
 62	  ISEC=ISECS(JTIME)
 63 C
 64 C INITIALIZE GRID IDENTIFIER TEXT TO BLANKS
 65 C NOTE LIT CONVERTS	A CHARACTER*4 TO AN INTEGER*4
 66	  DO 10	I=1,8
 67 10	  ID(I)=LIT('	 ')
 68 C
 69 C SET UP DIRECTORY ENTRY
 70 C
 71 C DIMENSIONS OF GRID
 72	  IDIR(1)=NLATS*NLONS*NHGTS
 73	  IDIR(2)=NLATS
 74	  IDIR(3)=NLONS
 75	  IDIR(4)=NHGTS
 76 C
 77 C LATITUDES	AND LONGITUDES IN DEGREES * 10000
 78	  IDIR(22)=4
 79	  IDIR(23)=NINT(XLATN*10000.)
 80	  IDIR(24)=NINT(XLONW*10000.)
 81	  IDIR(25)=NINT(XLATIN*10000.0)
 82	  IDIR(26)=NINT(XLONIN*10000.0)
 83 C
 84 C HEIGHTS IN METERS
 85	  IDIR(31)=1
 86	  IDIR(32)=NINT(XHGTT*1000.)
 87	  IDIR(33)=NINT(XHGTIN*1000.)
 88 C
 89 C CREATE THE GRID FILE
 90	  CALL IGMK3D(IGRIDF, ID, NLATS*NLONS*NHGTS)
 91 C
 92 C LOOP FOR TIME STEPS
 93	  DO 200 IT=1,NTIMES
 94 C
 95 C SET DATE AND TIME	IN DIRECTORY ENTRY
 96 C IYYDDD CONVERTS DAYS SINCE JAN. 1, 1900 TO OUR YYDDD FORMAT
 97	  IDIR(6)=IYYDDD(IDAY)
 98 C IHMS CONVERTS SECONDS SINCE MIDNIGHT TO OUR HHMMSS FORMAT
 99	  IDIR(7)=IHMS(ISEC)
100 C
101 C LOOP FOR PHYSICAL	VARIABLES
102	  DO 190 IV=1,NVARS
103 C
104 C SET VARIABLE NAME	IN DIRECTORY ENTRY
105	  IDIR(9)=LIT(CNAME(IV))
106 C
107 C *************************************************************
108 C READ YOUR	DATA FOR TIME STEP NUMBER IT AND VARIABLE NUMBER IV
109 C INTO THE ARRAY G HERE.
110 C NOTE THAT	G(1,1,1) IS THE	NORTH WEST BOTTOM CORNER AND
111 C G(NLATS,NLONS,NHGTS) IS THE SOUTH	EAST TOP CORNER.
112 C MARK A GRID POINT	AS 'MISSING DATA' BY SETTING IT	= 1.0E35
113 C *************************************************************
114 C
115 C CALCULATE	3D GRID	NUMBER
116	  IGRID=IV+NVARS*(IT-1)
117 C WRITE DATA IN G AND DIRECTORY IN IDIR TO 3D GRID
118 C NOTE WE PASS THE NEGATIVE	OF THE GRID NUMBER (I.E. -IGRID)
119	  CALL IGPT3D(IGRIDF,-IGRID,G,NLATS,NLONS,NHGTS,IDIR,IGNO)
120 C
121 C END OF PHYSICAL VARIABLE LOOP
122 190	  CONTINUE
123 C
124 C INCREMENT	DATE AND TIME, CONVERT JSTEP FROM HHMMSS TO SECONDS
125	  ISEC=ISEC+ISECS(JSTEP)
126 C IF SECONDS CARRY PAST ONE	DAY, ADJUST SECONDS AND	DAYS
127	  IDAY=IDAY+ISEC/(24*3600)
128	  ISEC=MOD(ISEC,24*3600)
129 C
130 C END OF TIME STEP LOOP
131 200	  CONTINUE
132 C
133	  RETURN
134	  END

     The routines IGMK3D and IGPT3D are	the interface to the 3D	grid structures.
The call to IGMK3D at line 90 creates a	3D grid	file. Its parameters are:

   1  INTEGER*4	- number of 3D grid file to create
   2  array of 8 INTEGER*4 - a 32 byte text ID for the file
   3  INTEGER*4	- maximum number of grid points	in any 3D grid.

After the 3D grid file is created, IGPT3D is called in line 119	once for each
combination of time step and physical variable to put 3D grids into the	file.
Its parameters are:

     1	INTEGER*4 - number of 3D grid file to write to
     2	INTEGER*4 - minus the number of	the 3D grid to write.  This is 0 or
	  positive to indicate write to	next empty grid.
     3	array of REAL*4	- array	of grid	points to write
     4	INTEGER*4 - first dimension of grid array, # of	latitudes
     5	INTEGER*4 - second dimension of	grid array, # of longitudes
     6	INTEGER*4 - third dimension of grid array, # of	heights
     7	array of 64 INTEGER*4 -	directory for 3D grid
     8	INTEGER*4 - number of 3D grid actually written,	returned by IGPT3D.

     Vis5D allows data sets which span more than one 3D	grid file.  In this case
the grid sequence of repeating variables and repeating time steps continues
across grid file boundaries.  A	single 3D grid file is limited to 100,000,000
grid points (400 megabytes).  If your data set contains	more than this number of
grid points, then you should alter sample.F to create a	new 3D grid file (by
incrementing IGRIDF and	calling	IGMK3D)	on every Nth time step,	where N	time
steps will fit in one 3D grid file.  Note that the comp5d command described in
section	4 references data sets as sequences of 3D grid files.

     The Vis5D system processes	the gridded data based on the information in the
grid directories, which	is contained in	the IDIR array in the sample.F program.
It is a	good idea to initialize	IDIR to	all zeros, as in line 40.  The size of
the 3D grid is set in entries 1	to 4 of	IDIR (lines 72 to 75).	Note the
restrictions on	data set size described	in section 4 of	this document.

     The date and time of the 3D grid are set in entries 6 and 7 of IDIR, as in
lines 97 and 99.  Note that they are represented in our	YYDDD and HHMMSS formats
described above.  Four functions are available in libmain.a for	converting
between	these formats and a format which makes date and	time calculations easy.
The IDAYS function converts YYDDD format to days since January 1, 1900,	as in
line 60.  The ISECS function converts HHMMSS format to seconds since midnight,
as in lines 62 and 125.	 This makes it easy to do calculations with dates and
times, as in lines 125,	127 and	128.  Then the IYYDDD function converts	days
back to	YYDDD and the IHMS function converts back to HHMMSS, as	in lines 97 amd
99.

     The physical variable name	is 4 ASCII characters packed into entry	9 of
IDIR, as in line 105.  The LIT function	in libmain.a converts a	CHARACTER*4 to
an INTEGER*4.

     The spatial location of the grid is described in terms of latitude	and
longitude in ten-thousandths of	a degree, and in terms of height (altitude) in
meters.	 The grid element G(1,1,1) is in the north west	bottom corner of the
grid, and the grid element G(NLATS,NLONS,NHGTS)	is in the south	east top corner.
The grid latitude and longitude	are described in entries 21 to 25 of IDIR, as in
lines 78 to 82.	 The grid heights are described	in entries 31 to 33, as	in lines
85 to 87.  The NINT function is	a FORTRAN intrinsic for	converting a REAL to the
nearest	INTEGER.  The latitude,	longitude and height spacings are simply the
distances between between successive grid points.  Latitudes are positive in the
northern hemisphere, longitudes	are positive in	the western hemispere, and of
course heights are positive above sea level.

     The real work in modifying	the sample.F program is	writing	code for getting
your data into the G array, in lines 107 to 113.  For some data	you may	want to
fake the latitude, longitude and height	coordinates.  However, if your data is
geographical and large scale, then you may want	to describe its	location
accurately, and	it may be necessary to resample	your data to a regularly spaced
grid in	latitude, longitude and	height from some other map projection.	It may
also be	necessary to transpose your data array to get the index	order to be LAT,
LON and	HGT, and to invert your	data array in some index to make sure G(1,1,1)
is the north west bottom corner.  Even in faked	coordinates, you may need to
transpose or invert your data array to get the right 'handedness' in the
display.  The Vis5D system allows grid points marked as	missing, indicated by
array values greater than 1.0E30.  If you do fake the latitude,	longitude and
height coordinates, then the topography	and map	display	of the vis5d program
will be	meaningless.  If you calculate trajectories for	your data set, either
use accurate coordinates, or take great	care to	get relative time, distance and
velocity scales	consistent in the faked	coordinates.  Otherwaise trajectory
paths will not be realistic.

     The IPP function in libmain.a returns the value of	a command parameter as
INTEGER*4, as in line 45.  There are similar functions CPP and DPP in libmain.a
which return CHARACTER*12 (converted to	upper case) and	REAL*8 values for
command	parameters.  They get command parameters based on their	sequential
position in the	command	line.  They all	have similar function parameters:

     1	INTEGER*4 - sequence number of command parameter
     2 (IPP) INTEGER*4 - default value of command parameter
	  or
     2 (CPP) CHARACTER*12 - default value of command parameter
	  or
     2 (DPP) REAL*8 - default value of command parameter.

There is also a	mechanism for picking up command parameters based on keywords.
This is	done with the functions	IKWP, CKWP and DKWP in libmain.a.  They	get
command	parameters based on position after a keyword of	the form '-keyword'.
IKWP returns an	INTEGER*4, CKWP	returns	a CHARACTER*12 (converted to upper case)
and DKWP returns a REAL*8.  They all have similar function parameters:

     1	CHARACTER*12 - keyword string in command line
     2	INTEGER*4 - sequence number of command parameter after keyword
     3 (IKWP) INTEGER*4	- default value	of command parameter
	  or
     3 (CKWP) CHARACTER*12 - default value of command parameter
	  or
     3 (DKWP) REAL*8 - default value of	command	parameter.

The NKWP function in libmain.a returns the number of sequential	parameters after
a keyword.  Its	function parameter is:

     1	CHARACTER*12 - keyword string in command line.

     On	the most machines the REAL*4 format is not a subset of the REAL*8
format,	so make	sure to	declare	DPP and	DKWP as	REAL*8,	as well	as their third
function parameters (for default values	of command parameters).

     If	you would rather write your grid conversion program in C instead of
FORTRAN, look at the file 'sample.c'.  It contains examples of how to easily
read and write grid files using	C structures and routines in stdio.


4.2 Using the McIDAS Utilities

     Once your data set	is in a	3D grid	file, you can list directory information
about the grids	using the command:

     igg3d list	I J -gr3df N

where N	is the 3D grid file number, and	I and J	give the range of grid numbers
to list.  You can get a	quick idea of the data values using the	command:

     igg3d info	I J -gr3df N

which will list	the minimum and	maximum	values,	the mean, the standard deviation
and the	number of grid points marked for missing data, for grid	numbers	I to J
in 3D grid file	number N.

     There are restrictions on the dimensions of data sets which can be
visualized using the vis5d program.  Currently,	you are	limited	to a maximum of
30 physical variables and 400 times steps.  The	vis5d program will also	fail if
there is a trivial spatial dimension:

     NLATS < 2
     NLONS < 2
     NHGTS < 2

The vis5d program will perform badly, possibly making errors, if the total 5-D
size:

     NLATS * NLONS * NHGTS * NTIMES * NVARS

is too large.  The limit depends on the	amount of memory in your system.  For a
64MB system, the limit is around 25,000,000, with performance degrading	as the
data set size exceedes the limit.

     Vis5D provides the	gg3d and igg3d programs	which can be used to reduce the
resolution and scale of	a data set to meet these limits.  The gg3d program
resamples a 3D grid to new array dimensions and	new extents in latitude,
longitude and height, using the	command:

     gg3d samp N I M J
     gg3d ave  N I M J

where N	and I are the numbers of the source 3D grid file and grid, and M and J
are the	numbers	of the destination 3D grid file	and grid.  The 'samp' version
calculates destination grid point values by linearly interpolating between
source grid point values, and is appropriate for increasing resolution.	 The
'ave' version calculates destination grid points by averaging multiple source
grid point values, and is appropriate for decreasing resolution.  Without any
keywords gg3d will do a	straight copy operation.  Invoke the gg3d command with
the keyword:

     -size NLATS NLONS NHGTS

to set the grid	dimensions for the destination grid as different from the
dimensions for the source grid.	 Invoke	gg3d with the keywords:

     -lat XLATS	XLATN
     -lon XLONE	XLONW
     -hgt XHGTB	XHGTT

to set extents (range bounds) for the latitude,	longitude and height for the
destination grid as different from the extents for the source grid.  The -lat, -
lon and	-hgt keywords take real	arguments.

     The igg3d program provides	options	for copying and	deleting 3D grids and
for interpolating between 3D grids in time.  Sequences of 3D grids are copied
using the command:

     igg3d get N I J M K

where N	is the source 3D grid file number, I and J are the range of source grid
numbers, M is the destination grid file	number,	and K is the starting
destination grid number.  A single grid	may be copied within a 3D grid file
using the command:

     igg3d copy	I J -gr3df N

where N	is the 3D grid file number, I is the number of the source grid and J is
the number of the destination grid.  A range of	grids may be deleted with the
command:

     igg3d del I J -gr3df N

where N	is the 3D grid file number and grid numbers between I and J are	to be
deleted.

The igg3d command provides two different options for time interpolation.  The
first is:

     igg3d ave K I J D T -gr3df	N

where grid number K is produced	by interpolating between grid numbers I	and J,
all in 3D grid file number N.  Grid number K will be assigned day D (in	YYDDD
format)	and time T (in HHMMSS format).	The relative weighting of grids	I and J
is calculated from this	date and time, assuming	linear time interpolation.  If
grid K is not between grids I and J in date and	time, igg3d prints an error
message.  The igg3d command also provides a more complex time interpolation
option:

     igg3d int I D T -setdel S M -lag U	V -gr3df N

     This will put a grid in the next empty slot of 3D grid file number	N,
assigned to day	D (in YYDDD format) and	time T (in HHMMSS format).  This grid
will be	interpolated from a sequence of	grids, all in file number N, at	grid
numbers	I, I+S,	I+2S, ... , I+(M-1)S.  This sequence of	grids should be
ascending in date and time.  igg3d will	search the sequence and	linearly
interpolate between the	two consectutive grids from the	sequence which bracket
day D and time T.  Furthermore,	the interpolation will be done in a coordinate
system moving at constant velocity (U, V), where U and V are in	meters per
second,	with V positive	for motion from	south to north and U positive for motion
from west to east.  The	two bracketing grids from the sequence will be shifted
in latitude and	longitude to their positions at	day D and time T, and the result
interpolated between these two spatially shifted grids.	 Furthermore, if the
grids in the sequence are identified in	their directory	entries	with variable
name 'U	  ' or 'V   ', then the	corresponding component	of the velocity	(U, V)
will be	subtracted from	the grid values.

     The 'int' option of igg3d may seem	complex, but it	is just	what you need if
you want to write a script to re-interpolate a five-dimensional	data set to a
new sequence of	time steps.  It	is particularly	useful if the source sequence
does not have uniform time steps, or if	the physics are	moving through the
spatial	grid and you want to avoid blurring in the time	re-interpolation.  You
would set M equal to the number	of time	steps and S equal to the number	of
physical variables in the source five-dimensional data set.  The I parameter
would be set equal to the grid number in the first time	step of	the variable
being interpolated.  Note that this igg3d option will put the new grid at the
end of the grid	file containing	the source data	set, but you can use 'igg3d get'
to move	it to another grid.

You can	use the	command:

     igu3d make	N M

to create 3D grid file number N, which allows 3D grids of up to	M points each.
The names of 3D	grid files have	the form:

     GR3Dnnnn

where nnnn is the four digit decimal grid file number, padded with leading zeros
if needed to make four digits.




5. Vis5D UTILITIES

Vis5D includes a number	of utility programs.  This section describes each one.
The v5dimport program is described seperately in section 7.


v5dinfo
     Usage:  v5dinfo file

     Description:  v5dinfo prints information about the	given v5d file such
     as	the size of the	3-D grid, the number of	time steps, the	names of
     the variables, etc.

     This program will also work on comp5d files.  Therefore, the old
     compinfo program has been removed.


v5dstats
     Usage:  v5dstats file

     Description:  v5dstats prints simple statistical information about	the
     grid data in the named v5d	file.  Again, comp5d files are also
     accepted.


v5dedit
     Usage:  v5dedit file.v5d

     Description:  v5dedit allows you to change	header information such	as
     the map projection, vertical coordinate system and	variables names	in
     the named file.  It is an interacive, menu-driven program and is
     intended to be self explanatory.  This program does NOT work with
     comp5d files.


v5dappend
     Usage:  v5dappend [-var] [...] file.v5d [...] target.v5d

     Description:  v5dappend allows you	to append a number of v5d files
     together to make one larger file.	This might be useful if	your
     weather model generates a separate	.v5d file for each timestep because
     youll want	to join	those files together to	view the data in vis5d.

     The arguments are,	in order:
	  An optional list of variables	to omit	from the output	file. For
	  example, if you want to omit the variables U and THETA you would
	  use the arguments -U and -THETA.
	  The list of v5d files	to append onto the target file.
	  The name of the target v5d file to create (if	it doesnt exit)
	  or append onto (if the target	file already exists).

     Note that the dimensions of the grids (rows, columns and levels) must
     be	the same in each file to append	them together.	The map	projection
     and vertical coordinate system information	will be	taken from the
     first input file and ignored the the remaining files.


gr3d_to_v5d
     Usage:  gr3d_to_v5d N M file.v5d C

     Description:  gr3d_to_v5d converts	(a) McIDAS GR3D	file(s)	to a v5d
     file.  N is a number which	indicates the name of the first	grid file,
     M is the number of	grid files to convert, file.v5d	is the name of the
     file to produce, and C is 1, 2 or 4 to indicate how many bytes per
     grid point	to use for compression (the default is 1).  Example:  if
     N=20 and M=4 then the files GR3D0020, GR3D0021, GR3D0022, and GR3D0023
     will be read an converted to the named file.v5d.


igg3d
     Usage:  igg3d ...

     Description:  igg3d is used to perform a variety of manipulations on
     McIDAS GR3D files.	 See section 4.2 for more details.


igu3d
     Usage:  igu3d  ...

     Description:  igu3d is a utility to perform a variety of manipulations
     on	McIDAS GR3D files.  See	section	4.2 for	more details.


gg3d
     Usage:  gg3d ...

     Description:  gg3d	is a utility for resampling McIDAS GR3D	files.	See
     section 4.2 for more details.


listfonts
     Usage:  listfonts

     Description:  listfonts, used on SGI systems only,	lists the IRIS GL
     fonts available for use in	vis5d's	3-D window.  After listing the
     fonts you may use one in vis5d by specifying it with the -font option.
     For non-SGI systems or systems using OpenGL, use the xlsfonts or
     xfontsel program to select	a font.


comp5d
     Usage:  comp5d N M	filename

     Description:  comp5d converts one or more McIDAS GR3D files to the
     comp5d format used	in previous (and the current) versions of vis5d.

     N is the first 3D grid file number	and M is the number of grid files
     in	the data set.  The M parameter allows data sets	which span multiple
     grid files	and should not be confused with	the total number of 3D
     grids in the data set.

     filename is the name of the compressed grid file.	You can	choose
     whatever name you want, but note that comp5d will convert the name	to
     all upper case characters.

     If	your data set contains wind vector components you can use the -wind
     keyword to	select a subset	of wind	components or calculate	horizontal
     wind speed, named 'SPD ', for the compressed file.	 The longitude,
     latitude, and vertical components of the wind vector must be named	'U
     ',	'V   ' and 'W	' respectively.	 If you	use the	-wind keyword, then
     only those	wind-relevant variables	(i.e. U, V, W &	SPD) whose names
     are listed	after -wind will be included in	the compressed file.  For
     example, to include SPD and W in the compressed file, from	a 3D grid
     file containing U,	V and W	components, use	the command:

     comp5d N M	F -wind	SPD W


help
     Usage:  help utilityname

     Description:  The help command will list a	quick reference	to the parameter
     formats for the named utility such	as igg3d, igu3d, gg3d, and comp5d
     utilities.	 Example:  help	igg3d


maketopo.c
     This program, found in the	util directory,	is a template program for
     generating	your own new topography	(*.TOPO) files.	 Read the information at
     the top of	the file for instructions.  To compile maketopo	see the	makefile
     named maketopo.m.


makemap.c
     This program, found in the	util directory,	is a template program for
     generating	your own new McIDAS map	outline	(OUTL*)	files.	Read the
     information at the	top of the file	for instructions.  To compile makemap
     see the makefile named makemap.m.	If you create a	map with lots too many
     line segments, it will be displayed with some line	segments missing and
     some extra	crazy line segments.  You can fix this by increasing MAXMAPVERT
     and MAXMAPSEG in src/globals.h, then re-making vis5d.


newmap.c
     This program and mapfunc.f, found in the util directory, is used to
     transform the vertices of an existing map outline file to make a new map
     outline file.  This might be useful if you	need to	transform a map	to a new
     coordinate	system.	 Read the newmap.c and newmap.m	files for more
     information.



6.  USING Vis5D	TO VISUALIZE YOUR DATA

     This section describes how	to use the Vis5D visualization program,	vis5d.
It is almost completely	controlled using the mouse with	a graphical user
interface.  The	best way to learn to use it is to experiment.  There is	no way
to harm	your data from within the program.


6.1 Starting vis5d

	  ** IMPORTANT NOTE FOR	OSF USERS **
	  you need to run 'limit stacksize 32m'	before you run vis5d

	  ** IMPORTANT NOTE FOR	SunOS 5	USERS **
	  SunOS	5.x users:  The	X shared memory	extension may not work
	  correctly.  If Vis5D prints an error message to the effect of	"Shared
	  memory error"	then you'll have to append the following three lines to
	  the end of your /etc/system file then	reboot:
	       set shmsys:shminfo_shmmax = 0x2000000
	       set shmsys:shminfo_shmmni = 0x1000
	       set shmsys:shminfo_shmseg = 0x100

After you have made a v5d file,	you can	interactively visualize	one or more file
with the command:

     vis5d file1.v5d [options] file2.v5d [options]...

[options] may be any combination of the	following (though none are usually
needed):

     -alpha
	  Use alpha blending instead of	"screen	door" transparency.
     -area N
	  [SGI only]  Specifies	the first of a sequence	of McIDAS area files to
	  read and then	display	inside the 3-D box.  See section 6.15 for more
	  information.
     -box x y z
	  This lets you	specify	the aspect ratio or proportions	of the 3-D box.
	  Default values are 2 2 1.
     -circle
	  Display a circular clock
     -cpgeom WIDTHxHEIGHT+X+Y (or WIDTHxHEIGHT or +X+Y)
	  Specify the geometry (position only) of the control panel.  Since the
     control panel  must be a fixed width, any WIDTH specification will	be
     ignored.
     -barbs
	  Use wind barbs in place of wind vectors.
     -date
	  Use 'dd month	yy' in place of	'yyddd'	on the clock.
     -dwell
	  Set the animation dwelling time when stepping	from time=NumTimes to
     time=0
     -font xfontname
     -font PEXfontname height
	  Set the X or PEX font	and its	height used in the 3D window.  Since 3D
	  fonts	have explicit heights, size controls the line spacing.	A size
	  of 0 will restore the	line spacing to	the font's height.  PEX	fonts
	  (those having	"PEX" in their names) are scalable.  To	restore	the
	  default PEX font, use	" " for	the name.  A PEX font's	default	size may
	  be resotred by specifying a size of 0.
	  Example: vis5d LAMPS.v5d -font helvb24 20
     -full
	  Open the 3-D window as a borderless, full-screen size	window.
     -funcpath pathname
	  Specify the directory	to search for user Fortran functions.
	  Example  vis5d LAMPS.v5d -funcpath /usr/local/vis5d/userfuncs
     -geometry WxH+X+Y	(or WxH	or +X+Y)
	  Specify the geometry of the 3-D window.
	  Example  vis5d LAMPS.v5d -geometry 640x480-10+10
     -hirestopo
	  Display a high-resolution topography.	 This is only recommended on
	  systems with fast graphics hardware.
     -legend position size x y
	  Set color legend position and	size.  Position	values are 1 (bottom,
	  the default),	2 (top), 3 (left) and 4	(right).  Size is the height of
	  the legend bar and is	between	10 and 1000 (default=128). Position is
	  controlled by	adding an offset value in the X	and Y direction	from the
	  default position.
     -log [a] [b]
	  Display height on a logarithmic axis instead of linear.  This	is
	  discussed in section 3.2.  The optional arguments a and b are	the
	  scale	and exponent factors in	the height/pressure equation.  The
	  defaults are 1012.5 and -7.2,	respectively.
     -map file
	  Use a	map file other than the	default	of OUTLSUPW.  See section 2.4 to
	  setup	a different default.
	  Example:  vis5d LAMPS.v5d -map OUTLUSAL
     -top_margin size
	  Specify the size in points for the top margin	of the 3d windows
     -bottom_margin size
	  Specify the size in points for the bottom margin of the 3d windows
     -left_margin size
	  Specify the size in points for the left margin of the	3d windows
     -right_margin size
	  Specify the size in points for the right margin of the 3d windows
     -mbs n
	  Override the assumed system memory size of 32	megabytes.  See	section
	  2.4 to setup a different default value.
     -nofile
	  Run vis5d with out loading a vis5d data set.
     -offscreen
	  Do off screen	rendering.  This is used in conjunction	with the -script
		    command
     -path pathname
	  Use a	different path for map and topo	files instead of the current.
	  Example:  vis5d LAMPS.v5d -path /usr3/data
     -projection p
	  Set the display map projection, default is to	display	data in	its
	  natural projection (obtained from the	data file).
	  p may	be one of:
	       cylindrical    -	display	data on	a cylindrical Earth
	       spherical - display data	on a spherical Earth
	  Only the first 3 characters are significant/needed.  You will	be
	  promted for
	  additional parameters.
	  Example:  vis5d LAMPS.v5d -projection	spherical
     -quickstart
	  Dont load any	grids when starting vis5d, even	if the whole file will
	  fit into memory.  The	grids will be read as needed.  This option is
	  useful when reading a	file via NFS.
     -rate ms
	  Change the default animation rate.  ms is the	minimum	delay in
	  milliseconds between frames.	Default	is 100 ms.
     -samescale
	  Set the scale	for the	vertical plot variables	to be the same for all
     three variables
     -script script.tcl
	  Specifies a Vis5D/Tcl	script to execute automatically.
     -sequence filename
	  [not available on all	systems]  Specifies a file containing a	sequence
	  of images to texture map over	the topography.	 See section 6.15 for
	  more information.
     -soundfont	fontname
	  Set the X font used in the sounding window.  Use xlsfonts to list your
	  system's fonts
     -title x y	font "string"
	  This is used in conjunction with the -_margin	option.	 This will print
	  the string at	location (x,y) in the BigWindow.  Any number of	titles
	  can be created.  The strings will not	show up	if they	are not	in a
	  margin
     -texture rgbfile
	  [not available on all	systems]  Specify an SGI .rgb file to texture
	  map over the topography.  See	section	6.15 for more information.
     -topo file
	  Use a	topography file	other than the default of EARTH.TOPO.  See
	  section 2.4 to setup a different default.
     -topobase [lev_value]
	  Display a base below the topography. lev_value is the	vertical grid
	  level	value to which the base	will extend.  Typically, this is a
	  negative value so that the base is below the lowest level (0.0).  If
	  lev_value is omitted,	0.0 will be used
	  Example: vis5d LAMPS.v5d -topobase -3.0
     -trajvars uvar vvar [wvar]
	  Specify which	variables are to be used for trajectory	tracing.
	  Defaults are U, V, and W.
	  Example:  vis5d LAMPS.v5d -trajvars U2 V2 W2
     -userdata flags
	  Use user-provided functions to read data, maps, or topography	.  flags
     is	a string    that may contain any combination of:
	       g or G	 -use the function for reading grid data
	       m or M -	use the	function for reading map data
	       t or T	 - use the function for	reading	topography data
	  Example: vis5d dataset -userdata g
     -vertical v
	  Set the vertical coordinate system, default is obtained from datafile.
	  v may	be one of:
	       generic	 - linear, equally spaced levels in generic units
	       equal	 - linear, equally spaced levels in km
	       nonequal	 - linear, unequally spaced levels in km
	  Only the first 3 characters of v are significant/needed.  You	will be
	  prompted for additional parameters.
	  Example:  vis5d LAMPS.v5d -vertical nonequal
     -wdpy xdisplay
	  Put the widgets on a different X display.  Useful in combination with
	  -full	for making slides and videos.
	  Example:  vis5d LAMPS.v5d -full -wdpy	pluto:0
     -wide w
	  Set width of line segments in	pixels (default	is 1.0).  Again, useful
	  for making videos.
	  Example:  vis5d LAMPS.v5d -wide 3.0
     -wind2 uvar vvar [wvar]
	  Specify the names of a secondary set of U, V,	and (optionally) W wind
	  component variables to use when drawing the Hwind2, Vwind2 and Strm2
	  vector slices.  Useful when you have two sets	of wind	vector
	  components that you want to visualize	simultaneously.
	  Example:  vis5d MYDATA -wind2	U2 V2 W2


     Most of the above arguments can also be changed by	entering the 'Options'
menu after
pressing the 'DISPLAY' button found on the main	control	panel.

     If	you start vis5d	without	arguments you will get a list of all the command
line options and keyboard functions.  Otherwise, vis5d will begin by reading the
data file.

     Previous versions of vis5d	required that the entire file be read into main
memory;	if you didn't have sufficient memory you couldn't visualize the	file.
In version 4.0 and higher, this	restriction is lifted; you may visualize files
which are larger than main memory.  This is implemented	with a grid cache: vis5d
reads data only	when needed and	discards it on a least-recently-used basis.
Small files will be read in their entirety as in previous versions.

     For the user, this	means vis5d will allow you to visualize	large files even
with only 32MB of main memory.	However, performance will degrade as the ratio
of file	size to	main memory size increases.  If	you observe sluggish performance
and a lot of disk activity while running vis5d you should get more memory.


6.2  The Control Panel

     After vis5d has opened/read your file/s, two windows will appear:	a large
window on the right containing one or more 3-D display windows and the current
control	panel on the left of the screen.  The 3-D window/s are used to view and
interact with the data.	 When there are	multiple 3-D display windows a control
panel is assigned to each.  The	current	control	panel will appear when ever a
mouse event occurs in the associated 3-D display.  In the upper-left corner of
the 3-D	display	is a combination analog/digital	clock which indicates the
current	time step.  The	control	panel contains several groups of buttons.

     Starting at the top, the first button group contains the following	buttons:

	  [ANIMATE]  [STEP]	NEW VAR	   EXIT
	  [TEXTURE]  TOP	SOUTH	   WEST
	  [TOPO]     [MAP]	BOX	   CLOCK
	  SAVE	     RESTORE	GRID #'s   CONT	#'s
	  [ANIM-REC] REVERSE	[SAVE PIC] [PERSPEC]
	  SCRIPT     INTERP	UVW VARS   LEGENDS
	  IMPORT     DISPLAY

     These buttons are used to control the primary functions of	vis5d.	Some of
the above buttons are enclosed in brackets [] to indicates that	they may be
blank upon starting vis5d.  This will happen when the button does not apply to
the current data set, because the button would conflict	with a command line
option,	or because the feature is not available	on your	hardware.

     The next group of radio buttons control the viewing mode which determines
how the	mouse is used in the 3-D window:

     Normal    Normal mouse mode is used to rotate, zoom, and pan the
	       graphics	in the 3-D window.  See	section	6.4.

     Trajectory	    This mode is used for creating and displaying wind
	       trajectories.  See section 6.8.

     Slice     This mode is used to reposition horizontal and vertical
	       slices.	See section 6.6.

     Label     This mode is used to create and edit text labels	in the 3-D
	       window.	See section 6.10.

     Probe     This mode is used to inspect individual grid values by
	       moving a	3-D cursor through the 3-D grid.  Using	the right
	       mouse button when clicking on this button will cause the
	       probe to	attach to the head of a	trajectory.  See section
	       6.11.

     Sounding  This mode is used to display a vertical sounding	and SkewT
	       at the location of a moveable vertical cursor.  See section
	       6.12.

     Clipping  This mode is used to reposition the six clipping	planes.
	       See section 6.18.

     These modes are mutually exclusive; only one may be selected at a time.  To
the immediate right of these buttons is	the mouse button legend.  It is	there to
remind you of the use of each mouse button in the 3-D window for the currently
selected mode.

Next are buttons labeled:

      Hwind1   Vwind1	HStrm	Hwind2	 Vwind2	  VStrm

     A wind vector slice (Hwind	or Vwind) depicts wind values by drawing small
arrows which point in the direction of the wind.  The length of	each line
segment	indicates its magnitude.  The tails of the line	segments are all
anchored within	a horizontal or	vertical plane through the 3-D box.  The
horizontal wind	streamline slice (HStrm) depicts wind values by	drawing
streamlines on a horizontal plane.  The	vertical wind streamline slice (VStrm)
depicts	wind values by drawing streamlines on a	vertical plane.	 The location of
slice planes can be changed with the mouse while in "Slice" mode.  See section
6.5 for	more details.

     The bottom	part of	the control panel window contains a 2-D	matrix of
buttons. Each row corresponds to a physical variable in	your dataset.  Each
column corresponds to one type of graphical representation.  By	selecting the
correct	row and	column you can view any	variable as a 3-D isosurface, horizontal
contour	slice, vertical	contour	slice, horizontal colored slice, vertical
colored	slice, or volume rendering.  This matrix of button is scrollable if
there are more rows of buttons than will fit in	the window.  You can use the
mouse to drag the scrollbar or press the up/down arrow keys on your keyboard to
scroll the button matrix.

     When multiple data	sets are viewed	in the same display a period and an
index number will be appended to the end of each variable name.	 This will be a
common notation	seen in	several	display	widgets	when ever multiple data	sets are
loaded.

     The display of any	graphic	is controlled by clicking on its widget	button
with the left mouse button.  Each type of graphic also has a small pop-up
control	window which appears when turned on.  The control windows are different
for each type of graphic and are explained below.  To bring up a graphic's
control	window without toggling	its display, use the middle mouse button.  When
the graphic is displayed it will be the	same color as the widget button, making
it easy	to distinguish and identify different variables	in the display.	 To
change the color of the	graphic, click on its widget button with the right mouse
button and a small window with four slider widgets will	appear.	 By changing the
levels of red, green, and blue you can make any	color.

     If	the control panel window becomes obscured by other windows, you	can
bring it to the	top by pressing	the "F1" key while the mouse pointer is	in the 3-
D window.  This	is especially useful when using	the '-full' option.

     When mutliple data	sets are displayed in different	displays there is the
option of grouping these them together.	 This synchronizes the control of one
display	with the others.  See section 6.19 for more information.


6.3 Controlling	vis5d

     The topmost group of buttons in the control panel operate the main
functions of vis5d.  Some will be discussed in more detail later.

     ANIMATE   This toggle button turns	animation on or	off. Use the left or
	       middle mouse buttons for	forward	animation and the right	mouse
	       button for reverse animation.  Does not appear when viewing data
	       sets with one time step.	 To make the animation slower or faster,
	       hit the S and F key on the keyboard while the mouse cursor is
	       inside the 3-D viewing window.

     STEP      This button has three possible uses depending on	which mouse
	       button is pressed:
		 Left Button - Step ahead one time step
		 Middle	Button - Go to first time step.
		 Right Button -	Backward one time step.
	       This button does	not appear when	viewing	data sets with one time
	       step.

     NEW VAR   Used to duplicate physical variables or invoke external analysis
	       functions. This is explained further in section 6.13.

     EXIT      Exit the	program.  A window will	appear to ask you to verify your
	       decision.

     TEXTURE   Toggles display of texture maps on/off if they are loaded.  See
	       section 6.15 for	more information.

     TOP       Depending on which mouse	button is pressed:
		 Left or Middle:  Reset	the 3-D	window to the default top-view.
		 Right:	 Set the 3-D window to a bottom-view.

     SOUTH     Depending on which mouse	button is pressed:
		 Left or Middle: Set 3-D window	to a south-view.
		 Right:	 Set 3-D window	to a north-view.

     WEST      Depending on which mouse	button is pressed:
		 Left or Middle:  Set 3-D window to a west-view.
		 Right:	 Set 3-D window	to an east-view.

     TOPO      Toggle the display of topography.  This button will not appear if
	       the topography file was not found.  Click on TOPO with the right
	       mouse button to edit the	topography color.

     MAP       Toggle the display of map lines.	 This button will not appear if
	       the map file was	not found.  Click on MAP with the right	mouse
	       button to edit the color	of the map lines.

     BOX       Toggle the display of the 3-D box.

     CLOCK     Toggle the display of the clock.

     SAVE      Save current graphics and colors.  After	you've setup a variety
	       of isosurfaces, slice, wind trajectories	and colors it is useful
	       to be able to save them and restore them	the next time the data
	       set is visualized.  You'll be prompted for a filename.  The file
	       format, as of Vis5D 4.2 is a Tcl	script.	 See section 6.16 for
	       more information.  Using	the right mouse	button when clicking on
	       this button will	allow the current vis5d	data set to be saved to
	       a file in the v5d format.  See section 6.21.

     RESTORE   Restore the information save with the SAVE button.  See section
	       6.16 for	more information.

     GRID #s   Normally	the bounds of the data set in latitude,	longitude and
	       kilometers are displayed	along the edges	of the box.  Use this
	       button to display the numbers in	grid coordinates instead.

     CONT #s   The numbers which are drawn on contour line slices can be toggled
	       on or off with this button.

     [ANIM-REC]	    This button	works just like	ANIMATE	but allows fast
	       animations on system with slow 3-D rendering.  After each time
	       step is rendered	the image is saved in memory.  When the
	       animation loop repeats the images are quickly copied from memory
	       to the 3-D window resulting in a	faster animation.

     REVERSE   Normally, the 3-D box and clock are drawn in white on a black
	       background.  This option	reverses that and draws	a black	box and
	       clock on	a white	background.  This is useful for	making paper
	       print outs.

     SAVE PIC  Used to save the	image in the 3-D or sounding window to a file.
	       When the	'Sounding' mode	is chosen from the radio widgets the
	       sounding	window	will be	saved.	If any other mode such as
	       'Normal'	or 'Slice' is chosen the 3-D window (including all
	       displays	if multiple displays exist) will be saved.  Depending on
	       what system you're using	a number of different picture file
	       formats are supported.  On SGI systems be sure you have the
	       'tops', 'frombin', and 'togif' program installed	from your IRIX
	       CD-ROM.	When using OpenGL on SGIs the 'fromxwd'	program	is also
	       needed.	Unfortunately there is a bug in	this program which often
	       causes it to fail.  Included with vis5d however is a patched
	       version of fromxwd.  An alternate way of	insuring more save
	       formats is to download ImageMagick's 'convert' program. See
	       section 6.14.

     PERSPEC   Toggle between perspective and orthogonal viewing projections.

     SCRIPT    Used to run Vis5D Tcl scripts.  When you	click on this button a
	       file request will appear	in which you can select	the Tcl	script
	       to run.	For more information see section 6.16.

     INTERP    Starts the Vis5D	interactive interpreter.  In your shell	window
	       you may then enter Tcl commands.	 Vis5D will be suspended while
	       the interpreter is active.  Type	'exit' to exit the interpreter.
	       For more	information see	section	6.16.

     UVW VARS  Opens a window in which you can specify the names of the
	       variables to use	for computing trajectories and wind slices.

     LEGENDS   Toggles the display of colorbar legends in the 3-D window.

     IMPORT    Invokes the import utility program for bringing new data	sets
	       into a Vis5D session.  For more information see sections	7.1 and
	       7.2.

     DISPLAY   Opens a window which allows you manipulate the assignment of data
	       sets to display windows and change various values associated with
	       display windows.	 For more information see section 6.20


6.4 Viewing Modes

     In	'Normal' mouse mode the	mouse is used to view the data in the 3-D
window.	 By pressing the left mouse button and moving the mouse	while the cursor
is in the 3-D window, the 3-D image can	be rotated.  At	any instant you	can only
control	two of the three degrees of freedom of box rotations.  However,	by
releasing and re-pressing the left mouse button	you can	change your "grip" on
the box.  With practice	you will learn to control the box through a series of
mouse moves, releasing and re-pressing the left	button between moves.

     The center	button controls	two very different things depending on how the
mouse is moved.	 Holding the center button down	and sliding the	mouse away from
yourself zooms in, making the box get bigger.  Sliding the mouse towards
yourself zooms out and makes the box get smaller.  Holding the center button
down and sliding the mouse right moves a plane of invisibility (i.e. a clipping
plane) into the	box, creating a	cut away view of the box contents.  Sliding the
mouse left brings the clipping plane toward yourself, eventually out of	the box
altogether.

     The right mouse button is pressed to translate the	box in the window.  This
is useful if you want to zoom in to something that is not in the center	of the
box.  Note that	the center of rotation for box rotations stays at the center of
the screen rather than in the center of	the box.

     The other five viewing modes will be discussed in detail in following
sections.


6.5 Isosurfaces

     An	isosurface (3-D	contour	surface) shows the 3-D volume bounded by a
particular isovalue.  The isosurface has the specified iso-level, the volume
inside contains	values greater (or less) than the isovalue.  The volume	outside
contains values	less (or greater) than the isovalue.

     The first column of buttons in the	control	panel's	button matrix controls
isosurfaces.  Clicking on one of these buttons with the	left mouse button causes
a pop-up window	with a slider and OK button to appear below.  Select an	isovalue
on the slider and click	on the OK button to generate an	isosurface for all time
steps.

     Toggling ANIMATE on will let you watch the	time dynamics of the iso-level
contour	surfaces.  Note	that the surfaces are generated	asynchronously with the
animation, so you may not see the surfaces for all the time steps as the clock
hand makes it revolution.  The new surfaces will appear	on successive clock
revolutions.

     Clicking on an isosurface button with the middle mouse button will	summon
the pop-up window without toggling the surface on or off.


6.5.1 Isosurface Color

     An	isosurface may either be drawn entirely	in one color or	colored
according to the values	of another physical variable.

     To	change the color of an isosurface, click on the	appropriate isosurface
button with the	right mouse button.  A window will appear with a column	of
variable names (first button labeled "monocolor") and four sliders labeled red,
green, blue, and transparency.

     By	default, monocoloring is used.	To change the isosurfaces's color just
move the red, green, and blue sliders.

     If	you click on a button other than "monocolor" you will tell vis5d to draw
the isosurface according to another physical variable.	The red,green,blue
sliders	will be	replaced with a	color table editor.  You can change the	color
table (which maps data values to colors) by drawing new	curves with the	mouse or
by pressing the	up, down, left,	and right cursor keys on your keyboard.

     As	an example, suppose you're viewing the LAMPS.v5d data set.  Make an
isosurface of wind speed at 40 m/s.  The isosurface should be blue.  Click on
the SPD	isosurface button with
your right mouse button.  The color window appears.  Click on the T button in
that window and
the isosurface will now	be colored according to	temperature.  You can modify the
mapping	from
temperature values to colors by	"drawing" the red, green, and blue curves in the
color table window with	the mouse buttons or by	pressing the cursor keys.
Changing the color table is explained more below in the	section	about colored
slices.




6.6 Slices

     Slices allow you to look at planar	cross sections of data in the 3-D box.
These slices can be oriented either horizontally or vertically and may depict
either contour lines, colored slices, wind vectors, or wind stream lines.

     As	described in section 6.1, the last group of buttons on the control panel
is a matrix of buttons,	the second through fifth columns of which control
slices.	 There is a column of buttons for horizontal contour slices, vertical
contour	slices,	horizontal colored slices and vertical colored slices,
respectively.  If your data set	contains U, V, and W variables,	there will also
be a row of wind vector	slice buttons as described in 6.2.  There are two
buttons	for horizontal wind slices and two buttons for vertical	wind slices.

     To	activate/turn on a slice, click	on the appropriate widget button with
the left mouse button.	The initial position for slices	is the middle of the
box.  The exact	slice location in terms	of latitude, longitude or elevation is
given by a small numeric labels	near the one corner of each slice.  To print the
numbers	as grid	coordinates instead of geographic coordinates, toggle the "GRID
#s" widget button on the control panel.

     The position of slices can	be changed interactively using the mouse.  To do
so you must first be in	SLICE mode by selecting	the SLICE radio	button.	 To move
any slice, simply point	at the slice's corner with the mouse, press the	right
mouse button and drag it to a new position.  Vertical slices may also be moved
in a perpendicular motion by "grabbing"	the middle of the top or bottom	edge and
dragging it.  A	slice may be moved while in animation mode, however, some
jumpiness may occur because new	slices are computed asynchronously.

     Slices may	also be	linked in a chain.  When slices	are linked, the	state
and movement of	all the	linked slices are synchronized.	 Horizontal and	vertical
slices can not be linked.  Slices can be linked	by using the API function call
'vis5d_link_slices' and	'vis5d_unlink_slice' from a script or via the 'INTERP'
button in the control panel.


6.6.1 Contour Line Slices

     When viewing a horizontal or vertical contour line	slice (button columns
two and	three) a small control window will appear as well.  In this pop-up
window you can enter the interval to
use between contour lines.  Just type in a new number to change	the interval.
Decreasing the interval	will cause denser contour lines	to be generated,
increasing the interval	will result in sparser lines.

     If	you enter a negative interval then all contour lines with a negative
value will be drawn with dashed	lines while positive values will be drawn with
solid lines.

     Optionally, after the interval value you may specify a range of values
(a,b) which will cause only contour values between a and b to be drawn.	 For
example, suppose you enter

     -10 (-30,20)

This will result in contour lines for values between -30 and 20	at intervals of
10 with	negative lines drawn as	dashed lines.

     The "CONT #s" button on the control panel toggles the display of the
contour	numbers	within the slice.

     The SFC button will cause the horizontal slice data to be sampled from the
topography surface then	displayed on top of the	topograhpy.


6.6.2 Colored Slices

     When a viewing a horizontal or vertical colored slice (button columns four
and five) a color table	window will appear.  In	this pop-up window you can
change the mapping from	data values to colors.	If the LEGENDS control panel
button is selected the color table will	also be	displayed in the 3-D viewing
window.

     The window	shows graphs of	red, green, and	blue over the range of data
values.	 To change the red, green, or blue function press the left, middle, or
right mouse button, respectively, and drag the mouse to	draw a new function.  By
default, low data values are mapped to blue and	high data values are mapped to
red.

     Instead of	using the mouse	you can	use the	keyboard cursor	(arrow)	keys to
modify the shape and position of the default function curves.  Press the
left/right keys	to move	the curves left	or right.  Press the up/down keys to
change the shape of the	curves.

     You may also change the transparency of the slice as a function of	the data
values.	 Press and hold	the SHIFT key while using the mouse or up/down keys to
change the transparency.

There are a number of other keyboard controls for the color table window:
     r	  reset	red, green and blue values
     R	  reset	transparency values
     c	  copy color to	an off-screen clipboard
     p	  paste	colors from the	off-screen clipboard
     s	  save color values to a file, enter filename in your shell window
     l	  load color values from a file, enter filename	in your	shell window


6.6.3 Wind Vector Slices

     Wind vector slices	are displayed with the buttons near the	center of the
control	panel labeled HWIND-1, VWIND-1,	HWIND-2	and VWIND-2.  The pop-up window
for these
graphics contains two type-in fields to	control	the density and	scaling	of the
wind vectors.  The scale parameter is used to multiply the length of vectors
drawn.	If you want to double the length of all	vectors, enter 2.0.  If	you want
to halve the lengths, enter 0.5.  The density parameter	controls how many wind
vectors	are displayed.	This value can only be between zero and	one.  To make
one-half the number of vectors,	enter 0.5, for one-fourth enter	0.25, etc.  The
default	values for both	parameters is 1.0.

     The SFC button for	horizontal wind	slices will cause the slice data to be
sampled	from the topography surface then displayed on top of the topograhpy.

6.6.4 Wind Stream Slices

     Wind stream slices	show the path of wind as connected line	segments.  The
pop-up control window contains a type-in widget	to control the density of
streamlines (note that the scale parameter is not used).  The density parameter
controls how many streamlines are displayed.  This value can only be between 0.5
and 2.0.  To make one-half the number of streamlines, enter 0.5, to make twice
the number of streamlines, enter 2.0, etc.  The	default	density	is 1.0.

     The SFC button will cause the horizontal slice data to be sampled from the
topography surface then	displayed on top of the	topograhpy.

6.6.5 Slice colors

     The color of a slice's control button matches that	of the slice itself
(except	for colored slices for which the slice's tick mark matches the slice's
button.)  To change the	color of a slice
click on the slice's button with the right mouse button.  A window with	red,
green, and blue	sliders	will appear.  Move the sliders to change the color.


6.7 Volume Rendering

     Volume rendering is a technique for displaying a 3-dimensional field as a
semi-transparent colored fog.  Though volume renderings	of some	physical
variables don't	look, others can be displayed very effectively with the	right
color mapping.

     The volume	rendering feature is available in Vis5D	on almost all systems.
Be warned that systems without 3-D graphics hardware (i.e. those using Mesa)
will render volumes very slowly.

     The sixth column of buttons on the	control	panel are the volume buttons.
Only one may be	displayed at a time.  When a volume rendering is activated a pop-
up window with a color table appears.  This color table	is used	in exactly the
same way as described for colored slices above.	 That is, using	the mouse or
keyboard you can change	the function which maps	data values to color and
transparency.  Again, the transparency can be changed while holding down the
SHIFT key and drawing a	curve with the mouse or	pressing the up/down keys.

For those who are curious about	the implementation of this feature, the	volume
rendering is made as follows:
     1.Examine the current viewing transformation to determine which axis of
       the 3-D box is most nearly parallel to the view direction.
     2.Create a	number of colored slices perpindicular to that axis which map
       data values to colors and opacity.
     3.Render the colored slices in back to front order.  The alpha values at
       vertices	are interpolated and blended to	make smooth transitions	between
       and within slices.

     Despite the simplicity of the algorithm, most fields are rendered
acceptably.  Those that	aren't can be improved by adjusting the	color and
opacity	mappings.  While more attractive volume	rendering techniques are known,
this technique can be implemented quickly on many systems.


6.8 Wind Trajectories

     Wind trajectories trace the motion	of air through the 3-D volume much line
smoke trails in	a wind tunnel.	To enter trajectory mode select	the TRAJECTORY
radio button on	the control panel.  A pop-up window will appear	near the bottom
of the screen and a 3-D	cursor will appear inside the 3-D view box.  This 3-D
cursor is used to specify where	a new wind trajectory should be	made.  The STEP
button on the main control panel is also important because it is used to select
the time step at which to create the trajectory.

     Wind trajectories are dealt with in sets.	Currently, eight sets are
available.  Each set is	represented in the trajectory window with a button
labeled	Set1, Set2, ..., Set8.	Each set can be	individually displayed,	colored,
or deleted.  As	you create new trajectories you	may want to group them in sets
corresponding to location, time, etc.

     The first step in creating	a trajectory is	to select a position with the 3-
D cursor.  Use the right mouse button to drag the 3-D cursor around inside the 3-
D box.	The 3-D	cursor will move in 2-D	in a plane parallel to the plane of
projection.  That is, the cursor will stay at a	constant distance of depth.  By
alternately rotating the view box with the left	mouse button and placing the
cursor with the	right mouse button, the	3-D cursor can be placed anywhere inside
the view box.  The TOP,	SOUTH, and WEST	buttons	as explained in	section	6.2 can
also be	useful when making trajectories.

     Second you	should select a	time step with the STEP	button on the control
panel.	When the trajectory is made, it	will be	traced forward from the	current
time step to the last time step	and will be traced backward through time to the
first time step.

     Finally, to make a	trajectory at the current cursor location and current
time step, press the middle mouse button when pointing inside the 3-D window.
The trajectory will appear as a	line segment.  By turning on the ANIMATE button,
you can	observe	how the	trajectory travels through time	and space.  Typically,
you will repeat	the process of positioning the 3-D cursor and clicking the
middle mouse button to create a	set of trajectories.

     Interesting results can be	seen by	making a trajectory when the ANIMATE
button is turned on:  a	trajectory will	be created for every time step instead
of just	one.  This will	show you the path of every air parcel which passes
through	a single point in space.

Here is	a summary of the various trajectory functions:

      1.To position the	3-D cursor, use	a combination of rotating the view box
	with the left mouse button and dragging	the 3-D	cursor with the	right
	mouse button.

      2.Use the	STEP button or ANIMATE option to select	a time step.

      3.Press the middle mouse button to create	a trajectory at	the current
	cursor location	and time step.

      4.To toggle the display of a trajectory set on or	off, click on the set
	button with the	left mouse button.

      5.Select the current trajectory set by clicking on the set button	with
	the middle mouse button.

      6.A trajectory set may be	deleted	with the 'Delete Set' button in	the
	trajectories window.  You will asked to	verify your decision.

      7.You can	delete the last	trajectory made	by clicking on the 'Delete
	Last' button in	the trajectories window.

     Wind trajectories can be depicted in two ways:  as	line segments or as
ribbons.  You can select ribbons by clicking on	the RIBBON button in the
trajectory window.  Toggling the RIBBON	button will not	effect trajectories you
have already made; it only controls how	new trajectories will be displayed.

     The trajectory window also	contains two type-in widgets labeled STEP and
LENGTH.	 The STEP value	is used	to control the step size used in the trajectory
tracing	algorithm.  The	LENGTH value is	used to	control	the length of
trajectories.  1.0 is the default value	for each.  Each	acts as	a multiplier.
If you want the	trajectory tracer to integrate in steps	1/2 the	default	size,
enter a	step value of 0.5.  If you want	trajectories to	be twice as long as the
default	length,	enter a	length value of	2.0

     The color of trajectories is controlled in	the same way as	for isosurfaces.
That is, a trajectory set may either be	mono-colored or	colored	according to
another	physical variable.  Click on the trajectory set	button with the	right
mouse button to	bring up its color window.  See	section	6.5.1 for details on
using the color	window.

     When viewing color-mapped trajectores be aware that the color of a
trajectory is time dependent.  Only the	head of	the trajectory is colored
according to the value of another variable for the current time	step.  The tail
of the trajectory is colored according to the color of the other variable when
the head was at	that location.


6.9 Wind Variables

     By	default, wind trajectories and the first set of	wind slices are	computed
from the variables named U, V, and W while the second set of wind slices are
computed from the variables named U2, V2, and W2.  Other variables can be
specified through the "UVW VARS" button	on the control panel.  When you	click on
this button a pop-up window appears in which you can
specify	the names of the variables to use for computing	trajectories, the first
set of wind slices, and	the second set of wind slices.	Just type in the new
variables names.  Be aware that	uppercase and lowercase	are significant.  Be
sure you enter valid names otherwise vis5d may not compute the graphic you
select.

     When multiple data	sets are being viewed in one display a period and data
context	index number must be appended to the end of each variable to specify a
data set index number.	For example the	first set of UVW's might be " U.0 V.0
W.0" while the second set might	be "U.2	V.2 W.2".  The wind variables belonging
to a set MUST be from the same data set	other wise they	will be	considered
invalid.

     After you've entered new wind component variable names click on APPLY to
use the	new values but keep the	window visible.	 Click on OK to	use the	new
values and close the window.  Click on CANCEL to discard your changes and close
the window.

     You can also specify the wind component variables on the command line when
you start vis5d.  See section 6.1.


6.10 Text Labels

     Text labels are used to annotate the image	in the 3-D viewing window.
Typically this is used for making presentation graphics.  You could add	a title,
your name, the date, highlight a particular feature of the data, or document the
meaning	of the data seen in the	window.

     To	enter text labeling mode select	the LABEL radio	button on the control
panel.

     To	create a text label position the mouse pointer somewhere in the	3-D
window and press the left mouse	button.	 A vertical bar	cursor will appear at
that location and you can now type in the text.	 The <Backspace> key can be used
to correct errors.  When you are finished, press <Return>.

     To	move a text label to a new position, point at it with the mouse, hold
down the middle	mouse button and drag the mouse.  As you move the mouse	an
outline	of the text will be dragged with the pointer until you release the mouse
button.

     To	delete a text label, pointing at it with the mouse and pressing	the
right mouse button.  Be	careful, you will not be asked for verification	before
deleting a label.  Once	it's deleted you can only restore it by	retyping it.

     The SAVE button on	the control panel will save any	text labels you	have
made.

     Use the '-font' command option to select a	different font or change the
'fontname' field in the	'Options' menu.


6.11 Data Probe

     Sometimes it's useful to be able to inspect individual data values	at
various	locations in the 3-D volume.  You can do this with the data probe.
Click on the PROBE radio button	on the control panel.  A 3-D cursor appears in
the 3-D	box which you can move around using the	right mouse button.  For each
physical variable the value for	the current time step is printed along the left
edge of	the 3-D	window.	 If physical units are specified for the variable they
will be	printed	next to	the value.  Units can be assigned with the v5dSetUnits()
function in your data conversion program as described in section 3.1.

     If	you turn on the	GRID #'s button, the probe will	be constrained to
integral grid coordinates.  That is, the cursor	will 'snap' to the nearest
discrete grid coordinate.

     When the PROBE radio button is clicked on with the	right mouse button is
will be	attached to the	head of	a trajectory.  The probe will search for the
first set of trajectories being	displayed, then	attach to the head of the first
trajectory made	in that	set.  The probe	will also follow the movement of the
trajectory during animation.  This feature is useful for identifying the values
at the location	of a trajectory	as is moves along its path.

     One may also select which variables to display while in the PROBE mode.
The API	function 'vis5d_set_probe_vars'	can be used in a script	or via the
'INTERP' button.


6.12  Vertical Sounding	and SkewT

     When you select Sounding mode, Vis5D displays a vertical line cursor that
runs from the bottom to	the top	of the 3-D box,	and displays a vertical	sounding
window.	 The sounding window includes a	SkewT diagram generated	for grid data at
the location of	the vertical cursor (unless your data set uses generic vertical
coordinates), and vertical plots of up to three	variables.  The	user can
interactively select and change	which variables	are used for temperature, dew
point and wind fields in the SkewT diagram.  Variables named T,	TD, U and V are
used as	defaults if they exist.	 The user can also interactively select	and
change which variables are used	for the	vertical plots.	 Users can interactively
control	the background of the SkewT diagram and	vertical plots,	including dry
adiabats, moist	adiabats, constant mixing ratio	lines, temperature lines and
height tick marks.  They can also interactively	resize and reposition the
sounding window.
     When multiple data	sets are being viewed in one display a period and data
context	index number must be appended to the end of each vertical plot variable
(e.g., "T.1" or	"TD.2").
     The scale for the vertical	plot variables can be forced to	be the same for
all three variables.  This can be achieved by using the	command	line option '-
samescale' or by entering the display widget (press 'DISPLAY') then pressing the
'OPTIONS' button and selecting 'samescale'.


6.13  Making New Variables

     The NEW VAR button	on the control panel is	used to	add new	physical
variables to the button	matrix.	 There are three kinds of new variables	you can
add:

     1.	Cloned variables:  these are copies of existing	variables.  You	can use
a cloned variable to make two different	isosurfaces of the same	variable
simultaneously,	for example.

     2.	External function variables:  you can invoke an	external function (which
you write) to compute a	new variable as	a function of existing variables.

     3.	Computed variables:  you can compute a new variable by typing in a
formula	involving values of existing variables.

     When you click on the NEW VAR button a window appears which lists the
variables that you can clone, lists the	external functions that	you can	invoke,
and lets you type in a formula for computing a new variable.  After a new
variable has been created a new	row of buttons will be added to	the control
panel for the new variable.  You can then make isosurfaces, contour slices, etc.
of the that variable like any other.


6.13.1	Cloned Variables

     Suppose you want to clone the U wind component variable so	that you can
make both +20 and -20 isosurfaces of it.  First, click on NEW VAR and then
select U from the pop-up window.  The cloned variable will be named U'.	 You can
then treat U' as any other variable and	make an	isosurface of it.


6.13.2	Type-in	Formulas

     Type-in formulas let you type in mathematical expressions to compute new
variables as a function	of existing variables.	For example, to	compute	wind
speed from U, V, and W you would enter the formula:

     SPD3D = SQRT( U*U + V*V + W*W )

To compute the ration of the dew point (TD) to the temperature you would enter
the formula:

     RATIO = TD	/ T

     Formulas may use the names	of existing variables, numbers,	the arithmetic
operations +, -, *, / and ** (exponentiation), and the functions SQRT, EXP, LOG,
SIN, COS, TAN, ATAN (arc tangent), ABS (absolute value), MIN and MAX.  MIN and
MAX take two arguments,	while the other	functions all take one argument.

     There is a	special	operator 'time'.  This will allow one to choose	the grid
values for a certain time step relative	to the current time step.  The format is
'time(var, time_step_change).  If the var is subsituted	with the word 'time'
then the grid will be a	constant value,	the number of second since the first
time step.  For	example	in order to create a time derivative of	U of the type:


	  U(t+1) - U(t-1)
		  -----------------------------------------
     Time(t+1) - Time(t-1)


you would enter	the formula:

     dUdt = ( time(U,1)	- time(U,-1) ) / ( time(time,1)	- time(time,-1)	)


     Click on the OK button to compute the new variable	or CANCEL to discard the
formula.  You can edit the formula later by selecting it again from the	NEW VAR
pop-up window.

     When multiple data	sets are being viewed in one display a period and data
context	index number must be appended to the end of each variable in the
formula.  For example the above	formula	might instead look like:

     SPD3D.2 = SQRT(U.0*U.0 + V.2*V.2 +	W.2*W.2)

To compute the difference of two seperate variables you	would enter the	formula:

     DIFFT.0 = T.0 - T.1

If there are multiple data sets	but no index number appended then it will be
assumed	that the variable belongs to the first data set	(i.e., index 0)
deposited into the display.  In	some cases the time steps for two different
variables will not coincide.  When this	happens	the variable is	computed
according to the time steps of the data	set which the new variable belongs to.
Time steps will	be matched as close as possible	and time steps out of range from
one other will be void of data.	 For example, in the formula "DIFFT.0 =	T.0 -
T.1", if the time steps	were such:

	       Data Context 0
		   Date(YYDDD)	Time(HH:MM:SS)
Time 0		  82091	     0:00:00
Time 1		  82091	     2:00:00
Time 2		  82091	     4:00:00
Time 3		  82091	     6:00:00
Time 4		  82091	     8:00:00
Time 5		  82091	    10:00:00

	       Data Context 1
		   Date(YYDDD)	Time(HH:MM:SS)
Time 0		  82091	     2:30:00
Time 1		  82091	     4:30:00
Time 2		  82091	     6:30:00
Time 3		  82091	     8:30:00

The resulting variable "DIFFT.0" would contain the data:

Time 0	       No Data
Time 1	       No Data
Time 2	       T.0(time=2) - T.1(time=1)
Time 3	       T.0(time=3) - T.1(time=2)
Time 4	       T.0(time=4) - T.1(time=3)
Time 5	       No Data




6.13.3	External Analysis Functions

     External analysis functions are an	advanced feature, so new Vis5D users may
want to	skip this section for now.

     An	external analysis function is a	function written by you	in FORTRAN which
is called by Vis5D to produce a	new variable as	a function of the existing
variables.  As an example, there is included a function	SPD3D which computes
wind velocity as:  SPD3D = SQRT( U*U + V*V + W*W ).  Be	aware that the external
function feature is intended for experienced Vis5D users who are also proficient
FORTRAN	programmers.

     All external functions must be placed in a	directory named	"userfuncs"
(this may be changed in	the vis5d.h file).  This is relative to	the current
directory when you run vis5d.  For example, suppose you	always run vis5d while
in "/usr/jones/data", then your	analysis functions must	be in
"/usr/jones/data/userfuncs".  Also, this directory contains a script "externf"
which is used to compile your function.

     To	write an external function it's	best to	copy one of the	supplied
examples and then modify it.  The included "userfuncs/example.f" is fully
commented for this purpose.  Later, when you call your function	from within
vis5d, the function will be invoked once for each time step.  The arguments
passed to the function include (the data set is	the first data set in the
display	associated with	the current control panel):

     1.	the number of physical variables in the	data set
     2.	the name of each variable
     3.	the size of the	3-D grid
     4.	the date and time of the time step
     5.	map projection and vertical coordinate system information
     6.	the actual 3-D grids of	data for each physical variable

     Your function will	have to	scan the list of variable names	to find	the ones
it needs for the computation.  Then it must do the actual computation,
generating a new grid of data to return	to vis5d.  The examples	we've included
demonstrate how	to do this.  Specifically, you should look at example.f	which
has detailed documentation of the function arguments.  The map projection and
vertical coordinate system arguments work in exactly the same way as the
v5dCreate library call discussed insection 3.1

     Suppose you want your function to be named	"delta".  Then the name	of the
FORTRAN	program	must be	"delta.f".  You	would compile the function by typing
"externf delta".  If there are no errors, an executable	file "delta" will be
written.  Then in vis5d	when you select	NEW VAR, "delta" should	appear in the
list of	functions in the pop-up	window.

     There are two places for vis5d to get the grid data which it passes to your
external function:  from the original, uncompressed McIDAS file	or the
compressed v5d/comp5d file.  The uncompressed McIDAS data is better because it
has more precision.  If	the McIDAS file	can't be found,	then the compressed data
which vis5d has	in memory will be passed to your external function.  Note that
this has no bearing whatsoever on the construction of your external function.

     You can retrieve the position and values of the data probe	from within your
function.  To get the position of the probe use:

     CALL PROBEPOS( ROW, COL, LEV, LAT,	LON, HGT )

The position in	grid coordinates will be returned in ROW, COLumn, and LEVel.
The position in	geographic coordinates will be returned	in LATitude, LONgitude,
and HeiGhT.

To get the value of any	physical variable at the current probe position	and
current	time step use:

     VALUE = PROBEVAL( VAR )

where VAR specifies which physical variable you	want.


6.14 Saving Image Files	and Printing

     The SAVE PIC button on the	control	panel can be used to save the image in
the 3-D	or sounding window to a	file.  If you are in 'Sounding'	mode the
sounding window	will be	saved, any other mode will save	the 3-D	window
(including all displays	if multiple displays exist).  When you click on	SAVE PIC
a pop-up window	appears	in which you can select	the file format	and filename.
The choices of file formats depends on the computer you're using or whether or
not you	have the 'convert' program installed.  The formats supported by	Vis5D
are:

     XWD - X Window Dump, displayable with xwud	or xv.
     RGB - SGI image file format, displayable with ipaste or xv.
     GIF - Standard GIF	format,	displayable with xv and	many other programs.
     PostScript	- may be printed or viewed on-screen with a program like
     ghostview.
     Color PostScript -	may be printed or viewed with a	ghostview-like program.
     PPM - standard unix file format.
     TGA - only	available with the 'convert' program

     It	is recomended that the 'convert' program be downloaded.	 This ensures
more save file formats and in some cases produces higher quality save pictures.
ImageMagick's 'convert'	program	can be downloaded at:
   ftp://ftp.wizards.dupont.com/pub/Imagemagick
and the	www page is
   http://www.wizards.dupont.com/cristy/ImageMagick.html
Once the 'convert' binary has been downloaded or compiled it has to be placed in
a directory 'util' where vis5d is being	run.  For example if you are running
vis5d from '/usr/home/jane' then the convert program must be placed in
'/usr/home/jane/util'.

     Configurations of Vis5D  using OpenGL directly write XWD files.  The
following methods are used if no 'convert' program is present.	To make	an RGB
file the fromxwd program is used.  Unfortunately, the fromxwd program shipped by
SGI has	a bug which causes it to fail.	Since source code for fromxwd is shipped
with IRIX we include a patched version which works correctly.  To make a gif
file requires both fromxwd and togif (only available on	SGI systems).  To make a
grayscale PostScript file requires the xpr utility (standard with X11).	 To make
a color	PostScript file	the tops program is needed (only available on SGI
systems).

     If	you don't have any of the utilities mentioned above you	should try using
xv to convert your image files.	 xv is available by ftp	from export.lcs.mit.edu
in contrib/ and	from ftp.cis.upenn.edu in the pub/ directory.

     To	print a	Vis5D image, position the mouse	pointer	over the 3-D window and
press the P key.  If you are in	'Sounding' mode	the sounding window will be
printed, any other mode	and the	3-D window will	be printed.  You'll be asked to
verify your action.  Vis5D uses	lpr to send a PostScript image file to the
default	printer	or the printer specified by the	PRINTER	environment variable.
To generate the	PostScript file	Vis5D uses the utilities described above.  If
you have problems printing you should try to first save	your image as a
PostScript file	then try to print it manually using lpr	or lp.	Another	option
is to save your	image as an XWD	file then use xpr (a standard X11 utility) to
convert	it to PostScript and print it.

     To	learn more about the xwud, xpr,	fromxwd, tops and togif	program	read the
man pages.  Many of these programs have	options	which you may find useful.


6.15 Texture mapping

     Texture mapping is	a term from computer graphics which means to display a 2-
D image	over a surface in 3-D.	In Vis5D you can display images	over the
topography (or bottom of the 3-D box when topography is	turned off) such as
satellite or map images.  Texture mapping is only available on SGI systems and
those using the	Mesa library.  Hardware	support	for texture mapping is highly
recommended.

There are three	types of texture/image mapping in Vis5D	which can specified on
the command line or in the 'Options' menu:

     -area N   N is the	number of the first of a sequence of McIDAS area files.
	       The number of files read	equals the number of timesteps in your
	       datafile.  Images should	all be of the same size.  You must use
	       McIDAS to do remapping if necessary.

	       Example:	 Suppose your datafile has 4 time steps	and you	specify
	       -area 100, then AREA0100, AREA0101, AREA0102 and	AREA0103 will be
	       loaded and displayed.

	       This option needs the McIDAS library which is only available on
	       SGI systems.

     -sequence file This works like the	-area option, except that the data come
	       from a very simple file format rather than from McIDAS area
	       files.  The file	starts with 3 int's that contain the number of
	       images in the sequence, the number of lines per image, and the
	       number of pixels	per line.  The rest of the file	contains the
	       images, one byte	per pixel.  The	function read_texture_sequence
	       in the image.c file of the src directory	reads this file	and
	       serves as a file	format reference for those wishing to create
	       such image sequence files.

     -texture file  This options specifies a single image to display over the
	       topography for all time steps.  The file	format is the SGI RGB
	       format.	The free XV program can	be used	to convert your	image to
	       RGB format.

When a texture map is available	the TEXTURE button on the control panel	is used
to toggle the display of the imagery on	or off.
     Note these	command	line options can be used with each data	set named on the
command	line, and can be entered under Options for each	display	in the display
widget window described	in Section 6.20.


6.16 Tcl scripting

     Vis5D 5.1 features	a scripting facility.  That is,	you can	control	Vis5D
with a text file of commands using the Tcl language.  Scripting	is an advanced
subject	and documented separately in the Vis5D scripting document at
http://www.ssec.wisc.edu/~billh/script.html.

     Note that the SAVE	and RESTORE buttons on the control panel write and read
Tcl files.  You	may want to use	bits of	these files as a basis a new Tcl
scripts.


6.17 Keyboard Functions

     The following keyboard functions can be invoked while the mouse pointer is
inside the 3-D viewing window:

     Key  Function
     F1	  Raise	or lower the control panel window.  This is useful with	the -
	  full option.
     F2	  Toggle display of system information including memory	used and number
	  of graphics to be computed.
     P	  Print	the current window image.  A PostScript	printer	must be
	  available.  Set the PRINTER environment variable from	your shell to
	  specify which	printer	to use.
     S	  Slower animation - increases the minimum time	between	frames by 10
	  msec.
     F	  Faster animation - decreases the minimum time	between	frames by 10
	  msec.
     R	  Reset	the clipping planes to there default positions
     B	  Turn of the window borders.( This is useful when using Sun
     workstations, an	 unsolved bug causes the borders to flash in a very
     annoying manner!)
     l	  Reduce the size fo the Vis5D logo
     L	  Increase the size of the Vis5D logo

     If	you want to program your own keyboard functions	look the in the	file
src/gui.c for the
func1(), func2(), func3(), etc functions.  They	are called when	the
corresponding function key is pressed.


6.18  The Clipping Planes

     Six new clipping planes has been added in Vis5D version 5.1.  This	allows
you to manipulate the viewing volume in	a more precise manner.	Press the
'Clipping' radio button	in order to enter the clipping mode.

     There are two horizontal clipping planes the top and bottom.  There are
also four vertical clipping planes, the	north, south, east and west.  Only one
clipping plane may be moved at a time.	The middle mouse button, when clicked in
the 3-D	display	window,	will cycle through and highlight the six planes.  The
clipping planes	are then moved in the same manner as the vertical and horizontal
slices.	 Simply	click on a corner or midpoint of the clipping slice with the
right mouse button and drag it.	 The clipping planes may set back to there
default	positions by pressing the 'R' key.


6.19 Grouping

     When there	are multiple displays you can group them together in up	to 9
groups.	 To group a display press the desired group number 1..9	on the keypad.
This puts you in group toggling	mode.  No other	mouse or GUI event will	be
accepted while in this mode.  Then click with the left mouse button in a 3-D
display	window to add it to or delete it from the group.  If the display
selected is not	already	in the group it	will be	added, and 'Group #' will show
up in the upper	right hand corner of the display window.  If the display
selected is in a different group it will be switched to	the current group.  If
the selected display is	already	in the group you are toggling for then it will
be ungrouped and the 'Group #' message will dissapear.	Any 3-D	display	will be
toggled	in this	manner until you exit group toggling mode by simply pressing a
number 1..9 on the keypad.

     If	two or more displays are grouped together than the following will
happen:

     - If one display is rotated, zoomed or translated,	all displays will change
       in the same manner.
     - If a graphic for	a certain variable is toggled in one display, the same
       variable	name is	searched for in	the other displays.  If	the variable
       exists, the same	graphic	will be	toggled.
     - Isosurfaces are set to the same value.
     - Slices will move	in sync.  They will move to the	same geographical
       position.
     - Many buttons on the control panel will be in sync.
     - The time	steps for all grouped displays will be merged for animation.
     - The probe and sounding cursor will move in the same geographic position.
     - All of the radio	buttons	will be	in sync.  If sounding mode is chosen,
       the sounding window for all displays will be mapped.
     -	 Slices	will be	linked from all	displays, sometimes creating a large
       chain of	linked slices

When a display is grouped or ungrouped the buttons on its control panel	are set
to their default settings.  The	graphics for every variable are	also turned off.
If more	than one data set is attached to a grouped display and they contain
similar	named variables, only the first	data set can display graphics for that
variable.


6.20  The Display Widget Window

     The display widget	window is the control center when multiple data	sets are
loaded and is invoked by pressing the 'DISPLAY'	button on the main control
panel.	A data set is always assigned to exactly one display, but a display may
contain	zero, one or more data sets.  A	display	includes a 3-D graphics	window
and defines a virtual grid space where all the graphics	from its data sets are
mapped.	 If the	data grid is different from the	virtual	grid the appropriate
resampling is applied.	In some	cases this resampling will cause graphics
generation to be slow.

     The display widget	window allows you to: change the number	of displays and
how they are arranged, change the assignment of	data sets to displays, change
the parameters of a display which define the virtual grid, and change most of
the command line options.

     Each display's user interface includes a set of buttons and type-in fields
and a data set browser.	 At the	top of the user	interface is the 'Display #'
which gives the	index of the display.  Below that is a browser showing a list of
data sets attached to that display.  Each entry	in the browser contains	the
context	index of the data set and the context name. There is a scroll bar to the
right of the browser which can scroll though the list if it gets larger	than the
browser	window.	 Above the browser is the 'Options' button which is described in
section	6.20.4.	 Below	the browser is the 'SET	DISPLAY	PARAMETERS' which is
described in section it	6.20.3.	 Currently there can be	a total	of 16 displays.
Watch out though, opening many displays	can eat	up a lot of memory.


6.20.1 Changing	the Number of Displays

     In	the upper left hand corner is the 'Display Matrix' with	9 buttons,
'1x1', '1x2', '1x3', '2x2', '3x2', '2x3', '3x3', '3x4',	'4x3', and '4x4'.  These
buttons	control	the number and layout of displays.  Underneath this is the
'Return	to Vis5D' button.  This	will exit from the display widget window and map
the 3-D	graphics window	of each	display	according to the chosen	button matrix.
If a display is	created	but has	no data	set attached to	it then	the 3-D	window
is left	blank.


6.20.2 Changing	the Display Assignment of a Data Set

     In	order to change	the aassignment	a data set to a	different display you
have to	highlight the desired data set.	This is	done by	simply clicking	on the
appropriate entry in the display browser.  You then click inside the data set
browser	of another display and the data	set transfered.	 If a data set is
transfered to an empty display it may take several seconds while the display is
initialized.


6.20.3 Changing	the Parameters of a Display

      The parameters of	a display define the virtual grid.  These parameters
include: the number of rows, columns and levels	of the grid, the map projection,
and the	vertical coordinate system.  There are three ways of changing these
parameters.  When an index number is typed into	the 'FROM Context #' field, the
parameters are copied from the specified data context over to the current
display.  When an index	number is typed	into the 'FROM Display #' field, the
parameters are copied from the specified display over to the current display.
The third option is to manually	edit one or all	of the parameters by pressing
the 'User Input' button.  A set	of fields associated with each parameter will
then appear on the left	hand side.  When you are finished changing the
parameters press the 'Done' button found at the	bottom.


6.20.4 Changing	the 'Options' for a Display

     In	Vis5D version 5.1 the command line options (refer to section 6.1) can
now be changed at any time instead of just once	while first running vis5d.  When
the 'Options' button is	pressed	at the top of the display browser a set	of
fields will appear on the left hand side.  These fields	correlate to the command
line options.

6.21 Saving the	current	v5d file.

     When the user clicks on the SAVE button with the right mouse button a
window will show up prompting for a file name.	The current vis5d data set in
the display will then be saved to a file in v5d	format.	 This is only useful
when new variables have	been created via the NEW VAR button or thru the	use of
external functions.


6.30  Final Notes

     The SGI version of	vis5d uses multiple CPUs if available to compute
graphics in the	background thereby increasing vis5d's speed.  On other systems,
vis5d tries to interleave the computation of graphics with user	interaction.
This results in	the user interface being a bit sluggish	until all pending
graphics computations are completed.

     The vis5d user interface may be complex to	describe in words, but we have
tried hard to make it simple in	reality.  After	a little practice using	the
sample data sets we hope it feels natural.

     Since version 3.2 of Vis5D	there is a user-contributed software directory:
contrib/.  See the README file in that directory for a description of current
contributions.



7.  THE	v5dimport UTILITY

     The v5dimport utility is a	program	for converting grid files to v5d format,
combining multiple source files, resampling to new coordinate systems and
culling	variables and timesteps.  It has both a	graphical and command line user
interface.

     For example, you may use v5dimport	to read	2 McIDAS GR3D files and	a 2-D
McIDAS GRID file, resample all the data	to a Lambert Conformal projection, omit
the CWAT and VORT variables and	then write the data to a Vis5D file called
lambert1.v5d.

The basic order	of events when using v5dimport is:
     1.	Read the input file(s).
     2.	Select grids for output	according to timestep, physical	variable, map
       projection or vertical coordinate system.
     3.	Setup a	map projection and vertical coordinate system for the output
       file.
     4.	Write the output file.	Resampling is done at this time.
     5.	Optionally, start Vis5D	on the output file.

Currently, v5dimport can read the following file formats:
     McIDAS GR3D and GRID files
     Vis5D v5d and comp5d files
     GRADS files
     "UW vis" files (used at the University of Wisconsin)
     EPA MM4 and RADM files (on	Crays only)


7.1 Using v5dimport's graphical	interface

Start v5dimport	from your shell	with

     v5dimport [-path pathname]	[files]

where [files] is an optional list of input files and [-path pathname] specifies
that the directory named "pathname" is to be used as the default, in place of
the current directory, for the input file browser and for making output	files.

When v5dimport has started you'll see its main window appear.  It consists of:
     1.	a scrollable list of all grids scanned from the	input files
     2.	buttons	used for selecting/culling grids according to variable name,
       timestep, projection or vertical	coordinate system
     3.	buttons	and type-in fields for describing and creating the output file.


7.1.1 Reading input grids

     You may read additional grid files	into v5dimport at any time by clicking
on the "Read file..." button.  Use the file selector to	locate your file and
click on OK or CANCEL.	It's best to read all input files right	at the beginning
because	whenever a new file is read all	grids are selected for output,
overriding any selections you may have previously made.

     The button	labeled	"Discard all grids" does exactly what it says.	It's
equivalent to exiting v5dimport	and restarting it.

     After reading each	input file, the	list of	grids shown in the top half of
the window, will be resorted by	time then variable name.

The columns in this list are:
     Grid - grid number	(no significant	meaning)
     YYDDD - the year and date of the grid
     HHMMSS - the time of the grid in hours, minutes, and seconds
     Variable -	the variable name
     Nr	- number of grid rows
     Nc	- number of grid columns
     Nl	- number of grid levels
     Proj# - the projection number (see	"Select	by projection..." window)
     VCS# - the	vertical coordinate system number (see "Select by VCS...")
     Filename -	name of	file the grid was found	in


7.1.2 Selecting	grids for output

     It's often	the case that one wants	to discard some	physical variables or
timesteps from the input file so they aren't written to	the output file.  By
default, all variables are selected for	output.

     To	select/cull variables, click on	the "Select by variable..." button.  A
pop-up window will appear which	lists all the variables.  The ones that	are high
lighted	are selected for ouput.	 Click on variables names to select or deselect
them.

     Similarly,	you can	select timesteps via the "Select by time..." button.  A
pop-up window listing all time steps will appear.  Use the mouse to select the
time steps you want and	unselect the timesteps you wish	to omit.  Note that you
can select/deselect a number of	timsteps by just dragging the mouse while
holding	down the button.

     Finally, grids may	be selected or discarded according to their map
projection or vertical coordinate system (VCS) via the "Select by
projectiion..."	and "Select by VCS... buttons.

     Note that as you select/deselect timesteps, variables, projections, or VCSs
the effected grids will	be high-lighted/unhigh-lighted in the main grid	list.

     The "Select All" and "Select None"	buttons	do just	what they imply.


7.1.3 Defining the output file

     The default parameters for	the output file	(grid size, projection,	etc) are
taken from the first file read in.  You	should always review these parameters
before making your output file.	 It will often be necessary to change these
values.

     The number	of rows, columns, and levels for the output file is specified by
the type-in fields on the main window labeld "Rows", "Columns" and "Max	Levels".
Type in	new values if the defaults are incorrect.

     The map projection	for the	output file can	be viewed and changed by
clicking on the	"Map projection..." button.  In	this pop-up window you'll be
able to	choose a map projection	type then enter	the specific projection
parameters.  There is also a "Guess" button which will attempt to find a
reasonable output projection given the currently selected grid list.  It's often
helpful	to have	the "Select by Projection" pop-up window on-screen to compare
the output projection to the input projections.

     The vertical coordinate system for	the output file	can be viewed and
changed	by clicking on the "Vertical Coord System..." button.  In this pop-up
window you'll be able to choose	a vertical coordinate system type and enter the
specific parameters.  This window also has a "Guess" button to try to find a
reasonable default.  Similarly,	it's often helpful to have the "Select by VCS"
pop-up window on-screen	to compare the output VCS to the input VCSs.


7.1.4 Making the output	file

     Enter a filename for the output file in the type-in field at the bottom of
the main window	then click on "Make".  Messages	will be	printed	as the file
conversion takes place.	 If there are any errors the process will halt.	 Note
that generating	the output file	can be time-consuming if data must be resampled
from the input grid's coordinate system	to a new coordinate system for the
output file.

     If	you click on "Visualize" this will make	the file and then automatically
start up Vis5D on that file (i.e., you don't need to click on "Make" first).  If
you type a filename in the type-in field, it wil use that name.	 Otherwise, it
will use your login name followed by ".v5d".  If you want command line options
on the Vis5D command, put them in a file named "vis5d_options".	 For example, "-
mbs 64".


7.1.5 Miscellaneous

An options window is available by clicking on the "Options..." button.

     The first item controls the "combining of co-located data".  It may be the
case that several 3-D grids, selected for output, are co-located in space and
time.  When computing the value	to put in the output file you can either choose
the data value from the	higher resolution grid at that location, or take the
average	of all grid values at that grid	location.

     The second	item controls how grid data is compressed in the output	file.
By default, grid values	are scaled down	to 1-byte integers.  Alternately, you
can scale down to 2-byte integers for better resolution, or perform no
compression/scaling by selecting 4-byte	floating point values.	This option
respresents a tradeoff in file size and	precision.


7.2 The	v5dimport User Interface Embedded in Vis5D

     In	Vis5d version 5.1 v5dimport has	been incorporated into the main	control
panel and is invoked by	pressing the 'IMPORT' button.  This version of v5dimport
is the same as the one mentioned above except that you can load	the newly
created	v5d file without exiting from the program.  When the 'Make' button is
pressed	it will	create the file	and name it using the field 'File name:'.  If
there is a name	in the field 'Context name:' the file will be loaded into Vis5d
and attached to	the first display.  A number must also be entered into the 'MBS'
field to specify the amout of memory to	allocate for the data set.  A filename
must always be entered to use for disk backup for caching grids.


7.3 Using v5dimport's text interface

     The text/type-in interface	to v5dimport is	useful when X is not availableor
when you want to run v5dimport with a script.  To start	v5dimport in text mode
enter:

     v5dimport -t [-path pathname] [files]

where [files] is an optional list of input files and [-path pathname] specifies
that the directory named "pathname" is to be used as the default, in place of
the current directory, for the input file browser and for making output	files.
Through	the text interface it's	possible to run	v5dimport with a script	by using
your shell's import redirection	feature:

     v5dimport -t <script

After you've invoked v5dimport with the	-t option you'll see a >> prompt at
which you can issue any	of these commands:

     exit   exit v5dimport
     help   online help
     list   show lists of grids, timesteps, variables, map projections,	or
	    vertical coordinate	systems.
     read   read an input file
     keep/omit	 used to select	which grids, according to timestep, variable,
	    map	projection or vcs, are to be included in or omitted from the
	    output file.
     info   display parameters of output file
     rows   specify number of grid rows	for output file
     columnsspecify number of grid columns for output file
     levels specify max	number of grid levels for output file
     projection	 specify the output file's map projection
     vertical	 specify the output file's vertical coordinate system
     make   make the output file
     visualize	 make the output file and start	Vis5D

Using the text interface to v5dimport is similar in strategy to	the graphical
interface:
     1.	Read input files
     2.	Select grids by	timestep, variable, projection,	and/or VCS.  This is
       typically done by a series of list, omit, and keep commands.
     3.	Set/adjust output file parameters. Typically a series of info, rows,
       columns,	levels,	projection, and	vertical commands.
     4.	Make the output	file, or make the output file and start	Vis5D.

Use the	help command to	learn the exact	syntax for each	command.

A v5dimport script is simply an	ASCII file of v5dimport	commands and their
arguments.  In the simplest case it may	contain	only a few commands such as:

     # read my file, omit two vars, write v5d file
     read mydata.dat
     omit var CW
     omit var RW
     make outdata.v5d
     exit

As v5dimport executes a	script it prints each command and its result.  Lines
which start with a # are considered comments and ignored.


7.4 Adding support for new file	format

     v5dimport was written so that adding code to read new file	formats	should
be easy.  The source code for v5dimport	is in the import/ subdirectory.	 Look
for the	comment	/*** ADD NEW FORMATS HERE ***/ to see where code has to	be added
to support a new file format.

     Basically,	you need to write two new functions.  One which	scans your file
format to build	a list of grid_info structs.  The other	reads the actual grid
data from your file given a grid_info struct.  These functions should be put in
a new file named read_foo.c where foo is the name of your file format.	Then,
update the file.c file to use your functions.  Use the existing	read_*.c files
as a guide.


7.5 Notes on specific file formats

     The symbol	EPA is defined on the cc command line with -DEPA only on systems
which can read EPA files.  Currently, only Cray	systems	can read EPA files
because	the EPA-provided file reading functions	only work on Cray computers.

     The symbol	MCIDAS is defined on the cc command line with -DMCIDAS only on
systems	which can use the libmcidas.a file.  Only SGI's	in 32-bit mode are
supported now.



8. SAMPLE DATA SETS

To demonstrate or experiment with Vis5D	we provide two sample datasets.


8.1  Bob Schlesinger's thunderstorm simulation

To visualize the Schlensinger thunderstorm file	enter the command

     vis5d SCHL.v5d

To view	an isosurface of QL (moisture content):

     1.	Click on the QL	button in the left column of the button	matrix.
     2.	On the slider, select a	value near 1.0,	then click on the OK button.
     3.	Turn on	animation with the ANIMATE button.

To view	a vertical contour line	slice of QL:

     1.	Turn off animation by clicking on ANIMATE again.
     2.	Click on the QL	button in the third column.
     3.	Move the slice by first	selecting the SLICE radio button.  Then	use the
	right mouse button to drag any corner of the slice along the edges of
	the 3-D	box.


8.2  LAMPS model

To visualize a LAMPS (Limited Area Meso-Scale Prediction System) model
simulation of an extratropical cyclone,	enter the command:

     vis5d LAMPS.v5d

To view	an isosurface of wind speed over a topography with map lines:

     1.	Click on the TOPO and MAP buttons.
     2.	Click on the SPD button	in the first column.  Then select a value near
	45.0 on	the slider and click on	OK.
     3.	Turn on	ANIMATE	and you	will see an animation of the 45	m/s wind
	isosurface.

To make	some interactive wind trajectories:

     1.	Turn off the wind speed	isosurface by clicking on the SPD button again
     2.	Select the TRAJECTORY button.
     3.	Move the mouse pointer into the	3-D window and press the middle	mouse
	button.	 You will get a	series of white	wind trajectory	lines passing
	through	the 3-D	cursor location.
     4.	Move the 3-D cursor by dragging	it with	the right mouse	button then
	click the middle button	to make	more trajectories.
     5.	Select RIBBON and then the SET 2 button	and try	making some yellow
	ribbon trajectories.


8.3  Example McIDAS files and utilities

     The Schlesinger and LAMPS data sets are also available as the 3D McIDAS
grid files named GR3D0001 and GR3D0002.	 They are available on the Vis5D ftp
site.  See section 2 for more information.

To list	the grids in GR3D0001 and to see statistics about them,	enter the
commands:

     igg3d list	1 190 -gr3df 1
     igg3d info	1 190 -gr3df 1

The SCHL.v5d file was made from	the GR3D0001 file with the command:

     gr3d_to_v5d 1 1 SCHL.v5d


To list	the grids in GR3D0002 and to see statistics about them,	enter the
commands:

     igg3d list	1 189 -gr3df 2
     igg3d info	1 189 -gr3df 2

The LAMPS.v5d file was made from the GR3D0002 file with	the command:

     gr3d_to_v5d 2 1 LAMPS.v5d

A variety of other sample datasets are available on the	ftp site or upon
request.



9. VERSION HISTORY

This is	a summary of the versions of Vis5D.

1.0  (December 1988)
     This was the original version of Vis5D for	the Stellar GS-1000.  It was
     used to give demonstrations at the	ECMWF in December 1988 and at the AMS
     conference	in Anahiem in January 1989.  It	had the	following features:
	  Depict time series of	multivariate 3-D grids by animated isosurfaces
	       and horizontal contour line slices.
	  World	topography map with map	boundaries.
	  Wind trajectory tracing with the traj5d program.

2.0  (Fall 1991)
     This version was only available for the Stellar GS-1000/2000 and introduced
     the following features:

	  Faster isosurface generation.
	  Horizontal and vertical slices moved interactively with the mouse.
	  Colored slices.
	  Interactive wind trajectory creation.
	  Ribbon trajectories.
	  Label	/ text annotations.
	  "Pretty" rendering option.

     The format	of the compressed grid file was	changed	slightly with version
     2.0.  Specifically, the trajectory	files of version 1.0 were eliminated,
     trajectories are now stored in the	compressed grid	file itself.  Also, the
     internal storage representation for surfaces and slices has been changed.

2.1  (February 1992)
     This is the first version of Vis5D	available for the SGI and IBM
     workstations.  It was also	modified to use	less memory during isosurface
     generation.

2.2  (April 1992)
     This version of Vis5D runs	on the base SGI	Indigo with 8-bit color	though
     some features not available.  It also has the following improvements:

	  The -box option for changing the proportions of the 3-D box (SGI and
	       Stardent	only).
	  User topography files.  Vis5D	now uses the EARTH.TOPO	file instead of
	       TOPOHRES	to make	the map.  The maketopo.c program shows how to
	       make new	.TOPO files.  (SGI and Stardent	only)

3.0  (August 1992)
     This version features the following improvements:
	  Horizontal and vertical wind vector slices.
	  Improved SAVE	and RESTORE functionality.
	  New trajectory widget	options.
	  Separate map and topography controls.
	  CLONE	option added.
	  Simultaneous colored and contour line	slices.
	  Improved transparency, PRETTY	option on SGI.
	  Same source code for SGI, Stardent, and IBM.
	  Improved portability and porting guide added.
	  New video and	hardcopy convenience features.

3.1  (July 1993)
     New features:
	  User-written analysis	functions.
	  SAVE PIC button to save window image to a file.
	  Perspective viewing mode.
	  New contour line options to draw dashed negative lines and restrict
	       contouring to a specific	range of values.
	  Data Probe mode.
	  Topography color editing.
	  Grid compression done	layer-by-layer.

3.2  (August 1993)
     New features and changes:
	  Volumetric rendering on SGI systems with VGX,	VGXT, VTX, RE, or RE2
	       graphics	hardware.
	  User-contributed software directory.
	  2-D contour function rewritten in C.

3.3  (January 1994)
     New features:
	  Vis5D	ported to HP, DEC, Sun,	and Kubota (DEC	Alpha) workstations.
	       The most	important part of this work was	the enhancement	and
	       integration of the VOGL library.	 This work was done by Simon
	       Baas and	Hans de	Jong for the Dutch Meteorological Institute,
	       KNMI.  Porting to the Kubota Denali graphics system was done by
	       Pratish Shah of Kubota Inc.  Thanks guys!
	  -wdpy	option now creates a window on the widget display which	can be
	       used to move and	interact with the 3-D view using the widget
	       display's mouse.
	  SAVEPIC button let's you save	the window image in PostScript or color
	       PostScript formats (SGI only).
	  -wind2 option	added to specify a second set of U,V,W variables for the
	       second set of wind vector slices.
	  -texture option added	for a texture mapping an image onto the
	       topography (SGI only).
	  user functions are computed faster on	SGI multi-processor systems by
	       computing time steps in parallel.

4.0  (December 1994)
     New features:
	  Map projections and new vertical coordinate systems.
	  Type-in formulas for computing new variables.
	  Time sequences of satellite images can be texture mapped onto	the
	       topography for visual comparison	with model data.
	  Data may be displayed	over a spherical Earth.
	  File caching:	 compressed grid files which are too large to read into
	       memory in their entirety	are read in piece-by-piece as needed, a
	       least-recently-used replacement policy is used to purge data when
	       memory is full.
	  New compressed grid format.  New format allows new header information
	       to be added in the future, currently stores additional projection
	       information.  Also allows control of data compression.
	  New command line options:  -geometry,	-trajvars, -projection,
	       -vertical, -area, -sequence
	  External functions can query the probe position and values with
	       PROBEPOS	and PROBEVAL functions.
	  Interactive control over animation rate (using F and S keys)
	  When the "GRID #'s" button is	turned on, the probe/trajectory	cursor
	       snaps to	discrete grid points.
	  New utilities	for .v5d files:	 v5dinfo, v5dstats, v5dedit,
	       comp_to_v5d, and	gr3d_to_v5d.

4.1  (May 1995)
     New features:
	  Rotated map projection.
	  Improved widgets.
	  Stored-frame animation.
	  Better 3-D rendering in software using Mesa instead of VOGL.
	  Vis5D	files defined as a World Wide Web medium for exchanging	model
	       output.

4.2  (April 1996)
     New features:
	  Wind streamlines.
	  Colored isosurfaces and trajectories.
	  Scripting with Tcl.
	  UVW variable widget.
	  Pressure vertical coordinate system.
	  programmer's API between Vis5D and its user interface.
	  v5dSetLowLev function	allows fields to occupy	any sub-interval of
	       vertical	levels.
	  physical units can be	specified for each variable in a v5d file.
	  v5dimport program.

4.3  (April 1997)
     New features:
	  Vertical sounding window.

5.0  (July 1998)
     New features:
	  Display multiple v5d datasets	in one window.
	  Display multiple v5d datasets	side-by-side in	multiple windows.
	  Link user interface controls in 'groups' of windows.
	  Type-in formulas can combine fields from multiple data sets.
	  Open or create new datasets during a Vis5D session (v5dimport	embedded
	       in Vis5D).

5.1  (March 1999)
     Major New Features:
        Slice Linking - slices can be linked together so that the status and
          movement of all the slices in the link are synchronized.  Horizontal
          slices can not be linked with vertical slices.
        Probe Var Selection - the number and type of variables can be
          controlled when using the probe.  Useful for data sets with many variables.
        Transparency in Legends - the legends now reflect the transparency of
          the color map.
        User Data - user specified formats can be used in loading grid data,
          topography data, and map data.
        Surface Graphics - horiz. contour slices, horiz. Wind slices, horiz.
          Stream lines slices, and the map can now be resampled
          to the topography and displayed on top of the topography.
        Horz. Slice Sliders - GUI sliders have been added to control the level
          at which slices are displayed.
        Changing Map Height - a user can select the level at which the map is
          displayed at.  A GUI slider has been added to control this.
        Volume Rendering for PEX
        New Sounding Features - the look of the sounding has changed.
          Temperature lines can be displayed.  The sounding data is also clipped
          at the level of the topograpy.
        TopoBase - a solid base can extend below the topography.
        Animation Dwell - a pause can be inserted between timestep=Numtimes
          and timestep= 0.
        Time Derivatives - the 'time' command can be used in the formula for
          creating  new variables.
        More Formats in Saving Pictures - when ImageMagicks's convert program
          is installed more formats are accepted, and better save quality.
        Probe and Trajectory Can Be Coupled
        Offscreen Rendering