Help file for the Molray molecular-graphics rendering interface

Molray is a web interface for various molecular-graphics programs, most of which use the popular ray-tracing renderer POV-Ray for producing realistic images.
POV-Ray is a free program available from the Persisence of Vision Development team at http://www.povray.org

Plt_pov, for example, is a program for converting O plot files into input files for POV-Ray, with which sytem images of publication quality can be produced from O, as well as simple movie sequences. You should be using O v7.0 or above to get the best out of the Molray system.

The interface is invoked with a command of the form : http://portray.bmc.uu.se/cgi-bin/markh/molray.pl
That address is to the public version on our internet server, which is currently being evaluated for world-wide use, and may have to be restricted to small stills if demand is high. Keep tuned to the O user group mailing list for more information.

Some examples to help you create suitable oplot files from O are available at oplot help.

If you live at BMC, Uppsala, the functioning intranet version is at : http://intray.bmc.uu.se/cgi-bin/markh/molray.pl
And if you don't, you can install your own local version by following the installation help and other resources available via the Molray homepage at http://xray.bmc.uu.se/markh/notes/howto/molray.html.

User help is generally available by clicking on '(help)' buttons, which take you to the appropriate section of the single helpfile, and there is more general help on plt_pov and making plot files from O at http://xray.bmc.uu.se/markh/notes/howto/plt_pov_help.html.
However, the interface is designed to be intuitive, and indeed default values can be used for most options. The only real decisions that have to be made involve filenames and image quality, and these sections are highlighted in orange, so that the nervous user can ignore all the other sections in the beginning of their Molray careers.

Quick Index
Transparent surfaces Image Width Quality Antialiasing Mail me results Camera distance X, Y and Z trans X, Y and Z rots
Background colour Texture New line colour Map transparency Line thickness Stereo Perspective No shadows
Transparent GIF Start frame Steps Rock Pendulum Perspective Morph Assemble only
Append Advanced MolScript Depth cueing Fog parameters

General options :

Display types

By default the user is presented with a window containing 4 frames, and each component of the rendering system has its own frame. This is great if you have a big, high-resolution screen, but otherwise you might want to choose to have a single frame and have each dialogue page erase the previous one. You can also choose to have a new window open for each page.
There are boxes to click on to change these options, but if you want to start up the interface with a particular option, invoke with a "?1" or "?2" appended to the address, eg :
http://xray.bmc.uu.se/cgi-bin/markh/molray.pl?1
for single window mode.
Help is always sent to a separate help window.

Plt_pov input form :

The default starting window is the plt_pov input form, where you are invited to enter the name of your O plot file from which you would like to make an image. You can browse around your directories to find files. Unfortunately this browsing is handled by your web browser, and so I cannot change the default filetype filter from ".html", so you must change this (probably to .plt) if you are to see the right files. Having selected a file, hit "run" to set plt_pov in motion and bring up the plt_pov selection dialogue.
If you check the "select-all-objects" box then you will bypass the selection dialogue and go directly to the POV-Ray parameter page. Do this to save time and screen space if you know you want all objects and no transparent surfaces.
There are also the standard buttons for resetting the form, getting help, and submitting helpful criticism to the guestbook ("feedback").
You will also find a link there to a demo plot file, which you can use to explore the possibilities of the interface if you haven't yet made your own plot files from O. Simply click on the link to see the plot file in a new window, and then download the file to your local machine, whence it can be uploaded to the Molray interface in the usual way.
Lower down in the box are options to run any other programs that can use the interface, and also a 'cleanup' button. This option kills any jobs that were started from your machine, and also deletes any temporary files that were created during your runs. Although this operation should be invoked automatically, it is a good idea to use it manually if you suspect that the disk has filled, if you are creating very large files, or you want to abort a job.

Plt_pov selection options :

The plt_pov selection window presents you with a list of objects that were found in your O plot file, and you can select which of these to include in your picture. The actual object name is highlighted, and there follows plt_pov's attempt to describe what that object is (which is not always obvious because O makes up cryptic names for some objects that it generates). You can also select groups of objects to display, such as 'all sticks' or 'all CPK objects'. The default is to draw all objects.

