This manual should tell you what you need to know to start using PovChem. You can download version 1.00 of PovChem by following this link!
PovChem is really designed for small molecules, but works equally well even on whole proteins. There are three basic model types available, that should be familiar to organic chemists: CPK, ball and stick, and cylinder. The user can choose between several coloring schemes, including coloring by element type and coloring by residue name and other sequence information in the PDB records. The program can search the model for hydrogen bonds and include those in the picture. PovChem tries to find a good viewing angle so that as much of the molecule as possible will fit in the picture. Finally, the user can create a stereo pair for three-dimensional viewing.
There is a basic facility for setting up the view of the molecule: PovChem can be used to call POV-Ray to generate a preview image, and then allows the user to do simple rotations, translations, and zooms so that the molecule can be set at a good viewing angle before creating the larger finished picture. Of course, given a little knowledge of POV-Ray's control language, the user can easily modify all the elements that PovChem sets up, in order to tailor the picture more precisely, to add interesting backdrops, new textures, fancier lighting, etc... With all of POV-Ray's sophisticated features, the scope of what can be created depends only on the user's imagination.
With the configuration file and the
"-default" command-line option, PovChem
can be run non-interactively, using the options specified by the user. This will
make it easy to use to render a long series of frames, say for an animation, that have the same model type and coloring.
Input: PDB Format
More information on the PDB
format can be obtained directly from Brookhaven National Laboratory, reproduced here in a text file
of the PBD format. PovChem uses the
3-d atomic coordinates, the atom name
to determine the element, and can use residue, chain, and sequence information
for coloring options. ATOM and HETATM records are treated identically, and
CONECT records are read to determine bonds and bond orders. Although PovChem can
calculate hydrogen bonds, HYDBND records are currently ignored. All data up to
and END record are used.
I chose PDB originally because it was the only format supported in common by
all the chemical software my research group uses. But since then, I have
discovered other advantages, mainly in the ability to use residue and sequence
information supplied in the PDB format to make more powerful coloring schemes
easily available. The disadvantages are that bonds (atom connectivity) and bond
order information are not always supplied, and that sometimes (with the
old-style format) the element of a given atom is a bit ambiguous. I have tried
to make PovChem flexible in recognizing elements by the atom names, but it is
not 100% guaranteed to work.
Output: POV-Ray Scene File
Currently, PovChem's output is written for POV-Ray
2.2, and should be fully supported by future versions of POV-Ray. (Once version 3 is out, I may include
features specific to that version.) Because the molecules are created entirely
out of simple, highly optimized objects - spheres and cylinders - the scenes are
quick to trace even for fairly large molecules. See below
for more information on how to take advantage of the scene definition that
PovChem creates.
I chose POV-Ray as the graphics engine
for several reasons. One, it's perhaps the best raytracer available, and it's
free! Its many advanced features (most of which PovChem doesn't use) allow the
chemical models to be incorporated into more sophisticated and artistic scenes.
Two, by letting the raytracer do all the hard work, I save myself the trouble of
writing any graphics code, which would be beyond my ability and time
availability, anyway. Three, this system allows you to make an image of any
size, from thumbnails for Web pages up to enormous files for pulibcation quality
printouts or even posters.
What PovChem Doesn't Do
PovChem is entirely text-based, because I don't have time to write graphics
code, and more importantly, so that it will be portable to any machine. So,
there is no nice graphical user interface, no ability to pick atoms, edit a
color palette, or otherwise manipulate your model beyond the basic questions
PovChem asks, and the information set in the PDB file and configuration files.
There are at least three major limitations to PovChem at the moment. First, it depends on the presence of CONECT records - connectivity information in the PDB file - in order to do ball and stick or cylinder models. In the Protein Data Bank and in the output of many molecular modeling programs, CONECT information is not specified for standard amino acids and nucleic acids, and so the desired model type may not be possible. There are programs, Babel in particular, that will create CONECT information for any PDB file, and such programs can often be used to fill this lack. Check the included Babel documentation. I might eventually include a bond calculator so that this step will be unnecessary.
Secondly, PovChem only creates "real" chemical models. Meaning, it does not do any schematic representations like ribbons for helices or sheets, or straight bars for DNA base pairs as are often seen in pictures of large molecules. It builds a model atom by atom, as is usually desired by chemists who deal with smaller molecules. I cannot forsee ever including such schematic ability in PovChem.
Lastly, PovChem does not set up anything but the chemical model. It does not
do "artistic" things like put in neat sky backgrounds or textured
surfaces. This is left entirely to the user, and as such, requires some
knowledge of POV-Ray's language to create.
However, I have spent a lot of time making PovChem's scene files easy and
intuitive to modify so that such artistry can be smoothly added to the scene,
and so that details of color, atom size, lighting, and so on can be adjusted
with minimal effort. See below for more on this.
Features in Future Releases
This is just a list of feature I have in mind that someday may be included in
PovChem. Please, give me your
suggestions on what else you'd like to see.
I will post bug fixes occasionally, so be sure to download the very latest
version and check it before reporting to me.
Known Bugs
See the "what PovChem doesn't do" section for
some features unavailable. Other bugs will be listed here as they are
discovered.
If you get a message that says "MAX_BONDS_PER_ATOM exceeded ...",
this is not a bug. All you need to do is set MaxBondsPerAtom in
the configuration file (usually povchem.cfg) to a higher value.
Bugs Fixed
I have discovered a few bugs in version 0.500, which should be fixed in 1.0.
Please notify me of any new bugs you discover.
Distribution Information
Version 1.0 has all the main features that PovChem will have in the forseeable
future, although I am still open to suggestions on features I may not have
thougt of. The comments and response I have received so far, based on version
0.500 and my graphical preview page, have been
encouraging, and I hope that people will want to use the program. This release
is the culmination of a year of work, and I hope that it satisfies the need for
high-quality, easy-to-generate chemical visualiztion. Please, by all means, let me know what you think!
Legal Stuff
I have decided to make PovChem free for any use, commercial or otherwise. But it
is still copyrighted; neither the compiled program nor any part of the source
code may be sold for profit.
DISCLAIMER: I make no guarantees that PovChem will perform perfectly. If you use it, you are agreeing that I cannot be held liable for any losses incurred by the use of PovChem. You are also agreeing to abide by all applicable copyright laws.
Please do not distribute PovChem in any way without my permission. I don't mind its being put into archives, but I would like to negotiate this personally if you would like to do so.
PovChem may not be distributed at all if it is modified in any way from my
own distribution. No part of the code may be incorporated into other programs
without my permission. All copyright laws are applicable.
Machine Requirements
I will provide binaries for PC's, SGI Irix 5.x, and hopefully Mac. I will make
the source code available so that PovChem should be usable on any machine with
an ANSI C compiler. This is an entirely text-based program with no graphics, so
there should be no problem with portability. I have tried to make PovChem
memory-efficient; a 6000-atom protein requires about 450k memory to create a
ball and stick or cylinder model; CPK models take almost no memory no matter how
big the molecule. (Insufficient memory is more likely to be a problem when
running POV-Ray on large molecules.) Of
course, some machines may not be able to view the images created in full the
24-bit color that POV-Ray uses, and you may
be required to convert into an 8-bit format (such as GIF) before you can view
them.
Compiling PovChem
At this point, compilation should be trivial since PovChem is contained in a
single C program file. Please contact me if you have source-file-related
problems compiling it with an ANSI C compiler; I cannot help you with the
specific context of your compiler, but a typical UNIX-ese command line is
"cc povchem.c -o povchem -lm" and should be all that is necessary most
of the time. (The "-lm" is needed to link in the mathematical library
and may have a different syntax on different compilers.)
See the Known Bugs section for a fix of a minor
error that shows up with some compilers.
The PovChem Source Code
PovChem is written in ANSI C and should be portable to any machine.
You should not need to change the source at all in order to compile PovChem and start working with it; the default options are no longer in the source, and have been moved to a configuration file. There are a very few options that can be changed regarding the size size hydrogen bonding element lists and some floating point type definitions. But unless PovChem gives you an error message about these when you run it, these options should not need to be changed.
I do not make any claims as to the quality, efficiency, or readability of
this source code! :) I am not a professional programmer, nor have I commented
heavily (yet). You are free to read it, play with it, modify it for your own
purposes, but you may not distribute a modified form in any way, nor may you use
my code in other programs without my permission.
The PovChem Mailing List
Currently, everyone who has contacted me about PovChem is on my e-mailing list
through which I will provide information about major releases and other
important news about PovChem. If you wish to be added to or removed from this
list, just contact me with your
request and your e-mail address.
Running PovChem: Main Features
Running PovChem is easy. When run without command-line
arguments, the program asks a series of questions about what type of model
you want, how it should be colored, and how to set up the view. See below for
more details on individual options and on how to create the
picture.
Of course, you will need a pdb file for PovChem to read. Just type in the name of your file when asked; PovChem assumes that the filename ends with ".pdb", so if you enter "molecule", PovChem will look for a file called "molecule.pdb".
PovChem can also be run non-interactively so that it can be used in batch
files to process a large number of molecule scenes without requiring the user to
answer the same questions over and over. All the options available in
interactive mode are still available via the configuration
files. See the section on animations for more
detailed information.
Command-Line Options
There are three command line options to PovChem. They can all be used
independently of each other, and in any order. In each case the second word of
the option is any filename, and can be a full path. If no path is given, PovChem
looks for the file in the current directory.
Details instructions concerning the options available, their values, and
their format, are in the comment sections of the files themselves, so consult
them for more specifics.
The Periodic Table
A periodic table, by default in a file called "periodic.tab", must
be present for PovChem to run. Alternate filenames can be specified on the command line, or in the configuration
file. This file defines the Z-numer, name, symbol, van der Waals radius, and
color for each element in your molecule. Note that every element in your PDB
file must be defined in the periodic table or odd results may be obtained!
The Configuration File
The main idea behind this file is to allow PovChem to run without asking the
user questions about the setup. All the features available through the
interactive questions are available as user-definable options in the
configuration file. There are also a few options that can only be changed via
this file. By default, PovChem looks for the file "povchem.cfg", but
the filename can be changed by a command-line option.
Note that the configuration file is not strictly necessary and PovChem will
run without it, but you will be greatly limited in the types of uses to which
PovChem can be put.
The Three Model Types
The first and most important question PovChem asks is about what type of model
you want to build - that is, how do you want to portray atoms and bonds? There
are three models that are most familiar to organic chemists: CPK,
Ball and Stick, and Cylinder.
See below for what each of these are and the options associated with them.
The CPK Model
CPK (sometimes called "space-filling") is the simplest of the models.
Each atom is a sphere of the element's van der Waals radius. Because these atom
spheres are large and overlap each other, no bonds are visible. This is the best
model to use if you want an overall feel for the shape and surface of the
molecule.
Note that for many elements a scientifically accurate van der Waals radius is
not available. I have tried to use reasonable values for all atoms, and
published values whenever possible. But especially for atoms like metal ions of
different oxidation states, the default radii may need some tinkering to suit
what you think is a good size.
Atom Colors
The next three items deals with how the atoms are colored. Note that this
applies to all the models, not just CPK. In all cases, default colors are
assigned, but may easily be changed to suit your taste. See the next section,
and the section on working with PovChem's scene files for
details on how to change these colors.
Color by Element
Coloring by element, as the name implies, makes atoms of each element a
particular color - such as the usual red for oxygen, blue for nitrogen, white
for hydrogen, etc. Default colors for each element are supplied in the periodic table. For the most common elements, I have
supplied colors that, in my experience, have been typical for that element. If
there is an element in the PDB file that is not defined in PovChem's periodic
table, odd results may be obtained! In such a case, you must add that element to
the periodic table yourself, by manually editing the file and following the
format of the rest of the table.
Color by PDB Fields
This coloring scheme is the most complicated, and in my opinion, the most
powerful. The basic idea is to take information in the PDB fields about residue
name, sequence number, and chain ID, and assign colors based on these fields or
combinations of these fields.
This allows quite a range of information to be portrayed visually. So for instance, if you color by residue, each amino acid in your protein will have a particular color, allowing the quick visualization of what amino acids are placed in what regions of the protein. Or for multi-component proteins, each chain can be colored separately so you can quickly see the different domains of the protein.
Currently there are four built-in PDB fields (and combinations) that can be used to assign colors:
See the section on color assignment where I
describe how colors are assigned once it has been determined what to assign them
to.
How PDB-Based Colors Are Assigned
When atoms or bonds are colored by PDB fields, the
selected fields for each atom are composed into a color tag. These color tags
are put into a dynamic list (currently in the order in which they appear in the
PDB file). When the list is done - that is, when the whole PDB file has been
read and all atoms have been assigned a color tag - then actual colors are
assigned to these tags. The colors vary in a gradient spanning the list, going
from red, to green, to blue, then back to red. Since PDB files usually have
their residues appearing in the order of their chemical sequence, this gradient
coloring can give nice smooth shifts of color.
This color assignment is pretty crude at the moment, but is a simple way to
automatically generate a possibly large number of colors. Someday I hope to have
a more sophisticated user-modifiable color assignment scheme.
Color All the Same
Obviously this just makes the whole molecule one solid color. PovChem will ask
you for a color made up of three (red,green,blue) values from 0.0 to 1.0.
Ball and Stick Model
The Ball and Stick model is made up of spheres for atoms, connected by cylinders
for bonds. This is perhaps the most flexible format PovChem can use because
atoms and bonds can be colored independently if desired. So you can do things
like color atoms by element to show chemical information, and color bonds by
residue to show sequence information simultaneously. This can be a very powerful
visualization technique.
You will be asked to specify both ball and stick radii. There are options for
both: ball radii can either be constant for all atoms, or proportional to their
vdW radii. Stick radii can either be constant, or thicker for higher bond order.
Atom Colors
Atom coloring is exactly the same as CPK atom colors.
Bond Colors
Stick coloring is also the same as CPK atom colors,
with the option of using the same colors as the atoms, or coloring
independently.
When coloring sticks (or cylinders in the Cylinder model) by element or by PDB field, the colors at either end of the stick may be different, so now you have to decide where the color will change. There are currently three options:
Note that currently HYDBND records in the PDB file are ignored. Also,
hydrogen atoms must be present for this to work; usually hydrogens are not
specified in Protein Data Bank entries. You'll have to add them yourself with
your favorite molecular modeller.
Bond Order
Only in the Ball-and-Stick model is bond order
relevant. Multiple bonds (i.e. double, triple, and anything higher) are
portrayed simply by thicker sticks. The increase in thickness is specified in
the configuration file as a multiplier. For
instance, if the "DoubleFactor" variable is 1.5, a double bond will
have a radius 1.5 times that of a single bond.
Caveat: Bond order is not formally defined by the PDB format! PovChem uses the number of CONECT statements between two given atoms to determine the order, and some molecular software packages treat bond order this way. But most of the time, each bond is represented as two CONECT statements - one saying "A is bound to B" and another saying "B is bound to A", so generally PovChem will internally consider all bonds to be double bonds.
I realize this is not really a satisfying way of presenting multiple bond
order, but the geometrical issues involved in making two- or three-cylinder
bonds were just too complex, especially since bond order is almost never
specified in PDB files anyway.
Cylinder Model
The Cylinder model is really a subset of Ball-and-Stick
wherein the balls and sticks are all of the same radius and color at the ends.
This gives a picture that is sort of like a thick, space-filling wireframe model
with rounded ends. This is probably the most common format for molecular
graphics that I have seen.
Cylinder Colors
The coloring of the cylinders in this model shares the same basic options with
the CPK and Ball-and-Stick
coloring.
Hydrogen Bonds
The hydrogen bonding for the Cylinder model is exactly the same as the Ball-and-Stick hydrogen bonds.
Display Options
Although PovChem's facilities for manipulating the molecular scenes are
admittedly primitive due to the text-based interface, there are several options
that will allow some basic picture setups:
Page Orientation
The molecule can be set in either a "portrait" or
"landscape" picture. In either case, PovChem can try to guess a molecular orientation such that as much as possible of
the molecule is visible. Page orientation is not an issue when using a user-defined view, since part of that definition is the
size and aspect ratio of the image.
Remember that if you are manually running POV-Ray on
your molecules, the pixel size you give it must match the aspect ratio that
PovChem sets up! It will be obvious if this is messed up, since your picture
will be squished in one direction.
Model Orientation
This sections deals with how the molecule is positioned in the picture - i.e.,
where the camera is located relative to the molecule, how "zoomed in"
it is, etc.
Best Guess
If you choose the Best Guess model setup, then PovChem will try to fit the
molecule as well as possible into the image. It is, of course, not always
perfect, and the camera will always lie on and look along one of the principal
axes. If you don't like the result, you can preview the
picture, then manipulate the view manually until
you get it just the way you want.
Standard
The Standard view is most useful when you are using some 3-d molecular modeling
software to set up your molecule. This view has the +X axis to the right, the +Y
axis up, and the +Z axis up out of the plane. Most graphical chemistry programs
have some sort of option to apply rotations and translations to an output file
to set up this standard view.
User-Defined
The user defined view has two main purposes. One is to define a view to be used
for all frames in an animation, and the other is to allow PovChem to interface
with graphical chemistry programs as an external module for high-quality output.
With a set of vectors, you can set up the image precisely, with camera position,
angle, zoom, and aspect ratio. It also places lights, indirectly, since they are
positioned relative to the camera. The user-defined view can only be specified
in the configuration file.
Background
This is just the background color, that can be black (0,0,0), white (1,1,1),
dark blue (0,0,.2), or a user-specified color. It is not like a solid object in
the background - there are no shadows or reflections or anything on the
backdrop. To do that, you will have to place a (colored, textured) plane behind
the molecule manually, by editing the output files.
Stereo Pairs
A stereo pair is a pair of images that, when viewed properly, allow you to see
your molecule in three dimensions. Imagine you are looking at a physical object.
You see in 3-d because your left eye and your right eye, being set apart, see
slightly different pictures of that object. Your brain takes those minor
differences and translates them into depth.
PovChem allows you to do the same thing with the molecules you create. It generates two separate scene files, which when traced by POV-Ray, give a left-eye and a right-eye image. When you put these two images next to each other, and with a special stereo viewer, or with some practice, by just crossing your eyes, you can see your molecule in glorious 3-d!
You can set up PovChem to automatically generate a stereo pair, and also to call POV-Ray for each image. You can set the separation factor that determines just how much depth will be perceived in the final image. Unfortunately, you will still need to use some image manipulation program to combine the individual stereo images into a single paired image, but any art program should be able to do this easily.
For a proximal (cross-eyed) stereo image, put the left-eye picture on the right, and the right-eye picture on the left. Cross your eyes until the two pictures meet in the center, and you'll see a 3-d molecule.
For a distal (parallel-eye) stereo image, put the left-eye picture on the
left, and the right-eye picture on the right. Uncross your eyes so that the
pictures meet in the center. You can buy various types of (cheap) stereo image
viewers that generally are for distal stereo pairs. You can also just take a
piece of paper or cardboard, place it on edge between the two images, put your
nose and forehead up against the cardboard, and look straight forward. This will
force your eyes to look at only the appropriate picture, and may make it much
easier for you to see the 3-d image if it's not too large.
Manipulating the View
PovChem 1.0 now gives you the ability to fine-tune the view of the molecule, so
that you can rotate, translate,
and zoom in an out. Together with the preview
option, you can manipulate the molecule to get it just right before taking time
to create a high-resolution final image.
Previewing the Image
The biggest and obvious disadvantage of having a text-based program like PovChem
is that you can't just use your mouse to rotate your molecule to set up a nice
view. I have tried to partly overcome this limitation by putting in an image
previewer. All it does is generate a small, "rough draft" version of
your picture (that can take as little as 10 seconds to trace). After viewing the
draft, you can manipulate the view until it's ready
for the final draft.
Rotating the Molecule
You can rotate the molecule in the plane of the screen (clockwise,
counterclockwise), about a horizontal axis (rotating the molecule
top-to-bottom), or about a vertical axis (rotating the molecule left-to-right).
The axes of all rotations pass through the center of the image, not the center
of the molecule, so that if your molecule is not centered on the screen the
results may not be quite what you expect. You will be asked how many degrees to
rotate.
Translating the Molecule
You can move the molecule left-and-right, and up-and-down in the screen. You
will be asked how many Angstroms to translate.
Changing the Zoom Factor
There are two parts to changing the size of the molecule in the image: the
distance between the camera and the object, and the size of and distance to the
view window (what PovChem calls the "zoom factor"). Think of yourself
as in a room with a window facing another building. Think of your eye as the
camera, the window as the image of the molecule on the screen, and the building
as the molecule itself. The amount of the building you can see depends on how
close to the window you are, how big the window is, and how far the building is
from you and the window.
This is how POV-Ray determines what is visible in the image. If you want to
make your molecule bigger, you can either bring it closer to the camera or
increase the zoom by moving the view window closer to the object. You can do
either with the view manipulator, but I would suggest that you keep the zoom
factor between about 2-5, because if you're zoomed too far out (factor around 1
or less), the molecule will be distorted at the edges, like a fish-eye view. If
you're zoomed too far in (factor > 5), the object will appear to have less
depth, especially if you're doing a stereo pair.
Using PovChem to Create Animations
An animation is just a rendering of a bunch of frames, keeping the camera angle
and lights constant. PovChem can be used in non-interactive mode so that you can
write batch files or shell scripts to process large numbers of frames using
PovChem and POV-Ray. Here is a recipe for creating animations with PovChem:
The .inc file contains all the spheres and cylinders at the appropriate coordinates. Each atom is a sphere, and each bond is a single cylinder, except hydrogen bonds that have variable numbers of small cylinders. You should never have to edit the .inc file.
All the parameters I felt are variable are put into the .pov file, including
things like colors, atomic radii, bond radii, camera setup, lights. In fact,
many small changes to the image are much more easily made by a small change to
the .pov file, rather than having to re-run PovChem all over. All parameters are
defined in variables that should be pretty obvious. I have set it up so that you
can use objects other than spheres and cylinders for atoms and bonds, mostly
because I did some artistic work like that and wanted to be able to do it
easily... :) It should also be very easy to incorporate PovChem's molecules into
other POV-Ray scenes.
Making the Picture
Remember that PovChem itself doesn't do the graphics. You will need to use
POV-Ray to create your image. This section will try to help you through the
basic procedure, but a full discussion of all POV-Ray' abilities is beyond the
scope of this manual. You should try to familiarize yourself with POV-Ray's main
features in order to get the best quality images out of PovChem's scene files.
Obtaining POV-Ray
See POV-Ray's WWW page. Much thanks goes to
them for creating such a great (and free) program!
Running POV-Ray with PovChem Scene Files
The first essential point to remember is that the aspect ratio of your picture
must be 4/3 for landscape, and 3/4 for portrait orientation. In other words, if
you create a landscape-oriented picture, the pixel width must be (4/3)*pixel
height, i.e. 800x600, 640x480, etc. For portrait, use 600x800, 480x640, etc. If
your aspect ratio doesn't match this setup, your picture will be distorted!
There are then two ways to use POV-Ray to make your picture:
1) Set up PovChem so that it will do it for you. There are options in the config file that you can set to your preferences. I would suggest leaving POV Options alone unless you know enough about POV-Ray to change them. You will need to set the absolute path of the main POV-Ray program. You may also want to change the default image size.
If you set it up this way, PovChem will also be able to make a preview image, currently set as a 240x180 picture with no antialiasing. This should be fast even for a complicated image, so you can see whether it's about right before taking the time to make a full-quality image.
2) Run POV-Ray manually. This will make it easier for you to control image size and quality, but of course involves more typing... :) The command-line I usually use is
(path/)povray +V +A +FT +B64 +W640 +H480 +i(name).pov +o(name).tgawhere (path/) is the full path to povray and (name) is the name of the input PDB file that you entered into PovChem - usually the whole process goes from (name).pdb, to (name).pov and (name).inc, and finally to (name).tga. If you're using a unix box or PC, you can set up an alias or a batch file to avoid having to type all that. I use the following script on my unix machine, in a executable script file called "pov":
#!/bin/sh /usr/local/bin/povray +V +A +FT +B64 +W$1 +H$2 +i$3.pov +o$3.tga $4 $5 $6so that when I want to make a picture, all I have to type is "pov 640 480 Cool-picture". I can't tell you how to set this up on your own system, but perhaps this general idea will help.
If you are planning to use one of these pictures for a printed image, I would
suggest for the final version a resolution of at least 300 pixels per inch of
printed dimension for a smooth look. I would also recommend against using other
programs to resize the image POV-Ray creates, as this can cause the subtle
smoothing POV-Ray does to get messed up. In such a case, you should have POV-Ray
create a file of the exact pixel dimensions you need, and then import that
directly into whatever layout program you use.