BALLS(1)

✨ BALLS(1) ✨

okay bestie, welcome to the General Commands Manual entry for balls — yes that's really its name, no we are not changing it, it's iconic 💅. This is the Raster3D page, so buckle up 🎀

---

🌸 NAME 🌸

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

---

✨ SYNOPSIS ✨

balls [-h]

so like, balls reads a file describing atom colours and/or a PDB coordinate file, and spits out a file full of Raster3D descriptor records — one for every atom in the input, no cap 🔥. And the file it makes? You can feed it straight to render, or you can mix it with descriptor files from the other Raster3D utilities. Chef's kiss 👑

---

🍓 EXAMPLES 🍓

Wanna describe a simple space-filling model, coloured by residue type? Say less:

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

Wanna bring a pre-selected view matrix along for the ride with that same model? Here's the vibe:

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

Wanna prepend header records describing a pre-selected scale and view? Obsessed with this one:

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

---

💅 OPTIONS 💅

• -h — suppresses the header records in the output. By default balls produces an output file that starts with header records containing a default set of scaling and processing options. The -h flag suppresses those header records so the output file contains only sphere descriptors. This one is for when you're producing files that describe only part of a scene and you're gonna combine them later with descriptor files from other programs 🌈

---

🧚 DESCRIPTION 🧚

The input to balls is a single text file containing colour information and atomic coordinates in PDB data bank format. Coordinates get 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. Also by default, the output file contains a set of header records as required by the render program. That header is constructed to include a TMAT matrix corresponding to the transformation matrix contained in the file setup.matrix (if it exists), or to the Eulerian angles contained in the file setup.angles (if it exists) 🦋

Colours get assigned to atoms using a matching process, using COLOUR records prepended to the input PDB file. Raster3D uses a pseudo-PDB record type 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

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

The Mask field is used in the matching process like this 🎀: 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, searching for a COLOUR record that matches the ATOM/HETA record in all of columns 7 through 30. The first such COLOUR record it finds determines the colour and radius of that atom. Periodt 💅

So that one COLOUR record can serve up colour and radius specs for more than one atom (like, based on residue or atom type, or literally any other criterion where labels can go 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 of an ATOM or HETA record. Every other character has to match literally to count as a match. And heads up — the very last COLO record in the input should have # symbols in all of columns 7 through 30, so that any atom whose ATOM/HETA record fails to match any previous COLOUR record still gets a colour 🫶. This whole idea of matching masks for colour specifications is due to Colin Broughton, king behaviour honestly 👑

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

---

🌈 ENVIRONMENT 🌈

The files setup.matrix and setup.angles, if they exist, affect the header records produced by balls. That's it, that's the whole section 💖

---

⭐ 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) — go read those next bestie, iykyk 🔥

---

💜 AUTHORS 💜

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

---

k that's the whole page! this one's from Raster3D, dated 8 May 1999 — vintage but she still ate 💅✨ bye bestie, go build some molecules 🧚🌸