			PSC P3D 2.2 Release Notes
			-------------------------

Copyright 1992, Pittsburgh Supercomputing Center, Carnegie Mellon University
See the end of this file for further copyright information.

HIGHLIGHTS

The most fundamental change with this release is that the P3D interpreter
now stores geometrical implementation in a much more compact form.  This
will allow models of roughly twice the earlier size to fit in a machine's
physical memory.

There have been numerous improvements to the Motif user interface to
the P3D interpreter.  That interface can now generate flybys of P3D
models, for example.  The interface will also link and run with the
GL renderer on Silicon Graphics and IBM RS6000 platforms.

The DrawP3D library has been improved considerably.  Two interactive
renderers, a version of the Painter renderer and an interface to Silicon
Graphics GL, have been added.  This means that programs calling
DrawP3D can now draw directly to a workstation screen.  Numerous bugs
have also been patched.

MarchP3D has been completely rewritten to take advantage of the new
functionality of DrawP3D, and now uses DrawP3D's isosurface routine
rather than that from the Scry package from Lawrence Berkeley Labs.
This is now a much more useful and flexible tool.  It can, for
example, now do on-screen rotations of the isosurfaces it generates.

The Sun Phigs renderer has been rewritten to match the new version of
Sun Phigs, and will link and run with the Motif or Xview user interfaces.

RELEASE CONTENTS

This directory structure contains version 2.2 of the P3D software and
documentation from the Pittsburgh Supercomputing Center.  If you grab
this software, please send mail to Joel Welling (welling@psc.edu) so
that we can add you to our mailing list for updates and such.  If you
would like to negotiate redistribution rights, we would be glad to
talk about that.

The PSC P3D software has been tested on Vaxes under VMS, DECStations
under Ultrix, Suns under SunOS, Silicon Graphics Personal Irises, 
IBM R6000 workstations, and Crays under Unicos.  We would expect it 
to run on most Unix platforms.  (We no longer have a Stardent Titan
to test that port, but we believe everything should still run there).
If you are interested in porting the software to another platform, 
please contact us.

The directory structure contains:

	directory	contents
	---------	--------

	.		This directory.  After any modifications (see below),
			make should be run from here.

	src		The core software for the P3D model display
			executables.  This includes:

			display-p3d, which allows a model to be
			  rotated and examined.
			render-p3d, which marches sequentially through
			  the views in a model.
			dump-p3d and tdump-p3d, which dump ascii
			  descriptions of models for debugging
			  purposes.

			All of these executables have names using
			underscores instead of hyphens on VMS systems.

	src/painter	A simple painter's algorithm renderer which uses
			the PSC's DrawCGM library and GPlot device driver
			interface.

	src/rayshade	A version of Craig Kolb and associates' Rayshade
			ray tracer (version 3.0, path level 5) interfaced
			to load and render P3D models.  For example,
			models can be previewed with the Painter renderer
			and then ray traced with Rayshade.

	imakestuff	Directory of files needed by 'imake', the Unix
			self-installation facility.  Imake comes from
			the MIT X Window System software distribution.

	load		Directory searched by alisp and the P3D renderers
			for include files.  This directory contains
			several files which determine the behavior and
			defaults of P3D.  If you delete or move this
			directory, the P3D display facilities will not
			work.

	doc		Documentation for P3D, alisp, and various renderers
			and user interfaces.  Other documentation can be
			found in the 'doc' subdirectories of the various
			model builders.

	samples		some sample p3d files, including:
			joel.p3d: tests all the elements.
			planttrans.p3d: a short animation.
			camel.p3d: a Sopwith camel
			LA_r50.p3d:  Landsat image of LA basin (takes a
				few minutes to load)
			(and some others)

	modelbuilders	This directory tree contains programs which can
			be used to generate P3D models, which can then
			be rendered by the renderers provided in the src
			subtree.

	modelbuilders/drawp3d
			This is a fairly general 3D modelling subroutine
			library with functionality similar to that of
			Phigs/Phigs+ or Dore(TM).  It produces P3D output
			files, or generates output images directly via
			a Painter's Algorithm renderer or Silicon Graphics
			GL.  Interfaces are available for calling the 
			package from Fortran and C.

	modelbuilders/flyby
			A simple tool for generating flybys of P3D models
			from position data.  Documentation can be found in
			the doc subdirectory of this directory.  This tool
			is now obsolete;  the Motif user interface to
			the P3D interpreter will do this job better.

	modelbuilders/marching_cubes
			An interface to the Marching Cubes implementation
			in DrawP3D (see below) which produces P3D as
			output or draws directly to a workstation display.
			The doc subdirectory of this directory contains 
			documentation.  This tool provides a convenient
			way to do isosurface extraction from the command
			line.


	modelbuilders/movietop3d
			A translator from Movie.BYU-type model format
			to P3D format.  The translator supports scalar
			fields, displacements, and part coloring.  
			Documentation can be found in the doc subdirectory
			of this directory.

	modelbuilders/pdbmodel
			A program which generates KLM-type space-filling
			molecular models from Protein Database-format
			molecular data.  Documentation can be found in
			the doc subdirectory of this directory.

	contrib		The beginnings of a subdirectory tree for contributed
			code.

	contrib/gleichauf
			Includes a Common Lisp (.lis) file which should
			allow a generic Common Lisp interpreter to parse
			and check the syntax of P3D code.

	contrib/dxf
			This directory includes dxftop3d, a utility for
			converting AutoCAD DXF format to P3D format.  This
			tool was contributed by Alaa Eldin Ibrahim of
			Carnegie Mellon University.


