NAME

       rd3_objects - object types used by the Raster3D package

DESCRIPTION

       These are the object descriptor types, and the required parameters, recognized by the
       render program and other components of the Raster3D package.

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 - cylinder with round ends

       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 - cylinder with flat ends

       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;
        The plane is defined by any three points. It's color fades from full intensity in the
       foreground to half-intensity at the back.

Object type 7 - Vertex normals

       Explicit vertex normals for preceding triangle object. This object must directly follow
       the triangle object, and uses the same format.

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 next
       line of the input stream:
        8
        MPHONG MSPEC SR SG SB CLRITY OPT1 OPT2 OPT3 OPT4

       MPHONG
            value >=0 overrides the global Phong power for specular highlighting

       MSPEC
            value >=0 overrides the 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 component will default to the base colour
            component of the object being rendered.

       CLRITY
            The degree of transparency for this material, with 0.0 indicating an opaque surface
            and 1.0 a purely transparent one.

       OPT1 Affects processing of transparent objects which belong to the same material, but
            occlude each other (for instance the front and back surfaces of a transparent
            molecular surface).
             OPT1 = 0 will render all outward-facing transparent surfaces
             OPT1 = 1 will render only the topmost outward-facing surface
             OPT1 = 2 will render both the outward- and inward- facing surfaces of transparent
            spheres and cylinders

       OPT2 Selects from several variant treatments of transparency as a function of alpha and
            the Z component ZN of the surface normal.
             OPT2 = 0    T(ZN) = 0.25(1+cos(pi*alpha*ZN)^2
             OPT2 = 1    T(ZN) = (1-abs(alpha*ZN))^2
             OPT2 = 2    T(ZN) = 1 - alpha ^ (cos(pi/4) / abs(ZN))
             OPT2 = 3    T(ZN) = 1 - alpha Option 0 is an empirical function that I think looks
            good.

       OPT3 Not used

       OPT4 Non-zero to indicate that additional modifier records follow immediately. Each
            modifier must constitute a single line, and OPT4 tells how many of these lines there
            will be.  Here is a complete list of modifiers currently available, and their
            parameters
             SOLID         RED GREEN BLUE
             BACKFACE RED GREEN BLUE MPHONG MSPEC
             FRONTCLIP     ZFRONT
             BACKCLIP ZBACK
             BOUNDING_COLOR     RED GREEN BLUE
             BOUNDING_PLANE     BPTYPE X Y Z Xnorm Ynorm Znorm
             ORTEP_LIKE    used to create fancy ellipsoids (see rastep documentation)

Object type 9 - End_material

       Terminates application of all previously defined special material properties (object type
       8) or isolation from TMAT transformation (object type 15).

Object types 10,11,12 - Label descriptors

       These object types are used as label descriptors.  The current version of render ignores
       them unless the -labels option is selected on the command line.

       Object type 10 - font_name size alignment
       Legal values subject to details of font processing implementation.
        font_name is any font name recognized by libgd
        size is the font size in points, but is modified by render's -fontscale option
        alignment is "Left", "Right", "Center", or "Offset".

       Object type 11 - Label text
        X Y Z R G B     (On one line) label position and color
        Label text      (On 2nd line)

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.
        13
        GLOWSRC(3) GLOWRAD GLOW GOPT GPHONG GLOWCOL(3)

       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

       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 is the set of points for which Q(x,y,z) = 0 where

        Q(x,y,z) = Ax2 + By2 + Cz2 + 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 - TMAT Isolation

       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. If the image is
       rectangular, coordinates run from -0.5 to +0.5 along both X and Y. If the image is
       rectangular, coordinates run from -0.5 to +0.5 along the shorter dimension.  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 16 - Global property

       Object type 16 is always followed by a single record that affects the rendering of the
       entire scene. Currently the options are FOG, FRONTCLIP, and BACKCLIP.  There are also
       options ROTATION and TRANSLATION that affect only objects following their appearance in
       the input stream.

Object type 17 - Vertex colours

       Explicit vertex colours for preceding triangle or cylinder object.
           R1 G1 B1   R2 G2 B2   R3 G3 B3

Object type 18 - Vertex transparency

       Explicit transparency at vertices of preceding object.  All three values are required,
       though only the first two are used for cylinders, and only the first one for spheres.
           Trans1 Trans2 Trans3

Object type 19 - TMAT Isolation

       Similar to object type 15, except the the x and y scales are the same only in the case of
       a square image.  Both the x and y axes run from -0.5 to +0.5 regardless of the aspect
       ratio of the rendered image.

SEE ALSO

        PostScript and HTML documentation
        render(l)