Vis5D Version 4.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" or "lattice" 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 or one time step (i.e. no time dynamics). However, your data should have some depth in all three spatial dimensions. 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, 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. Also, if you would like to be added to the Vis5D mailing list, send email to: Bill Hibbard (email: whibbard@macc.wisc.edu) or Brian Paul (email: brianp@ssec.wisc.edu) at: 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 Visualizing the sample data sets Section 8 Version history Section 9 Vis5D as a subsystem of McIDAS 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: 1. Silicon Graphics workstations: 32MB RAM 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 PEX optional 4. Sun Sparc workstations*: 32MB RAM 8 or 24-bit color display SunOS Release 4.1.x or later 5. DEC workstations*: 32MB RAM 8 or 24-bit color display ULTRIX V4.2 or later on MIPS-based systems OSF/1 V1.3 or later on Alpha-based systems 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, Vis5D does all 3-D rendering in software using the Mesa (an OpenGL work-alike) or VOGL (an IRIS GL work-alike) library. Be aware that software rendering is slow. We would like to encourage anyone with one of these workstations with 3-D graphics hardware to modify Vis5D to utilize that hardware. 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. If you don't have Internet access, you can obtain Vis5D on tape by sending us a blank QIC or DAT and a note explaining what you need. 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-4.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-4.1 directory: ftp> cd pub/vis5d-4.1 5. Transfer files in binary mode: ftp> binary 6. Get the Vis5D archive file: ftp> get vis5d-4.1.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-4.1.tar.Z % tar -xvf vis5d-4.1.tar 10. Change to the newly created vis5d directory: % cd vis5d-4.1 11. 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 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. 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 Vis5D: % ./vis5d LAMPS.v5d NOTE: To quit, click on the "EXIT" widget button. 13. You may delete the .tar files if desired. 14. 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 v5dinfo /usr/local/bin % mv v5dstats /usr/local/bin % mv OUTL* /usr/local/data % mv EARTH.TOPO /usr/local/data then change change the vis5d.h file as below to indicate where the map and topography files are stored. 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. For example, if you've moved your map and topography files to /usr/local/bin as described above, you would specify "/usr/local/data/EARTH.TOPO" and /usr/local/data/OUTLUSAM" respectively. When finished changing the src/vis5d.h file you must re-make the system by repeating installation step 11 above. 2.4 Manifest When you are finished installing Vis5D you should have a directory named "vis5d-4.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 OUTLGRID Map lines of constant latitude and longitude at 10 degree intervals OUTLUSAL Low resolution map of US with state boundaries OUTLUSAM Medium resolution map of US with state boundaries EARTH.TOPO Earth topography file 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 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 src/ source code for vis5d util/ source code for the Vis5D utilities lui2/ source code for LUI user interface library Mesa/ source code for Mesa 3-D graphics library vogl/ source code for VOGL 3-D graphics library userfuncs/ directory of user-written analysis functions contrib/ software contributed by Vis5D users convert/ source code for sample data conversion programs And optionally, GR3D0001 McIDAS GR3D file of Schlesinger's thunderstorm model GR3D0002 McIDAS GR3D file of LAMPS model 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 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 are produced by the comp5d program as in previous versions of Vis5D. The v5d file format is the new, and prefered, file format used in version 4.0 and higher of Vis5D. It is intended to be a replacement for the comp5d format because it much more flexible and extendable. The most direct way to visualize your data with vis5d is to 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. 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. 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 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 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 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 of grid level 1 (bottom) vert_args(2) = height of grid level 2 ... vert_args(N) = height 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 have a different number of grid levels for different variables. For example, suppose most of your variables have 30 grid levels. There may be a few other variables who's values are only of interest near the bottom of the box, or there may a variable, such as sea-level pressure that is only needed at one grid level. Prior to version 4.0 of Vis5D, you would have had to filled in the extra levels with redundant or dummy data values. By using the v5dCreate function you can now specify how many grid levels are present for each variable. Remember, then, that the amount of data passed to the v5dWrite call will depend on which variable you're writing. The v5dCreate and v5dcreate functions allow you to control how the grid point values are compressed. The default is that grid point values are linearly scaled to one byte integers. This works very well for most data sets, since the scaling factors are chosen independently for each cobination 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. 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 4.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 bounds increase upward and east/west bounds increase to the right, like an XY cartesian grid. 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 79.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. North/south bounds increase upward and east/west bounds increase leftward. 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) Stereographic: a general 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 a 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 bounds increase upward on the rotated sphere and east/west bounds 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 Vis5D 4.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. 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. Positive U values are eastward, negative U is westward. Positive V values are northward, negative V is southward. 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 specify other wind variables to vis5d by means of the -trajvar and -wind2 command line options. 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'. 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. 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.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. 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 you’ll 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 doesn’t 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 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. 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 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 After you have made a v5d file, you can interactively visualize it with the command: vis5d file.v5d [options] [options] may be any combination of the following (though none are usually needed): -alpha [SGI only] 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. N is the number of the first file. 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. -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 xfontname -font glfontname height Set the font used for the clock and text labels in the 3-D window. You can determine which form of the font option is used on your system by typing ‘vis5d’ alone and examining the options. The first form expects the name of an X window system font. Use the xlsfonts command to see a list of X fonts on your system. The second form expects the name and size (72=1 inch) of an IRIS GL font. Use the listfonts command included with Vis5D to see a list of GL fonts on your system. Example 1: vis5d LAMPS.v5d -font fg-30 Example 2: vis5d LAMPS.v5d -font Helvetica 30 -full Open the 3-D window as a borderless, full-screen size window. -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. -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.3 to setup a different default. Example: vis5d LAMPS.v5d -map OUTLUSAL -mbs n Override the assumed system memory size of 32 megabytes. See section 2.3 to setup a different default value. -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 Don’t 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. -sequence filename [not available on all systems] Specifies a file containing a sequence of images to texture map over the topography. 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 rgbfile [not available on all systems] Specify an SGI .rgb file to texture map over the topography. -topo file Use a topography file other than the default of EARTH.TOPO. See section 2.3 to setup a different default. -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 -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 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 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, two windows will appear: 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. Starting at the top, 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 [ANIM-REC] REVERSE [SAVE PIC] [PERSPEC] These buttons are used to toggle, activate, or 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.3. Trajectory This mode is used for creating and displaying wind trajectories. See section 6.7. Slice This mode is used to reposition horizontal and vertical slices. See section 6.5. Label This mode is used to create and edit text labels in the 3-D window. See section 6.8. Probe Used to inspect individual grid values by moving a 3-D cursor through the 3-D grid. See section 6.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 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. 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. 6.4 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.11 EXIT Exit the program. A 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. [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 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. 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. PERSPEC Toggle between perspective and orthogonal viewing projections. 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 four viewing modes will be discussed in detail in following sections. 6.5 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. 6.6 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 6.1, the last group of buttons on the control panel form 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. 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. 6.7 Volume Rendering If you are running Vis5D on an SGI workstation with a VGX, VGXT, VTX, RE or RE2 graphics system, a Kubota/Denali workstation, or using the Mesa software 3-D library, 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 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 , or 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 , or 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 Vis5D. 6.8 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 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.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. 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 6.9 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 key can be used to correct errors. When you are finished, press . 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. 6.10 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 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. 6.11 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 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. 6.11.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.11.2 Type-in Formulas Type-in formulas let you type in mathematical expressions for computing new variables in terms of existing variables. For example, you can type in the expression SPD3D = SQRT( U*U + V*V + W*W ) and a new variable named SPD3D will be computed accordingly. Or, you can compute the ration of the dew point (TD) to the temperature by typing in the formula RATIO = TD / T Your formulas can involve 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. Once you compute a variable this way, its name is added to the list of analysis functions. If you select this name again, you can edit the formula and recompute different values for the variable. 6.11.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: 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 and 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.12 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. 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.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 files. 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 6.12. 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 Vis5D 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 well. 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. Some SGI systems have such a converter built in. There is no scripting language in Vis5D so you must compose your video "on the fly" and edit it later if you have two VCRs. You can even make simple video titles with vis5d! Start vis5d with '-full' and a large font with '-font', go into 'Label' mode, turn off the clock and box, hide the control panel window, and then make your titles. 6.14 Final Notes The SGI and Stardent versions of vis5d are parallel programs; multiple CPUs are used to compute graphics in parallel. 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. 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 "LAMPS.v5d" data set, the save file will be named "LAMPS.v5d.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 Vis5D there is a user-contributed software directory: contrib/. See the README file in that directory for a description of current contributions. 7. VISUALIZING THE SAMPLE DATA SETS We have included two sample data sets. To visualize one of Bob Schlesinger's thunderstorm simulations, enter the command: vis5d SCHL.v5d 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 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 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 SCHL.v5d file was made from the GR3D0001 file with the command: gr3d_to_v5d 1 1 SCHL.v5d 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 LAMPS.v5d compressed grid file was produced 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. 8. 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 satllite images can be texture mapped onto the map 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. .