Transparent surfaces

Makes all surfaces transparent, to a degree determined by parameters in the header file (Map_Trans, Stick_Trans etc), which you will one day be able to adjust later in the POV-Ray dialogue window. By default all surfaces have zero transparency, except for maps, which have 50%. Note that choosing transparency increases the calculation time by many thousand percent, so it's not very practical to do on a regular basis.
When making maps in O for transparent rendering in Molray, you must either use old-style type 5 maps, or the new fast maps with type solid or type transparent.

Depth cueing

Adds artificial depth cueing to the picture by fading colours towards black or white (depending on what your background will be). Positive values fade to black towards the back of the molecule, negative values fade to white, and the magnitude determines the speed of fading. It works quite well on a black background, but on a white background shadows and shading on the white bonds at the back spoil the effect. Note that the fading is also calculated to run from the front to back slab positions, so if you have a very wide slab, the effect will be reduced.
Note that you can't use depth cueing if you are going to rotate your molecule within Molray (either for stills or rotating movies), since the darkening is calculated for the original orientation, and would thus move around as the molecule rotated.

Fog parameters

An alternative way to depth-cue, which works better on white backgrounds. There are 3 parameters that control the fog function Thin, Fade and Offset, and there is also a toggle button to swith fog on or off. If the value of Thinness is not set or set to zero nothing happens, but otherwise the value is interpreted as the thickness of fog (in Angstroms) that will leave 36.8% of the background visible. ie it really represents thinness of the fog, hence the name. Fade then controls how fast the fog builds up in the distance. Setting this to zero gives a constant fog density, larger values exagerate the effect. Offset limits the depth of the fog bank, so that the front of the molecule can be completely unfogged. Small values make the front of the molecule more visible. Appropriate starting values for T, F and O are 10, 0, 5, but the best values for any particular picture will depend on many factors, including the size and complexity of the molecule and the position of the camera and clipping planes. If a black background has been chosen, the fog colour will automatically be set to black too, which gives an effect equivalent to night vision.

Run

When you hit "Run", plt_pov is executed, creates a POV-Ray input file, and opens the POV-Ray dialogue window.

Pov-Ray options :

The availability of the options listed below is limited by which program generated your POV-Ray file.

You will mostly only want to change three parameters : image-width, quality, and antialiasing.

Image Width

Specifies the width and height of the final image in pixels. It must be square, so only one value need be given.

Quality

Determines how hard POV-Ray works on the rendering. More quality, more time.
Use low quality for quick development, high quality for final image.
The values are as follows :
0,1 Just show quick colors. Use full ambient lighting only.
2,3 Show specified diffuse and ambient light.
4 Render shadows, but no extended lights.
5 Render shadows, including extended lights.
6,7 Compute texture patterns.
8 Compute reflected, refracted, and transmitted rays.
9 Compute halos.

Antialiasing

Smooths jaggies by interpolation. Expensive, but worthwhile on final pictures.

Mail-me-results

Causes the URLs of the POV-Ray output files to be mailed back to you instead of being displayed in the window. This is useful for long runs when the browser connection may timeout, or you may go home.
(Not available on the public server yet)
Type your mail address in the box, and click the button to get notification of where to find your files when the rendering is finished. Enabling this option also causes the job to be submitted to the batch queue or be R-shelled elsewhere, on the assumption that it will be a longer job than we want running interactively. The files will remain on the scratch disk for collection for a day or so.
Note that each job submitted from a particular frame will use the same temporary filenames, and so it is important not to submit multiple simultaneous jobs from the same frame, as they will trash each other's files. If you want to submit a second job, make sure that you regenerate the frame by re-running the previous program in the chain (eg regenerate a POV-Ray frame by clicking on 'Run' in the plt_pov frame, or regenerate a movie frame by clicking on 'Movie' in the POV-Ray output frame).

Save

Saves the current form entries as a dated cookie. Separate cookies are saved for the Stills and the Movie panels.
Note that the tickmarks that appear in the save and restore buttons mean nothing, except that I used the wrong sort of form element...

Restore

Restores the form entries to the last state saved in the cookie.

