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 knowlege 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. 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. 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.
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.
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.
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!
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.
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.
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
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.
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
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 coloring is exactly the same as CPK atom 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.
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.
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.
The coloring of the cylinders in this model shares the same basic options with the CPK and Ball-and-Stick coloring.
The hydrogen bonding for the Cylinder model is exactly the same as the Ball-and-Stick hydrogen bonds.
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:
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.
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.
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.
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.
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.
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.
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.
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.