
                           VisAD

1. Introduction

VisAD is a pure Java system for interactive and collaborative
visualization and analysis of numerical data.  It is described
in detail in the:

  VisAD Java Class Library Developers Guide

available from the VisAD web page at:

  http://www.ssec.wisc.edu/~billh/visad.html


2. Downloading the VisAD Source Code

To download the VisAD source code, first make sure the current
directory is a directory in your CLASSPATH (which we will refer
to as '/parent_dir' through the rest of this README file).
Then get:

  ftp://demedici.ssec.wisc.edu/pub/visad-2.0/visad_src.2.0.tar.Z
 
or:
 
  ftp://demedici.ssec.wisc.edu/pub/visad-2.0/visad_src.2.0.jar
 
If you have previously downloaded the VisAD source you
should run 'make clear' in your visad directory to clear
out the old source files before you unpack the new source.

Unpack the jar file by running:
 
  jar xvf visad_src.2.0.jar
 
or unpack the compressed tar file by running:
 
  uncompress visad_src.2.0.tar.Z
  tar -xvf visad_src.2.0.tar
 
Unpacking VisAD will create the following sub-directories:

  visad				// the core VisAD package
  visad/ss			// VisAD Spread Sheet
  visad/java3d			// Java3D displays for VisAD
  visad/java2d			// Java2D displays for VisAD
  visad/util			// VisAD UI utilities
  visad/data			// VisAD data (file) format adapters
  visad/data/fits		// VisAD - FITS file adapter
  visad/data/netcdf		// VisAD - netCDF file adapter
  visad/data/netcdf/in		// netCDF file adapter input
  visad/data/netcdf/out		// netCDF file adapter output
  visad/data/netcdf/units	// units parser for netCDF adapter
  visad/data/hdfeos		// VisAD - HDF-EOS file adapter
  visad/data/hdfeos/hdfeosc	// native interface to HDF-EOS
  visad/data/vis5d		// VisAD - Vis5D file adapter
  visad/data/mcidas		// VisAD - McIDAS file adapter
  visad/data/gif		// VisAD - GIF file adapter
  visad/data/visad		// VisAD serialized object file adapter
  visad/paoloa			// GoesCollaboration application
  visad/aune			// ShallowFluid application
  visad/benjamin		// Galaxy application
  visad/examples		// small application examples
  nom/tam/fits			// Java FITS file binding
  nom/tam/util			// Java FITS file binding
  nom/tam/test			// Java FITS file binding
  ucar/multiarray		// Java netCDF file binding
  ucar/netcdf			// Java netCDF file binding
  ucar/tests			// Java netCDF file binding

These directories correspond to the packages in distributed with
VisAD, except that the classes in visad/examples are in the
default package (i.e., they do not include a package statement).
 

3. Building VisAD

Your CLASSPATH sould include:

  1. The parent directory of your visad directory.
  2. The current directory.

Thus if VisAD is installed at /parent_dir/visad and you use csh,
your .cshrc file should include:

  setenv CLASSPATH /parent_dir:.

VisAD requires JDK 1.2 and Java3D.  More information about
these is available at:

  http://java.sun.com/

On systems that support Unix make, you can simply run:

  make compile

to compile the Java source code in all the directories unpacked
from the source distribution, as well as native code in the
visad/data/vis5d and visad/data/hdfeos/hdfeosc directories and
certain application directories.  If you want 'make compile'
to compile native libraries, then you may need to change the
line:

  JAVADIR=/opt/java

in visad/Makefile if your java is installed in a directory
other than /opt/java.

If you have NMAKE on WinNT you may run:

  nmake -f Makefile.WinNT compile

This does not compile native code.

If you cannot use Unix make or WinNT NMAKE, you must invoke the
Java compiler on the Java source files in all the directories
unpacked from the source distribution.  Note that the Java
source code in the visad/examples directory has no package, so
you must run 'cd visad/examples' before you compile these Java
source files.

If you do not use make, then you must also run the rmic compiler
on the following classes (after they are compiled by the javac
compiler):

  visad.RemoteCellImpl
  visad.RemoteActionImpl
  visad.RemoteDisplayImpl
  visad.RemoteThingReferenceImpl
  visad.RemoteDataReferenceImpl
  visad.RemoteThingImpl
  visad.RemoteDataImpl
  visad.RemoteFunctionImpl
  visad.RemoteFieldImpl
  visad.RemoteServerImpl


4. Building Native Code for the HDF-EOS and Vis5D File Adapters

Although VisAD is a pure Java system, it does require native
code interfaces in its adapters for HDF-EOS and Vis5D file
formats.  We believe that the need for these will disappear
as the organizations supporting these file formats develop
Java interfaces.

You can build the necessary libraries from source or on
Sparc Solaris you can simply download:

  ftp://demedici.ssec.wisc.edu/pub/visad-2.0/libhdfeos.so

into your visad/data/hdfeos/hdfeosc directory, and download

  ftp://demedici.ssec.wisc.edu/pub/visad-2.0/libvis5d.so

into your visad/data/vis5d directory.

The rest of this section describes how to make these
library files from source.

