NAME

       balls - preprocessor for space-filling models in Raster3D molecular graphics package

SYNOPSIS

       balls [-h]

       Balls  reads  a  file describing atom colours and/or a PDB coordinate file and produces a file containing
       Raster3D descriptor records for each atom in the input file.  The file  produced  by  balls  may  be  fed
       directly to render or it may be combined with descriptor files produced by other Raster3D utilities.

EXAMPLES

       To describe a simple space-filling model coloured by residue type:

            cat mycolours.pdb protein.pdb | balls | render > mypicture.png

       To include a pre-selected view matrix with the same model:

            cp  view1.matrix setup.matrix
            cat mycolours.pdb protein.pdb | balls | render > mypicture.png

       To prepend header records describing a pre-selected scale and view:

            cat mycolours.pdb protein.pdb | balls -h > balls.r3d
            cat header.r3d balls.r3d | render > mypicture.png

OPTIONS

       -h

       Suppress header records in output.  By default balls will produce an output file which starts with header
       records  containing  a  default  set  of scaling and processing options.  The -h flag will suppress these
       header records so that the output file contains only sphere  descriptors.   This  option  is  useful  for
       producing  files  which describe only part of a scene, and which are to be later combined with descriptor
       files produced by other programs.

DESCRIPTION

       The input to balls consists of a single text file containing colour information and atomic coordinates in
       PDB data bank format.  Coordinates are output as Raster3D descriptor  records  with  colours  and  sphere
       radii assigned according to the COLO records described below.  By default atoms are assigned CPK colours.
       By  default  the  output  file  contains  a set of header records as required by the render program.  The
       header is constructed to include a TMAT matrix corresponding to the transformation  matrix  contained  in
       file  setup.matrix  (if  it  exists),  or  to  the  Eulerian angles contained in file setup.angles (if it
       exists).

       Colours are assigned to atoms using a matching process, using COLOUR records prepended to the  input  PDB
       file.  Raster3D uses a pseudo-PDB record type with with COLO in the first 4 columns:

          Columns

           1 -  4   COLO

           7 - 30   Mask (described below)

          31 - 38   Red component

          39 - 46   Green component

          47 - 54   Blue component

          55 - 60   van der Waals radius in Angstroms

          61 - 80   Comments

       Note  that the Red, Green, and Blue components are in the same positions as the X, Y, and Z components of
       an ATOM or HETA record, and the van der Waals radius goes in place of the Occupancy.  The Red, Green, and
       Blue components must all be in the range 0 to 1.

       The Mask field is used in the matching process as follows.  First the program reads in and stores all the
       ATOM, HETA, and COLOUR records in input order.  Then it goes through  each  stored  ATOM/HETA  record  in
       turn,  and searches for a COLOUR record that matches the ATOM/HETA record in all of columns 7 through 30.
       The first such COLOUR record to be found determines the colour and radius of the atom.

       In order that one COLOUR record can provide colour and radius  specifications  for  more  than  one  atom
       (e.g.,  based  on residue or atom type, or any other criterion for which labels can be given somewhere in
       columns 7 through 30), the "#" symbol is used as a wildcard. I.e. a # in  a  COLOUR  record  matches  any
       character  in  the  corresponding  column  in  an  ATOM  or HETA record.  All other characters must match
       literally to count as a match.  Note that the very last COLO record in the input should have # symbols in
       all of columns 7 through 30 in order to provide a colour for any atom whose  ATOM/HETA  record  fails  to
       match  any previous COLOUR record.  This idea of matching masks for colour specifications is due to Colin
       Broughton.

       Several files of COLOUR records, including one based on Bob Fletterick's  "Shapely  Models"  and  another
       mimicking CPK model parts, are provided as samples.

ENVIRONMENT

       The files setup.matrix and setup.angles, if they exist, affect the
            header records produced by balls.

SOURCE

       anonymous ftp site:
             ftp.bmsc.washington.edu

       web URL:
             http://www.bmsc.washington.edu/raster3d/raster3d.html

       contact:
             Ethan A Merritt
             University of Washington, Seattle WA 98195
             merritt@u.washington.edu

SEE ALSO

       render(l), rods(l), ribbon(l)

AUTHORS

       Originally written by David J Bacon and Wayne F Anderson.
        Extensions and revisions by Ethan A Merritt.

Raster3D                                           8 May 1999                                           BALLS(1)