Provided by: raster3d_3.0-7-2build1_amd64 bug

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 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 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 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.

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.