***************************************************************************
*                                                                         *
*  SciAn README File                                                      *
*  Eric Pepke                                                             *
*  September 1, 1992                                                      *
*                                                                         *
***************************************************************************

This file describes the process of obtaining and installing SciAn on your
workstation.  Please read it thoroughly before doing any installation.  I
know it's not always much fun to read things before jumping in and compiling,
but please do it anyway--there are some definable options that you need to
know about before you begin.

Table Of Contents

1.0  Introduction
2.0  System requirements
3.0  Obtaining and installing SciAn
   3.1  Connecting to ftp.scri.fsu.edu
   3.2  Downloading the SciAn Package
   3.3  Installing SciAn
      3.3.1  Configuring SciAn
      3.3.2  Checking the configuration
      3.3.3  Compiling and linking SciAn
      3.3.4  Releasing SciAn
4.0  Downloading the documentation
5.0  Using the technical notes
6.0  Getting help
   6.1  Common problems and solutions

---------------------------------------------------------------------------

1.0  Introduction

SciAn is a scientific visualization and animation program for Silicon
Graphics and IBM RISC/Sytem 6000 workstations.  It was developed at the
Supercomputer Computations Research Institute at Florida State University
to help meet the daily visualization needs of our scientists.

SciAn is primarily intended to do 3-D visualizations of data in an 
interactive environment with the ability to generate animations using
frame-accurate video recording devices.  A user manual, on-line help, and
technical notes will help you use the program.

As a research institution, we have always relied upon the availability of
free software to meet our needs, and we wanted to give something back to the
research community in return.  For this reason, we are making SciAn 
available at no charge.

If you have problems with or suggestions about SciAn, please don't hesitate
to send us electronic mail.  However, please understand that we are a 
research institution, not a software development company.  We work best in
an environment of cooperation and collaboration, and we hope that you will
join us.

If you use SciAn to produce images or animations for publication, please
give credit to the Supercomputer Computations Research Institute at Florida
State University.  It is a lot easier to justify continuing to put effort
into maintaining SciAn if we can point to places where it is being used to
do real work.

2.0  System requirements

SciAn currently runs on two platforms:
  1) Silicon Graphics 4D workstations
  2) IBM RISC/System 6000 workstations

Beginning with version 0.60, SciAn should run on all Silicon Graphics Power
Series, Personal IRIS, and Indigo workstations with Z-buffer capability.  It
will not run on very old workstations, such as the 1000, 2000, and 3000
series.

SciAn will run only on IBM RISC/System 6000 workstations that have 3-D
graphics accelerators that provide GL compatibility.  SciAn also requires
a Z-buffer.  If there is any question about whether your hardware provides
this, please get in touch with your system manager or IBM sales 
representative.  (IBM makes a bewildering variety of hardware, and I can't
keep up, but the magic words are Z-buffer and 3-D GL compatibility.)

On all workstations, SciAn ABSOLUTELY REQUIRES a Z-buffer.  If you try 
to run it on a workstation that does not have a Z-buffer, you will get
strange results.

Because SciAn is distributed as source code, you must also have access to
a C compiler to install.  Future versions may also require a FORTRAN 
compiler to install certain features, such as the PLOT-3D file reader.
A single set of source files is used to produce all versions of SciAn.

SciAn may also optionally be installed using the Hierarchical Data Format
(HDF) library developed by the National Center for Supercomputing 
Applications at the University of Illinois at Urbana-Champaign.  This library
is available via anonymous FTP from ftp.ncsa.uiuc.edu.  We strongly recommend
that you obtain this library, as it provides a good data format.

3.0  Obtaining and installing SciAn

If you would like to obtain SciAn, please send electronic mail to 
scian-info@scri.fsu.edu, if you haven't already done so.  You can also
request to be put on the SciAn mailing list, which will keep you informed
of updates.

SciAn is normally distributed via anonymous ftp from ftp.scri.fsu.edu.  If 
you do not have access to anonymous ftp, send us mail, and we'll try to
figure out some other way to get you the program.  It is much easier to
get the program through ftp, however, and it's certainly easier to get
updates that way.

3.1  Connecting to ftp.scri.fsu.edu

Before you connect to the SciAn distribution machine, make sure that you are
in a directory on your machine where you want the SciAn source to reside.  You
will need a few megabytes to keep the files during the installation process.

