raster3d(1) [debian man page]
Raster3D(1) General Commands Manual Raster3D(1) NAME
Raster3D - molecular graphics package SYNOPSIS
The Raster3D molecular graphics package consists of a core program render and a number of ancillary programs (balls, rastep, rods) which produce input files for rendering from PDB (Protein Data Bank) files of atomic coordinates. Raster3D can also render images composed using other programs such as MOLSCRIPT [Per Kraulis (1991), J. Appl. Cryst. 24, 946-950]. Raster3D is freely available. If you use the package to prepare figures for publication, please give proper credit to the authors. The proper citation for the current version is Merritt & Bacon (1997). Bacon & Anderson (1988) J. Molec. Graphics 6, 219-220. Merritt & Murphy (1994) Acta Cryst. D50, 869-873. Merritt & Bacon (1997) Meth. Enzymol. 277, 505-524. DESCRIPTION
Raster3D uses a fast Z-buffer algorithm to produce high quality pixel images featuring one shadowing light source, additional non-shadowing light sources, specular highlighting, transparency, and Phong shaded surfaces. Output is in the form of a pixel image with 24 bits of color information per pixel. Raster3D does not depend on graphics hardware. The following image output formats are supported: AVS, JPEG, PNG, TIFF, and SGI libimage. To actually view or manipulate the images pro- duced, you must also have installed an image viewing package (e.g. John Cristy's ImageMagick or the SGI libimage utilities). A filter utility avs2ps is included in the package which can convert an AVS format output stream directly to a dithered monochrome PostScript image. Although Raster3D is not intended as a general purpose ray-tracing package, nothing in the rendering process is specific to molecular graphics. EXAMPLES
Using only programs included in the Raster3D distribution one can create and render space-filling models, ball-and-stick models, ribbon models, and figures composed of any combination of these. The following set of commands would produce a composite figure of an Fe-contain- ing metalloprotein with a smoothly shaded ribbon representation of the protein and spheres drawn for the Fe atoms: # # Draw smooth ribbon with default color scheme 2, # save description (with header records) in ribbon.r3d # cat protein.pdb | ribbon -d2 > ribbon.r3d # # Extract Fe atoms only, and draw as spheres. # Color info is taken from colorfile. # Save description (with no header records) in irons.r3d # grep "FE" protein.pdb | cat colorfile - | balls -h > irons.r3d # # combine the two descriptions and render to a PNG image # cat ribbon.r3d irons.r3d | render > picture.png Integrated use of MOLSCRIPT/Raster3D/ImageMagick allows one to describe, render, and view 3D representations of existing MOLSCRIPT figures: molscript -r infile.dat | render | display png:- SOURCE
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
render(l), rastep(l), rods(l), ribbon(l), balls(l), avs2ps(l), stereo3d(l) AUTHORS
Originally written by David J Bacon and Wayne F Anderson. Ancillary programs by Mark Israel, Stephen Samuel, Michael Murphy, Albert Berghuis, and Ethan A Merritt. Extensions, revisions, and modi- fications by Ethan A Merritt. Raster3D V3.0 14 December 2010 Raster3D(1)
Check Out this Related Man Page
RENDER(1) General Commands Manual RENDER(1) 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 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. 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 images whose labels are at the correct nominal font size when printed at 300 dpi. For images to be viewed on the screen, you probably want to set -fontscale 1. -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] 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 Process labels (object types 10, 11, 12) and include them in the rendered image. -png [outfile.png] 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 hor- izontal 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 writ- ing 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 writ- ing 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 image is rendered piecemeal by dividing it into an array of equal size rectangular tiles.) The width of the output image in pixels is NTX*NPX by NTY*NPY. The speed of the program is sensitive to the number of tiles. However, as a convenience you can set NPX and NPY to zero and use NTX, NTY to provide the net size of the output image in pixels. In this case the program will choose the number of tiles itself so that you don't have to worry about it. NPX,NPY Number of computing pixels per tile in each direction. Maximum = 36 (MAXNPX, MAXNPY in render.f). If you set NPX and NPY to zero, the program will use NTX and NTY as the net size of the image in pixels. 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 correspond- ing 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 shad- ows. 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 transla- tion, 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 pos- sible to re-use standard objects in multiple rendered scenes, e.g. a set of bounding planes or standard definitions of material proper- ties. 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 shad- owing "error" refers to a shadow which lies outside of the image entirely. However, if your image does in fact contain missing or trun- cated 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. SOURCE
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), stereo3d(l) AUTHORS
Originally written by David J. Bacon. Extensions, revisions, and modifications by Ethan A Merritt. Raster3D V3.0 14 December 2010 RENDER(1)