This directory contains some example uses of Raster3D, which
may serve as confirmation of successful installation or as
models for general use.

Most of the example scripts assume that ImageMagick is installed 
on your system as an image viewer.  If it is, then executing these 
shell scripts should produce an image on your X-windows screen.

There is a small picture gallery of the example images included 
in the HTML documentation  ../html/r3d_examples.html

The ./msms subdirectory contains source code for filters to 
convert molecular surfaces calculated using msms into Raster3D
files, and an example of use.

Example 1
=========

Example 1 illustrates the use of object types 8 + 9 to change the 
material properties for individual objects in the figure.  
It also illustrates using file indirection and the library of 
special materials included in the Raster3D distribution kit.
The library is made known to the system by setting the environmental
variable R3D_LIB.

You can run example1.script or else type something
like:
	setenv R3D_LIB ../materials
	render < example5.r3d | display avs:-          		(ImageMagick)
    or
	render -sgi test.rgb < example5.r3d ; ipaste test.rgb  	(SGI)
    or
	render -tiff test.tiff < example5.r3d			(TIFF file)


Example 2
=========

Example 2 excercises the utilities balls and rods.
example2.sgi is the same as example2.script, except that it
assumes that you are using the SGI libimage utilities as a viewer.


Examples 3, 4, and 5
====================

The 3rd, 4th, and 5th examples provided here correspond to a figure of
the galactose binding site in the E. coli Heat-labile enterotoxin.  
The figure was composed and generated using the program MOLSCRIPT, 
by Per Kraulis.  I have included three files here:

example3.mol	- the MOLSCRIPT input file
example3.ps	- the output from MOLSCRIPT when run in PostScript mode
		  (should be displayable using a PostScript viewer)
example3.r3d	- the output from MOLSCRIPT when run in Raster3D mode

The example3.script will just render and display the example.r3d file.

The example4.script requires that Molscript is installed and
that you have built TIFF support into the Raster3D package. It should
start with the Molscript input file and produce a TIFF file containing 
the same image produced by example3.  If you have Molscript V2.0 you
should see labels in the Raster3D image; earlier versions of Molscript
did not pass labels through to Raster3D.

Example 5 adds a transparent molecular surface around the galactose
molecule in example 3. This is a fairly complicated example which
illustrates merging Raster3D input files created by two different
programs, in this case Molscript and GRASP.   I have included a
Raster3D input file produced from a GRASP V1.1 surface file by a
conversion program. I have not included the actual GRASP file because
the format of such files is both version and machine dependent. A copy
of the "ungrasp" utility program I used for conversion is included in
the directory ../grasp, but you may have to modify this source depending
on your local installation. 
This example illustrates:
	- the inclusion of a molecular surface file
	- the specification of a transparent surface
	- application of a post-multiplied rotation/translation matrix
	- uncompression of a gzipped input file during processing

Note:  It would be a more informative figure if the accessible surface
of the protein were shown, rather than that of the bound sugar.  However
this would have required inclusion of an absolutely huge surface
description file so I judged it impractical.  A JPEG figure illustrating
Raster3D rendering of a protein surface should be available on the
Raster3D distribution site.


Example 6
=========

Example 6 demonstrates the Version 2.5 command line options to render.


Example 7
=========

Example 7 demonstrates support for PostScript labels added to the
render program in version 2.5.  Label commands in the input file are
converted to PostScript while the scene is being rendered. The resulting
PostScript file is fed through ghostscript to produce a raster image 
containing the labels. Finally the two raster images, one containing 
the molecular graphics and the second containing the labels, are 
composited to yield a single image file with both molecules and labels.
This procedure is automated by the label3d script.


Example 8
=========

Demonstrates the creation of a stereo pair using the stereo3d command.
It also illustrates the use of the ribbon command to draw a minimal
representation of the protein backbone.


Example 9
=========

This example shows the use of the Raster3D Termal Ellipsoid Program
(rastep) to display isosurfaces corresponding to anisotropic 
displacement parameters Uij. 
