In the following sections we describe the hardware and software required to run Vis5D and detail how to install Vis5D on your system. Vis5d+ should, in principle, run on any system with X windows, OpenGL libraries, and at least an 8-bit color display. 32MB of RAM is recommended, and an ANSI C compiler is required to build the program. It is known for certain to run on the following systems: Silicon Graphics: IRIX version 4.0.1 or higher; Multiple processors are used when present; IrisGL is not supported IBM RS/6000: Model 320H or higher; AIX version 3 or later; 3-D graphics hardware is supported through OpenGL HP series 7000 or 9000 workstations: HP-UX A.09.01 or later; PEX optional Sun SPARC: SunOS 5.x or later The X shared memory extension may not work correctly. If Vis5D prints an error message to the effect of "Shared memory error" then you'll have to append the following three lines to the end of your /etc/system file then reboot: set shmsys:shminfo_shmmax = 0x2000000 set shmsys:shminfo_shmmni = 0x1000 set shmsys:shminfo_shmseg = 0x100 Compaq Alpha: OSF/1 V1.3 or later; Kubota Denali Graphics hardware supported with KWS V1.3.3 or later and NPGL Run-time license you need to run 'limit stacksize 32m' before you run Vis5D Linux: x86, PowerPC, and Alpha Linux systems have been tested. A 75MHz Pentium CPU or faster is recommended. gcc 2.95.2 on PowerPC has a bug that causes problems; be sure to get a version with the latest developer patches. Note that on systems which don't have 3-D graphics hardware or OpenGL, all 3-D rendering is done in software using Mesa (an OpenGL work-alike). 3-D graphics hardware is recommended for high-end use. If you do not have Mesa, you must download and install it as described below. 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. With the new autoconf-based installation procedure, porting to new machines should be considerably easier than before (and may often work with no modifications at all). Before installing Vis5D, you may want to download the following: Mesa is a free OpenGL replacement, and is required if your system does not already have OpenGL, IrisGL, or PEX (an old 3d library for X). If you don't know whether you have Mesa or one of these other libraries, you can skip this step for now; when you try to configure Vis5D (in section 2.2.3) , the configure script will stop and complain if it can't find one of the libraries. Then you can go back to this step. To install Mesa on your machine, go to the Mesa home page and download it. You'll get a file something like MesaLib-3.1.tar.gz Unpack it: % gunzip MesaLib-3.1.tar.gz % tar -xf MesaLib-3.1.tar Then, cd to the MesaLib-3.1 directory and type: % ./configure % make This should configure and compile Mesa. Finally, switch to root (superuser) and type: % make install If you don't have access to the root account on your machine, and your system administrator is unwilling to install Mesa for you (unlikely, since Mesa is very standard and widely-used), you can instead install it to a location in your home directory, e.g. ~/Mesa. To do this, you would use the following steps instead of the above: %./configure --prefix=$HOME/Mesa % make % make install The last step will copy the Mesa libraries and headers to ~/Mesa/lib, ~/Mesa/include, etcetera. When you run 'make install', it may print out some important directions regarding shared libraries. If you install in a non-standard location, it will typically tell you add the prefix/lib directory to some environment variable. On Linux systems, you may need to run /sbin/ldconfig, etcetera. NetCDF is a free library for reading scientific data that can optionally be used by Vis5D. If you do not have NetCDF, then certain features of Vis5D will be disabled, notably irregular dataset support. To get NetCDF, go to the NetCDF home page and download the NetCDF package. As of this writing, the current version is 3.4. Once you have downloaded it, unpack and compile the package with: % uncompress netcdf-3.4.tar.Z % tar xf netcdf-3.4.tar % cd netcdf-3.4/src % ./configure % make On Linux systems, you may instead have to use: % make CC="gcc -Df2cFortran" because NetCDF doesn't know how to deal with GNU g77. Vis5D only needs the libnetcdf.a file, located in libsrc/libnetcdf.a. If you have downloaded and unpacked Vis5D already, you can copy this file to the Vis5D directory now; otherwise, just leave it there and remember where it is. Since you are reading this file, you have probably already downloaded and unpacked Vis5d+. Otherwise, go to the Vis5d+ home page and download the latest version. It will be something like vis5d+-1.0.1.tar.gz. Unpack it with: % gunzip vis5d+-1.0.1.tar.gz % tar xf vis5d+-1.0.1.tar Now, cd to the Vis5D directory (cd vis5d+-1.0.1 if you were following the steps above). At this point, you will run a "configure" script to automatically configure Vis5D for your machine. The most basic way to run configure is by: % ./configure but there are several optional arguments that you may want to pass it: --prefix=dir By default, Vis5D will be set up to install (when you run 'make install' below) under /usr/local on your system. That is, the programs will be installed in /usr/local/bin, etcetera. This argument allows you to install to a different place. For example, if you don't have root access you may want to install to your home directory by using: --prefix=$HOME/Vis5D --with-netcdf=lib This allows you to specify the location (lib) of the libnetcdf.a file. You don't need to do this if you copied libnetcdf.a to the Vis5D directory or if you installed it to a standard system location. Contrariwise, --without-netcdf forces Vis5D to not use NetCDF even if it could find the library. --enable-threads Turn on multi-threading mode in Vis5d (if a threads library is found); should enhance responsiveness, even on single-CPU systems. --with-memory=MB Set the maximum amount of memory to use MB megabytes (defaults to 32). Vis5d normally uses a bounded amount of memory to avoid swapping. When the limit is reached, the least-recently viewed graphics will be deallocated. If MB is set to 0, there will be no memory limit and Vis5d will never deallocate graphics. --with-mesa Force the use of Mesa even if a "real" OpenGL library is available. This just means it looks for libMesaGL libraries, etcetera, before libGL instead of afterwards. This option isn't useful with recent versions of Mesa, which install as libGL, etcetera. --with-mcidas=lib Specify the location of a McIDAS library file, an optional (proprietary) library that Vis5D can use. (Vis5D comes with an older McIDAS library binary for IRIX, which will be used if it works with your system.) --disable-fortran Don't compile any of the Fortran utility programs, etcetera, even if there is a Fortran compiler on your system (it will normally be used automatically). You can use this if your Fortran compiler gives you troubles when compiling Vis5D. --disable-shared --disable-static Disable creation of the shared (.so) and static (.a) libaries, respectively. Don't disable both, as the Vis5D program requires a library to link to! You can also set one or more environment variables before running configure, to help it find libraries and otherwise control its behavior. (You can go back and do this if configure has trouble.) You set an environment variable by the syntax setenv variable value (or export variable=value if you are using ksh, bash, or the like). Most of the time, you won't need to do this, but if you do, some possible environment variables are: CC: the name of the C compiler CPPFLAGS: -I dir flags to tell the C compiler where to look for header files CFLAGS: C compiler flags F77: the name of the Fortran compiler FFLAGS: Fortran compiler flags LDFLAGS: linker flags (e.g. -L dir to look for libraries in dir) The most common use for these variables is when you have libraries installed in nonstandard locations, in which case you will use the CPPFLAGS and LDFLAGS environment variables. For example, consider the case above where you installed the Mesa library in ~/Mesa. You would then tell configure where to find the Mesa libraries and header files with: % setenv CPPFLAGS "-I$HOME/Mesa/include" % setenv LDFLAGS "-L$HOME/Mesa/lib" Be sure to scan the configure output for important warning messages, which will be surrounded by asterisks (*******). Once you have run configure successfully, you can compile Vis5D by typing: % make If you want, you can run the program right away by typing: % src/vis5d hole.v5d -path src hole.v5d is a sample data file included with Vis5D. The -path src argument is necessary to tell it where the map data files are located; it will no longer be need after you do a 'make install' (see below). Click and drag in the display window to rotate it, and click on buttons in the lower portion of the control window to plot the data. If this completes succesfully, you will then want to install Vis5D: % make install (You may need to switch to root first, or do su -c "make install", if you are installing in system locations.) Note that the make install output may contain important instructions regarding shared libraries (if you want to link to the Vis5D libraries in your programs). e.g. on Linux you'll need to run /etc/ldconfig and possibly edit /etc/ld.so.conf. Once this is done, the vis5d program, utilities, data, and libraries are installed under /usr/local, or wherever you specified with the --prefix argument to configure (as described above). You should now be able to run it by simply typing vis5d (if you installed in a system directory) or by typing prefix/bin/vis5d (otherwise, where prefix was the argument to --prefix), in either case followed by the name of a data file. One sample data file, hole.v5d, is included with Vis5D, and more may be downloaded from the Vis5D ftp site . If you want to uninstall Vis5d at any time, you can do: % make uninstall which removes the files installed by make install. The files installed by Vis5D include: vis5d this is the vis5d visualization program v5dappendutility to join v5d files together v5dinfoutility to see summary of a v5d file v5dstatsutility to see statistics of a v5d file v5deditutility to edit the header of a v5d file v5dimportutility to convert, resample, and reduce v5d files comp_to_v5d utility to convert (a) comp5d file(s) to v5d format listfontsutility to list fonts (only on SGI systems for IRIS GL) topoinfoutility to see info about a .topo file fromxwdutility to convert .xwd files to SGI .rgb format gr3d_to_v5dutility to convert a McIDAS GR3D file to v5d format gg3dMcIDAS grid utility igg3dMcIDAS grid utility igu3dMcIDAS grid utility libv5d .v5d file I/O API libvis5d the rest of the Vis5D API (Programs using the full Vis5D API should link with -lvis5d -lv5d, while programs just doing file I/O can link with just -lv5d.) v5d.h,binio.h the file I/O API definitions v5df.h file I/O API for Fortran api.h rest of the Vis5D API OUTLSUPW World continental map lines file OUTLUSAM Medium resolution map of US with state boundaries EARTH.TOPO Earth topography file README short description of the program COPYING the GNU general public license COPYRIGHT copyright notice PORTING an ASCII document with notes on porting Vis5D hole.v5d sample dataset (dielectric function and z-comp. of a magnetic field guided in a dielectric slab with holes) doc/ this manual, in PDF and HTML formats scripts/ example scripts src/ source code for vis5d and v5dimport util/ source code for the Vis5D utilities lui5/ source code for LUI user interface library userfuncs/ directory of user-written analysis functions contrib/ software contributed by Vis5D users convert/ source code for sample data conversion programs You can also download from the Vis5D web site sample code for user supplied data formats, including: LAMPS.v5d: Sample LAMPS data set SCHL.v5d: Sample data set; Bob Schlesinger's thunderstorm model After installation and testing you may want to customize the vis5d program by editing the src/vis5d.h file: 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. This value is now controlled by the --with-memory=MB option to the configure script (see above). There are two ways to specify a different topography and/or map file. One way is to edit src/vis5d.h and change the values for TOPOFILE and/or MAPFILE. For example, if you move the map and topography files to /usr/local/data, you would specify /usr/local/data/EARTH.TOPO and /usr/local/data/OUTLUSAM respectively. The other way is press the 'DISPLAY' button on the main contral panel, then press the 'Options' button found above each display menu. The 'toponame' and/or 'mapname' fields can be changed accordingly. By default, these files are looked for in /usr/local/share/vis5d+, or whereever Vis5D was installed. You can change this by either the -path argument to Vis5D or the VIS5D_PATH environment variable. When you are finished changing the src/vis5d.h file, you must recompile. the programs.