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
Plt_pov, for example, is a program for converting O plot files into input files
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 :
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
If you live at BMC, Uppsala,
the functioning intranet version is at :
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
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.
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 :
for single window mode.
Help is always sent to a separate help window.
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.
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.
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.
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.
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.
When you hit "Run", plt_pov is executed, creates a POV-Ray input file,
and opens the POV-Ray dialogue window.
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.
Specifies the width and height of the final image in pixels.
It must be square, so only one value need be given.
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.
Smooths jaggies by interpolation. Expensive, but worthwhile on final pictures.
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
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).
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...
Restores the form entries to the last state saved in the cookie.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Sets the line thickness (primarily for electron-density contours).
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.
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.
Shadows are normally nice, but with a dense electron density map
the molecule inside can look dim unless you switch them off.
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".
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
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.
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.
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.
The number of frames with which to make the animation.
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.
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.
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.
Makes the GIF-format file with a transparent background for use in compositing.
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.
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.
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.
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 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.
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.
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
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...
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).
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.
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.
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.
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.
The MolScript input form takes a standard molscript control file and feeds it to
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.
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 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.
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.
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 :
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)