VIS5D.TXT
Remove Frame
VIS-5D VERSION 3.3
1. OVERVIEW OF VIS-5D
VIS-5D is a software system for visualizing data made by
numerical weather models and similar sources. VIS-5D works on
data in the form of a five-dimensional rectangle. That is, the
data are real numbers at each point of a "grid" or "lattice"
which spans three space dimensions, one time dimension and a
dimension for enumerating multiple physical variables. Of
course, VIS-5D works perfectly well on data sets with only one
variable or one time step (i.e. no time dynamics). However, your
data should have some depth in all three spatial dimensions.
The VIS-5D 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 VIS-5D
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.
VIS-5D 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, 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 VIS-5D to HP
workstations. Pratish Shah of Kubota Inc. ported VIS-5D to the
Kubota Alpha/Denali workstation.
VIS-5D 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 VIS-5D system, but we would
be interested in hearing about your questions and problems.
Also, if you would like to be added to the VIS-5D mailing list,
send email to:
Bill Hibbard (email: [email protected]) or
Brian Paul (email: [email protected]) at:
Space Science and Engineering Center
University of Wisconsin - Madison
1225 West Dayton Street
Madison, WI 53706
This document was written to make it easier for you to use
VIS-5D. The next section tells you how to install VIS-5D on your
system. Section 3 gives you a sample data conversion program and
tells you how to modify it to convert your data into the VIS-5D
file structures. Section 4 describes how to prepare your data
for visualizing using the VIS-5D analysis programs. Section 5
describes how to visualize your data using the vis5d program.
Section 6 leads you through using VIS-5D on the two sample data
sets included on the tape. Section 7 tells you something about
writing your own analysis programs that fit into the VIS-5D
structure. Section 8 is a history of the versions of VIS-5D.
The last section has a few words about the relation of VIS-5D to
our much larger McIDAS system.
2.1 SYSTEM REQUIREMENTS
VIS-5D currently works with the following systems:
1. Silicon Graphics workstations:
32MB RAM
24-bit color and Z-buffer (or 8-bit Indigo)
IRIX version 4.0.1 or higher.
Multiple processors are used when present.
2. IBM RS/6000 workstations*:
32MB RAM
Model 320H or higher
AIX version 3 or later is suggested.
8 or 24-bit color display
A 3-D graphics accelerator such as the GTO is
recommended but not required.
3. HP series 7000 or 9000 workstations*:
32MB RAM
8 or 24-bit color display
HP-UX A.09.01 or later
4. Sun Sparc workstations*:
32MB RAM
8 or 24-bit color display
SunOS Release 4.1.x or later
5. DECstation workstations*:
32MB RAM
8 or 24-bit color display
ULTRIX V4.2 or later
6. Kubota / DEC Alpha 3000 workstations:
32MB RAM
Denali Graphics
OSF/1 V1.3 or higher
KWS V1.3.3 or higher
NPGL Run-time license
7. Stardent GS-1000 or GS-2000 workstations:
32MB RAM
True-color display (i.e. 32 planes).
Optional SpaceBall is supported.
Stellix version 2.3 or later is suggested.
*Note: for these workstations, VIS-5D does all 3-D rendering
using a modified version of the VOGL library using X Windows.
Because of this, rendering is rather slow. We would like to
encourage anyone with one of these workstations having 3-D
graphics hardware to modify VIS-5D to utilize that hardware.
If you would like to port VIS-5D 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 VIS-5D
VIS-5D is obtained via anonymous ftp. If you don't have
Internet access, you can obtain VIS-5D on tape by sending us a
blank tape and a note explaining what you need.
Here are the installation instructions:
1. Go to the directory in which you want VIS-5D installed:
% cd /usr/mydir
NOTE: The installation of VIS-5D will result in a new
subdirectory named "vis5d-3.3/" 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 VIS-5D 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 id as the password:
Name: anonymous
Password: myname@mylocation
4. Go to the pub/vis5d directory:
ftp> cd pub/vis5d
5. Transfer files in binary mode:
ftp> binary
6. Get the VIS-5D archive file:
ftp> get vis5d-3.3.tar.Z
7. Get optional files:
NOTE: The GR3D0001 and GR3D0002 files are sample
McIDAS grid files. You will only need them if you want
to work through the examples using igg3d, igu3d, and
comp5d:
ftp> get GR3D0001 [optional]
ftp> get GR3D0002 [optional]
8. Exit ftp:
ftp> bye
9. Uncompress and un-tar the archive file:
% uncompress vis5d-3.3.tar.Z
% tar -xvf vis5d-3.3.tar
10. Change to the newly created vis5d directory:
% cd vis5d-3.3
11. Run make:
% make
Make will print a list of systems supported for VIS-5D.
Look for yours on the list and type the appropriate
make command. For example, suppose you have an IBM
RS/6000 without 3-D graphics hardware. You should
type:
% make ibm-x
VIS-5D 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. Repeat steps 1 through 5 as above.
b. Then get the archive of executable files for your
system:
ftp> get vis5d.xxx.bin.tar.Z
where xxx is one of the system configuration options
listed previously by 'make'.
c. Exit ftp:
ftp> bye
d. Uncompress and un-tar the archive:
% uncompress vis5d.xxx.bin.tar.Z
% tar -xvf vis5d.xx.bin.tar.Z
12. Test VIS-5D:
% ./vis5d COMPLAMP
NOTE: To quit, click on the "EXIT" widget button.
13. You may delete the .tar files if desired.
2.3 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. If you want to specify a different default topography
or map file, you can edit src/vis5d.h and change the
values for TOPOFILE and/or MAPFILE.
When finished changing the src/vis5d.h file you must re-make
the system by repeating installation step 11 above.
2.4 ORGANIZATION
When you are finished installing VIS-5D you should have a
directory named "vis5d" which contains the following:
1. The VIS-5D program: vis5d
2. Utility programs: comp5d, compinfo, gg3d, igg3d, igu3d,
help, and listfonts [SGI only]
3. Sample data sets: COMPLAMP, COMPSCHL
4. Map outline files: OUTLHRES, OUTLSUPW, OUTLUSAL, and
OUTLUSAM
5. Earth topography file: EARTH.TOPO
6. The VIS-5D documentation (this file): README
7. The GNU general public license file: NOTICE
8. Hints on porting VIS-5D: PORTING
9. The vis5d source code directory: src/
10. The user interface source directory: lui2/
11. The utilities source directory: util/
12. User analysis functions directory with examples:
userfuncs/
13. The user contributed software directory: contrib/
14. The VOGL GL-like library: vogl/
15. Optionally, sample McIDAS grids: GR3D0001, GR3D0002
3. PUTTING YOUR DATA INTO VIS-5D FILES
A data set for VIS-5D has a real number at each point in a
five-dimensional grid. These data are organized into a series of
three-dimensional spatial grids whose dimensions are latitude,
longitude and height (i.e. altitude). 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 data are stored in our 3D grid files. A 3D grid file
is identified with an integer between 1 and 9999, and contains a
sequence of 3D grids, which are also identified by integers. 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 represented by five digit decimal integers
YYDDD where YY are the last two digits of the year and DDD is the
three digit day within the year, so February 4, 1988 is 88035.
Times are represented by six digit decimal integers HHMMSS where
HH are the hour, MM are the minute, and SS are the second, so 2
AM is 020000.
The following sample program creates a 3D grid file and
fills its 3D grids with data for a five-dimensional data set. It
is repeated in the file sample.F, with make file 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, VIS-5D
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.
VIS-5D 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 VIS-5D 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 VIS-5D 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.
To make your own topography files for use with the -topo
option there is a maketopo.c program in the vis5d/src/ directory.
It explains the format of the file and shows how to create such
files.
4. MANAGING AND ANALYZING YOUR DATA
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.
Before you can visualize your data set, you must convert it
to a compressed file structure using the command:
comp5d N M F
where 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. F 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
The 'compinfo' program is used to get information about a
compressed grid file made by comp5d. For example:
compinfo COMPLAMP
will print information about the COMPLAMP file including the grid
dimensions, number of time steps, number of variables, etc.
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.
VIS-5D 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. Use the UNIX
command:
rm GR3Dnnnn
to delete a 3D grid file.
The help command will list a quick reference to the
parameter formats for the VIS-5D utility commands. Just enter:
help NAME
where NAME is the name of the command such as igg3d, igu3d, or
comp5d.
5.1 USING VIS-5D TO VISUALIZE YOUR DATA
This section describes how to use the VIS-5D 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
within from the program.
After you have used comp5d to produce a compressed file, you
can interactively visualize your data set with the command:
vis5d file [options]
where 'file' is the file name of the compressed file (made with
comp5d) which you want to visualize. A number of options are
available (none are usually needed):
-alpha
[SGI only] Use alpha blending instead of "screen door"
transparency.
-box x y z
This lets you specify the aspect ratio or proportions
of the 3-D box. Default values are 2 2 1.
-font xfont
[Stardent] Sets the font used in the 3-D window. Use
the xlsfonts command to see a list of X fonts on your
system.
Example: vis5d COMPLAMP -font fg-30
-font glfont height
[SGI] Sets the font used in the 3-D window. Use the
listfonts command included with VIS-5D to see a list of
GL fonts on your system. The height argument is the
font height in points where 72 points = 1 inch.
Example: vis5d COMPLAMP -font Helvetica 30
[IBM] Not supported.
-full
Open the 3-D window as a borderless, full-screen size
window.
-map file
Use a map file other than the default of OUTLSUPW. See
section 2.3 to setup a different default.
Example: vis5d COMPLAMP -map OUTLUSAL
-mbs n
Override the assumed system memory size of 64
megabytes. See section 2.3 to setup a different
default value.
-rate ms
Change the default animation rate. ms is the minimum
delay in milliseconds between frames. Default is 100
ms.
-texture rgbfile
Specify an SGI .rgb file to texture map over the
topography. [SGI only]
-topo file
Use a topography file other than the default of
EARTH.TOPO. See section 2.3 to setup a different
default.
-wdpy xdisplay
Put the widgets on a different X display. Useful in
combination with -full for making slides and videos.
Example: vis5d COMPLAMP -full -wdpy pluto:0
-wide w
Set width of line segments in pixels (default is 1.0).
Again, useful for making videos.
Example: vis5d COMPLAMP -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 H-WIND 2 and V-WIND 2 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
If you type 'vis5d' without arguments you will get a list of
available options.
When you start vis5d it loads your data set and then opens a
3-D window on the right and a control panel on the left of the
screen. The 3-D window is used to view and interact with the
data. In its upper-left corner is a combination analog/digital
clock which indicates the current time step. The control panel
contains several groups of buttons.
The first button group contains the following buttons:
[ANIMATE] [STEP] NEW VAR EXIT
NEW SURF TOP SOUTH WEST
[TOPO] [MAP] BOX CLOCK
SAVE RESTORE GRID #'s CONT #'s
[PRETTY] REVERSE [SAVE PIC] [PERSPEC]
These buttons are used to toggle, activate, or control
various functions as described below. 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 are used to determine how
the mouse behaves 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 5.3.
Trajectory - This mode is used for creating and displaying
wind trajectories. See section 5.7.
Slice - This mode is used to reposition horizontal
and vertical slices. See section 5.5.
Label - This mode is used to create and edit text
labels in the 3-D window. See section 5.8.
Probe - Used to inspect individual grid values by
moving a 3-D cursor through the 3-D grid.
See section 5.9.
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, if your data set contains U, V, and W wind component
variables there will be a row of four wind slice buttons:
H-WIND 1 V-WIND 1 H-WIND 2 V-WIND 2
A wind slice depicts the motions of the wind by drawing
small arrows which point in the direction of the wind. The
length of each line segment indicates it's magnitude. The tails
of the line segments are all anchored within a horizontal or
vertical plane through the 3-D box. The location of the slice
plane can be changed with the mouse while in "Slice" mode. See
section 5.5 for more details.
The remaining set of widget buttons is used to control the
display of 3-D isosurfaces, horizontal contour slices, vertical
contour slices, horizontal colored slices, vertical colored
slices, and volume renderings of your data. The buttons are
arranged in a matrix. Each row corresponds to a physical
variable in your data set. Each column corresponds to one type
of graphic listed above.
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 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.
5.2 VIS-5D CONTROL BUTTONS
The following is a description of each button in this group.
Some of them will be described in more detail later in this
document.
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.
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 5.10.
EXIT Exit the program. A verification window will
appear to ask you to verify your decision.
NEW SURF Computes a new 3-D contour surface.
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.
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. Click on SAVE with left mouse
button to save all graphics and colors. Click on
SAVE with the right mouse button to just save all
colors.
RESTORE Restore the data last saved with the SAVE button.
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.
PRETTY Toggle the 'pretty' rendering option on or off.
When turned on the 3-D graphics will be rendered
using whatever high quality options are available
on your system:
Stellar: isosurfaces are antialiased and
rendered with improved transparency.
SGI: antialiasing is done on systems with an
accumulation buffer.
Others: Pretty rendering is not supported on
other systems
When PRETTY is turned on, your mouse pointer will
turn into a "busy" symbol. Pretty rendering is
slow and may take over minute to render a single
image. It should normally be turned off. This is
used when making slides or printouts.
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 used with the xwd(1) program
when making print outs.
SAVE PIC Used to save the image in the 3-D window to a
file.
PERSPEC Toggle between perspective and orthogonal viewing
projections.
5.3 NORMAL VIEWING MODE
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.
5.4 3-D CONTOUR SURFACES
A 3-D contour surface (isosurface) 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 iso-level. The volume outside contains values
less (or greater) than the iso-level.
The display of 3-D isosurfaces is controlled with the first
column of buttons in the button matrix in the control panel.
Clicking on one of these buttons with the left mouse button
causes a small window with a slider widget to appear below. It
is used to select iso-level values for contour surfaces. The
slider window displays the variable name and the range of values
for that variable. The slider value is initially set to the
minimum of the range. You can select an iso-level by placing the
cursor on the slider, holding any mouse button down, and moving
the cursor right or left. When you have the iso-level value you
want, click on the 'NEW SURF' widget button above. This will
cause iso-level contour surfaces to be generated for the selected
physical variable for each time step.
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. If you use a slider and the NEW SURF widget to
change the value of iso-level contour surfaces, the animation may
show a combination of new and old valued surfaces while the
system calculates the new surfaces.
Clicking on an isosurface widget button with the middle
mouse button will summon a variable's iso-level slider without
turning the surface on or off.
To change the color of an isosurface, click on the
appropriate isosurface widget with the right mouse button. A
window will appear with four sliders labeled red, green, blue,
and transparency. The color of the isosurface is a mixture of
red, green and blue components. By changing the mixture with the
sliders, any color can be made. The transparency value slides
between 0.0 for invisible and 1.0 for opaque. On SGI and IBM
systems, "screen-door" transparency is used by default and only
four levels of transparency are available. On the Stellar and
SGI VGX, VGXT, VTX, or RE using the -alpha option, alpha blending
is used. Neither method is perfect and may produce unexpected
artifacts under certain conditions.
5.5 CONTOUR, COLOR, AND WIND 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,
or wind vectors.
As described in section 5.1, the last group of buttons on
the control panel form a matrix of buttons, the four right-most
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 5.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.
When a slice is turned on, a small control window will
appear as well. The function of the control window depends on
the type of slice:
Contour slice: the control window contains a type-in widget
used to specify the interval between contour lines. To
enter a new value, first point at the value with the
mouse. The field will blank to white. You can now
type in a new value and press RETURN. If you don't
press RETURN the old value will be restored when you
move the mouse pointer away. The BACKSPACE key can be
used to correct typing mistakes. 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)" (without quotes).
This will result in contour lines for values between
-30 and 20 at intervals of 10 with negative lines drawn
as dashed lines.
Color slice: the control window contains a 3-function graph
which maps data values to colors. 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.
If you need to restore the default mapping, press 'r'
while the mouse pointer is in the window.
Instead of using the mouse to draw a new function 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.
Wind vector slice: the control window contains two type-in
widgets to control the scale and density of 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.
As with 3-D surfaces, the middle mouse button can be used to
toggle the control window without changing the slice's on/off
status.
To match a slice to its respective widget button, look at
the colors:
Contour line and wind vector slices: the color of the
widget button is the same as the slice color. To
change the color, select the widget button using the
right mouse button. A window with four sliders: red,
green, blue, and transparency will appear. By changing
the amount of red, green, and blue you can make any
color. The transparency slider has no effect.
Colored slices: the color of the widget button is the same
as the slice's position label. To change the color,
click on the appropriate widget button using the right
mouse button. Use the red, green, and blue sliders as
previously described.
5.6 VOLUME RENDERING
If you are running VIS-5D on an SGI workstation with a VGX,
VGXT, VTX, RE or RE2 graphics system or a Kubota/Denali system
you can make volumetric renderings of the variables in your
dataset. In this case there will be a sixth column of buttons
will be present in the main button matrix. To get a volume
rendering of any variable just click on that variable's button in
the sixth column using the left mouse button. Note that only one
volume rendering can be viewed at a time.
You can change the mapping of data values to colors and
opacity with the color window which appears when the volume is
first displayed. As with colored slices (described above), you
can change the mapping by "drawing" them with the mouse. Use the
left mouse button to modify red, middle mouse button to modify
green and the right button to modify blue. The fourth curve,
which is drawn in white, controls opacity. Hold down any of the
<shift>, <control> or <alt> keys with any mouse button to change
the opacity curve. High values are opaque and low values are
transparent. Also, you can use the cursor keys to modify the
curves. Holding down any of the <shift>, <control> or <alt> keys
causes the cursor keys to modify the opacity curve.
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 by
the graphics hardware to make smooth transitions between
and within slices.
Note that the volume rendering is completely recomputed
whenever a different variable is selected, animation is turned
on, or when the 3-D box is rotated to a new orientation.
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, none are fast enough to
support interactive visualization as needed in VIS-5D.
5.7 WIND TRAJECTORIES
If your data set contains U, V, and W wind component
variables, you can create 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 window titled
"Interactive Wind Trajectories" 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 5.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. Change the color of a trajectory set by clicking on the
corresponding trajectory set button with the right mouse
button. A color selection window will appear on the
left of your screen. By adjusting the red, green, and
blue sliders, you can change the trajectory set's color.
7. A trajectory set may be deleted with the 'Delete Set'
button in the trajectories window. You will asked to
verify your decision.
8. You can delete the last trajectory made by clicking on
the 'Delete Last' button in the trajectories window.
The ability to make individual sets of trajectories can used
to group them according to position or time criteria.
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 but
rather 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. 100 is the
default. The LENGTH value is used to control the length of
trajectories. It is simply a scaling value which multiplies the
length of the trajectory. For example, to double the length of
new trajectories enter a value of 2, to triple the length enter
3.
5.8 TEXT LABELS
Text labels are used to annotate the image in the 3-D
viewing window. Typically this is used as the final step before
presenting the output. 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' option to select a different font.
5.9 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 mode 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.
5.10 MAKING NEW VARIABLES
The NEW VAR button on the control panel is used to add new
physical variables in vis5d. There are two 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 the existing ones.
When you click on the NEW VAR button a window appears which
lists the variables which you can clone and external functions
which you can invoke. After you select one, a new row of buttons
will be added to the control panel for the new variable. You can
use then make isosurfaces, contour slices, etc. of the that
variable.
5.10.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.
5.10.2 EXTERNAL ANALYSIS FUNCTIONS
An external analysis function is a function written by you
in FORTRAN which is called by VIS-5D 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 VIS-5D users who are also
proficient FORTRAN programmers.
All external functions must be placed in a directory named
"userfuncs". 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:
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 3-D grids of data for each variable
5. the date and time of the time step
Your function will have to scan the list of variables to
find the ones it needs for the computation. Then it must do the
actual computation, generating a new grid of data. The examples
we've included demonstrate how to do this.
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 VIS-5D file. The
uncompressed McIDAS data is better because it has more precision.
In order for vis5d to find the McIDAS file, the compressed file
must have been made with the version 3.1 comp5d and the McIDAS
file must be in the current directory. 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.
5.11 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 widget 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.
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.
5.12 SPACEBALL SUPPORT
Version 2.1 and later of VIS-5D for the Stardent also
supports the SpaceBall made by Spatial Systems, Inc. If you have
a SpaceBall make sure the environment variable 'SPACEBALL' is
defined. This can be done by adding a line similar to 'setenv
SPACEBALL /dev/tty04' (make sure you use the correct tty number)
to your .cshrc file. If vis5d recognizes the SpaceBall it will
emit two short beeps upon startup. See your SpaceBall
documentation for more information about setup.
Twisting the SpaceBall causes an appropriate rotation of the
3-D box. Pressing the SpaceBall up, down, left, or right is
analogous to translation with the mouse. Pressing the SpaceBall
toward or away you causes the box to zoom in or out,
respectively. The SpaceBall function keys are defined as
follows:
(1) Top view (2) South View (3) West View (4) Unused
(5) Bottom View (6) North View (7) East View (8) Rezero
Ball
These assignments can be changed in the src/sb.c source file.
5.13 COMMON QUESTIONS (AND ANSWERS)
Q: Why doesn't the map and/or topography work for me?
A: If the "MAP" and "TOPO" buttons don't appear on the control
panel, the default files were not found. By default, vis5d looks
in the current directory for the OUTLSUPW and EARTH.TOPO iles.
Change the src/vis5d.h file to specify absolute path names or
copy the map and topography files to your current directory.
Q: How can I print the image in the window?
A: Just press P as mentioned in section 5.11. Also, if
available, you should first turn on the "PRETTY" button to get a
good quality image and select the "REVERSE" button. If you do
not have a color printer you should make all your VIS-5D colors
shades of gray to get a good idea of what results you can expect.
Alternatively, you can save the window image to a file and then
manipulate it with other programs before printing.
Q: How do I make photographic slides?
A: A 35mm camera on a tripod works good. First turn off all
lights in the room and close all window shades to prevent glare.
Setup your image and turn on "PRETTY" if available. Take several
pictures at various exposures to find the best setting for your
camera.
Q: How do I make videos?
A: First you'll need a scan converter to convert the RGB video
signal sent to your monitor into an NTSC (or PAL) signal which
can be recorded by any standard VCR. There is no scripting
language in VIS-5D so you must compose your video "on the fly"
and edit it later if you have two VCRs. You can even make video
titles with vis5d! Start vis5d with '-full' and a large font
with '-font', go into 'Label' mode, hide the control panel
window, and then make your titles.
Q: Does VIS-5D support non-uniform grid height spacing and/or
other map projections?
A. Wait for the next version of VIS-5D...
5.14 FINAL NOTES
The SGI and Stardent versions of VIS-5D are parallel
programs; after you select a new isosurface, move a slice, etc.
you are free to do other things such as rotate the box. The
other versions does not allow this; user input is blocked while
graphics are being computed. [A way to set up multiple threads
of execution within a process is required to solve this problem.]
For a large data set, generating isosurfaces or slices for all
the time steps may take a while.
VIS-5D uses a bounded memory management system to avoid
using more memory than what is available, thereby preventing
virtual memory thrashing which leads to poor performance. When
the memory limit is reached, the least recently displayed
graphics are deallocated. You can monitor the amount of memory
used by pressing the F2 key. If you try to read in a grid file
which will not fit into memory, or not leave enough working
memory free, you will get an error message saying so. A system
with 32MB of RAM can read with files of up to approximately 12.5
million data points, with a 128MB system you can visualize 50
million data points, etc.
When you save the current graphics and/or colors with the
SAVE button, the information is written to a file with the
extension ".SAVE". For example, if you do a SAVE while
visualizing the "COMPLAMP" data set, the save file will be named
"COMPLAMP.SAVE". This file can be rather large. When it's no
longer needed you can delete it.
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 VIS-5D there is a user-contributed
software directory: contrib/. See the README file in that
directory for a description of current contributions.
6. VISUALIZING AND ANALYZING THE SAMPLE DATA SETS
We have included two sample data sets. To visualize one of
Bob Schlesinger's thunderstorm simulations, enter the command:
vis5d COMPSCHL
Then 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
NEWSURF 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.
To visualize a LAMPS (Limited Area Meso-Scale Prediction System)
model simulation of an extratropical cyclone, enter the command:
vis5d COMPLAMP
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 NEWSURF.
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.
These data sets are also available in the form of 3D McIDAS
grid files name GR3D0001 and GR3D0002. See section 2 if you
don't have these files. To list the thunderstorm grids and to
see statistics about them, enter the commands:
igg3d list 1 190 -gr3df 1
igg3d info 1 190 -gr3df 1
The COMPSCHL compress file was made from the GR3D0001 file with
the command:
comp5d 1 1 COMPSCHL -wind spd u v w
To try out the compinfo program, type:
compinfo COMPSCHL
Then, as before, the data can be visualized with:
vis5d COMPSCHL
To list the LAMPS grids and to see statistics about them, enter
the commands:
igg3d list 1 189 -gr3df 2
igg3d info 1 189 -gr3df 2
The COMPLAMP compressed grid file was produced with the command:
comp5d 2 1 COMPLAMP -wind spd u v w
7. WRITING YOUR OWN DATA ANALYSIS PROGRAM
The source files igg3d.F and gg3d.F, in the src
subdirectory, are both good models for analysis programs. They
use the IGGT3D routine to read arrays from 3D grids, and the
IGPT3D routine to write arrays to 3D grids. Section 3 of this
document describes many of the routines in libmain.a which may be
useful for writing analysis programs.
8. VERSION HISTORY
This is a version history of VIS-5D.
1.0 (December 1988)
This was the original version of VIS-5D 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 VIS-5D 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 VIS-5D 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. VIS-5D 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:
VIS-5D 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.
9. VIS-5D AS A SUBSYSTEM OF McIDAS
VIS-5D is being distributed as a stand alone system free of
charge. However, it is also a subsystem of a much larger system
named McIDAS (Man-computer Interactive Data Access System).
McIDAS is a proprietary system of the Space Science and
Engineering Center which we have been developing for over twenty
years and which now includes about two million lines of FORTRAN.
McIDAS also includes lots of SSEC designed hardware for satellite
data acquisition, communications, and workstations. McIDAS can
ingest data from almost all weather satellites and many other
sources in real time, manage enormous data bases (our GOES
archive contains 100 trillion bytes), display that data, and
apply lots of source specific analyses to the data. As a
subsystem of McIDAS, VIS-5D needs to be consistent with its
structures. This may make VIS-5D seem a little odd as a stand
alone system. McIDAS is evolving to be sure, but a system so
large changes slowly. As recently as 1980 the source code for
McIDAS resided on several tons of punch cards, and it has come a
long way since then.
