%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%     To install Raster3D       %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The installation process for Raster3D has changed in version 2.6 so
that a single set of Makefiles is shared by all platforms.
User configurable options are contained in two files:
   	Makefile.template	select or deselect TIFF, JPEG, etc support
	parameters.incl		array bounds

1) inspect Makefile.template to make sure that it is appropriate for your site,
   and possibly edit the file to enable or disable the following options:

   	-tiff	enabled by default (TIFF output)
	-jpeg	enabled by default (JPEG output)
	-png	enabled by default (PNG output)
	-sgi	disbled by default (SGI libimage output)
	-out    enabled by default (output piped through ImageMagick)
	GUNZIP	enabled by default (auto-decompression of input files)

2) Configure the Makefiles for your operating system.
	make help	gives a list of supported OS options
	make OS		(OS is your operating system name) configures things

3) Build the programs
	make all

4) Install the package
	make install

5) Add R3D_LIB to your system-wide initialization of environmental
   variables, or instruct users to insert one of the following into their
   login shell initialization. If you change the installation location
   to something other than /usr/local/share/Raster3D then you need to
   modify the examples below accordingly:

	csh/tcsh:	setenv R3D_LIB /usr/local/share/Raster3D/materials

	sh/ksh/bash:	R3D_LIB=/usr/local/share/Raster3D/materials
			export R3D_LIB

   These commands are provided in files Raster3D.csh and Raster3D.sh
   Depending on your system configuration, it may be sufficient to simply
   copy these two files into directory /etc/profile.d

6) [Optional] If you have ImageMagick version 4.1.8 or newer installed, you
   may want to teach it how to use the Raster3D rendering program as a 
   delegate.  You can do this by adding lines at the end of the file
   /usr/local/share/ImageMagick/delegates.mgk   as shown below:

# Version 4.x of ImageMagick used a private format for the delegate file
# Use Raster3D rendering program as a delegate for files ending in .r3d
   r3d=>
	   render -tiff %o < %i

# Versions 5.x and 6.x of ImageMagick uses XML for the delegate file
# Use Raster3D rendering program as a delegate for files ending in .r3d
   <delegate decode="r3d" command='render -png "%o"<"%i"' />


7) Go to the examples subdirectory and try running the example scripts
   to verify installation.

A sample installation on a DEC Alpha might go:
	vi Makefile.template           # check options and installation directories
	make dec                       # configure
	make all                       # build the programs
	make install                   # install them
	cd examples                    # run the demo/verification scripts
	./example1.script
	./example2.script
	./example3.script
	... and so on ...

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%       Known Problems          %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Digital Unix
============
Everything is fine under DU 4.0D and above.  The "-r8" compiler option
forces double precision arithmatic, which slows down rendering by 
approximately 7%.  Some image quality degradation is noticeable if you
settle for single precision.

Irix
====
"make irix6" uses the new f77 compiler (-mips 3), which produces 
code for render that runs about 30% faster.  
Under Irix 6.1 6.2 6.4, you may have to fiddle with the library search 
paths to bring in compatible versions of the libimage, libtiff, and libjpeg 
libraries.
Works with no fiddling under Irix 6.5

Some versions of Irix 6 include self-incompatible versions of 
libjpeg.h and libjpeg.so.  To work around this there is a conditional
flag in local_jpeg.c triggered by adding the definition -DBROKEN_LIBJPEG
in Makefile.template. Or just obtain and build a correct version of libjpeg.so
from the independent JPEG development group ftp://ftp.uu.net/graphics/jpeg/

Irix 6.5 contains an ancient, beta-test, version of the PNG library.
You will have to choose between disabling PNG support in Makefile.template
or obtaining and installing a more recent version of libpng from
     http://www.libpng.org/pub/png/libpng.html

linux
=====

