RENDER

SYNOPSIS

render is the central image rendering program of the Raster3D molecular graphics package render [-tiff outfile.tiff] [-sgi outfile.rgb] [-original] < input.r3d > outfile Render reads an ascii file consisting of several header lines followed by individual object descriptors. The objects are rendered using a fast Z-buffer algorithm to produce a high quality pixel image which contains two light sources, specular highlighting, Phong shaded surfaces, and shadows. Output is to stdout [or optional file] in the form of a pixel image with 24 bits of color information per pixel. The default output file format is an AVS image file. Support for TIFF or SGI libimage image files may be optionally included during installation of the Raster3D package.

Several utility programs exist which will create all or part of an acceptable input file by reading atomic coordinates from a Brookhaven PDB file. These include balls, rods, and ribbon from the Raster3D distribution kit, and Molscript [Per Kraulis (1991) J. Appl. Cryst. 24, 946-950].

Black&white half-toned PostScript output may be obtained by filtering the output stream from render through the utility program avs2ps.

EXAMPLES

Render a simple space-filling model coloured by residue type: cat mycolors.pdb protein.pdb | balls | render > mypicture.avs Display the same picture on an X-windows display directly using ImageMagick: cat mycolors.pdb protein.pdb | balls | render | display avs:- Render and display the same picture using the SGI libimage format: cat mycolors.pdb protein.pdb | balls | render -sgi picture.rgb ipaste picture.rgb Render a stick-figure model of a cofactor jointly with a ribbon model of a protein. Note that the header records are generated by the ribbon command in this case; the -h flag suppresses generation of a second set of header records in the rods command. The ImageMagick convert command is used to save the resulting image as a TIFF file. ribbon -d4 protein.pdb > ribbon.r3d cat colors.pdb cofactor.pdb | rods -bs -h > cofactor.r3d cat ribbon.r3d cofactor.r3d | render | convert avs:- picture.tiff If TIFF support has been built directly into Raster3D, then the previous command can be modified to produce a TIFF file without conversion: cat ribbon.r3d cofactor.r3d | render -tiff picture.tiff

OPTIONS

-tiff filename: Only if compiled with -DTIFF_SUPPORT. By default render will produce an AVS-compatible image on stdout. The -tiff flag will cause it to output a TIFF image to the specified file instead.
-sgi filename: Only if compiled with -DLIBIMAGE_SUPPORT. By default render will produce an AVS-compatible image on stdout. The -sgi flag will cause it to output an SGI libimage style *.rgb file instead. In this case default output is to the file render.rgb, but specifying a file on the command line will override this default.
-original: This flag causes render to produce an output image compatible with some earlier versions of the Raster3D package. Output is to stdout.

DESCRIPTION

The input to render consists of a single text file containing everything necessary to prepare the image of a scene consisting of coloured spheres, cylinders and triangles. The header records contain information global to the scene being rendered. The header records are followed by individual object records containing coordinate and color specification for the objects in the scene. The surface shading of primitive objects (spheres, cylinders, and simple triangles) is calculated analytically. Sequential triangles forming a ribbon-like chain are rendered by a more complex algorithm which produces the appearance of a a smoothly-shaded surface rather than a faceted one [ref: Merritt & Murphy].

HEADER RECORDS

The required header records of a render input file are described below. Except where noted, each item is on a line by itself in free format. The names are of variables in the program source code.

TITLE

Anything you like, up to 80 characters.

NTX,NTY

Number of ``tiles'' in each direction. (The output display is considered to be divided up into an array of identical rectangular tiles.) The maximum is 192 unless you have increased MAXNTX and MAXNTY in render.f.

NPX,NPY

Number of computing pixels per tile in each direction. Maximum = 36 (MAXNPX, MAXNPY in render.f)

SCHEME

Pixel averaging (anti-aliasing) scheme. Anti-aliasing reduces the jaggedness of edges at the cost of additional computation. If you are going to matte your images against an externally generated background, use scheme 0 (matting and anti-aliasing do not mix well).

Scheme 0: no anti-aliasing, include alpha blend (matte) channel in output image
Scheme 1: no anti-aliasing, no matted channel
Scheme 2: anti-alias by averaging 2x2 computing pixels for each output pixel
Scheme 3: anti-alias by averaging 3x3 computing pixels for each 2x2 output pixels
Scheme 4: anti-alias as in scheme 3, but header specifies final raster size rather than computing raster size

(i.e. schemes 0, 1, and 4 produce a NTX*NPX by NTY*NPY pixel image; scheme 3 produces a (2/3)NTX*NPX by (2/3)NTY*NPY image). Scheme 3 requires that NPX and NPY be divisible by 3. Schemes 2 and 4 require that NPX and NPY be divisible by 2.
Images can be previewed using scheme 1 for greater speed, and re-rendered with anti-aliasing scheme 4 with no change in the output image size. No changes to NTX, NTY, NPX, NPY are required in this case.

