NAME
render - Raster3D molecular graphics package rendering program
SYNOPSIS
render < infile.r3d > outfile.png
render -png < infile.r3d > outfile.png
render -avs < infile.r3d > outfile.avs
render [-quality NN] -jpeg < infile.r3d > outfile.jpeg
render -tiff outfile.tiff < infile.r3d
render -sgi [outfile.rgb] < infile.r3d
render -out outfile.xxx < infile.r3d
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 one light source, additional non-shadowing light sources,
specular highlighting, transparency, and Phong shaded surfaces. Output
is to stdout [or optional file] in the form of a pixel image with 24
bits of color information per pixel. As of version 2.7, the default
output format is PNG.
OPTIONS
-aa Force anti-aliasing (SCHEME 4)
-alpha
Force output of transparency information (SCHEME 0). This only
works if the output image format supports an alpha channel (AVS,
TIFF, but not JPEG). Note that this turns off anti-aliasing.
-avs [outfile.avs]
By default render will produce an PNG image on stdout. The -avs
flag will cause it to output an AVS image file instead, or stream
the output to stdout if no file is specified.
-bg white|black|#RRGGBB
Set background color. #RRGGBB is a hexadecimal number representing
the red, green and blue components.
-draft
Turn off anti-aliasing (SCHEME 1) to increase rendering speed.
-fontscale
Only meaningful in conjunction with the -labels option. Modifies
the interpretation of font sizes during label processing.
Defaults to -fontscale 3.0, which will generate PostScript labels
that are at the correct nominal fint size when printed at 300 dpi.
-gamma GG
Apply gamma correction to output image.
-help
Prints a short summary of command line options.
-invert
Invert image top-to-bottom. This may be necessary if you are using
some odd viewing program.
-jpeg [outfile.jpeg]
Only if compiled with -DJPEG_SUPPORT. By default render will
produce an PNG image on stdout. The -jpeg flag will cause it to
output a JPEG image file instead, or stream the output to stdout
if no file is specified.
-labels [outfile.ps]
Process labels (object types 10, 11, 12) and create a PostScript
output file label3d.ps in addition to the rendered image file.
Output filename defaults to label3d.ps. This option is used by
the label3d script.
-out filename.xxx
Only if compiled with -DIMAGE_PIPE. The -out flag causes render
to pipe output to the ImageMagick command convert, with
instructions to convert it to an image file whose type is
determined by the filename extension xxx.
-png [outfile.png]
Only if compiled with -DPNG_SUPPORT. This is now the default
output format. The -png flag will stream the output to stdout if
no file is specified.
-quality
Only meaningful in conjunction with -jpeg option; sets the quality
(compression level) of the output image. Allowable values 1 - 100
(default 90).
-[no]shadow
Turn shadowing on or off.
-size HHHxVVV
Override the image size parameters (NTX,NTY,NPX,NPY) in file
header and produce an output image that is exactly HHH pixels in
the horizontal and VVV pixels in the vertical.
-sgi [filename.rgb]
Only if compiled with -DLIBIMAGE_SUPPORT. The -sgi flag will
cause render to output an SGI libimage style *.rgb file instead of
writing to stdout. The filename defaults to render.rgb, but
specifying a file on the command line will override this default.
-tiff filename
Only if compiled with -DTIFF_SUPPORT. The -tiff flag will cause
render to output a TIFF image to the specified file instead of
writing to stdout.
-transparent
(same as -alpha). Force output of transparency information
(SCHEME 0). This only works if the output image format supports an
alpha channel (AVS, TIFF, but not JPEG). Note that this turns off
anti-aliasing.
-zoom ZZ[%]
Rescale image by factor ZZ (ZZ% if the % sign is present).
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.) Maximum = 192 (controlled by MAXNTX, MAXNTY in render.f)
NPX,NPY
Number of computing pixels per tile in each direction. Maximum =
36 (controlled by MAXNPX, MAXNPY in render.f)
SCHEME
Pixel averaging (anti-aliasing) scheme. Anti-aliasing reduces the
jaggedness of edges at the cost of additional computation.
0 no anti-aliasing, include alpha blend (matte) channel
1 no anti-alaising, no matte channel
2 anti-alias by averaging 2x2 block of computed pixels for
each output pixel. Resulting image dimensions are 1/2 of
the nominal requested size.
3 anti-alias by averaging 3x3 block of computed pixels for
each 2x2 block of output pixels. Resulting image
dimensions are 2/3 of the nominal requested size.
(obsolete - use scheme 4 instead)
4 anti-alias as in scheme 3, but output image dimensions
are exactly as requested.
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 NPX and NPY to be divisible by 3. Schemes 2 and 4
require NPX and NPY to be divisible by 2.
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 reflections. A smaller value
results in a larger spot.
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 reflection quantity (e.g., 0.05).
SPECLR
Specular reflection quantity (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 Raster3D 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. EYEPOS = 0 disables 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 this
vector (see note on co-ordinate convention below). The secondary
light source is always haed-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 produces global scaling. Coordinate vectors [x y z] are
extended with a 1 to make them homogeneous, and then
postmultiplied by the entire matrix;
i.e., if
[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 always use mode INMODE 3.
type 1 = triangle
type 2 = sphere
type 3 = round-ended cylinder
type 4 (not used)
type 5 = flat-ended cylinder
type 6 = plane (triangle with infinite extent)
type 7 = normals at vertices of previous triangle
type 8 = material properties for subsequent objects
type 9 = terminate previous material properties
type 10/11/12 = reserved for label processing
type 13 = glow light source
type 14 = quadric surface
type 15 = do not apply TMAT to subsequent objects
type 16 = global rendering properties
type 17 = colors for vertices of preceding triangle or cylinder
type 0 = end of input file
INFMT or INFMTS
Object input format specifier(s). Normally * for free-format
input.
SAMPLE HEADER
Title (This is a 1280x1024 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 (from over right shoulder)
1 0 0 0 TMAT matrix describing
0 1 0 0 input coordinate transformation
0 0 1 0
0 0 0 0.6 enlarge by 40% (smaller scalar -> bigger objects)
3 mixed objects
* (free format triangle 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.
Files are first searched for in the current directory. If this search
fails, they are sought relative to the library directory specified by
the environmental variable R3D_LIB.
RASTER3D OBJECT TYPES
For Raster3D object types and object descriptor formats, see the man
page for r3d_objects.
ERROR MESSAGES
Some error messages may be safely ignored.
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.
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
See the HTML or PostScript documentation for instructions on increasing
array sizes.
SOURCE
anonymous ftp site:
ftp.bmsc.washington.edu
web URL:
http://www.bmsc.washington.edu/raster3d/raster3d.html
contact:
Ethan A Merritt
University of Washington, Seattle WA 98195
merritt@u.washington.edu
SEE ALSO
HTML and PostScript documentation
r3d_objects(l), avs2ps(l), rastep(l), rods(l), ribbon(l), balls(l),
label3d(l), stereo3d(l)
AUTHORS
Originally written by David J. Bacon.
Extensions, revisions, and modifications by Ethan A Merritt.