Debug info

Tells you what is going on behind the scenes. Use it only if you are a nerd, or want to feel very grateful that you're not having to type all that stuff in by hand like in the good old days.

Monitor

Opens a little JavaScript window that allows you to monitor progress of your job. It disappears soon after the job is completed, and sometimes before if you are using Internet Explorer. Note that it's hard to estimate completion time, as it depends on the complexity of the image, not just pixel count. Estimates generally start off optimistic because the top of the picture is usually a plain background. When making a movie, the estimated time is for the completion of the current frame, not the whole movie, but the number of frames rendered and left are also displayed.
The monitor window also has a button that allows you to kill the current job.

Camera distance

The distance of the virtual camera from the origin of the coordinate system, possibly expressed in Ångström units. For centered images from O, the value of 20.0 is usually good, but if you translated in Z whilst running O, you may need another value. As you can imagine, putting the camera further away gives you a little picture in a big frame, and putting it closer zooms in on a small region.
But note that if you are using plt_pov, then O has already cropped away all that was not visible on the original screen, so translating closer will not make visible things that were originally out of frame.

X, Y and Z translation

Allows you to translate the molecule around the screen. Note that if you are using the default orthographic projection, then moving the object in Z will not change its size.

X, Y and Z rotation

Allows you to rotate the molecule about the origin. This is intended as a way of making fine adjustments to viewpoints, and you should really be doing gross rotations in O.

Background colour

Sets the background colour to the RGB values you type into the boxes. The default is black, but clicking in the R box will change it to white.

Texture

Allows you to choose a textured background, which will be placed at a distance behind the origin determined by the value you specify in the 'dist' box.
If you choose the 'Plain' texture, the colour will be set to the background colour.
You can also use the textured plane to cut off the back of your molecule.
This texturing is mostly for fun, so I haven't debugged it much.

New line colour

Allows you to set a new line colour. This is primarily intended for changing the colours of countour maps, but will also affect other simple lines (but not sticks). Clicking on the option box causes the original colour to be thrown away and be replaced by the RGB values you type into the other boxes.

Map transparency

Adjusts the transparency for maps from O, assuming transparency was enable during the plt_pov run. 0.0 is opaque, 1.0 is complete transparent.

Line thickness

Sets the line thickness (primarily for electron-density contours).

Stereo

Produces a side-by-side stereo view. Click on the option box to enable it, and type in an appropriate separation for the images. A positive number will give you cross-eyed, a negative number wall-eyed.

Perspective

Sets perspective distortion on. Normally in molecular modelling we use orthographic (parallel) projection, which causes object size to be independent of distance, and so makes judging of interactions easier, but for more artistic pictures, perspective looks more natural. When selected, the angle set in the adjacent box is used for the field of view, so if want a less exagerated perspective you can move the camera back and set a narrower angle to compensate for the image size reduction.

No shadows

Shadows are normally nice, but with a dense electron density map the molecule inside can look dim unless you switch them off.

Transparent GIF

Makes a GIF-format file with a transparent background for use in compositing. This overrides 'black background', and also causes the other output files to develop a vile pink background.

When you hit "Make Image", POV-Ray is executed, creating a bunch of output files and presenting them in the results window.

Advanced feature - Metallic colouring

If you want to have metallic surfaces on your molecule, there is a devious way to make this happen. What you do is define a colour in o that has a red component between 257 and 511 (ie it has between 100% and 200% redness). Molray interprets this extra redness as a request for a metallic surface, and then subtracts 256 from the red component. For example, a nice silver colour can be specified as "476 200 200" in O, and will result in a metallic surface with colour of "220 200 200".

The results window :

Unless you opted for mailed results, when the rendering is finished you will see a limited-size GIF image in the results window, along with links to the full-sized image in various formats. Remember that the full quality of your file cannot be displayed in your browser, because it is restricted to GIF and JPEG formats, so you should use the TIFF file for critical work. For more information on choice of file formats see http://xray.bmc.uu.se/markh/notes/image_proc.html
You can also pick up your intermediate POV-Ray input file if you want to play with the parameters in there in ways that the interface can't handle (for example moving light sources). You can then resubmit the .pov file through the POV-Ray-script form in the first window, or you can download it to your own computer and run POV_Ray locally. You might particularly want to consider that option if you are running transparent surfaces that can take days to complete, during which Molray may lose control of the job, and it can run much faster if you have a cpu that you can dedicate to the task. Installing POV-Ray under Windows or Linux is quite straightforward.
On the results page there is also a "Movie" option button, which will open the movie dialogue window to allow you to animate your image.

