			     
			     SURF 
                             ~~~~	

			 VERSION 1.0
                    Author: Amitabh Varshney
			  1992-1994

The source code for SURF is copyrighted by the original author and the 
University of North Carolina at Chapel Hill. Permission to use, copy, 
modify, and distribute this software and its documentation for educational, 
research, and non-profit purposes is hereby granted, provided this notice, 
all the source files, and the name(s) of the original author(s) appear in 
all such copies.

BECAUSE THE CODE IS PROVIDED FREE OF CHARGE, IT IS PROVIDED "AS IS" AND
WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED. 

A Note from the Author:
~~~~~~~~~~~~~~~~~~~~~~~
Although I have written the code, the ideas used in this program have 
evolved over a course of three years of lively weekly discussions with 
Professor Frederick P. Brooks, Jr. (my advisor) and Professor William 
V. Wright. Of course, any bugs that might still be lurking in the 
program are solely my responsiblity. I would like to hear about them,
so please send me some email at: varshney@cs.unc.edu. 

People I would like to acknowledge for their time, help, and/or useful 
discussions during this project are: David Richardson (Duke), Dinesh 
Manocha (UNC), Pankaj Agarwal (Duke), Jan Prins (UNC), Mark Surles (SDSC), 
Larry Bergman (IBM), Lynn Ten Eyck (SDSC),  Mike Pique (Scripps)
Victoria Roberts (Scripps), the GLAB Hackers Inc. @ UNC and scores of
others, who I might be forgetting at this moment.

If you are using this code, I would really appreciate it if you could
kindly send a brief email/note regarding this fact to Professor Brooks
(brooks@cs.unc.edu) and/or Professor Wright (wright@cs.unc.edu). It helps 
us in our grant reviews.
  
-Amitabh 
March 16, 1994.

Installation:
~~~~~~~~~~~~
To install this, simply do a 
% make depend	------- this will set up the dependencies correctly
% make surf     ------- compiles the whole system

The whole thing will take just under a Megabyte of space.

Preparing the Input:
~~~~~~~~~~~~~~~~~~~~
Since .pdb files are such a pain to parse, I have adopted the following format 
to be read in by the system:

The input file consists of one line per atom. The entries
in each line are organized as follows:

<atom_id> <atom_radius> <atom_center_x> <atom_center_y> <atom_center_z>

I am appending the first few entries of a sample file for crambin. The program 
right now ignores all the <atom_id> values in the input file but in the output 
it tags each triangle with the sequential location of its atom position in the 
input file. I am planning to change this so that the triangle tag matches the
atom-id field in the input, but haven't done it yet. At present it would 
be best to just sequentially number the atoms in their <atom_id> field 
(as in the sample crambin file). 

-------------------begin crambin .pdb file ------------------
ATOM      1  HN1 THR     1      17.017  14.972   4.068
ATOM      2  HN2 THR     1      16.297  13.912   2.883
ATOM      3  N   THR     1      16.982  14.095   3.587
ATOM      4  HN3 THR     1      17.707  14.470   3.008
ATOM      5  CA  THR     1      16.949  12.808   4.348
ATOM      6  C   THR     1      15.686  12.779   5.142
ATOM      7  O   THR     1      15.236  13.827   5.603
ATOM      8  CB  THR     1      18.140  12.771   5.349
ATOM      9  OG1 THR     1      19.304  12.851   4.478
ATOM     10  CG2 THR     1      18.163  11.585   6.283
.....
-------------------end crambin .pdb file ------------------

----begin system input file-------------
0 1.00 17.017 14.972 4.068
1 1.00 16.297 13.912 2.883
2 1.75 16.982 14.095 3.587
3 1.00 17.707 14.470 3.008
4 1.85 16.949 12.808 4.348
5 1.85 15.686 12.779 5.142
6 1.60 15.236 13.827 5.603
7 1.85 18.140 12.771 5.349
8 1.60 19.304 12.851 4.478
9 1.85 18.163 11.585 6.283
.....
----end system input file----------------

You could write an awk script for this conversion, or use a program like the 
pdbtoview available from ftp.cs.unc.edu in directory pub/VIEW/Binaries. This
was written by Larry Bergman while he was at UNC-Chapel Hill. The documentation
regarding this is in pub/VIEW/Documentation.

