========================================================================
README for 3D Visualizer version 1.15
Copyright (c) 2005-2017 Oliver Kreylos
========================================================================

Overview
========

3D Visualizer is a highly interactive application for visualization and
analysis of 3D multivariate gridded data, such as produced by finite
element method (FEM) simulations, confocal microscopy, serial
sectioning, computerized axial tomography (CAT) scans, or magnetic
resonance imaging (MRI) scans.

3D Visualizer is based on the Vrui software development toolkit (see
http://idav.ucdavis.edu/~okreylos/ResDev/Vrui), and runs in a variety of
environments ranging from laptop or desktop computers over semi-
immersive environments such as Geowalls to fully immersive virtual
reality environments such as CAVEs. More information about 3D Visualizer
can be found at http://www.keckcaves.org.

3D Visualizer's development was supported by the University of
California, Davis, by the UC Davis W.M. Keck Center for Active
Visualization in the Earth Sciences (KeckCAVES,
http://www.keckcaves.org), the W.M Keck Foundation, and the National
Science Foundation.

Requirements
============

3D Visualizer requires Vrui version 4.2 build 006 or newer. To read
images in PNG, JPEG, or TIFF formats, libpng, libjpeg, or libtiff have
to be installed, respectively, and Vrui has to be configured with
support for these image formats (see Vrui README file).

Installation Guide
==================

It is recommended to download or move the source packages for Vrui and
3D Visualizer into a src directory underneath the user's home
directory. Otherwise, references to ~/src in the following instructions
need to be changed.

It is also recommended to skip optional steps 4 and 6 in the following
instructions. 3D Visualizer does not need to be installed in order to
be used; installation (to a system directory such as /usr/local) is
only recommended if 3D Visualizer will be used from multiple user
accounts.

0. Install Vrui from ~/src/Vrui-<version>-<build> (see Vrui README
   file).

1. Change into ~/src directory and unpack the 3D Visualizer tarball:
   > cd ~/src
   > tar xfz <download path>/3DVisualizer-<version>.tar.gz
   - or -
   > tar xf <download path>/3DVisualizer-<version>.tar

2. Change into 3D Visualizer base directory:
   > cd 3DVisualizer-<version>

3. If the Vrui version installed in step 0 was not 4.2, or Vrui's
   installation directory was changed from the default of /usr/local,
   adapt the makefile using a text editor. Change the value of
   VRUI_MAKEDIR close to the beginning of the file as follows:
   VRUI_MAKEDIR := <Vrui install dir>/share/make
   Where <Vrui install dir> is the installation directory chosen in
   step 0. Use $(HOME) to refer to the user's home directory instead
   of ~.

4. Optional: Adapt makefile if 3D Visualizer is to be installed in a
   different location, for example /usr/local. Set INSTALLDIR to the
   desired target location. 3D Visualizer will be then be installed in
   $(INSTALLDIR)/bin, $(INSTALLDIR)/lib (or $(INSTALLDIR)/lib64 on
   64-bit Linux systems), and
   $(INSTALLDIR)/share/3DVisualizer-<version>.
   Important note: Do not use ~ as a shortcut for the user's home
   directory here; use $(HOME) instead. For example, write
   INSTALLDIR = $(HOME)/apps
   instead of
   INSTALLDIR = ~/apps

5. Build 3D Visualizer:
   > make

6. Optional: Install 3D Visualizer in the selected target location.
   This is only necessary if the INSTALLDIR variable in the makefile
   was changed. By default, 3D Visualizer can be run from its base
   directory. To install:
   > make install
   - or, if the target location is a system directory -
   > sudo make install

7. Optional: Add directory containing the 3D Visualizer executable
   (~/src/3DVisualizer-<version>/bin in the default installation,
   $(INSTALLDIR)/bin otherwise) to the user's search path. This allows
   running 3D Visualizer from any directory. Using csh or tcsh:
   > setenv PATH ${PATH}:~/src/3DVisualizer-<version>/bin
   - or -
   > setenv PATH ${PATH}:<INSTALLDIR>/bin
   where <INSTALLDIR> is the target location set in the makefile.
   Using bash:
   > export PATH=${PATH}:~/src/3DVisualizer-<version>/bin
   - or -
   > export PATH=${PATH}:<INSTALLDIR>/bin
   These lines can also be added to the user's .cshrc or .bashrc files
   to make the additions persist between logins.

Running 3D Visualizer on Alaska Example Data
============================================

These instructions assume that 3D Visualizer was installed in its base
directory, (see steps 4 and 6 above).

1. Change into 3D Visualizer base directory:
   > cd ~/src/3DVisualizer-<version>

2. Download example data tarball AlaskaData.tar.gz.

3. Unpack example data tarball in 3D Visualizer directory:
   > tar xfz <download path>/AlaskaData.tar.gz
   - or -
   > tar xf <download path>/AlaskaData.tar

4. On MacOS X: Start X11. 3D Visualizer requires a running X server,
   but, if preferred, it can be started from a MacOS X terminal instead
   of xterm.

5. Run 3D Visualizer on example data:
   > ./bin/3DVisualizer -palette AlaskaData/slab2.pal
     AlaskaData/slab2.in
   - or (full command line) -
   > ./bin/3DVisualizer -palette AlaskaData/slab2.pal
     -class MultiCitcomtFile AlaskaData/slab2.dat Temp "log(Visc)"

6. See Vrui's HTML documentation or 3D Visualizer's user's guide on
   Vrui's basic user interface and how to use 3D Visualizer.