Vis5D Documentation
<<< Previous | System Requirements and Installation | Next >>>

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

- 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`.

## Manifest

The files installed by Vis5D include:

Table 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

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

`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`.)

Table 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 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 5. Uninstalled files and subdirectories:

`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

## 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.

<<< Previous | Home | Next >>>
System Requirements and Installation | Up | Putting Your Data Into Vis5D