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.

Compiling

	gcc -Wall -O2 -o xyz2rgb xyz2rgb.c -lm

Command Line options

-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

babel -ipdb 1crn.pdb -oxyz 1crn.xyz
xyz2rgb -o 1crn -distance 40 -size 400x300 -longitude -45 -i 1crn.xyz
convert -size 400x300 -interlace line 1crn000.rgb 1crn.gif

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 tubev03.xyz
convert -loop 20 -size 200x150 -interlace line wee*.rgb globus-tube.gif
rm wee*.rgb

Source code, related links

• The source code is in xyz2rgb.c.
• The home page for Babel
• The home page for ImageMagick
• The home page for AVI Constructor
• The xyz2rgb program was motivated by an idea I had for a popularly-funded prize in computational chemistry.