File: r3d_hints.html

package info (click to toggle)
raster3d 3.0-7-2
links: PTS, VCS
area: main
in suites: bookworm, bullseye, forky, sid, trixie
size: 5,180 kB
sloc: fortran: 9,536; ansic: 1,064; makefile: 311; sh: 272; csh: 1
file content (498 lines) | stat: -rw-r--r-- 21,897 bytes
parent folder | download | duplicates (5)
<html>
  <head>
    <title>Suggestions for better pictures</title>
    <!-- OWNER_NAME="Ethan A Merritt, Biological Structure" -->
    <LINK rev=made href="mailto:merritt@u.washington.edu">
    <!-- OWNER_INFO="University of Washington Box 357742, Seattle WA 98195" -->
   <LINK REL=stylesheet HREF="r3d_docstyle.css" TEXT="text/css">
  </head>

<body>
	<h1 align=center>Suggestions for better pictures</h1>

<h4>Topics covered</h4>
<ul>
    <li><a href="#shadowing">
	Shadowing</a>
    <li><a href="#output device">
	Tailoring your image to the output device</a>
    <li><a href="#modularity">
	Making your pictures modular</a>
    <li><a href="#stereo1">
	Side-by-side figures and stereo pairs</a>
    <li><a href="#stereo2">
	Stereo pairs and Molscript</a>
    <li><a href="#colours">
	Creating your own colour descriptions</a>
    <li><a href="#composing">
	Composing figures in other programs</a>
    <li><a href="#matrix">
	Coordinate systems</a>
    <li><a href="#labels">
	How can I keep the Molscript labels in my Raster3D picture?</a>
    <li><a href="#black-white">
	Black &amp White figures</a>
    <li><a href="r3d_transparent.html">
	Transparent surfaces</a>
    <li><a href="#clipping">
    	Clipping planes</a> and
	<a href="#bounding">
	Bounding planes</a>
</ul>
<hr>

<a name="shadowing">
<h4>Shadowing</h4></a>
<p>
The primary purpose of shadowing is to convey a feeling of depth in
the rendered image. This can be particularly effective when there are a
relatively small number of elements in the scene, or when there is a grouping
of foreground objects which cast shadows onto a separate grouping of background
objects. However if there are a large number of elements in the scene, e.g. a
ribbon and arrow representation of a large molecular assembly, the use of
shadows may actually complicate the visual impact and make the image less
satisfactory. In this case you may wish to try rendering the image both with
and without shadows, or you might experiment with the location of the primary
light source (the SOURCE parameter in the 12th header record input to
<b><i>render</i></b>). Finally, you can de-emphasize the shadows by increasing
the secondary (straight-on) light source contribution parameter STRAIT.
</p>

<a name="output device">
<h4>Tailoring your image to the output device</h4></a>
<p>
The quality of pictures generated by
Raster3D is ultimately limited by the output device. Although you will probably
compose and preview your figures on a workstation screen, you will probably
want to re-render the final version with a larger number of pixels before
sending it to a film recorder or high performance color printer. For example, a
typical film recorder can produce slides with a resolution of roughly 4000x3000
pixels (much larger than can be displayed on a workstation screen). The number
of pixels in your rendered image is controlled by the parameters (NTX,NTY) and
(NPX,NPY) in the 2nd and 3rd header records input to the render program, 
or by the <i>-size</i> command line option to render. 
If you need to convert your image to PostScript so that you can send it to a
PostScript printer (the <i>only</i> time you should ever convert to PostScript!)
then read the section on <a href="#PostScript">PostScript conversion</a> below.
You should also be aware that color balance and particularly the appropriate
``gamma correction'' varies from one device to another. The Raster3D render
program can apply a gamma correction or you can apply one afterwards to the generated
image files using a general purpose image processing program (e.g. the ImageMagick
"mogrify" command).
If you will be using a particular output device regularly, it is worth an initial round of
experimentation to determine the best gamma value for future runs. The
appropriate gamma correction can then be applied to each rendered picture
before sending it for printing.
</p>

<a name="modularity">
<h4>Making your pictures modular</h4></a>