RENDERERS

The P3D software currently supports nine renderers.  They are:

	Painter, a Painter's Algorithm renderer.  This runs on just
	about everything, but requires the PSC's DrawCGM library and
	can only draw flat-shaded polygons.  If you need the DrawCGM
	library, get the GPlot software distribution by anonymous
	FTP from calpe.psc.edu, in the directory pub/gplot.

	Silicon Graphics Inc. GL language renderer interface.  This
	is the recommended renderer for SGI workstations and IBM R6000
	workstations.

	Generic Phigs renderer interface.  This renderer should work with
	only minor modification on any implementation of Phigs, but because
	(like generic Phigs) it does not handle light sources it is not
	the recommended renderer on any platform.

	Sun Phigs+ renderer interface.  This renderer works with
	Sun Phigs.  Try this renderer if you have a Sun platform, 
	and if you don't like the results, switch to the Painter 
	renderer.

	DEC Phigs+ renderer interface.  This renderer should work with
	DEC Phigs.  It is the recommended renderer for DEC platforms
	with 24 bit displays and graphics accelerators, for example
	accelerated DECStation 5000's.  For 8 bit DECStations, one might
	want to try both this renderer and the Painter renderer.

	Dore renderer, which is an interface to the Kubota Pacific Dore
	renderer software.  This is the recommended renderer for
	Stardent workstations.

	Rayshade ray tracer renderer interface.  This renderer is an
	interface to Craig Kolb and associates' Rayshade ray tracer
	(version 3.0, patch level 5).  It produces some very nice images,
	very slowly.  The current implementation is a first release
	of the interaface and does not properly support all P3D
	model elements (for example, vertex colors).
	See the associated document in the 'doc' subdirectory for
	more information on the limitations of the renderer, but don't
	get too discouraged by them;  it can still do an excellent job
	on a wide range of models.  This renderer should run on any
	platform.  The Rayshade renderer also uses the DrawCGM library
	by default, but can be switched to using the Utah Raster Library
	by applying the proper -D option to the compilation of
	src/rayshade/outputp.c .  Note that some optimizing compilers
	have problems with some of the routines in src/rayshade;  if
	you have problems with the ray tracer try recompiling some or
	all of these routines without -O.  This renderer supports
	facilities for doing multiple scenes for animation purposes.

	ART ray tracer interface.  This renderer is an interface to
	the ART ray tracer, distributed with the VORT package.  VORT
	is available by anonymous FTP from gondwana.ecr.mu.oz.au.
	This is currently the best free high-quality renderer for P3D.
	The ART folks have been very generous in supporting new
	features for us, and now almost all aspects of P3D are well
	supported.  This renderer also supports facilities for doing
	multiple scenes for animation purposes.  See doc/art_ren.t for
	further information.  This renderer interface should run on
	any platform.

	Pixar RenderMan interface.  This renderer links against
	Pixar's RenderMan renderer interface to produce high quality
	rendered images.  This software is generally significantly
	faster than a ray tracer, for example ART.  The software was
	developed using Pixar's own Developer's Renderman product, but
	in theory it should work with any renderer with a
	Renderman-compatible interface.  Contact us if you don't have
	the library but are interested in an executable which can
	output models in the RenderMan 'RIB' format.  This renderer
	and Developer's Renderman should run on any Unix platform.


USER INTERFACES

