xyz2rgb - a tool for animating molecules

Simulation data courtesy of NASA Ames, animated GIF constructed from XYZ data using xyz2rgb. Notice the ripples across the surface of the tube after it gets struck by the partial benzene.

This program makes pretty pictures and movies of molecules. It expects input in the form of an XYZ file, one of the file formats frequently used by computational chemists. As output, it produces one or more line-interlaced RGB files. These can be converted to other formats using the ImageMagick image processing toolkit. Conversion between a wide variety of molecule file formats can be accomplished using a program called Babel.

Computational chemists often want to simulate the behavior of atoms and molecules over a period of time, resulting in something like a movie. It's actually a concatenation of XYZ files (each representing one frame of the movie). The format for single-frame XYZ files is simple. The first line is the number of atoms. The second line is a comment. Subsequent lines identify atoms: each line gives a chemical symbol ("C", "H", "Na", whatever) followed by X, Y, and Z coordinates. These coordinates are typically given in angstroms (10-10 meters). A multiple-frame XYZ file is just a concatenation of these frames, with no blank lines between them.

Notes on orientation: when longitude and latitude are both zero (the default case) the camera lies on the x axis. The camera always faces the origin. The z axis always points up, and for zero longitude, the y axis points to the right. Increasing longitude will swing the camera around toward the y axis. There are two other parameters for controlling the camera, which are the width of the viewing area and the distance from the camera to the origin (in same distance units as input file, usually angstroms). Longitude, latitude, and width are all angles expressed in degrees. The viewing area is assumed to have an aspect ratio of 4:3.

The molecule is automatically centered. Its center of gravity (assuming the masses of all atoms are equal) is translated to the origin of the coordinate system. Perspective relative to the position of the camera is also handled automatically.

In addition to atoms, an image generated by xyz2rgb.c can also include "walls", which are 4-sided polygons that can lie anywhere in space. Walls are read from a separate file. The format for a "wall file" is pretty simple: the first line tells how many walls are in the file. Each wall is then described by five lines. The first of the five lines gives the R, G, and B components of the wall's color, optionally followed by an opacity value (described below). The next four lines give the X, Y, and Z coordinates of the wall's vertices, in an order going around the perimeter of the wall.

xyz2rgb allows atoms and walls to have different levels of opacity (from fully transparent to fully opaque). Atoms and walls may be assigned individual opacity values within their input files, or the following global settings are available: by default, atoms have an opacity of 1.0 (fully opaque) and walls have an opacity of 0.5 (half opaque). The global opacity of atoms may be changed as a command line option. Any opacity value given in an input file (an XYZ file for atoms, a wall file for walls) always overrides any global default.

To specify opacity for one or more atoms in an XYZ file, place an opacity value after the X, Y, and Z coordinates on the lines for those atoms. This would probably be a useful way to call a viewer's attention to a particular part of the molecule; set the global atom opacity to a low value and make the atoms of interest fully opaque.

If no output filename is given in the command line arguments, the RGB file is written to standard output. If an output filename is given (using the "-o" option), it should be a prefix, and the output files will also be given three-digit numbers and a ".rgb" extension. For instance, if you use the option "-o foo", expect the following output files: foo000.rgb, foo001.rgb, foo002.rgb, etc., one for each frame in your XYZ file.

There are some examples of multiple-frame XYZ files in this directory on a computer operated by Al Globus' group at NASA Ames.


	gcc -Wall -O2 -o xyz2rgb xyz2rgb.c -lm
to compile xyz2rgb on a Unix system. You may need to do something different on a DOS/Windows box or a Macintosh.

Command Line options

xyz2rgb has several command line options. Here they are:
-i filename      input filename (XYZ format)
-longitude a     specify horizontal angle of camera
-latitude a      specify vertical angle of camera
-distance x      specify distance to origin of camera
-width a         specify wide-angleness of camera (an angle)
-size HxV        specify number of horizontal, vertical pixels
-radius r        select a common radius for all atoms
-o filename      output filename, files will have numbers
                   and ".rgb" appended to their names
-walls filename  specify a file of walls
-walls-ok        walls should not be centered or rotated
                   (perspective is still done on walls)
-opacity n       opacity of atoms (0.0-1.0, default 1.0)

Examples of how to use xyz2rgb

Here is an example usage. Take the crambin file from the RasMol distribution, 1crn.pdb, and do the following commands.
babel -ipdb 1crn.pdb -oxyz
xyz2rgb -o 1crn -distance 40 -size 400x300 -longitude -45 -i
convert -size 400x300 -interlace line 1crn000.rgb 1crn.gif
Babel is a tool that translates between the many standard file formats currently used for representing molecules. PDB and XYZ are two formats, PDB is probably in wider use, but XYZ is easier to parse. Convert is part of the ImageMagick suite of image processing tools. Convert can also take a sequence of still images and convert them to an MPEG movie or an animated GIF. (But to do this, you need a pretty recent copy of ImageMagick.)

The result of doing all that is this pretty picture, 1crn.gif:

If you want to make a video of your molecular animation, you'll probably want to produce either an AVI file (for the Windows world) or a Quicktime movie (for the Macintosh world). Video production houses can record these formats onto videotape. There's an interesting-looking sharerware program for Windows called AVI Constructor that can create an AVI movie from a sequence of JPEG stills.

Here is a little MPEG movie.

Here is a Perl script that helps to create this pretty picture of overlapping cones, using the "wall" feature of xyz2rgb, and without any atoms at all:

Here are the commands used to build the animated GIF at the top of this page.

xyz2rgb -size 200x150 -latitude 30 -longitude 40 -o wee -i
convert -loop 20 -size 200x150 -interlace line wee*.rgb globus-tube.gif
rm wee*.rgb
Here is where to find the file.

Source code, related links