Installation instructions for Molray/POV-Ray rendering system

Molray is a web interface for running various molecular graphics programs (in particular O) and converting the output of these programs into input files for the popular ray-tracing renderer POV-Ray. Using these programs, images of publication quality can be produced with a few mouse clicks, and simple movie sequences with a few more.

This is the help file for installing this web interface, molray.pl.
The system is particularly suitable for large groups with a throughput of occasional users who would otherwise waste a lot of time getting used to complicated sequences of UNIX commands to make images.
For small groups and nerdy individuals, the stand-alone system may suffice.

User help and other resources are available via the Molray homepage at http://xray.bmc.uu.se/markh/notes/howto/molray.html.

Molray is a perl-based web interface, and to install it you must have a web server that is capable of running the cpu- and memory-intensive ray-tracing calculations, or to be able to fire up remote shells on another machine that can. Our internet server did not have that capacity, and our compute servers are protected behind a firewall, so we set up an intranet server especially for this rendering system. This setup also had the advantage that we don't have to worry about outsiders swamping our server with hour-long POV-Ray runs.

Having chosen a web server, you then need to install the following programs on it :

Perl v5.0 or above.
plt_pov, which can be found at : http://xray.bmc.uu.se/markh/notes/howto/plt_pov.f
molray.pl, which can be found at : http://xray.bmc.uu.se/markh/notes/howto/molray.ppl.save
Strip off the ".save" extension from the filename and change the .ppl to .pl.
POV-Ray can be found via : http://www.povray.org/
But if you want to support the advanced movie features, you need to install instead
MegaPov from : http://megapov.inetart.net/
convert, which is part of the ImageMagick suite at : http://www.imagemagick.org/www/convert.html
If you have another program that can produce GIFs and JPEGs from TARGA files, you can use that instead of 'convert' (there is a variable to change in the molray.pl script). We had trouble installing the new version that handles PNGs, so we have a separate program (convert_png), but it could be the same one.
gifsicle, at : http://www.pdos.lcs.mit.edu/~eddietwo/gifsicle/index.html
gifsicle is only used for making the transparent GIFs and assembling animated gifs, so if you don't want to install that, you won't loose much functionality, and convert_v4.2 can actually do the transparency work, but we had trouble installing that on our DEC alpha.
mpeg_encode, at : http://bmrc.berkeley.edu/frame/research/mpeg/index.html
And pick up a parameter file for running this at http://xray.bmc.uu.se/markh/notes/howto/mpeg.params.
These are used for making the MPEG versions of the movies. If you don't install it, you will still get animated GIFs.
file_growth_monitor.pl, at : http://xray.bmc.uu.se/markh/notes/howto/file_growth_monitor.ppl.txt
This optional module allows a JavaScript window to be opened in which POV-Ray execution progress can be monitored.
Strip off the ".txt" extension from the filename and change the .ppl to .pl.
spline.inc, at http://www.geocities.com/ccolefax/spline This optional third-party POV-Ray include file is needed if you want to use the advanced camera moving function. Pick up the zip file provided at this URL, rename spline.mcr to spline.inc (for consistency with all the other POV-Ray include files), and put it in the same directory as your other POV-Ray include files.

The interface also supports povscript (a derivative of molscript), and surfout (for rendering Grasp surfaces). If you don't have these installed, they are quietly ignored, so don't worry, otherwise pop them in the directory with the other executables.

plt_pov builds with a one-line command, and is tested on DEC alpha, Linux and SGIs.
First edit the file and set 'incl_dir' to point at the directory containing the POV-Ray include files and font files that came with the POV-Ray distribution. (If you choose to set this location to "./", then you must move the POV-Ray include files to the cgi-bin directory where molray is executing.) Then :
% f77 plt_pov.f -o plt_pov

Then you need to install the perl scripts under the cgi-bin directory of your server. Change the variables at the top of the file to reflect your local system, and you should be ready to go.

1) Set the perl pointer on the first line to reflect your perl executable location.
2) Set '$script_name' to the URL of the location you chose for the script, somewhere under the cgi-bin directory of your web server.
3) Set '$scratch_dev' to a scratch area read-writable by the web server account.
Note that '/tmp' will normally not be accesible, and that you may need to make a link under the server root if you want to use a disk that is not normally web accesible. The address should serve as part of both a URL and a filespec, hence the default of "../../tmp", which in our case is equivalent to "hostname/www/tmp".
4) Set '$scratch_url' to the URL equivalent to the scratch device, so that users can pick up files that have been batched processed.
5) '$prog_bin' is the directory where the programs live. If they live in different places you can set the individual locations further down in the script.
6) '$remote_cmd' is the command to use for longer runs. We use the DQS batch system, but you might prefer to RSH to another machine, or just set it to "" to run locally.
7) '$Imagedir' is the directory where the logo images are stored. Feel free to leave that pointed at us, but for faster access you can download the following files to somewhere local (it must be readable for the outside world, so under cgi-bin is not a good idea) : povscript_logo.gif, molray_logo.gif, pltpov_logo.gif
8) See that all the program variables point to the correct locations of the executables.
9) Tell your web server to use mng mime types for .mng files, so that users can see that format directly in their browsers.
In apache you do that by adding the line "AddType video/x-mng .mng" to your httpd.conf file.
10) If you send me a mail to let me know that you have installed Molray, I will notify you of updates, if you wish. It would also be nice to let us know that the system is useful.

For debugging purposes, it may be useful to know the program flow, and how temporary filenames are assigned.
The first PIDs are included in the temporary filenames to avoid clashes with other users, and the second ones are used to force the browser to refresh when a picture is remade with different parameters.
POV-Ray runs are performed through a temporary shell script (tmppPID1.csh), and a variety of log and list files are written out (see the shell script for details).


name.plt 
|
| Molray
V
tmppPID1.plt
|
| plt_pov
V
tmppPID1.pov
|
| sed
V
tmppPID1.tpv --POV-Ray--> tmppPID1PID2.tga --convert--> .gif, .jpeg (Stills)
|
| sed
V
tmppPID1.mpv
|
| POV-Ray
V
tmppPID1_*.tga
|
| convert
V
tmppPID1_*.gif
|
| gifsicle
V
tmppPID1PID2.GIF (Movie)
|
| mpeg_encode
V
tmppPID1PID2.mpeg (Movie)

Feel free to mail me for help at : markh "at" xray.bmc.uu.se

Mark Harris, 27 Nov '99

(The Molray Homepage)

Counter