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
% ./configure % make
% make install
%./configure --prefix=$HOME/Mesa % make % make install
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.
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
% make CC="gcc -Df2cFortran"
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
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:
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.
Turn on multi-threading mode in Vis5d (if a threads library is found); should enhance responsiveness, even on single-CPU systems.
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.
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.
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.)
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 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"
% src/vis5d hole.v5d -path src
If this completes succesfully, you will then want to install Vis5D:
% make install
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
The files installed by Vis5D include:
Table 2-1. Programs (in prefix/bin):
|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|
|v5dimport||utility to convert, resample, and reduce v5d files|
|comp_to_v5d||utility to convert (a) comp5d file(s) to v5d format|
|listfonts||utility to list fonts (only on SGI systems for IRIS GL)|
|topoinfo||utility to see info about a .topo file|
|fromxwd||utility to convert .xwd files to SGI .rgb format|
|gr3d_to_v5d||utility to convert a McIDAS GR3D file to v5d format|
|gg3d||McIDAS grid utility|
|igg3d||McIDAS grid utility|
|igu3d||McIDAS grid utility|
(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.h||file I/O API for Fortran|
|api.h||rest of the Vis5D API|
Table 2-4. Data (in prefix/share/vis5d+):
|OUTLSUPW||World continental map lines file|
|OUTLUSAM||Medium resolution map of US with state boundaries|
|EARTH.TOPO||Earth topography file|
Table 2-5. Uninstalled files and subdirectories:
|README||short description of the program|
|COPYING||the GNU general public license|
|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|
|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|
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.