The movie window :

This window allows you to produce animations of your molecule, representing either alterations of global viewpoint or conformational changes.
The result is an animated GIF file, and a compressed MPEG file. Quicktime format is not output because a) there are no good conversion programs for the DEC Alpha, and b) it is very time consuming to do routinely. To make your own Quicktime movie, feed the MPEG file into MediaConvert on an SGI.
You may even want to make your own mpeg files from the animated GIF output, so that you can choose your own compression parameters, or choose to repeat frames in the MPEG in order to control the speed of playback.
Animation is controlled by specifying starting and ending conditions, and the number of frames over which the transformation should take place. There are only a limited number of rendering options available, since it is assumed that the appearance of the molecule was chosen in the earlier POV-Ray dialogue.

Start frame

The frame number for the begining of the animation sequence. Allows a complex series of transformations can be chained together, by starting them with different frame numbers.

Steps

The number of frames with which to make the animation.

Stereo

This causes a second series of frames to be written out with the word 'left' appended to the filename, but is of limited use to the general user just now as it's not obvious how to view stereo movies just yet. Let me know if you have ideas.

Rock

This option causes the movie assembler to reuse all the images and append them backwards to the end of the sequence, causing the movie to reverse the transformation and return to the original scene. Because this doubles the number of images, the program secretly halves the number entered in the steps box when rock is selected, so that the total number of frames is correct. Unless of course you requested an odd number of frames, in which case you will be warned that the movie will have one more frame than you expect.

Pendulum

Checking this option causes a sinusoidal instead of a linear progression of the transformation. The motion starts slowly, speeds up, and then slows again, just like a pendulum. Although most obviously useful for Y rotations, it also looks pretty cool on zooms.

Transparent GIF

Makes the GIF-format file with a transparent background for use in compositing.

Perspective

Sets perspective distortion on. Since your audience is unlikely to be taking measurements from your movie, there are fewer disadvantages to having perspective on here, so I recommend it. If you do have perspective switched off, and also choose to translate your scene in Z, in principle nothing should happen, but users will probably expect their objects to get bigger anyway, and for that reason the program secretly moves the camera position under these conditions. This causes the whole scene to get bigger, while maintaining relative object sizes. In fact the program now always moves the camera instead of translating in Z, since zooming is useful function, but not if the molecule is then moved out of the X-Y plane and thus orbits instead of spins when an X or Y rotation is subsequently used.

Morph

If your original O file contained objects with names containing the special strings FM01, FM02, etc, then you will be presented with the option to morph between these objects. This means that the FM objects will rendered sequential through the movie. ie FM01 first, then FM02, then FM03 etc. They will be spread out evenly across the movie so that the last FM object appears at the end of the movie. These FM frames may have been generated manually, or by external programs such as LSQMAN. Other transformations can be applied simultaneously, so you can, for example, rotate the whole scene whilst stepping through your structures.

Assemble frames only

This option skips over all the image rendering, and just assembles pre-made frames into the animation. This is useful if you have made several acts that you want to composite together. For example you could have made one act with frame numbers 1 to 10, and another from 11 to 20, and then assemble them with the command 'assemble frames only' with start frame set to 1, and number of steps set to 20. Note that all the different acts must have been generated from the same Movie window, since the process id of that window is used to identify your frames on the server.

Append

Appends your next rendering sequence to the movie previously made by the current movie window. For the animated GIF you don't need to care about frame numbers, and you can append as many times as you want, but for the MPEG you can only append once, and you must set the new frame numbers to carry on after the old ones. And one ugly little feature here is that the frame numbers must have the same number of digits in all the frames to be assembled, ie all the frame numbers must be between 1 and 9, or between 10 and 99, or between 100 and 999. It will fail if you try to assemble frames 1 to 15 for example. Sorry.