The Makefile knows about 3 compilers for linux.
g77  - "make linux" The package works when compiled with g77,
but runs slower than it does when compiled by a better compiler.
pg77 - I have included another configuration option "make linux-pgf77"
that can be used with the Portland Group compiler.  It produces faster code,
and correctly supports the auto-delete option for scratch files.
gfortran - "make linux-gfortran" The newer gcc Fortran front end is better
than g77, but has not yet settled down into a stable version. I suspect
we will be seeing version incompatibilities for a while.

Sun
===
Makefile.sun assumes you are using the g77 compiler.  As such it suffers
from the same problem as under linux - no support for autodeletion of
scratch files.  If you are worried about space in the system temp directories,
you could comment out -DGUNZIP from Makefile.template
On the sun machine I used for tests the -DTIFF_INVERT flag was required
for proper image orientation.  I don't know how general this is, but I
made it the default.

HP
==
No reported problems, but I don't have access to this platform so 
I haven't checked the package myself.  If you can confirm that it works
as distributed, I'd appreciate the information.  If you had to make
changes, I'd be even more appreciative if you'd let me know what they
were so that I can fix the distribution accordingly.


=== OS/2 ===

Uwe Baumert reports the following:

>> I'm pleased to say that I was also able to compile your Raster3D package
>> under OS/2 (Linux will follow). I used f2c 19970211. I had to modify some
>> code (I got wrong iocontrols etc.).  
[EAM - He means the CARRIAGECONTROL option in the normal3d.f OPEN statements;
just delete these two lines from the source code].
>> I compiled against the libtiff-library (version 4.2). I used the one that
>> was included in the NETPBM-Port of Peter Meerwald (pmeerw@cosy.sbg.ac.at)
>> and is available from
>>    ftp://ftp.leo.org/pub/comp/os/os2/leo/graphics/netpbm*.zip. 


=== Windows ===

Suhaib Siddiqi has kindly provided a pre-built set of Raster3D executables
for version 2.6c, which is available from the Raster3D web site.

If you want to build Raster3D from source under Windows, I can't help you.
But here is a recipe that Suhaib provided earlier for builing with the
cygwin environment. (I gather that he used a different procedure 
altogether when building 2.6c but I do not know any details).

>>  I have successfully compiled Raster3D 2.4g on Windows NT/95/98.  It is a
>>  direct port of your source code without any modifications or deletions.
>>  
>>  1) Go to http://sourceware.cygnus.com/cygwin
>>  2) Download G77 and ObjectC in addition to Cygwin-B20
>>  3) Unmount C drive (umount -a /) and remonut as binary (mount -b c: /).  It
>>  is very important.
>>  4) Install Cygwin-b20 in C:\usr, instead of default directories.
>>  5) Download Cygwin-B20
>>  6) Download Jpeg, PNG and TIFF libraries from ftp.uu.net
>>  7) Compile Jpeg,PNG and TIFF with Cygwin-B20 and install
>>  8) Install all the jpeg and tiff libraries in /usr/local
>>  9) download Raster3D source code and etxract using tar utility supplied with
>>     Cygwin-b20. Download Raster3D_xxx.gz (rather than .Z) as
>>     Cygwin-B20 only handles gzip compression.
>>  (Note: Don't use WinZip or any other Windows programs to extract archive of 
>>  Raster3D and JPEG etc libraries otherwise you will get parse errors during 
>>  compilation). 
>>  
>>  Please let your users know that they will also need to download compiled
>>  binaries of Image Formate Libraries from http://www.sgi.com - Go to OpenGL
>>  web pages and look for OpenGL Optimizer Version 1.1 download site.  You will
>>  find Image Formate Libraries for Windows there.  I used these libraries
>>  together with libjepg.a and libtiff.a for linking.  They produced better
>>  results - that is images were of better quality.
>>  
>>  To use Raster3D from /usr/H-i586-cygwin32/bin copy cygwin1.dll to Raster3D
>>  directory and include Raster3D to your Windows enviroment.  That is it.
>>  
