Installing Vis5D

Before installing Vis5D, you may want to download the following:

Mesa

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 (optional)

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.

Vis5d+

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:

Optional Arguments

--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:

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.

Manifest

The files installed by Vis5D include:

Table 2-1. Programs (in prefix/bin):

vis5dthis 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

Table 2-2. Libraries (in prefix/lib):

libv5d.v5d file I/O API
libvis5dthe 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.)

Table 2-3. Headers (in prefix/include/vis5d):

v5d.h,binio.h the file I/O API definitions
v5df.hfile I/O API for Fortran
api.hrest of the Vis5D API

Table 2-4. Data (in prefix/share/vis5d+):

OUTLSUPWWorld continental map lines file
OUTLUSAMMedium resolution map of US with state boundaries
EARTH.TOPOEarth topography file

Table 2-5. Uninstalled files and subdirectories:

READMEshort description of the program
COPYINGthe GNU general public license
COPYRIGHTcopyright notice
PORTINGan ASCII document with notes on porting Vis5D
hole.v5dsample 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

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. This value is now controlled by the --with-memory=MB option to the configure script (see above).

  2. There are two ways to specify a different topography and/or map file. One way is to edit src/vis5d.h and change the values for TOPOFILE and/or MAPFILE. For example, if you move the map and topography files to /usr/local/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.