Wiggle

Wiggle stereo is a technique for showing depth in an image by flipping between two slightly rotated images. Although it is tempting to think of this as a binocular stereo pair, it is more strictly a trivial case of depth-cueing by rotation of the scene or by head movement, where the rotation is represented by only two states. Because of this, a rotation about the X axis works just as well as one about Y.
Clicking the wiggle stereo button simply sets the following parameters : 2 steps, stereo off, rock off, pendulum off, and a rotation of +/- 2 degrees in Y.

Advanced

Opens a new frame where advanced movie options can be set. Unchecking the box causes the advanced parameters to be ignored, and a normal movie is made. See below for details.

Make Movie

When you hit "Make Movie", the program creates all the frames, assembles the movie, and shows the result in a separate window, from which it can be saved, along with the POV-Ray input file, and the controlling shell script, which you may or may not be able to interpret and use offline later.

Advanced Movie Options Window

There is currently only one advanced facility on this page, and that is the ability to define a trajectory for the movie camera by giving a number of control points for a spline function. Maybe later you will be able to control light sources here, and if so those controls will also be able to be used to make stills by making a 1-frame movie. Bug me if you think I should start working on light-control features.
Even the flying-camera option is till under development, so for example the headlamp feature seems to wobble. Help with debugging that would be great, as I'm kind of busy with my day job...

Camera trajectory

Here you can enter control points to construct a spline function along which you would like the camera to travel as the movie progresses. The coordinates are in POV-Ray space, not O space, so the normal camera position is 0,0,20; increasing x moves the camera right, increasing y moves it up, and increasing z moves it away from the scene, which is always centered at 0,0,0. These control points can be typed in as x,y,z on one line for each point, commas between x and y, but not after z, as in the default example, but the idea is to get the trajectory from O (see below).

Preview

Here you can select a 'preview', which consists of an overview of the scene in which the trajectory is represented as a tube coloured from red to white along the time axis. This allows you to check that the camera movement is how you expect it to be before expending the time to make the whole movie.
If this option is not checked, the camera moves along the defined trajectory, resulting in the final movie.

Preview distance

This sets the fixed camera distance for the trajectory preview. If you find that part of your trajectory is outside of the preview image, move the camera back to include more. This value is ignored for the final movie generation.

Spline tension, continuity and sampling

These control the exact shape of the spline, the details of which can be found at Chris Colefax's site, linked to below.

Headlamp

This attaches a headlamp to the camera, in case in goes inside a dark cavity. Still a bit buggy.

Save advanced parameters

This button saves the parameters from this window so that they will be used for subsequent movies generated from the regular movie window, if the 'advanced' button is still checked there. Note that movie making is not started from the "advanced" window, only parameters are set.

When you open the advanced-options window or do a save with preview on, the frame count for the movie is set to 1, on the assumption that you will want to make a preview first. If preview is off and the frame count is set to one, the frame count is set to a default value of 10 when you do a save. This makes sense most of the time, but remember to check this parameter when you make your final movie. Perspective is also automatically switched on when the camera trajectory is used, since an orthographic projection would nullify the effect of moving a camera towards the scene. This cannot be overriden by the perspective button in the movie window. Rock and pendulum are switched off too, but they can be switched back on if they are wanted.

Setting the default trajectory

Although a simple camera trajectory can be thought up and entered into the box by hand, more complex paths can be designed in O and uploaded in the oplot file. In order to do this, a dummy object called KAMRA should be created with atom positions representing the path of the camera. These atoms should not be bonded together and should be numbered in the order that they will be traversed by the camera. The easiest way to do this is by using water molecules generated by O. This KAMRA object is then included in the oplot file in the normal way, and it will miraculously appear as the default trajectory when the advanced options window is opened. It will not appear in the final image, only during the preview phase.

Thanks to Chis Colefax for providing the macros for the spline functions.

POV-Ray script input form :

This input form takes a pre-written POV-Ray input file and feeds it directly to POV-RAY. This might be hand-written, an old output from plt_pov, or you may have picked it up from molray so that you could manually edit some of the parameters that are not yet accesible through the web interface.