To connect to ftp.scri.fsu.edu, start up ftp on your unix machine like
this:

    ftp ftp.scri.fsu.edu

When asked for a user name, enter anonymous.  When asked for a password,
enter your network electronic mail address.

The SciAn program and documentation are located in the SciAn subdirectory
of the pub directory.  To get into that directory, enter

    cd pub/SciAn

In that directory, you will find a README file (which is this document)
and several subdirectories.

The release subdirectory contains the release versions of SciAn.  Obtaining
SciAn from this directory is described in section 3.2.

The beta subdirectory contains versions of SciAn for our beta testers.  These
versions are not as thoroughly tested as the release versions.  When a version
passes beta test, it is moved to the "release" directory.

The patches subdirectory contains minor patches to particular versions of 
SciAn which do not require the bother of recompiling the entire source.  You
will receive notice of patches through the SciAn mailing list.

The documentation subdirectory contains documentation for SciAn.  Obtaining
and printing it is described in section 3.3.

The technotes subdirectory contains technical notes for using SciAn.  These
are text files that contain information about topics that we haven't had time
to put in the manual.

3.2  Downloading the SciAn Package

In the "release" subdirectory (enter  cd release  to get to the directory)
you will find several files.  They will all have names of the form
scianXXX.tar.Z, where XXX is the version number of SciAn.  For example, the
file scian060.tar.Z contains SciAn version 0.60.

It is usually best to get the latest version of SciAn, unless you have 
recieved a note to use an older version.

You must download the file in binary mode.  Most versions of ftp figure out
that the target machine is running UNIX and go into binary mode automatically.
Just to make sure, enter

    image

to put ftp in binary mode.  Now it is time to download SciAn.  Let's assume
that you want to download SciAn version 0.60.  Enter

    get scian060.tar.Z

After the file has been transferred, you can get out of ftp by entering bye
or quit, depending on the version of ftp you have.  

The SciAn distribution is a compressed tar file.  The first step in getting 
the file ready is to uncompress it.  Enter

    uncompress scian060.tar

When the uncompress command finishes, you will have a file called scian060.tar.
To extract the individual files from the tar file, enter

    tar -xvof scian060.tar

If you get an error message, try

    tar -xvf scian060.tar

Many files will be extracted from the SciAn tar file.  Files ending in .c,
.h, and .f are the source files of SciAn.  (Currently, you don't need the
FORTRAN compiler to compile SciAn.)  The Makefile and files with .make
in their names are for the make program.  There is also a directory called 
demo which contains demonstration files for SciAn.  There may also be a file 
called RELEASE.NOTES.  Look in this file to determine special features of the 
version you have just downloaded.

3.3  Installing SciAn

Before SciAn can be installed, it must be configured to your machine.  In
order to understand the process of configuration, you must first understand
how the SciAn source is structured.

One copy of the SciAn source is used to produce all versions of SciAn.  Which
version is being compiled depends on constants defined in the file machine.h.
At compile time, the file tests constants to see if it is running on an IBM
or a Silicon Graphics machine and adjusts automatically.  However, there are
several options that you need to set by hand.

There are four basic steps in installing SciAn:

1) Configure SciAn by editing the file machine.h to set #defines for the
   installation options.
2) Check the installation options by entering make INSTALL.  Read everything
   the computer prints to the console.  If there is an error which will cause
   problems later on in the installation, it will be described in a message,
   and you will need to go back to step 1.
3) Compile and link SciAn by entering make scian (or pmake scian on Silicon
   Graphics machines with more than one processor).  
4) Release SciAn by moving the scian executable and the demo files to the
   appropriate directories.

These four steps are described in the next four sections.

3.3.1  Configuring SciAn

The machine.h file controls how SciAn is installed.  All it contains are 
preprocessor directives such as #define which have the effect of defining 
constants that control the installation of SciAn.  There are plenty of 
comments in the file to help you understand exactly what is going on.

The installation process has been automated so that you probably won't 
have to change anything in this file.  However, it is a good idea to be
familiar with the file in case problems arise.

At the beginning of the file is some code which tries to figure out what kind
of machine is compiling SciAn.  As far as I can tell, this always works 
properly and should not need to be changed.  Nearly all of the installation
options are set automatically based on the machine, but there are a few 
described later that you will need to know about.