The P3D display software is built using a user interface, which
provides a way for the user to rotate and view a P3D model.  There
are currently eight user interfaces:

	Motif user interface, which works with the Painter renderer
	and is the recommended UI for all platforms supporting Motif
	and using Painter or Silicon Graphics GL.  It runs well on 
	all X Windows systems we have tested it on.

	Open Look user interface, which works with the Painter and Sun
	Phigs renderers and is the recommended UI for all platforms 
	supporting Open Look but not Motif and using Painter.  

	SGI GL user interface, which works with the SGI GL renderer.
	This user interface has been superceded by the Motif user
	interface, but is still the recommended user interface
	for Silicon Graphics machines running versions of IRIX below
	4.0 and IBM RS6000's which support GL but are running AIX
	versions below 3.2 .

	Dore DUI Interface, which works with the Dore Demo User
	Interface software and is the recommended UI for the Dore
	renderer.

	Keyboard User Interface, a simple user interface which uses
	keystrokes to move the object being viewed.  This works with
	all renderers, and is the recommended user interface for the
	Phigs and DEC Phigs+ renderers.

	Flying User Interface, a flight simulator useful in making
	flybys of P3D models.

	Rocket User Interface, a rocket flight simulator useful in
	making flybys of P3D models.

	Trivial User Interface, which is used automatically in
	creating the render-p3d (render_p3d on VMS) utility.


DOCUMENTATION