MolScript input form :

The MolScript input form takes a standard molscript control file and feeds it to povscript, a patched version of molscript that can output a POV-Ray input file instead of PostScript. It also takes a PDB file that you have referenced in the molscript file with a local filename (ie no directory specification). The filename of the uploaded file must match that in the script, and there must only be one "read mol" instruction in the script. eg:
read mol "myprotein_and_ligand.pdb";
At the moment your molscript description file must be set up to produce a square image, you cannot make movies, and if you want it to work from a windows machine, the pdb filename must begin with the string "NTNT" (eg NTNTmyfile.pdb).
You can also select BobScript instead of the standard MolScript via a pull-down in the first window.

GRASP input form :

The surfout program claims to be able to take a GRASP surface file and prepare it for POV-Ray rendering, but when I try it, I get a complaint that I have "additional information" in my surface file. But I don't know GRASP, so I'm sure it's my fault.

Ligplot input form :

Ligplot is a program for plotting diagrams of ligand binding, and although it doesn't lend itself to RAY-tracing, I thought I'd include a form for running it here anyway. The output PostScript files goes straight to the results page, but cannot be viewed yet because we haven't installed Ghostscript, so you have to pick it up and take it elsewhere.
Also note that you should not have chain id's in your ligand, and that the residue numbers should be unique.

Cookies :

Apparently I'm legally obliged to tell you that Molray sets cookies on your computer if you ask it to save parameters. The only information saved is the status of all the buttons on the current page, and I promise that I don't sell this information to anyone else, however much they offer me to know what your favorite colour is. You can prevent any cookies from being set by choosing the appropriate option in your browser's preferences. There, that should keep me out of jail.

Reference :

If you use Molray in a publication, we would be grateful if you would use the following reference :

Molray - a web interface between O and the POV-Ray ray tracer.
Harris, M. and Jones, T.A.
Acta Cryst (2001). D57, 1201-1203.


Known bugs :

None.

Unexpected features :

1) Don't give your objects names that could be interpreted as a colour, vector or other POV-Ray keyword ! For example, calling your map 'red' or 'x' will give POV-Ray a fatal headache. Think of this as artificial intelligence - if you said to a person "draw a tyrosine", they would understand, but if you said "draw a red", they would say "draw a red what ?".
And after 10 years of service, I've just discovered that Molray doesn't like minus signs in names either, so use underscores instead.

2) Map colours taken from the original file are a little unpredictable.
This stems from a quirk of the oplot format that has always been a challenge. The colours are set only when the maps are instanced, not in the original definition. If you really want several maps with their original colours, you should edit the .plt file and put in a colour statement as the first line of each map definition.
Look for "MyMapName_MAP" in the file, then add a line like "color 0.9 0.2 0.3".

3) Stereo with perspective on is not a good combination.

4) Textured backgrounds develop strange shadows in stereo, and plain backgrounds always give strange shadows in stereo. Metallic-textured backgrounds become so dazzling when quality is set above 7 that they appear white.

5) A Y2K bug in old versions of the "at" command cause tidy-up of temporary files to fail since the new year. This will only bother systems managers who didn't do their Y2K fixes. Their penance is to regularly clear up their tmp directories by hand.

6) Sometimes helices turn blue. I'm not sure why, but the fix is to switch off the "new line colour" option.

7) The file-growth-monitor may crash netscape on a O2 when the window closes. Uncheck the 'monitor' box to stop this happening.

8) Safari can't handle the file-growth-monitor, and downloads it to disk instead of showing it. Safari also refuses to update a window until the whole page can be loaded. This causes a problem when a long job times out, in which case you will not have received the emergency link that would let you access the output file. The workaround is to use a different browser for big jobs. To avoid the annoying window with the error messages from the file-growth-monitor, delesect 'monitor'.

9) Explorer under Mac OSX corrupts uploaded molscript files, but safari works fine.

10) Molscript doesn't understand the 'slab' command.

Mark Harris, 15 Sep 2004

(The Molray Homepage)

Mark Harris