BKGND

Background colour (red, green, and blue components, each in the range 0 to 1).

SHADOW

T to calculate shadowing within the scene, F to omit shadows

IPHONG

Phong power (e.g., 25) for specular highlights. A smaller value results in a larger spot.
IPHONG = 0 disables specular highlighting and all processing of ribbon triangles

STRAIT

Straight-on (secondary) light source contribution (e.g., 0.15). The primary light source contribution (see also SOURCE below) is given by PRIMAR = 1 - STRAIT.

AMBIEN

Ambient illumination contribution (e.g., 0.05). Increasing the ambient light will reduce the contrast between shadowed and non-shadowed regions.

SPECLR

Specular reflection contribution (e.g., 0.25).
The diffuse reflection quantity is given by DIFFUS = 1 - (AMBIEN+SPECLR). Ambient and diffuse reflections are chromatic, taking on the specified colour of each object, whereas specular reflections are white.

EYEPOS

You can think of the image produced by render as corresponding to a photograph taken by a camera placed a certain distance away from the objects making up the scene. This distance is controlled by the EYEPOS parameter. EYEPOS = 4 describes a perspective corresponding to a viewing distance 4 times the narrow dimension of the described scene. A very large value of EYEPOS will yield a scene with essentially no parallax or perspective.

SOURCE

Primary light source position (e.g., 1 1 1). This is a white light point source at infinite distance in the direction of the vector given (see note on co-ordinate convention below). The secondary light source is always head-on. Only the primary light source casts shadows.

TMAT

Homogeneous global transformation for input objects, given as a 4x4 matrix on 4 lines just as you would write it if you intended it to be a postfix (suffix) operator. The upper left 3x3 submatrix expresses a pure rotation, the lower left 1x3 submatrix gives a translation, the upper right 3x1 submatrix should be zero (otherwise extra perspective is introduced), and the lower right scalar (h) produces global scaling. Note that the scale factor h ends up being applied as an inverse; i.e. a larger value of h will result in shrinking the objects in the picture. Input coordinate vectors [x y z] are extended with a 1 to make them homogeneous, and then post-multiplied by the entire matrix; i.e. [x' y' z' h'] = [x y z 1][TMAT], then the ultimate co-ordinates are [x'' y'' z''] = (1/h')[x' y' z'].

INMODE

Object input mode (1, 2, or 3), where mode 1 means that all objects are triangles, mode 2 means that all objects are spheres, and mode 3 means that each object will be preceded by a record containing a single number indicating its type. The Raster3D programs use only mode 3.
type 1 = triangle
type 2 = sphere
type 3 = round-ended cylinder
type 5 = flat-ended cylinder
type 6 = plane (triangle with infinite extent)
type 7 = explicit surface normals at vertices of previous triangle
type 8 = explicit material properties for subsequent objects
type 9 = terminate previous explicit material properties
types 10/11/12 = (version 2.3) these object types are reserved for label processing
type 13 = glow light source (version 2.3)
type 0 = end of input file

INFMT or INFMTS

Object input format specifier(s). For object input modes 1 and 2, there is just one format specifier INFMT for the corresponding object type, while for mode 3, there are three format specifiers INFMTS on three lines. The first describes the format for a triangle, the second for a sphere, and the third for a cylinder. Each format specifier is either a Fortran format enclosed in parentheses, or a single asterisk to indicate free-format input. Parameters are read in the order

triangle or plane (object types 1 or 6):: x1, y1, z1, x2, y2, z2, x3, y3, z3, red, green, blue
sphere (object type 2):: x, y, z, radius, red, green, blue
cylinder (object type 3 or 5):: x1, y1, z1, R1, x2, y2, z2, R2, red, green, blue (R1 is the cylinder radius, R2 is currently ignored).

Additional object types added in Version 2.1

Version 2.1 of Raster3D added support for a few new object types. These are intended to provide additional flexibility in adapting other molecular graphics tools to compose figures for Raster3D to render.

Object type 7

Explicit vertex normals for preceeding triangle object. This object must directly follow the triangle object, and uses the same format. The intended use of this object type is to allow rendering of arbitrary molecular surfaces.

Object type 8

Material properties. These values override the specification of lighting and specular highlighting in the header records, allowing some objects to have different surface properties from the rest. The specified values will apply to all subsequent objects until an object of type 9 is encountered. The parameters are read as free format floating point numbers from the following line:

MPHONG

override global Phong parameter for specular highlighting

MSPEC

override global specular scattering contribution

SR,SG,SB

RGB triple specifying color of reflected light (by default all specular highlights are white). A negative value for any colour component defaults to the corresponding base colour component of the object being rendered.

CLRITY

(floating point value between 0.0 and 1.0) The degree of transparency for this material, with 0.0 indicating an opaque surface and 1.0 indicating a purely transparent one.

OPT(4)