<p>
So long as you stick to a consistent coordinate system, you can build up
a complex Raster3D scene from bits and pieces created by various
different tools and programs. For example, you could create a scene that
is defined by a viewpoint selected interactively in Xfit, and that
contains a protein molecule drawn by Molscript, a molecular surface
drawn by GRASP, and a "floor" or bounding box from the Raster3D library
of pre-described objects. This scene can conveniently be described to
the render program by using file indirection in the input stream, which
might look something like this:
<pre>
	#
	# Header records written from inside Xfit
	@viewpoint.r3d
	#
	# Molscript V2.0 output file
	@secondary-structure.r3d
	#
	# Make the molecular surface (from GRASP via ungrasp)
	# transparent by using a material definition
	# from the Raster3D library $R3D_LIB 
	@transparent.r3d
	@surface.r3d
	@end_material.r3d
	#
	# Add a few extra goodies
	@red.r3d
	@floor.r3d
</pre>
This makes it very easy to experiment with your composition without
having to edit huge input files. You could, for example, change the
color of the floor by substituting the library file <i>blue.r3d</i> for the
file <i>red.r3d</i>. Or you could render the same scene from a different
viewpoint by changing the view matrix in viewpoint.r3d. Even better, you
could select from a number of pre-defined views described by header
records in files <i>view1.r3d, view2.r3d, view2.r3d</i>, and so on just by
making <i>viewpoint.r3d</i> be a symbolic link to the particular view you want
to render. That way you needn't edit any input files at all to shift the
scene. This approach is particularly useful for producing
<a href="r3d_animation.html">animation</a>.
</p>

<a name="stereo1">
<h4>Side-by-side figures and stereo pairs</h4></a>
<p>
The EYEPOS parameter input to the render
program specifies a viewing distance for the resulting image. You may think of
this as equivalent to the distance between a camera and the object being
photographed. 
EYEPOS = 4 means that the
distance from the camera to the center of the object is four times the width of
the field of view. 
Generally the sense of depth conveyed by the rendered image is
slightly increased by positioning the virtual camera reasonably close to the
object. 
However, if you are composing a figure containing two or
more similar objects which are next to each other, e.g. a comparison of two
variants of the same protein structure, then the resulting parallax may be more of a
hindrance than a help. Since the virtual camera is centered, it will ``see'' the
right hand object slightly from the left, and the left hand object slightly
from the right. This results in different effective viewpoints for paired
objects which would otherwise be identical. To overcome this effect you may
wish to set EYEPOS to 0.0, which disables all perspective and parallax.
The same considerations apply for the production of stereo pairs.
</p>

<a name="stereo2">
<h4>Stereo pairs and Molscript</h4></a>
<p>
All Raster3D objects emitted by a Molscript run are 
placed into a single scene description. That is, the pairs of ``plot'' and
``end plot'' statements in a Molscript input file have no effect in Raster3D
mode. Therefore a Molscript file which describes a
stereo pair as two separate plots will not work correctly when fed through to
<b><i>render</i></b>. 
You should instead use Molscript to produce a single [mono] scene description
for Raster3D, and run it through the <a href="stereo3d.html">stereo3d</a>
script to produce a stereo pair.
Here is an example:
<pre>
#
# Use molscript to generate a Raster3D input file
#
molscript -r &lt; image.mol &gt; image.r3d
#
# Render image once to check that it's what we want
#
render -tiff mono.tiff &lt; image.r3d
#
# Render it again, this time as a stereo pair
#
stereo3d -tiff stereo.tiff &lt; image.r3d
</pre>
</p>

<a name="clipping">
<h4>Clipping planes</h4> </a>
<p>
A clipping plane restricts the contents of the rendered image based on the Z
coordinate of individual objects. There is both a front clipping plane and a
rear clipping plane. Objects closer to the viewer than the front plane are not
rendered, and objects further from the viewer than the rear plane are not
rendered. The Z-coordinate of the clipping plane must specified in the same
units as coordinates of your input objects, so if you are working in PDB
coordinates you should specify the clipping planes in ngstroms. Raster3D
allows two different methods of setting clipping planes with slightly
different effects. Clipping planes specified as a global property apply to all
objects in the image. An object is discarded on input if all of its vertices
lie outside the clipping plane; a clipped object is entirely omitted, an
unclipped object is entirely rendered even if part of it extends beyond the
clipping plane. An example of specifying global clipping planes is given
below:
<pre>
# set global clipping planes
16
FRONTCLIP 2.
16
BACKCLIP 10.
</pre>
The other option is to assign clipping planes as part of defining a set of
special material properties. In this case the clipping planes are applied only
to objects within the begin/end scope of the special material. In this case
the clipping is done on a pixel-by-pixel basis, which means that individual
objects may be rendered in part only. The portion of the object that extends
beyond the clipping plane is omitted from the rendered image. An example of a
material specification that includes a front clipping plane is given below:
<pre>
# Opaque material with specular properties inherited from header
# Extra record present to specify clipping plane
8
-1.0 -1.0  1.0 1.0 1.0   0.0   0 0 0 1
FRONTCLIP 2.
</pre>
</p>

