Ray-tracing O files with plt_pov and POV-Ray

plt_pov is a program for converting O plot files into input files for the popular ray-tracing renderer POV-Ray.
Using these programs, images of publication quality can be produced from O.

This is the help file for running standalone plt_pov and POV-Ray. To install this system see http://xray.bmc.uu.se/markh/notes/howto/plt_pov_install.html

For information on the alternative web interface to these programs, and other resources, go to : http://xray.bmc.uu.se/markh/notes/howto/molray.html

To make an image, you create an oplot file in the usual way, and then run plt_pov to produce instructions for POV-Ray. The POV-Ray instruction file contains only molecular-structure information, and knows nothing about viewpoints and lighting and such, so you need a wrapper file containing this information, and which makes a call to the file that you just made with plt_pov. Then you feed this wrapper file into POV-Ray, and out pops a targa-format image file, ready to be read into Photoshop or The Gimp, or to be printed.

Making the O plot file

Go see the oplot page for full documentation, but roughly speaking, here is how you do it.
In O, type something like this :
plot_setup myfile.plt 1 ; yes

sk_setup cylin smooth ; ;
sk_setup sphere smooth ;
sk_setup stick smooth ; ;


sk_stick mymol
sk_cpk mymol

map_obj mymap
map_param 40 40 40 1.4 0.00 0.88 1.00 0.5 0.0 1
map_file mysigmaa.omap
map_cover mymol 1.5


It is important to set the sketch options to smooth, or your structures will be rendered with ugly little triangles instead of nice chunky sphere and cylinders. The exception is when using ODL objects, where smooth rendering doesn't work and so you must use ugly solid rendering. Drawing bonds twice, once in each direction makes the triangulation a little less objectionable.
To create hydrogen bonds with an ODL, add lines like this to your omac file :

 sk_setup spheres solid ; ;
 draw myfile.odl

And in myfile.odl have the following lines :

 begin_object hbond                                                             
   line_type dotted                                                            
   colour slate_blue                                                           
   move_atom xet3 A118 OH                                                      
   line_atom  xet3 D784 05        

Running plt_pov

The latest release of the conversion program for locals at BMC lives at :
(or sarek:/usr/local/bin/plt_pov_sgi)
and POV-Ray v3.1 lives at :

plt_pov can be run with command-line parameters, or interactively. If you provide sufficient information on the command-line, it will not prompt you further, and can thus be run within a shell script. The syntax for command-line options can be found by typing :
% plt_pov -help
If you just type 'plt_pov', it will ask you for the names of your input and output files, and will then search the input file for O object names. Since O plot files contain all displayed objects, you must decide which ones you want to render. The program will list all the objects it can find, together with an attempt to identify the strangely named objects in terms of whether they are stick figures, CPKs, maps, notes or surfaces. When you have decided which you want to see, type their names in reply to the prompt, and plt_pov will potter away and convert them into structures recognisable by POV-Ray, and write them to your chosen output file.
Note that all objects that start with the proffered strings will be included, so typing "S" will select all objects that start with the letter S, and "CPK_" will select all objects that start with CPK_.

If you don't want to mess with wrapper files, you can feed plt_pov the command-line option '-complete', which will encourage it to output a complete POV-Ray input file with default conditions as well as your coordinates. This probably isn't the best way to run, as you will probably soon develop your personal preferences for parameters, and it would be a nuisance to have to re-edit the header of the new output file every time you re-run plt_pov, but it might get you over the threashold of using the program.
At present you must specify the virtual camera distance when you use this flag (eg '% plt_pov -complete=150'). This determines the viewport for the image, the further away the camera is, the more the image encompasses, and the smaller the size of individual atoms. Adjust to taste.

There are some limitations to plt_pov:
1) Ribbons are ugly and triangulated at the moment.
2) Text is primitive, and unless you want stereo, is best added later in Photoshop or The Gimp.
4) O plot files used to forget map colours, so you needed to edit these in.
If your map is called MAP_MAP (mine always are, but I think that's luck), then you can use plt_map.sed to set the colour to blue. Use :
% sed -f plt_map.sed infile.plt > outfile.plt
This O bug is fixed as of Nov '99, and new maps should retain their colour.

Advanced feature :
If you specify the command-line option '-transparency=t', surfaces will be drawn with a partial transparency determined by the values set in the header file with the variables Stick_Trans, Map_Trans etc. Values go from 0.0 (opaque) to 1.0 (invisible).

Note that this is an artificial type of transparency that attenuates the intensity of the background objects without filtering them according to the colour of the transparent surface. I think this looks better for the type of pictures we make. Also note that transparent surfaces slow down the ray-tracing calculations enormously (at least 10 times).

Running POV-Ray

The POV-Ray instruction file you just created contains only molecular-structure information, and knows nothing about viewpoints and lighting and such, so you need a wrapper file containing this information. I recommend the template file plt_pov.pov, which makes a call to "all.pov". If you call your output file from plt_pov "all.pov", then you can immediately run POV-Ray on plt_pov.pov, and out will pop your image in targa (.tga) format. In practice you will probably want to rename the template file, and change the reference to "all.pov" inside to better represent your image.

When you run POV-Ray, you need to supply some command-line parameters. The -i and -o options specify input and output filenames respectively, and the +w and +h parameters determine the pixel width and height of the final picture, +q sets the quality level (from 0 to 9) and +a sets antialiasing on. You can leave out both q and a for a quick and dirty picture, otherwise a complex picture can take many minutes to render on the alphas.

A small, quick and dirty picture would be made with :
% x-povray -i myfile.pov -o myfile.tga
while a publication-quality image would come from :
% x-povray -i myfile.pov -o myfile.tga +q9 +a +w3000 +h3000
Do not try to make non-square pictures unless you are very, very clever.

There are many parameters you can change in the POV-Ray wrapper file, on which you can get information from the on-line manual, or from myriad resources via the POV-Ray homepage at http://www.povray.org/ . The more obvious parameters are also documented in the wrapper file itself, and the most likely one that you will want to change is the camera distance, which determines the field of view for your image.
To change the thickness of lines (for example of maps), change the value of Line_Width in the wrapper file. Changing the value of zthick in the plot file as one did for oplot, no longer has any effect.

The targa file output from POV-Ray can be converted to your favorite format using photoshop, the Gimp, xv, or imconv.

The complete procedure :

The whole procedure for producing a ball and stick figure is as follows :
% ono (then make your O plot file)
% plt_pov myfile.plt -out=all.pov -obj=\"CPK S\"
(copy template file and rename to myfile.pov)
% x-povray -i myfile.pov -o myfile.tga
% imconv myfile.tga myfile.tiff
% xv myfile.tiff

Et voilá, you have a beautiful ray-traced image.

Automated running of the system

If even this procedure sounds complicated, you can try executing this shell script on gere :
% plt_pov.csh
and answer all the questions honestly. It should hold your hand through the whole procedure, but I haven't tested it thoroughly yet.
Better still, use the web interface via : http://xray.bmc.uu.se/markh/notes/howto/molray.html

Mark Harris, 2 Nov '99

(Image Processing notes)