Next there are some comments that explain what each one of the #defined 
constants does.  Next is some code which #defines constants based on which
machine SciAn is being compiled on.  Finally there are the #defines for the
options.

One important option is the HDF file format option, which is controlled by
the HDFDEF constant.  You can choose to compile SciAn with or without the 
HDF library.  By default, the distribution is set up to compile without HDF.  
However, we strongly recommend that you obtain and install HDF, as SciAn is 
much more useful with it.  Information on how to get HDF can be found in 
section 2.  The HDF library needs to be installed and placed in /usr/local/lib 
before you begin installing SciAn.  The make INSTALL process will produce
a file called machine.hdf.h which will declare whether the HDF library is
to be installed or not.

If you are compiling on an IBM RS/6000 machine, you may need to define the
MENUSFROM0 constant.  The numbering of menu items in GL is supposed to start
at 1.  However, some versions of the IBM GL emulation, such as with AIX 3.1.5,
start at 0.  There isn't really any way to tell this beforehand, but if you
compile SciAn and notice that the wrong menu items are getting highlighted,
you will need to go back and change this.

3.3.2  Checking the configuration

After you have set up machine.h the way you want it, you need to check the
configuration.  This is an extremely important step, and if you forget to 
do it, you may get link errors later.  Enter

    make INSTALL

A program called ScianPreInstall will go through the options defined in
machine.h and check to make sure that the libraries that are needed are 
present on your system.

When ScianPreInstall runs, it will ask you questions and print some messages
to the console.  Read everything it prints!  ScianPreInstall will tell you if
there is anything that needs to be changed in the libraries or in machine.h.
Do not proceed to the next step until ScianPreInstall tells you that it is OK
to do so.

ScianPreInstall also writes two very important files into the directory:
flags.make, which contains compiler flags, and lfiles.make, which contains
link files.  The way it produces these files is by reading a template file
specific to the kind of machine you are compiling on.  (To see all the template
files, enter ls *.*.make.)  Then it adds optional link files based on the
options in machine.h.  If, for some reason, you need to change the link files
because your system is unusual, do not edit lfiles.make, because it will be
overwritten the next time make INSTALL is done.  Instead, edit the appropriate
template file.

If and only if make INSTALL has given you the go-ahead to compile, you can go
on to the next step.

3.3.3  Compiling and linking SciAn

To make SciAn, enter

    make scian

If you are making on a Silicon Graphics machine with more than one processor,
you can do a parallel make instead by entering

    pmake scian

The makefile will compile and link SciAn resulting in an executable named 
scian.  If you get any kind of error, make sure that the configuration is
set up correctly as described in sections 3.3.1 and 3.3.2.  If that doesn't
help, read through section 6.1.  If you still cannot figure out what is 
wrong, send mail to us at scian-bugs@scri.fsu.edu.

When scian has been made, test it out by typing ./scian.  The user manual
has a brief tour, but if you don't have a copy of the manual, you can get
on-line help by clicking the mouse in the title window.

3.3.4  Releasing SciAn

The final step in installing SciAn is to release it to the users of your
machine.

First copy the scian executable file to a place where users can reach it.
One good place to put it is in /usr/local/bin.

Then copy or move the demo directory to some directory where users can reach
it and tell your users where it is.  The user manual refers to this directory,
so your users need to know its location.

The executable of the Silicon Graphics version of SciAn should run on any
Silicon Graphics workstation.  However, the IBM RS/6000 version will probably
only run on workstations configured in a similar way to the workstation where
it was compiled.  If you are running in a heterogeneous environment with 
several different versions of AIX, you may need to keep several executables
of SciAn.

4.0  Downloading the documentation

In the documentation directory, you will find files with names of the form
scianmanXXX.sit.hqx.  Each file contains the user manual for SciAn version 
X.XX.  Unfortunately, because we don't have a large staff and we have to choose
to allocate our time between improving SciAn and improving the manual, the
version of the manual lags behind the version of the program.  However, even
manuals for versions older than the version you are running are valuable.

Choose the file you want to download and download it using the technique
described in section 3.1.  In this case the files are text files, so you can
use either text or binary mode.