Documentation for P3D in general and for the P3D display utilities,
renderers, and user interfaces can be found in the doc subdirectory.
Documentation for the various modelbuilders exists in doc subdirectories
within the modelbuilders/* directories.  I am sorry to say that much
of the documentation is in text format, rather than proper man pages
or whatever you might prefer.  Anyone seeking documentation for a
particular aspect of the P3D software is encouraged to contact us
at the electronic mail address at the end of this document.  If anyone
converting documentation to new forms would be willing to add their
work to the distribution, it would be much appreciated.


NEED FOR DRAWCGM

The Painter renderer requires that you have available the DrawCGM
graphics library, which is available free from the PSC, also by
anonymous FTP from calpe.psc.edu in the GPlot software distribution.
In the default configuration, the Rayshade renderer also links against
DrawCGM, although this can be changed when src/rayshade/outputp.c is
compiled.  If DrawCGM is available when the software is built, the
DrawP3D library will be built to allow direct use of the Painter 
renderer.

If you are using an old version of the DrawCGM library with a color X
Windows display (for example, with the Motif or Open Look user
interfaces), you may see that the colors of all other windows become
incorrect when the P3D model is displayed in the correct colors.  The
solution to this is to get the most recent release of GPlot and
DrawP3D from the PSC and relink the executables.  If the problem
persists, try adding the command 'xstdcmap -all' to the top of your
.xsession file.


INSTALLATION UNDER UNIX

The PSC P3D software assembles itself on Unix systems by using the
'imake' utility distributed with the MIT X Window System.  This greatly
simplifies installation on Unix systems.  Imake is just a utility for
making Makefiles with appropriate switches and dependencies.  What happens
is that the normal Unix Make mechanism continues to handle the building
of the utilities, but it now has new targets which recreate the Makefiles
themselves from information in the Imakefiles in the same directory.  
The Makefiles used here also know how to recreate their own dependency
lists, and they do so, since dependencies can vary from machine to
machine.

To install PSC P3D on a Unix machine, do the following:

1)	Read the paragraphs at the end of this section to find out if
	there are any special instructions for your machine type.

2)	Edit the file config.imake in the top-level directory of
	the distribution, filling in the options given there.  This
	involves selecting a renderer and a user interface for the
	main P3D display utilities, and giving path names relevant
	to the installation.  Note that the path to the 'load'
	subdirectory is constructed from the ROOT_PATH you set in
	the config.imake file, and if the files in the 'load'
	subdirectory of this distribution are not found there the
	P3D display utilities won't work properly.  Note that the
	Motif and Xview user interface will only work with the 
	Painter, GL, and Sun Phigs renderers, so for any other
	renderer you must use the Keyboard user interface or
	some other simple user interface.

3)	Execute the command 'make' in the top-level directory.  The P3D 
	software will make itself based on the information given in the 
	config.imake file.  If you wish only to make certain subdirectories,
	execute the command 'make imakestuff/imake imakestuff/mkdepend 
	makefiles'.  This will cause all the right Makefiles to be 
	constructed.  After this is complete, you can change directory 
	to the subdirectories you are interested in and create them by 
	typing 'make' there.

	If you execute 'make' with no arguments in the top level directory,
	the software will be made in three steps.  First all of the
	Makefiles in all of the subdirectories will be produced, using
	the 'imake' utility.  There may be a number of C Preprocessor
	errors during this stage;  they can be ignored.  Second, the
	dependencies lists in the Makefiles are regenerated.  This step
	assures that the right files will be included for your machine.
	Warning messages from the 'mkdepend' utility can be ignored.
	Finally, compilation and linking of the actual code occurs.

	Some parts of the P3D distribution take a long time to
	compile and optimize.  The file isosurf.c in the DrawP3D
	package is a good example.  If your compiler seems to hang
	while working on this file, just wait;  it really hasn't
	crashed.  If your patience runs out, cd to the appropriate
	directory (modelbuilders/drawp3d in this case) and compile the
	module by hand without optimization, then return to the top
	level directory and restart the make.

4)	When you are satisfied that the software has been made correctly,
	execute 'make install' in the top-level directory to cause
	the relevant executables and libraries to be linked into
	the directory you specified for installation in config.imake .

5)	If you want to create executables using more than one combination
	of renderer and user interface, you can do so by repeating the
	appropriate parts of steps (1) through (4).  For example, if
	you want to create a display-p3d executable using the Painter
	renderer and the Motif user interface, and another using the
	Phigs renderer and the Keyboard User Interface, do the following.
	Follow steps (1) through (4) selecting the first pair of renderer 
	and interface, and then change the name of the resulting executable
	from display-p3d to something else in your executable directory.
	Repeat step (1), specifying the second pair in the config.imake
	file.  Proceed through steps (2) through (4), and the new
	executables will exist.  Customary alternate names for display-p3d
	executables are 'mp3d' for the Motif user interface with Painter,
	'olp3d' for the Open Look interface with Painter, and 'glp3d'
	for the Silicon Graphics renderer and interface.

6)	This procedure will make everything in the distribution except
	things in the 'contrib' contributed software tree.  To make
	programs in that tree, see the README files in their individual
	directories.
	

When you modify code in a subdirectory of the P3D software distribution,
always modify the Imakefile rather then the Makefile in the directory.
Then use the command 'make makefiles depend' in the local directory to 
transfer your changes to the Makefile.  This will assure that changes 
are preserved if you later change the config.imake file and do a new 
'make'.

Please note that the P3D renderers depend on special lisp files
(p3d.lsp, func_defs.lsp, p3d_global.lsp and p3d_dflts.lsp) for their
operation.  At execution time, these files are looked for first in the
current directory, and then in the load subdirectory of this directory
tree.  This behavior can be overridden by setting the environment
variable P3DLOADDIR; if this variable is set to a path name that path
is searched instead of the load subdirectory of this directory tree.
This provides a mechanism for running the renderers on machines where
the P3D distribution tree doesn't exist.  See the document
display-p3d.t for information on using your own p3d_dflts.lsp file to
change the default behavior of the renderers.

Installation details for specific machines are as follows.  If your 
machine is not mentioned here, the installation procedure should
proceed exactly as described above.

Ultrix DEC machines:
	Due to a compiler bug, versions of the C compiler on 
	DECStations will not properly compile the modelbuilder 
	DrawP3D below release 4.0 of Ultrix.  If you run into this 
	problem, you might try the GNU C compiler (which is free 
	and does not have this problem).

Suns:	The standard Sun C compiler does not recognize function
	prototypes, and these are used extensively in the modelbuilder
	DrawP3D.  For this reason, DrawP3D does not automatically get
	compiled on Suns.  If you are using a different C compiler,
	such as GNU C (which is free and seems to be substantially
	more capable than the standard Sun C compiler) or a different,
	more capable compiler from Sun, wait until the end of step
	(3) in the installation process and then do the following:

		cd modelbuilders/drawp3d
		make	

	Alternatively, there is a SPARC version of drawp3d.a available
	via anonymous FTP on ftp.psc.edu.

	When using the Sun Phigs renderer, the libraries -llphigs and
	-lphigs must be included in the LIBOPTIONS line of config.imake.
	Unfortunately both libraries are needed to link Sun Phigs with
	the XView or Motif user interfaces, but only the second (-lphigs)
	can be used when linking other user interfaces or render-p3d.
	This means that you must first build display-p3d using both
	libraries, then delete the created render-p3d, modify your
	config.imake to use only -lphigs, and re-make render-p3d as
	described in step (5) of the installation instructions.  Failure
	to do so will result in a version of render-p3d that always
	complains that it doesn't recognize the requested PHIGS workstation
	type.

Silicon Graphics Iris 4D workstations:  
	Unlike most Unixes, the 'make' command on Silicon Graphics 
	machines does not by default use /bin/sh to execute command 
	lines from Makefiles.  If you are using the C Shell, you must 
	set the environment variable SHELL to /bin/sh before beginning 
	the installation procedure.  Do this with the command 
	'setenv SHELL /bin/sh'.

Crays under Unicos:  
	If using the Painter renderer (which you probably will be), 
	specify the DRAWCGM library on the LIBOPTIONS line of config.imake, 
	rather than on the DRAWCGM line.  This avoids the loading of 
	unneeded and unresolved entry points.

Stardent or Kubota Pacific platforms:
	Unlike most Unixes, the 'make' command on Stardent machines 
	does not by default use /bin/sh to execute command lines from 
	Makefiles.  If you are using the C Shell, you must set the 
	environment variable SHELL to /bin/sh before beginning the 
	installation procedure.  Do this with the command 
	'setenv SHELL /bin/sh'.


INSTALLATION UNDER VMS

To install P3D on a VMS system, do the following:

1)	Modify [.src]descrip.mms, [.modelbuilders.pdbmodel]descrip.mms,
	and [.modelbuilders.marching_cubes]descrip.mms according to the 
	internal comments which apply to your case.  This involves 
	specifying file and directory names which need to be compiled 
	into the executables, and providing the locations of any needed 
	libraries.

2)	Find and modify the files [...]*.cld to reflect the locations
	to which you plan to move the various executables.

3)	Return to this directory (the top-level one) and type 'mms'.

	Some parts of the P3D distribution take a long time to compile
	and optimize.  The file isosurf.c in the DrawP3D package is a
	good example.  If your compiler seems to hang while working on
	this file, just wait; it really hasn't crashed.  If your
	patience runs out, cd to the appropriate directory
	([modelbuilders.drawp3d] in this case) and compile the module
	by hand without optimization, then return to the top level
	directory and restart the make.

4)	Move the various executables and [modelbuilders.drawp3d]drawp3d.olb
	to wherever is appropriate on your system.

5)	This procedure will make everything in the distribution except
	things in the 'contrib' contributed software tree.  To make
	programs in that tree, see the README files in their individual
	directories.  You may have to some porting to build these utilities
	under VMS.

Please note that the P3D renderers depend on special lisp files
(p3d.lsp, func_defs.lsp, p3d_global.lsp and p3d_dflts.lsp) for their
operation.  At execution time, these files are looked for first in the
current directory, and then in the load subdirectory of this directory
tree.  This behavior can be overridden by setting the logical variable
P3DLOADDIR; if this variable is set to a directory name that directory
is searched instead of the load subdirectory of this directory tree.
This provides a mechanism for running the renderers on machines where
the P3D distribution tree doesn't exist.  See the document
display-p3d.t for information on using your own p3d_dflts.lsp file to
change the default behavior of the renderers.


COPYRIGHT INFORMATION

This software is copyrighted in 1989, 1990, 1991 and 1992 by Carnegie
Mellon University, of which the Pittsburgh Supercomputing Center is a
department.  You may duplicate and modify it, but you may not
redistribute it to new sites without our written permission.  We do
this to better track the usage of the software.  Neither the PSC nor
CMU make any representation about the suitability of this software for
any purpose.  It is provided "as is" without express or implied
warranty.  Please preserve the documentation and copyright notices in
all copies.

The description of the P3D model description language, found in
the 'doc' subdirectory in various formats under the names
p3d_descr.mss, .doc, and .ps, is also copyrighted in 1991 by
the PSC and CMU.  Permission is granted to copy and redistribute
this document, but not to modify it.  If you are interested in
modifying or extending the P3D format, please contact us so we
can talk about it.

This distribution of P3D uses the 'imake' and 'mkdepend' utilities 
from the MIT X Window System software distribution.  Please see the 
'imakestuff' subdirectory for copyright information on this software.

Cray Research has kindly allowed us to use some of the Silicon Graphics
GL utilities in src/sgigl_utils, while retaining copyright to those
utilities.

AUTHORS

The software in this release was written by myself, Chris Nuuja, Doug
Wagner, Frank Wu, Julie Roskies, Brian Welcker, Brian Kircher, Doug
Straub, Quan Le, and Robert Earhart.  We hope you enjoy it.

-Joel Welling
 welling@psc.edu