<a name="bounding">
<h4>Bounding planes</h4> </a>
<p>
Bounding planes are a more general case of Z-clipping planes. They differ from Z-clipping planes as follows:<br>
<img align=right src="../examples/slice.gif">
<ul>
<li>A bounding plane is specified by giving the coordinates of some point 
    in the plane and the normal to the plane. The front Z-clipping plane 
    is effectively a bounding plane defined by some point with Z coordinate 
    FRONTCLIP and whose normal is given by [0,0,1].
<li>Bounding planes rotate, translate, and scale with the bounded objects. 
    Z-clipping planes do not.
<li>Bounding planes are specified as part of a special material definition, 
    and apply only to objects within that material.
<li>When an object is intersected by a Z-clipping plane, the clipped portion 
    of the object is not rendered at all. The default treatment of a bounding plane, 
    however, is to truncate the object by rendering a flat bounding surface. 
    Therefore if an opaque object or surface is Z-clipped, you will be able 
    to see into the interior of the object. On the other hand, if an opaque 
    object or surface is cut by a bounding plane, you will see the flat surface 
    resulting from this `slice'.
</ul>
</p>
<p>
The current implementation allows two slightly different variations in how 
multiple bounding planes interact with each other. One variant is used to 
draw ortep-like thermal ellipsoids in which one octant is cut away.
In this case a given volume is excluded from rendering only if it is `above' all 
bounding planes associated with its material definition; exclusion requires 
a logical AND of three bounding planes. Here is the specification for one 
such ortep-like ellipsoid. Note that all three bounding planes pass through 
the center of the ellipsoid, and a single color specification is given for 
all three bounding surfaces 
(<a href="rastep_options.gif"><i>-fancy6</i> option to rastep</a>).
If no BOUNDING_COLOR is specified, then the 
exposed surface is rendered using the base color of the materiall; 
if you like, you can specify a new BOUNDING_COLOR for each plane.

<pre>
# Thermal ellipsoids from Rastep Version V2.6d   
# Probability level 0.50
 8
 -1.0 -1.0  -1.0 -1.0 -1.0  0.0  0 0 0 5
ORTEP_LIKE
BOUNDING_COLOR  0.500 0.500 0.500
BOUNDING_PLANE  0   24.274 47.792 19.835   0.8259  0.5467  0.1376
BOUNDING_PLANE  0   24.274 47.792 19.835  -0.4475  0.7843 -0.4297
BOUNDING_PLANE  0   24.274 47.792 19.835  -0.3428  0.2934  0.8924
14
  24.274  47.792 19.835     0.893   0.7 0.7 0.7
      8.6581 6.0432 5.0725 2.9042 0.8405 0.3715 0.0 0.0 0.0 -2.3661
</pre>

<p>
In the absence of the ORTEP_LIKE restriction, multiple bounding planes are 
combined using a logical OR. A given volume is exluded from rendering if 
it is clipped by one or more of the associated bounding planes. This 
could be used, for example, to render a central slice from an extended 
structure or a single wedge from a sphere.