The manual is in Word 4 (Macintosh) format and has been compressed and
encoded with Stuffit. Use BinHex4 or StuffIt to decode the file and
then use StuffIt to extract the archive. When printing the manual BE
SURE TO CHECK "BLACK & WHITE" in the print dialog. Also, we have had
trouble with the figures not printing correctly when using background
printing.  It is safest to print with background printing turned off.

If you do not have access to Macintoshes, you may order a printed copy of
the latest manual from:

        Target Copy
        635 W. Tennessee Street
        Tallahassee, FL 32304

The price, including shipping, is $19 in U.S., $29 overseas. Payment may be
by Visa, MasterCard, check, or money order. If paying by credit card, order
may be faxed to (904)224-5014. Questions about manual orders or payments
should be taken up with Richard Bruce of Target Copy, at (904)224-3007.

We are not at all involved with the exchange of money between the copy shop
and anybody else.

5.0  Using the technical notes

When we need to release information about some aspect of SciAn that cannot
wait for the long time delay in releasing a new version of the manual, we will
put a technical note in the technotes directory.  A file called INDEX will
give summaries of all the technical notes in the directory.

Technical notes are not guaranteed to be easy to understand and may cover
esoteric topics.

6.0  Getting help

We hope you enjoy SciAn.  If you have difficulty installing or using it,
please first check through this file to make sure that you are doing everything
correctly.  Be sure to look through section 6.1.  If you still have problems,
send a message to scian-bugs@scri.fsu.edu.

If you have suggestions for new features for SciAn, please send them to 
scian-bugs@scri.fsu.edu.  Please keep in mind that we are a research program
and not a software house, and we work better in collaboration with you.

6.1  Common problems and solutions

This section contains some problems that a few people have had during 
installation or printing of the manual.  Please check this section if you
have a problem.

PROBLEM: I get link errors!

SOLUTION: About 95% of the time this is due to forgetting to do make INSTALL
before doing make scian.  Make INSTALL is a very, very important part of 
the installation process.  It will set up the link files to link properly
if it can and will tell you what to do to fix it if it can't.


PROBLEM: When I link, I get a message saying that libdf.a can't be found.

SOLUTION: The libdf.a file is the file that contains the HDF library.  Review
section 3.3.1 to find out what to do about it.  Also, be sure to do make
INSTALL before doing make scian.


PROBLEM: When I link, I get DFSDgetmaxmin or DFSDgetrange undefined.

SOLUTION: Between versions 3.1 and 3.2 of the NCSA HDF library, they changed
the name of one of the routines from DFSDgetmaxmin to DFSDgetrange.  SciAn
can link using either, but you have to specify in machine.h.  Look for 
constants beginning with the letters HDF.  The make INSTALL process will tell
you if SciAn is correctly configured for the right version of HDF.


PROBLEM: When I print the manual, the figures come out funny!

SOLUTION: Make sure you are using the latest version of the Apple laser
printer drivers, and turn background printing off.


PROBLEM: SciAn compiles fine on the IBM, but when I run it, I get an error 
and it exits.

SOLUTION: This one can mean a wide range of things, from trivial to 
disastrous.  In ascending order of difficulty, these are some of the things
we have run into:

1) When a user brings up X, some versions of AIX assume that the user "owns"
   the GL emulator and does not allow anyone else to use it.  Make sure that
   you are the user that ran xinit.
2) Binaries compiled under different versions of the operating system will
   not run on other versions.  (Also see MENUSFROM0 in machine.h.)  Make 
   sure that you have compiled and run on the same machine.
3) There are some software configurations that prevent you from using the
   GL emulator from within X.  Check with your system manager to see if this
   is the case.
4) If you have multiple versions of the X library, the search path specified
   may get the wrong one.  If this is the case, change the order of the
   directories in lfiles.ibm6k.make and rerun make INSTALL.  DO NOT change
   lfiles.make; it is written by make INSTALL.
5) SciAn does not run on every IBM system, only on those with graphics 
   accelerators that can do 3-D GL emulation, have Z-buffers, and can 
   do RGB color.


PROBLEM: When I try to run it on the IBM, the wrong menu items appear to 
highlight, and the fonts don't work in text boxes on the screen.

SOLUTION: This probably means that you have compiled under AIX 3.1.5 without
defining MENUSFROM0 in machine.h.  Take a look at machine.h, run "make INSTALL"
again, and try to make again.  This problem is further explained in section
3.3.1.
