Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
BALLS(1)		    General Commands Manual		      BALLS(1)

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

       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.

       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


       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 descrip-
       tors.  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.

       The input to balls consists of a	single text file containing colour in-
       formation 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 transforma-
       tion 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:


	   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 specifi-
       cations 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	pro-
       vide a colour for any atom whose	ATOM/HETA record fails to match	any
       previous	COLOUR record.	This idea of matching masks for	colour speci-
       fications is due	to Colin Broughton.

       Several files of	COLOUR records,	including one based on Bob Fletter-
       ick's "Shapely Models" and another mimicking CPK	model parts, are pro-
       vided as	samples.

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

       anonymous ftp site:

       web URL:

	    Ethan A Merritt
	    University of Washington, Seattle WA 98195

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

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

Raster3D			  8 May	1999			      BALLS(1)


Want to link to this manual page? Use this URL:

home | help