%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%     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)
	-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:

#
# Use Raster3D rendering program as a delegate for files ending in .r3d
   r3d=>
	   render -tiff %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/

linux
=====
Works fine under Redhat 6.x and Mandrake 7.1
There were some gotchas under earlier earlier Redhat versions, however:
	- The pre-built linux binaries for ImageMagick 3.8.8 got confused
	  by the byte order in AVS files.  To work around this problem I
	  added a conditional compilation flag -DNETWORKBYTEORDER
	  
In Redhat 6.1 "f77" is a symlink to the g77 compiler. The package works
when compiled with g77, but runs slower than it does when compiled by a
better compiler (e.g. Portland or DEC).  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. Do yourself a favor and buy a Portland compiler license.

Mandrake 8.0 contains a version of libtiff.so with no support for LZW
compression.  This makes your output tiff files much larger than they ought
to be.  Blame it all on Unisys, who are being litigious about use of LZW
compression.  If this is a problem, you can build your own libtiff from
any source distribution with version <= 3.3.2


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 ===

Many thanks to Suhaib Siddiqi, who offers the following recipe for 
building Raster3D under Windows:

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.