<a name="colours">
<h4>Creating your own colour descriptions</h4> </a>
<p>
The Raster3D distribution contains a number of
pre-defined colouring schemes (e.g. the shapely.colours file, cpk.colours, and
mycolors.pdb). If you choose to modify these, or create your own, then you
should be aware that render works internally with the square root of the
specified colour values (yes it's a very strange concept!). 
<a href="r3d_colorpicker.html"><img src="r3d_colorpicker.gif" alt="" align=right></a>
To convert a normal
RGB colour triple into a Raster3D color specification it is therefore necessary
to square each component. For example, to specify a half-intensity yellow you
would square the components of the pure RGB triplet (0.5, 0.5, 0.0) to yield
(0.25, 0.25, 0.0) in the COLOUR record input to render. The Raster3D output
option to Molscript performs this conversion automatically, so you should not
have to alter the colour specifications to switch between PostScript and
Raster3D modes.
The HTML tool <a href="r3d_colorpicker.html">r3d_colorpicker</a> provides 
an interactive colour previewer.
</p>

<a name="composing">
<h4>Composing figures in other programs</h4></a>
<p>
Suppose you are already working in some interactive graphics program,
and want to reproduce the current viewpoint/orientation for a Raster3D picture.
If the program will dump the current view matrix then you will probably be able to use
it as a view matrix for Raster3D also. However many programs (including 
Molscript) dump a matrix which is the transpose of the matrix used by Raster3D. 
</p>
<p>
Users of Alwyn Jones' program O
should obtain a copy of the program <b><i>o2mol</i></b> from the O ftp site.
Once you have composed your view in O you can convert to a Molscript/Raster3D
viewpoint description by dumping the O datablock named .GS_REAL

<pre>
O&gt; write_form .gs_real omatrix.dat
Heap&gt; Format: &lt;cr&gt;
</pre>
followed
by a shell command

<pre>
o2mol &lt; omatrix.dat &gt; o2mol.out
</pre>
The
file o2mol.out will now contain instructions for reproducing the O viewpoint in
Molscript. Also, the 3x3 matrix which o2mol gives as ``for coordinate
transforms'' is in the correct form to use directly as a Raster3D matrix if you
aren't processing with Molscript first.
</p>

<p>
Coot (<a href="http://www.biop.ox.ac.uk/coot/">home page</a>)
can create Raster3D input files or images directly from the current screen view.
</p>

<p>
Duncan McRee's XtalView program 
(<a href="http://www.sdsc.edu/CCMS/Packages/XTALVIEW/">
          http://www.sdsc.edu/CCMS/Packages/XTALVIEW/</a>) 
is another crystalloghic modeling tool that can create Raster3D input files or 
images directly from the current screen view, including atoms, bonds, view objects, 
electron density, etc. Many Raster3D rendering options can be varied using 
control widgets in the Xfit pop-up plotting menus. 
Xfit can also be used simply to create a set of 
Raster3D header records describing the current view. 
</p>

<p>
Another interactive tool you might be interested in is the
<b><i>VMD</i></b> program from the Theoretical Biophysics group at the
University of Illinois.  <b><i>VMD</i></b> provides a
wide variety of methods for interactively rendering and coloring a
molecule, and can generate a Raster3D input file which will very nearly
duplicate the view composed on your workstation screen.

A more complete description of VMD is available via the 
<a href="http://www.ks.uiuc.edu/Research/vmd/"> VMD WWW home page</a>.  
</p>

<a name="matrix">
<b><i>Coordinate systems</i></b>:
<p>
When Molscript runs it normalizes the coordinates of objects in the figure
so that they are described by an identity transformation matrix.
The 3x3 matrix printed out by Molscript to the terminal is the transpose of
that needed by Raster3D programs.  Swap the entries
about the diagonal from upper left to lower right before copying it into
the TMAT header records for 
<a href="render.html">render</a> or <a href="normal3d.html">normal3d</a>.
</p>

<p>
To normalize other Raster3D input files describing objects still in the original
PDB coordinate space (so that they can be merged with your Molscript output),
replace the four TMAT records in the header with a new matrix built as below
and then feed the resulting file through <a href="normal3d.html">normal3d</a>.

<center>
<table border>
<caption> TMAT (4x4 matrix) in Raster3D header</caption>
<tr>
<th colspan=3>Transpose of 3x3 Molscript matrix</th>
<th></th>
</tr>
<tr align=center> <td>a11</td> <td>a12</td> <td>a13</td> <td>0.</td> </tr>
<tr align=center> <td>a21</td> <td>a22</td> <td>a23</td> <td>0.</td> </tr>
<tr align=center> <td>a31</td> <td>a32</td> <td>a33</td> <td>0.</td> </tr>
</tr>
<tr>
<th colspan=3> Translation components</th>
<th> Scale</th>
</tr>
<tr align=center> <td>T1</td> <td>T2</td> <td>T3</td> <td>S</td> </tr>
</table>
</center>
<i>NB</i>: The value of S (scaling) comes from the "window" parameter 
in Molscript. The column values above it are <i>always</i> zero.
</p>

<a name="labels">
<h4>How can I keep the Molscript labels in my Raster3D picture?</h4></a>
<p>
This used to be a pain to do. Now there is an easy answer: get Molscript version 2.
The old, laborious, procedure may still be informative as an example of
mixing PostScript and Raster3D, however. Here is a 
<a href="r3d_labels.html"> summary of how to do it</a> if you really want to.
</p>

<a name="black-white">
<h4>Black &amp; White figures</h4></a>
<p>
It is possible to use a general image
processing program (e.g. ImageMagick) to convert a color figure to a monochrome
figure. In general a straight conversion will produce an image which is much
too dark. In order to improve the result you can try breaking the conversion up
into several steps: first convert from full 24-bit color to a smaller number of
colors (say 256), next apply a substantial gamma correction (e.g. gamma&nbsp;
&nbsp; 2.0) to lighten the image, and finally convert the color image to
monochrome being sure to select a dithering option if it is available. Some
experimentation with this process can produce acceptable, although not ideal,
monochrome images suitable for printing on a standard laser printer. You may
have to repeat the color reduction and gamma correction steps before finally
converting to monochrome. Better results can be obtained by using the auxiliary
program <b><i>avs2ps</i></b> as a filter. This utility will convert any
AVS-format image, including the default output stream from
<b><i>render</i></b>, directly into a dithered black &amp; white PostScript
image. As of this writing the <b><i>avs2ps</i></b> program is included with the
Raster3D distribution.
</p>

<a name="PostScript">
<h4>Conversion to PostScript</h4></a>
<p>
Do <i>not</i> convert your raster image to PostScript unless you really, 
really have to. This should only happen if you want to send the image to
a printer that understands nothing but PostScript. The raster image consists of
a certain number of pixels on X and on Y, and the size of each dot depends
entirely on the physical resolution of the device the image is displayed on.
To produce a Raster3D figure of a given size on a PostScript printer, you must
know the physical resolution of the printer.
A true PostScript figure would be scalable and device-independent; 
this will not be true for a raster image forced into a PostScript file.  
Here are the required steps:
<ol>
<li>Calculate the required number of pixels in your Raster3D image. For example,
    if you want to end up with a figure that is 4" by 3" when printed on a 
    300 dpi (dots-per-inch) PostScript printer, then your raster image must
    be 1200x900 pixels.  Render it using the command <i>render -size 1200x900</i>
    to force it to be this exact size.
<li>Confirm that the rendered image is the correct size.
    The ImageMagick utility <b>identify</b> will do this for you.
<li>Convert the rendered image to a PostScript file using the ImageMagick
    <a href="http:/man/ImageMagick/convert.html">convert</a>
    utility.  You must explicitly specify
    <ul>
    <li>the physical resolution of the printer (e.g. -density 300)
    <li>the input image size
    <li>the PostScript "page" size (exactly equal to the image size)
    <li>an offset to the page size if you don't want the image to appear
        at the extreme lower left of the printed page 
	(+50+50 in the example below).
    </ul>
    Here is a suitable command for this example:

    <pre>
    convert -density 300 -geometry 1200x900 -page 1200x900+50+50 image.tiff image.ps
    </pre>
<li>Send the converted image to your PostScript printer.  If it does not come
    out the size you expected, then probably the printer has a different
    resolution than you thought.  You will have to go back to the beginning 
    and try again.
</ol>
</p>


<hr>
<a href="raster3d.html">
<img src="index_button.gif" align=top> Back to top </a>
<a href="http://www.bmsc.washington.edu/raster3d/raster3d.html">
<img src="r3d_icon.gif" alt="" align=top> Raster3D homepage </a>

<hr>
<address>
Ethan A Merritt / merritt@u.washington.edu / 
    <a href="http://www.bmsc.washington.edu/index.html">
    Biomolecular Structure Center at UW</a><br>
</address>

</html>