The HDF-EOS and Vis5D file adapters include native interfaces
(JNI) to file interfaces written in C.  On systems that
support Unix make, change to the visad/data/vis5d and run
'make', then change to the visad/data/hdfeos/hdfeosc directory
and run 'make all'.

Note that the native code in visad/data/hdfeos/hdfeosc does
not include NASA/Hughes' HDF-EOS C file interface code; it
only includes our C native code for creating a Java binding
to their HDF-EOS C file interface.  You must obtain the
HDF-EOS C file interface code directly from NASA and NCSA.
Specifically, you must obtain and install HDF4.1r1 from:

   ftp://ftp.ncsa.uiuc.edu/HDF/HDF_Current
 
then install HDF-EOS:
 
   http://ulabibm.gsfc.nasa.gov/hdfeos/hdf.html#4

We have successfully linked these libraries on Irix and
Solaris.

The native code in visad/data/vis5d does include everything
you need to read Vis5D files.  Note that if you are compiling
this native code on a little-endian architecture (e.g., Linux
or DEC Alpha) you must first edit visad/data/vis5d/Makefile
to add '-DLITTLE' to CFLAGS.

Before you can run applications that use the HDF-EOS and
Vis5D file adapters, you must add:
 
  /parent_dir/visad/data/hdfeos/hdfeosNative/libhdfeosLib.so
  /parent_dir/visad/data/vis5d/libvis5d.so
 
to your LD_LIBRARY_PATH.


5. Building Native Code for Applications

Although VisAD is a pure Java system, applications of VisAD
may include native code.  The reality is that most science
code is still written in Fortran.

The applications in visad/paoloa, visad/aune and visad/benjamin
also include native code in both C and Fortran.

Before you compile the native code in the visad/paoloa
directory, download the necessary data files from either:
 
  ftp://demedici.ssec.wisc.edu/pub/visad-2.0/visad.paoloa.tar.Z
 
or:
 
  ftp://demedici.ssec.wisc.edu/pub/visad-2.0/visad.paoloa.jar
 
which include necessary data files.  Unpack these files in
/parent_dir (i.e., the directory in your CLASSPATH where
you unpacked the VisAD source).  They include all necessary
source code and Makefiles as well as the data files.

Then edit the Makefile in both visad/paoloa, visad/aune and
visad/benjamin to change the path:
 
  JAVADIR=/opt/java
 
to point to the appopriate directory where you installed Java.

On systems that support Unix make, change to the
visad/paoloa directory and run 'make', then change to
the visad/aune directory and run 'make'.  This will
create the shared object files (i.e., file names ending
in ".so") containing native code.  Before you can run
these applications, you must add:

  /parent_dir/visad/paoloa/libGoesRetrieval.so
  /parent_dir/visad/paoloa/libGoesCollaboration.so
  /parent_dir/visad/aune/libShallowFluid.so

to your LD_LIBRARY_PATH.


6. Downloading VisAD Classes in Jar Files

If you want to write applications for VisAD but don't want
to compile VisAD from source, you can dowload jar files that
include the VisAD classes.  These files are:

  ftp://demedici.ssec.wisc.edu/pub/visad-2.0/visad.jar

or 

  ftp://demedici.ssec.wisc.edu/pub/visad-2.0/visad.tar

If you get the tar file you will need to unpack it by running:

  tar -xvf visad.tar

It contains the single file 'visad.jar'.  Once you've got
visad.jar simply add:

   /parent_dir/visad.jar

to your CLASSPATH.  Then you can compile and run applications
that import the VisAD classes.  However, if your application
uses the HDF-EOS or Vis5D file format adapters, then you will
need to compile the native code as described in Section 4 of
this README file.  The visad.jar file includes the classes from
these packages:

  visad				// the core VisAD package
  visad.ss			// VisAD Spread Sheet
  visad.java3d			// Java3D displays for VisAD
  visad.util			// VisAD UI utilities
  visad.data			// VisAD data (file) format adapters
  visad.data.fits		// VisAD - FITS file adapter
  visad.data.netcdf		// VisAD - netCDF file adapter
  visad.data.netcdf.in		// netCDF file adapter input
  visad.data.netcdf.out		// netCDF file adapter output
  visad.data.netcdf.units	// units parser for netCDF adapter
  visad.data.hdfeos		// VisAD - HDF-EOS file adapter
  visad.data.hdfeos.hdfeosc	// native interface to HDF-EOS
  visad.data.vis5d		// VisAD - Vis5D file adapter
  visad.data.mcidas		// VisAD - McIDAS file adapter
  visad.data.gif		// VisAD - GIF file adapter
  nom.tam.fits			// Java FITS file binding
  nom.tam.util			// Java FITS file binding
  nom.tam.test			// Java FITS file binding
  ucar.multiarray		// Java netCDF file binding
  ucar.netcdf			// Java netCDF file binding
  ucar.tests			// Java netCDF file binding


7. Problems

If you have problems, send en email message to the VisAD mailing
list at:

  visad-list@ssec.wisc.edu

Join the list by sending an email message to:

  majordomo@ssec.wisc.edu

with:

  subscribe visad-list

as the first line of the message body (not the subject line).

Please include any compiler or run time error messages in the text
of email messages to the mailing list.


