Encyclopedia of Graphics File Formats Companion/GFF_CD.ISO/formats/vis5d/spec/howtoget.txt

Text File | 1994-06-21 | 17.0 KB | 458 lines

VIS5D

This following, extracted from a letter from Bill Hibbard to O'Reilly
& Associates, sums up the situation with VIS5D:

   We do not have a neatly worded file spec for the VIS-5D input
   files, since we do not intend that anyone write software to create
   those files.  Rather, we supply source code (in both C and Fortran)
   for a program that writes our file format, plus documentation to help
   our users to modify this program to add logic for reading their own
   file formats.  That is, this is a do-it-yourself file format
   conversion program.

   I have included below the information about getting VIS-5D by anonymous
   ftp, plus Section 3 of our README file, that includes the source code
   and documentation for our do-it-yourself file format conversion program.

--------------- how to get VIS-5D by anonymous ftp --------------------

VIS-5D version 3.1

VIS-5D is a system for interactive visualization of 5-D gridded data
sets such as those made by numeric weather models.  One can make
isosurfaces, contour line slices, colored slices, wind vector slices,
wind trajectories, etc. of data in a 3-D grid and then rotate and animate
the image in realtime.  There are also features for text annotation and
video production.

Distributed under the terms of the GNU General Public License as published
by the Free Software Foundation.  Development funded by NASA.

Hardware requirements:
Silicon Graphics:
IRIS with VGX, GTX, TG, or G graphics
SGI Crimson or Indigo
32MB RAM suggested
IRIX 4.0.x
IBM RS/6000:
3-D graphics hardware with GL
32MB RAM suggested
AIX version 3 or later
Stardent/Stellar:
GS-1000 or GS-2000
TrueColor display
32MB RAM suggested

How to get it:
% ftp iris.ssec.wisc.edu
or
% ftp 144.92.108.63

login: anonymous
password: myname@location

ftp> cd pub/vis5d
ftp> ascii
ftp> get README
ftp> bye

See section 2 of the README file for complete system requirements
        and installation instructions.

Includes:
Complete source code for visualization program and utilities
2 sample data sets
Sample conversion program to put your data into VIS-5D format
Documentation and porting guide
Executable files are also available

Contact:
        Bill Hibbard ([e-mail])
        Brian Paul ([e-mail])

Space Science and Engineering Center
University of Wisconsin - Madison
1225 W. Dayton St.
Madison, WI  53706

-------- documentation and source code for file conversion program ----------

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.