four additional fields are reserved for future expansion of the material properties list; they were ignored in previous versions, but starting in version 2.3 OPT(1) controls the algorithm used for rendering transparent surfaces:

OPT(1) = 0: Render each transparent object, even if it is occluded by another object with the same material descriptor.
OPT(1) = 1: Render a transparent object only if it is the "top" instance of a given transparent material. I.e. if one part of a transparent surface occludes another part, the occluded part is effectively invisible. This will, for example, remove interior cavities from a molecular surface.

Object type 9

Terminates previous set of special material properties. The rest of this record is ignored, so object type 9 may also be used as a comment record.

Additional object types added in Version 2.3

Version 2.3 introduces preliminary support for labels in a render input file. The actual implementation of label handling is not done in render, however, but rather in a separate, parallel, program called labels3d. Object types 10, 11, and 12 will be used to specify labels. The current version of the render program will recognize these, but otherwise ignore them.

Object type 10

Font specifier and alignment (single line of text)

Object type 11

[XYZ] [RGB]

label text

Object type 12

reserved (single line of text)

Object type 13

Glow light source. This is a colored, non-shadowing, light source with finite [x y z] coordinates and a limited range of illumination. Control parameters are read in free format from a single line of input following the line specifying the object type.

GLOWSRC(3): [x y z] coordinates of light source
GLOWRAD: limiting radius of light source (see GOPT)
GLOW: fractional contribution (0.0 - 1.0) of glow light to total lighting model
GOPT: (integer 0/1/2/3/...) - controls functional form in which limiting radius is applied [under development]
GPHONG: Phong parameter controlling specular highlights from glow light source
GLOWCOL(3): RGB triple specifying color of glow light source

SAMPLE HEADER

My picture. (describes a 1280 x 1024 pixel anti-aliased image) 
80 64 	  tiles in x,y 
24 24     pixels (x,y) per tile 
3 	  anti-aliasing level 3; 3x3->2x2 
0 0 0 	  black background 
F 	  no shadows cast 
25 	  Phong power 
0.25 	  secondary light contribution 
0.05 	  ambient light contribution 
0.25 	  specular reflection component 
4.0 	  eye position 
1 1 1 	  main light source position (from over right shoulder) 
1 0 0 0   view matrix describing input coordinate transformation 
0 1 0 0 
0 0 1 0 
0 0 0 0.6 no translation; enlarge objects in picture by 66% (1/.6)
3 	  mixed objects 
* 	 (free format triangle and plane descriptors) 
* 	 (free format sphere descriptors) 
* 	 (free format cylinder descriptors)

FILE INDIRECTION

At any point in the input stream to render where an object descriptor would be legal, it is also legal to insert a line beginning with `@'. In this case the remainder of the line is interpreted as the name of a file from which further input is taken. This mechanism makes it possible to re-use standard objects in multiple rendered scenes, e.g. a set of bounding planes or standard definitions of material properties. When input from this level of file indirection is terminated by encountering an object descriptor of type 0, control returns to the previous input stream. Multiple levels of file indirection are possible.

SAMPLE INPUT DATA FOLLOWING HEADER

The following records describe a single red triangle and a single blue sphere. The blue sphere is affected by whatever material descriptor is in the file material1.r3d

1
-.1 0. 0.     .1 0. 0.     0. -.2 0.5         1.0 0.0 0.0
@material1.r3d
2
0.3 0.3 0.0         0.1                       0.0 0.0 1.0
9 End material1
0

ERROR MESSAGES

Possible shadowing error NSXMAX = xxx: This is most usually caused by an object which projects far out of the field of view, for example a plane surface. In most cases the shadowing "error" refers to a shadow which lies outside of the image entirely. However, if your image does in fact contain missing or truncated shadows you can overcome this problem by re-compiling the render program with larger values of NSX and NSY as indicated by the error message.

INCREASING THE ARRAY SIZES IN RENDER:

If you are creating images of very large proteins, or if you are rendering surfaces with many facets, then you may fill the storage arrays in render. If so you will get an error message something like STOP 1234 **** too many objects - increase MAXOBJ and recompile The parameters which you may need to increase are contained in the following lines of render.f: * Maximum number of objects (was 7500) PARAMETER (MAXOBJ = 25000) * * Array elements available for object details PARAMETER (MAXDET = 250 000, MAXSDT = 250 000) * * Array elements available for sorted lists ("short" lists) PARAMETER (MAXSHR = 150 000, MAXSSL = 150 000) You can use the normal3d utility to calculate how many objects and object details are needed for your picture. The sorted list sizes are harder to calculate in advance, but the render program itself should indicate how much space would be required to complete a picture which it cannot currently handle.

Increase the appropriate PARAMETER values by editing render.f, and recompile the render program by typing "make render".

AUTHORS

Originally written by David J. Bacon. Extensions, revisions, and modifications by Ethan A Merritt.

Raster3D homepage