/usr/share/doc/raster3d/html/render.html is in raster3d-doc 3.0-3-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 | <html>
<head>
<title> render - Raster3D package </title>
<LINK REL=stylesheet HREF="r3d_docstyle.css" TEXT="text/css">
</head>
<body>
<h1 align=center>RENDER</h1>
<h4> SYNOPSIS</h4>
<p>
Render is the central image-rendering program of the
<a href="raster3d.html"> Raster3D </a>
molecular graphics package.
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.
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 file format is an PNG image sent to stdout.
Additional image file types may be optionally included
during installation of the Raster3D package.
</p>
Usage:
<pre>
input from stdin; output mode controlled from command line
render PNG image to stdout
render -avs [outfile] AVS image to outfile (defaults to stdout)
render -png [outfile] PNG image to outfile (defaults to stdout)
render -jpeg [outfile] JPEG image to outfile (defaults to stdout)
render -sgi [outfile] output to SGI libimage file (defaults to render.rgb)
render -tiff [outfile] output to TIFF file (defaults to render.tif)
</pre>
Options:
<pre>
these over-ride contents of input stream header records
-aa use anti-aliasing (SCHEME 4)
-alpha alpha channel in output image (SCHEME 0)
-bg COLOR set background, COLOR is black, white or #RRGGBB
-debug verbose output while running
-draft no anti-aliasing (SCHEME 1)
-fontscale FF multiplier for PostScript label fonts
-gamma GG apply gamma correction GG to output image
-invert invert y axis
-labels render embedded labels to the output file as well
-quality QQ 0 < QQ < 100 jpeg compression parameter (default 90)
-[no]shadow enable or disable shadowing
-size HHHxVVV specify size of output image in pixels
-transparent same as -alpha (SCHEME 0)
-zoom ZZ[%] rescale image by a factor of ZZ
</pre>
<H4>MORE INFORMATION</H4>
<div class="box">
<center>
<table cellpadding=5>
<tr>
<td><a href="#examples">Examples</a> </td>
<td><a href="#options">Options</a> </td>
<td><a href="#description">Description</a> </td>
<td><a href="#header">Header Records</a> </td>
</tr>
<tr>
<td><a href="#sample_header">Sample Header</a> </td>
<td><a href="#objects">Object Types</a> </td>
<td><a href="#comments">Comments</a> </td>
<td><a href="#indirection">File Indirection</a> </td>
</tr>
<tr>
<td><a href="#sample_data">Sample Data Stream</a> </td>
<td><a href="#errors">Error Messages</a> </td>
<td><a href="#arrays">Increasing Array Sizes</a> </td>
</tr>
<tr>
<td><a href="#authors">Authors</a> </td>
</tr>
</table>
</center>
</div>
<h4>
<a name="examples">EXAMPLES</a></h4>
Render a simple space-filling model coloured by residue type:
<pre>
cat mycolors.pdb protein.pdb | balls | render > mypicture.png
</pre>
Display
the same picture on an X-windows display directly using ImageMagick:
<pre>
cat mycolors.pdb protein.pdb | balls | render | display png:-
</pre>
Render
and display the same picture using the SGI libimage format:
<pre>
cat mycolors.pdb protein.pdb | balls | render -sgi picture.rgb
ipaste picture.rgb
</pre>
Render
a stick-figure model of a cofactor jointly with a ribbon model of a protein.
Note that the header records are generated by the ribbon command in this case;
the -h flag suppresses generation of a second set of header records in the rods
command. The ImageMagick convert command is used to save the resulting image as
a TIFF file.
<pre>
ribbon -d4 protein.pdb > ribbon.r3d
cat colors.pdb cofactor.pdb | rods -bs -h > cofactor.r3d
cat ribbon.r3d cofactor.r3d | render | convert png:- picture.tiff
</pre>
If
TIFF support has been built directly into Raster3D, then the previous command
can be modified to produce a TIFF file without conversion:
<pre>
cat ribbon.r3d cofactor.r3d | render -tiff picture.tiff
</pre>
</p>
<h4><a name="options">OPTIONS</a></h4>
<dl>
<dt><i> -aa</i>
<dd>Force anti-aliasing (SCHEME 4) regardless of the scheme specified in
the file header
<dt><i> -alpha</i>
<dd>Force output of transparency information (SCHEME 0) regardless of the scheme
specified in the file header. This only works if the output format
supports an alpha channel (AVS, TIFF, but <i>not</i> JPEG). Note that this
turns off anti-aliasing. This option can be used to produce an image with
a transparent background.
<dt><i> -bg white|black|#RRGGBB</i>
<dd>Set background color. #RRGGBB is a hexadecimal representation of the
color components.
<dt><i> -draft</i>
<dd>Turn off anti-aliasing to increase rendering speed.
<dt><i> -fontscale XX</i>
<dd>Only meaningful in conjunction with the <i>-labels</i> option.
Modifies the interpretation of font sizes during label processing.
If <i>-fontscale</i> is not specified, the program next looks for an
environmental variable FONTSCALE. If neither a command line value or
an environmental variable is found, the program defaults to
<i>-fontscale 3.0</i>, which generates PostScript labels that are
approximately the nominal font size when printed at 300 dpi.
<dt><i> -help</i>
<dd>Print summary of options.
<dt><i> -gamma GG</i>
<dd>Apply gamma correction to output image. Gamma > 1 makes it lighter;
gamma < 1 makes it darker.
<dt><i> -invert</i>
<dd>Invert the image top-to-bottom. This could be necessary
if you are using some odd viewing program.
<dt><i>-jpeg </i>
<dd>Only if compiled with -DJPEG_SUPPORT. By default
render will produce an AVS-compatible image on stdout. The -jpeg flag will
cause it to output a JPEG image stream to stdout instead.
<dt><i> -labels </i>
<dd>Process labels (<a href="#obj10">object types 10,11,12</a>)
and embed them in the output image. The text rendering is done via libgd,
so this option only works from png or jpeg output.
<dt><i> -quality NN</i>
<dd>Only meaningful in conjunction with the <i>-jpeg</i> option;
<dt><i> -size HHHxVVV</i>
<dd>Override the image size parameters (NTX,NTY,NPX,NPY) in the file header
and produce an output image that is exactly HHH pixels in the horizontal
and VVV pixels in the vertical.
<dt><i> -sgi [filename.rgb]</i>
<dd>Only if compiled with -DLIBIMAGE_SUPPORT. The -sgi flag
will cause render 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.
sets the output image quality parameter. Allowable values range from 1-100 (default = 90).
<dt><i>-tiff filename.tiff</i>
<dd>Only if compiled with -DTIFF_SUPPORT.
The -tiff flag will cause render to output a TIFF image to the specified file.
<dt><i>-transparent</i>
<dd>(same as <i>-alpha</i>) Force output of transparency information.
This only works if the output format supports an alpha channel (AVS, PNG, TIFF,
but <i>not</i> JPEG).
<dt><i>-zoom ZZ[%]</i>
<dd>Modifies the scale factor TMAT(4,4) in the header records. This does not change
the overall dimensions of the image, just the size of the objects within the image.
ZZ > 1 will make the objects appear larger, ZZ < 1 will shrink them. If the ZZ is
is given as a percentage, then ZZ > 100% enlarges and ZZ < 100% shrinks.
</dl>
</p>
<h4><a name="description">DESCRIPTION</a></h4>
The input to render consists of a single text file containing everything
necessary to prepare the image of a scene consisting of coloured spheres,
cylinders and triangles. The header records contain information global to the
scene being rendered. The header records are followed by individual object
records containing coordinate and color specification for the objects in the
scene. The surface shading of primitive objects (spheres, cylinders, and simple
triangles) is calculated analytically. Sequential triangles forming a
ribbon-like chain are rendered by a more complex algorithm which produces the
appearance of a a smoothly-shaded surface rather than a faceted one [ref:
Merritt & Murphy].
<h4>
<a name="header">HEADER RECORDS </a></h4>
The required header records of a render input file are described below. Except
where noted, each item is on a line by itself in free format. The names are of
variables in the program source code.
<dl>
<dt><b><i></i></b></dl><dl>
<dt><i>TITLE</i><dd>Anything you like, up to 80 characters.
<dt><i>NTX,NTY</i><dd>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.
<dt><i>NPX,NPY</i><dd>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.
<dt><i>SCHEME</i><dd>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).
<br>
<dl>
<dt> Scheme 0
<dd> no anti-aliasing, include alpha blend channel in output image
<dt> Scheme 1
<dd> no anti-aliasing, no alpha channel
<dt> Scheme 2
<dd> anti-alias by averaging 2x2 computing pixels for each output pixel
<dt> Scheme 3
<dd> anti-alias by averaging 3x3 computing pixels for each
2x2 output pixels (obsolete - use scheme 4 instead)
<dt> Scheme 4
<dd> anti-alias as in scheme 3, but header specifies <i>final</i>
raster size rather than <i>computing</i> raster size
</dl>
<br>
(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.
<br>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.
<dt><i>BKGND</i><dd>Background colour (red, green, and blue components, each in
the range 0 to 1).
<dt><i>SHADOW</i><dd>T to calculate shadowing within the scene, F to omit
shadows
<dt><i>IPHONG</i><dd>Phong power (e.g., 25) for specular highlights. A smaller
value results in a larger spot.
<br>IPHONG = 0 disables specular highlighting and all processing of ribbon
triangles
<dt><i>STRAIT</i><dd>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.
<dt><i>AMBIEN</i><dd>Ambient illumination contribution (e.g., 0.05). Increasing
the ambient light will reduce the contrast between shadowed and non-shadowed
regions.
<dt><i>SPECLR</i><dd>Specular reflection contribution (e.g., 0.25).
<br>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.
<dt><i>EYEPOS</i><dd>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.
EYEPOS = 0 disables perspective.
<dt><i>SOURCE</i><dd>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.
<dt><i>TMAT </i><dd>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'].
<dt><i>INMODE</i><dd>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.
<dt><i>INFMT or INFMTS</i><dd>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.
</dl>
</p>
<h4> <a name="sample_header">SAMPLE HEADER </a></h4>
<pre>
My picture. (describes a 1280 x 1024 pixel anti-aliased image)
80 64 tiles in x,y (or set these to 1280 1024)
16 16 pixels (x,y) per tile (and set these to 0 0)
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)
</pre>
<h4>
<a name="objects">OBJECT TYPES</a></h4>
<center>
<table border=1 cellpadding=5 width=90%>
<tr>
<td width=25%><a href="#obj1">cylinder (flat)</a></td>
<td width=25%><a href="#obj1">cylinder (round)</a></td>
<td width=25%><a href="#obj16">global properties</a></td>
<td width=25%><a href="#obj13">glow light</a></td>
</tr>
<tr>
<td width=25%><a href="#obj15">isolation</a></td>
<td width=25%><a href="#obj10">labels</a></td>
<td width=25%><a href="#obj8">material properties</a></td>
<td width=25%><a href="#obj6">plane</a></td>
</tr>
<tr>
<td width=25%><a href="#obj14">quadric surface</a></td>
<td width=25%><a href="#obj1">sphere</a></td>
<td width=25%><a href="#obj7">surface normals</a></td>
<td width=25%><a href="#obj9">terminate properties</a></td>
</tr>
<tr>
<td width=25%><a href="#obj1">triangle</a></td>
<td width=25%><a href="#obj17">vertex colors</a></td>
<td width=25%><a href="#obj18">vertex transparency</a></td>
<td width=25%> </td>
</tr>
</table>
</center>
<dl>
<a name="obj1"></a>
<dt> Object type 1
<dt><font color=#BB2222>triangle</font>
<dd> x1, y1, z1, x2, y2, z2, x3, y3, z3, red, green, blue
<p>
<dt> Object type 2
<dt><font color=#BB2222>sphere</font>
<dd> x, y, z, radius, red, green, blue
<p>
<dt> Object type 3
<dt><font color=#BB2222>round-ended cylinder</font>
<dd> x1, y1, z1, R1, x2, y2, z2, R2, red, green, blue<br>
(R1 is the cylinder radius, R2 is currently ignored).
<p>
<dt> Object type 4
<dt><font color=#BB2222>not used</font>
<dd>
<p>
<dt> Object type 5
<dt><font color=#BB2222>flat-ended cylinder</font>
<dd> x1, y1, z1, R1, x2, y2, z2, R2, red, green, blue<br>
(R1 is the cylinder radius, R2 is currently ignored).
<p>
<a name="obj6"></a>
<dt> Object type 6
<dt><font color=#BB2222>plane</font>
<dd> x1, y1, z1, x2, y2, z2, x3, y3, z3, red, green, blue
<p>
<a name="obj7"></a>
<dt> Object type 7
<dt><font color=#BB2222>explicit surface normals at vertices of preceding triangle</font>
<dd> u1, v1, w1, u2, v2, w2, u3, v3, w3<br>
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.
<p>
<a name="obj8"></a>
<dt> Object type 8
<dt><font color=#BB2222>material properties</font>
<dd> 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 next
line of the input stream:
<dl>
<dt> MPHONG
<dd>value >= 0 overrides the global Phong parameter for specular highlighting
<dt>MSPEC
<dd>value >= 0 overrides the global specular scattering contribution
<dt>SR,SG,SB
<dd>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
<dt>CLRITY
<dd>(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.
<dt>OPTS(4)
<dd>four additional fields are reserved for future expansion of
the material properties list; these must be present. The first two fields
control alternative algorithms for rendering transparent objects:
<dl>
<dd>OPT(1) = 0 render all outward-facing layers of a transparent material, even if they occlude each other
<dd>OPT(1) = 1 render only the "top" outward-facing surface of transparent material
<dd>OPT(1) = 2 render both the outward- and inward-facing surface of transparent spheres and cylinders
</dl>
OPT(2) specifies how net transparency varies as a function of surface normal.
<dl>
<dd>OPT(2) = 0 empirical function that looks best to me
<dd>OPT(2) = 1 faster empirical function
<dd>OPT(2) = 2 exponential function based on theory (slower)
<dd>OPT(2) = 3 ignore surface normal (transparent objects look flat)
</dl>
The fourth 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
<dl>
<dd>OPT(4) = 2 means that the next two lines contain additional material modifiers
</dl>
<dt>Object type 8 modifiers
<dd>
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:
<pre>
# Here is an example of specifying a double sided material.
# The MATERIAL record itself specifies an opaque material with PHONG
# value 20 and relative lighting contributions taken from the header records
# (MSPEC < 0). The trailing "2" indicates there are two following modifer lines.
# The SOLID modifier gives an RGB color triple that overrides colors on
# subsequent objects.
# The BACKFACE modifier specifies a separate RGB color for the other side
# of this material, and sets the Phong control parameter and specular
# 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
</pre>
Here is the complete list of modifiers currently available, and their parameters
<pre>
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 <a href="r3d_hints.html#bounding">bounding planes</a> of ellipsoids
</pre>
See elsewhere for more information on
<a href="r3d_hints.html#clipping">clipping planes</a> and
<a href="r3d_hints.html#bounding">bounding planes</a>.
</dl>
<a name="obj9"></a>
<dt> Object type 9
<dt><font color=#BB2222>terminate special properties</font>
<dd> 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'.
<p>
<a name="obj10"></a>
<dt> Object types 10-12
<dt><font color=#BB2222>Label descriptors</font>
<dd>
Version 3.0 supports rendering labels via the libgd library used to
produce png or jpeg output images.
Object types 10, 11, and 12 are used to specify labels.
Here is an example:
<pre>
# Force the label coordinates to be interpreted as screen coords
# (obviously you wouldn't do this if you want the label to get the
# same translation/rotation/scaling as other objects do)
15
# Choose a font
10
"Times-Italic" 12. "Center-align"
# specify a label
11
0.0 0.45 0.0 1.0 0.0 0.0
I am a red title centered at the top of the image
# Terminate isolation from coordinate transformation
9
</pre>
<dl>
<dt> Object type 10
<dd> <pre>"Font specifier" size "alignment"</pre><br>
Legal fonts specifiers are subject to the details of label processing implementation.
In the context of processing by libgd, <br>
<b>fontname</b> is any font name recogized by libgd,<br>
<b>size</b> is the font size in points (assuming eventual printing at 300 dpi),<br>
<b>alignment</b> is either "Right-align", "Left-align", "Center-align", or "Offset"
(only the first character is checked).<br>
The default is "Times" 10 "Left-align".
<p>
<dt> Object type 11
<dd> [XYZ] [RGB]<br>
Label text
<p>
(see <a href="r3dtops.html">r3dtops</a> for details of
label text processing and special characters.
<p>
<dt> Object type 12
<dd> reserved (single line of text)
<p>
<dt>
(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 <i>-EAM</i>).
</dl>
<p>
<a name="obj13"></a>
<dt> Object type 13
<dt><font color=#BB2222>Glow light source</font>
<dd> 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.
<dl>
<dt>GLOWSRC(3)
<dd>[x y z] coordinates of light source
<dt>GLOWRAD
<dd>limiting radius of light source (see GOPT)
<dt>GLOW
<dd>fractional contribution (0.0 - 1.0) of glow light to total lighting model
<dt>GOPT
<dd>(integer 0/1/2/3/...) - controls functional form in which
limiting radius is applied [under development]
<dt>GPHONG
<dd>Phong parameter controlling specular highlights from glow light source
<dt>GLOWCOL(3)
<dd>RGB triple specifying color of glow light source
</dl>
<p>
<a name="obj14"></a>
<dt> Object type 14
<dt><font color=#BB2222>quadric surface</font>
<dd> x, y, z, limiting_radius, red, green, blue, A, B, C, D, E, F, G, H, I, J
<br>
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 surface descriptor to render has the 17 parameters listed above.
<p>
The surface itself is the set of points for which Q(x,y,z) = 0 where
<dl>
<dt>Q(x,y,z) = Ax<sup>2</sup> + By<sup>2</sup> + Cz<sup>2</sup> + 2Dxy + 2Eyz + 2Fzx + 2Gx + 2Hy + 2Iz + J
</dl>
<p>
Points further from the origin (prior to translation!) than the
limiting radius are not rendered.
<p>
<a name="obj15"></a>
<dt> Object type 15
<dt><font color=#BB2222>begin isolation from TMAT transformation</font>
<dd> 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 square, the coordinates run from
-0.5 to +0.5 on both X and Y. If the image is rectangular, coordinates
run from -0.5 to +0.5 on 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.
<p>
The coordinate system used following object type 19 is similar except that
the horizontal and vertical scales are treated separately, so the the point
[-.5,+.5] is always at the top left corner. In both figures below the blue
cross is drawn at coordinates [+0.5,+0.3].
<table border=0>
<tr>
<td><img src="r3d_obj15.gif" hspace=5></td>
<td><img src="r3d_obj19.gif" hspace=5></td>
</tr>
<tr>
<td><b>Coordinate system defined by object 15</b></td>
<td><b>Coordinate system defined by object 19</b></td>
</tr>
</table>
<p>
<a name="obj16"></a>
<dt> Object type 16
<dt><font color=#BB2222>Global properties</font>
<dd> Object type 16 is always followed by a single record that affects the rendering
of the entire scene. The only global properties supported at the moment
are listed below.
FOG allows depth-cueing using either a linear or an exponential
model of fog density. A record simply consisting of the keyword FOG will
produce reasonable depth-cueing (linear decrease in intensity front closest
object to farthest object). If you need to control the depth-cueing indepently
from the specific rendered objects in a scene (i.e. to keep the depth-cueing
consistent between frames of an animation) then you should specify explicit
values for fogfront, fogback and fogden.
<p>
<pre>FOG fogtype fogfront fogback fogden</pre>
<DL>
<DT>fogtype</DT>
<DD>0 = linear multiplier = fogden * (fogfront - Z) / (fogfront - fogback)</DD>
<DD>1 = exponential multiplier = 1. - exp( -fogden * (fogfront - Z) / (fogfront - fogback) )</DD>
<DT>fogfront</DT>
<DD>0 = Z coord of front object, else fraction of front clipping plane</DD>
<DT>fogback</DT>
<DD>0 = Z coord of back object, else fraction of rear clipping plane</DD>
<DT>fogden</DT>
<DD>(see equations for linear and exponential models controlled by fogtype);
fogden=0.0 will default to some reasonable value</DD>
</DL>
<p>
<pre>BACKCLIP zback</pre>
<DL>
<DT>zback</DT>
<DD>Z coord of rear clipping plane for all objects; in original units
of original coordinate system, but relative to the center of the
transformed coordinate system.
That means if you are working in PDB coordinates, then everything
more than <i>zback</i> Angstroms behind the center is clipped.
</DD>
</DL>
<pre>FRONTCLIP zfront</pre>
<DL>
<DT>zfront</DT>
<DD>Z coord of front clipping plane for all objects; in original units
of original coordinate system, but relative to the center of the
transformed coordinate system.
That means if you are working in PDB coordinates, then everything
more than <i>zfront</i> Angstroms in front of the center is clipped.
</DD>
</DL>
<pre>ROTATION Matrix</pre>
<DL>
<DT>Matrix</DT>
<DD>3x3 rotation matrix applied by post-multiplication after the coordinate
transformation in TMAT. This is the transpose of the equivalent rotation
if it were specified in TMAT. It applies to all following coordinates
in the input stream.
</DD>
</DL>
<pre>TRANSLATION X Y Z</pre>
<DL>
<DT>X Y Z</DT>
<DD>3 element translation applied after the coordinate transformation
in TMAT. It applies to all following coordinates
in the input stream.
</DD>
</DL>
<p>
<a name="obj17"></a>
<dt> Object type 17
<dt><font color=#BB2222>explicit coloring at vertices of preceding triangle or cylinder</font>
<dd> R1 G1 B1 R2 G2 B2 R3 G3 B3<br>
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).
<p>
As of version 2.4j this mechanism may also be used to interpolate colors
along the length of a cylinder. In this case the third RGB triple is ignored.
<p>
<a name="obj18"></a>
<dt> Object type 18
<dt><font color=#BB2222>explicit transparency at vertices of preceding object </font>
<dd> Trans1 Trans2 Trans3<br>
Normally an object is transparent only if it belongs to a trasparent material.
Using this additional object, however, you can specify a separate degree of
transparency at each vertex of an object. The transparency at points in the
interior of the object are then determined by interpolation. All three values
(Trans1 Trans2 Trans3) are required; Trans3 is ignored for a cylinder, Trans2
and Trans3 are both ignored for a sphere.
<p>
<a name="obj19"></a>
<dt> Object type 19
<dt><font color=#BB2222>begin isolation from TMAT transformation</font>
<dd> Similar to <a href="#obj15">Object type 15</a>, except that the coordinate
scale along both x and y always runs from -0.5 to +0.5, regardless of the
aspect ratio of the rendered image.
<p>
<dt> Object type 0
<dt><font color=#BB2222>force end of input stream (optional)</font>
<dd> Further records in input file will not be read.
<p>
</dl>
</p>
<a name="comments">
<h4>COMMENTS</h4>
</a>
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 the `#' character. In this case the line is ignored, and may be used as a comment. Earlier versions of the program recommended using object type 9 as a comment delimiter, but this has the potential disadvantage of prematurely terminating the scope of a special material.
</p>
<a name="indirection">
<h4>FILE INDIRECTION</h4>
</a>
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.
<p>
The requested file is first searched for relative to the current directory.
If this search fails, the file is searched for relative to the directory
specified by the environmental variable R3D_LIB.
Typically this would be set via a command such as
<pre>
csh/tcsh: setenv R3D_LIB /usr/local/src/raster3d/materials
sh/ksh: R3D_LIB=/usr/local/src/raster3d/materials; export R3D_LIB
</pre>
</p>
<h4>
<a name="sample_data">
SAMPLE INPUT DATA FOLLOWING HEADER
</a>
</h4>
The following records describe a single red triangle and a single blue sphere.
The blue sphere is affected by whatever material descriptor is in the file
material1.r3d
<pre>
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
</pre>
</p>
<a name="errors">
<h4>ERROR MESSAGES</h4>
</a>
<dl>
<dt><b><i>Possible shadowing error NSXMAX = xxx </i></b>
<dd>
This is usually caused by an object which extends far out of
the field of view, for example a plane surface that extends to infinity.
In most cases the shadowing "error" refers to a shadow which lies
outside of the image entirely.
</dl>
</p>
<a name="arrays">
<h4>INCREASING THE ARRAY SIZES IN RENDER:</h4>
</a>
<p>
As of Version 3.0, this should no longer be necessary.
Arrays are expanded dynamically.
</p>
<h4>
<a name="authors">AUTHORS</a></h4>
Originally written by David J. Bacon. Extensions, revisions, and modifications
by Ethan A Merritt.
<hr>
<a href="raster3d.html">
<img src="index_button.gif" align=top> Back to top </a>
<a href="http://www.bmsc.washington.edu/raster3d/raster3d.html">
<img src="r3d_icon.gif" alt="" align=top> Raster3D homepage </a>
</body>
</html>
|