A crude awk script to just get you started (it is not fail-proof and you will
have to change $3, $6, $7, $8 in the script below depending on the pdb file)
without the pdbtoview program appears next.

--------------begin awk script-------------
BEGIN {
  radius["H"] = "1.00";
  radius["N"] = "1.75"; 
  radius["C"] = "1.85"; 
  radius["O"] = "1.60"; 
  radius["S"] = "2.00"; 
  count = 0;
}
{ 
  print count, radius[substr($3,0,1)],$6, $7, $8;
  count++;
}
END {
}
------------------end awk script------------



Command-Line Parameters:
~~~~~~~~~~~~~~~~~~~~~~~~
-R flpt         This allows one to set any desired probe radius. The default
                is 1.4 angstroms, the radius of a water molecule.

-E flpt         This is the maximum edge length of any output triangle. The
                triangles are first generated and then recursively subdivided
                till all their edge lengths are less than or equal to this 
                threshold length. This default length is MAX_TESS_LEN == 1.2
	        (in surf.h)

-W              Controls the triangle writing stage. There are three options 
                for this: 
-W 0            This prevents any output generation. All triangles are computed
                (including recursive subdivision), but none are written out.
                This is just to get timings for surface generation program and
                to get a feel for how fast this would be if directly hooked
                up to a graphics workstation. This is the default if "-W" option
                is not specified.
-W 1            This option keeps writing out the triangles as they are generated.
                The advantage of this method is that it doesn't use any memory for 
                storing the triangles.
-W 2            This generates and keeps storing the triangles in an internal
                buffer and writes them out at the end. This is useful for
                separating the surface generation stage with the triangle 
                output stage. If this is used, it prompts the user for the 
                size of the internal buffer to be used (the input to be given
                is the number of triangles in units of a thousand). As an 
                example, for R = 1.4, E = 1.2 (the default values), the surface 
                for crambin (396 atoms) consists of 18.2K triangles. Thus the
                dialog goes as:
		% surf -W 2 crambin
		  Maximum expected size of the output surface (in thousands of tris): 19
                  ...etc.

-T int		This takes in the expected size of the ouput surface in thousands 
                of triangles. This instead of the above, you could simply give:
		%surf -W 2 -T 19 crambin

-C              This just turns on a few extra checks here and there. 

Output Format:
~~~~~~~~~~~~~
The program outputs triangles in the following format:
<atom_id>
<coord0_x> <coord0_y> <coord0_z> <normal0_x> <normal0_y> <normal0_z>
<coord1_x> <coord1_y> <coord1_z> <normal1_x> <normal1_y> <normal1_z>
<coord2_x> <coord2_y> <coord2_z> <normal2_x> <normal2_y> <normal2_z>

The output file name is assumed to be the input file name suffixed with
".tri".


Publications: 
~~~~~~~~~~~~
The following publications are directly related to SURF and could be referred
to for understanding the algorithms and workings of the system.

   ``Linearly Scalable Computation of Smooth Molecular Surfaces",
   A. Varshney, F. P. Brooks, Jr., and W. V. Wright, IEEE Computer Graphics
   and Applications, September 1994 [invited submission].

   ``Interactive Visualization of Weighted Three-dimensional Alpha Hulls",
   A. Varshney, F. P. Brooks, Jr., and W. V. Wright, accepted in the Third 
   Annual Video Review of Computational Geometry to be presented at the 
   Tenth Annual Symposium on Computational Geometry, Stony Brook,
   NY, June 6--8, 1994.

   ``Fast Analytical Computation for Richards's Smooth Molecular Surface",
   A. Varshney and F. P. Brooks, Jr., IEEE Visualization '93, eds. G. M. Nielson 
   and D. Bergeron, San Jose, CA, October 25--29, 1993, pp 300-307.

Following technical reports are also relevant. They are available from
the Department of Computer Science, University of North Carolina at
Chapel Hill, Chapel Hill, NC 27599-3175 or via anonymous ftp to 
ftp.cs.unc.edu (152.2.128.159) in the directory pub/techreports.

   ``Bounding the Number of Unit Spheres inside a larger Sphere",
   A. Varshney, W. V. Wright, and F. P. Brooks, Jr., Technical Report TR-93-039.

   ``Fast Analytical Computation of Richards's Smooth Molecular Surface",
   A. Varshney and F. P. Brooks, Jr., Technical Report TR-93-002.
