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