RENDER

SYNOPSIS

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

EXAMPLES

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.

-invert

Invert the image top-to-bottom. This could be necessary if you are using some odd viewing program.

DESCRIPTION

HEADER RECORDS

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.

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.

SAMPLE HEADER

My picture. (describes a 1280 x 1024 pixel anti-aliased image) 
80 64 	  tiles in x,y 
16 16     pixels (x,y) per tile 
4 	  anti-aliasing level 4; 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)

OBJECT TYPES

Object type 1

triangle

x1, y1, z1, x2, y2, z2, x3, y3, z3, red, green, blue

Object type 2

sphere

x, y, z, radius, red, green, blue

Object type 3

round-ended cylinder

x1, y1, z1, R1, x2, y2, z2, R2, red, green, blue
(R1 is the cylinder radius, R2 is currently ignored).

Object type 4

not used

Object type 5

flat-ended cylinder

x1, y1, z1, R1, x2, y2, z2, R2, red, green, blue
(R1 is the cylinder radius, R2 is currently ignored).

Object type 6

plane

x1, y1, z1, x2, y2, z2, x3, y3, z3, red, green, blue

Object type 7

explicit surface normals at vertices of preceding triangle

u1, v1, w1, u2, v2, w2, u3, v3, w3
Explicit vertex normals for preceding triangle object. This object must directly follow the triangle object (see also object type 17). The intended use of this object type is to allow description of arbitrary molecular surfaces in terms of a triangular mesh.

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 in free format 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 reflections are white), a negative value for any component will default to the 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; 0.0 indicates an opaque surface and 1.0 indicates a purely transparent one.

OPTS(4)

four additional fields are reserved for future expansion of the material properties list; these must be present. The first field controls alternative algorithms for rendering transparent objects:

OPT(1) = 0 render self-occluding portions of a transparent material separately

OPT(1) = 1 render only the ``top'' surface of transparent material

The last field is non-zero to signal that additional modifier records will follow immediately. Each modifier record must constitute a single line, and OPT(4) states how many of these there will be. For example

OPT(4) = 2 means that the next two lines contain additional material modifiers

Object type 8 modifiers
Additional modifiers to MATERIAL descriptors (type 8) are now supported. Each modifier record must constitute a single line of input, and the total number of such modifier lines must be specified in the final parameter of the MATERIAL record. Modifiers currently supported include SOLID and BACKFACE records, as shown in the following example of a 2- sided material that is solid red on one side and solid blue on the other side: 9 Here is an example of specifying a double sided material 9 The MATERIAL record itself specifies an opaque material with PHONG 9 value to 25 and specular parameters taken from the header records, 9 and says that there are two following modifer lines. 9 The SOLID modifier gives an RGB color triple that over-rides colors on 9 subsequent objects. 9 The BACKFACE modifier specifies a separate RGB color for the other side 9 of this material, and sets the Phong control parameter and specular 9 component of this surface to zero (i.e. it's a matte blue surface). 8 20. -1. 1. 1. 1. 0.0 0 0 0 2 SOLID 1.0 0.0 0.0 BACKFACE 0.3 0.3 1.0 0 0

Object type 9

terminate special properties

Terminates previous set of special material properties (object type 8) or isolation from TMAT transformation (object type 15). The rest of this record is ignored, so object type 9 may also be used as a comment record. It is preferable, however, to begin pure comments with '#' rather than '9'.

Version 2.3 introduced 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. (If you are developing a higher-level application that will pass labels to Raster3D for rendering, please contact me so that we can make sure the protocols are compatible -EAM)

Object type 10

(label support)

Font specifier and alignment (single line of text)

Object type 11

(label support)

[XYZ] [RGB]
Label text

Object type 12

(label support)

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

Object type 14

quadric surface

x, y, z, limiting_radius, red, green, blue, A, B, C, D, E, F, G, H, I, J
Quadric surfaces include spheres, cones, ellipsoids, paraboloids, and hyperboloids. The motivation for this code was to allow rendering thermal ellipsoids for atoms, so the other shapes have not been extensively tested. A quadric surface is described by 10 parameters (A ... J). Although these parameters are sufficient to describe a quadric surface located anywhere, for efficiency during rendering it is also useful to know the center and a bounding sphere. So by convention we require that (A...J) describe a surface centered at the origin, and add additional parameters x, y, z to add a translation component. Therefore a QUADRIC descriptor to render has the 17 parameters listed above.

The surface itself is the set of points for which Q(x,y,z) = 0 where

Q(x,y,z) = Ax² + By² + Cz² + 2Dxy + 2Eyz + 2Fzx + 2Gx + 2Hy + 2Iz + J

Points further from the origin (prior to translation!) than the limiting radius are not rendered.

Object type 15

begin isolation from TMAT transformation

Objects following this descriptor are interpreted as being in an absolute coordinate system centered at the origin and having unit extent in X, Y, and Z. The rotation and translation described by the TMAT matrix is not applied. This isolation from TMAT applies to subsequent objects until an object of type 9 is encountered.

Object type 17

explicit coloring at vertices of preceding triangle

R1 G1 B1 R2 G2 B2 R3 G3 B3 Normally a triangle is colored uniformly in the color specified by the RGB triple in the TRIANGLE record itself. Using this additional object, however, you can specify a separate color for each vertex of the triangle. Points in the interior of the triangle are colored by interpolation using the vertex colors. This is commonly used in conjunction with explicit vertex normals (object type 7) to describe a smooth surface in terms of a triangular mesh. In this case the component triangles of the surface are described by three successive objects of types 1, 7, and 17. (The ordering 1, 17, 7 is also acceptable).

Object type 0

force end of input stream (optional)

Further records in input file will not be read.

SAMPLE INPUT DATA FOLLOWING HEADER

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

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.

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

AUTHORS

Back to top

Raster3D homepage