ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/radiance/ray/doc/ray.html
Revision: 1.3
Committed: Thu Jan 1 19:31:44 2004 UTC (20 years, 3 months ago) by greg
Content type: text/html
Branch: MAIN
Changes since 1.2: +2 -2 lines
Log Message:
Renamed rview, lam, calc, and neat to rvu, rlam, icalc, and neaten

File Contents

# Content
1 <html>
2 <head>
3 <title>
4 The RADIANCE 3.5 Synthetic Imaging System
5 </title>
6 </head>
7 <body>
8
9 Copyright � 2003 Regents, University of California
10
11 <p>
12
13 <h1>
14 The RADIANCE 3.5 Synthetic Imaging System
15 </h1>
16
17 <p>
18
19 Building Technologies Department<br>
20 Lawrence Berkeley National Laboratory<br>
21 1 Cyclotron Rd., 90-3111<br>
22 Berkeley, CA 94720<br>
23 <a HREF="http://radsite.lbl.gov/radiance"</a>
24 http://radsite.lbl.gov/radiance<br>
25
26 <p>
27 <hr>
28
29 <h2>
30 <a NAME="Overview">Overview</a>
31 </h2>
32 <ol>
33 <li><a HREF="#Intro">Introduction</a><!P>
34 <li><a HREF="#Scene">Scene Description</a><!P>
35 <ol>
36 <li><a HREF="#Primitive"> Primitive Types</a>
37 <ol>
38 <li><a HREF="#Surfaces">Surfaces</a>
39 <li><a HREF="#Materials">Materials</a>
40 <li><a HREF="#Textures">Textures</a>
41 <li><a HREF="#Patterns">Patterns</a>
42 <li><a HREF="#Mixtures">Mixtures</a>
43 </ol><!P>
44 <li><a HREF="#Auxiliary">Auxiliary Files</a>
45 <ol>
46 <li><a HREF="#Function">Function Files</a>
47 <li><a HREF="#Data">Data Files</a>
48 <li><a HREF="#Font">Font Files</a>
49 </ol><!P>
50 <li><a HREF="#Generators">Generators</a>
51 </ol><!P>
52 <li><a HREF="#Image">Image Generation</a><!P>
53 <li><a HREF="#License">License</a><!P>
54 <li><a HREF="#Ack">Acknowledgements</a><!P>
55 <li><a HREF="#Ref">References</a><!P>
56 <li><a HREF="#Index">Types Index</a><!P>
57 </ol>
58
59 <p>
60 <hr>
61
62 <h2>
63 <a NAME="Intro">1. Introduction</a>
64 </h2>
65
66 RADIANCE was developed as a research tool for predicting
67 the distribution of visible radiation in illuminated spaces.
68 It takes as input a three-dimensional geometric model
69 of the physical environment, and produces a map of
70 spectral radiance values in a color image.
71 The technique of ray-tracing follows light backwards
72 from the image plane to the source(s).
73 Because it can produce realistic images from a
74 simple description, RADIANCE has a wide range of applications
75 in graphic arts, lighting design,
76 computer-aided engineering and architecture.
77
78 <p>
79 <img SRC="diagram1.gif">
80 <p>
81 Figure 1
82 <p>
83 The diagram in Figure 1 shows the flow between programs (boxes) and data
84 (ovals).
85 The central program is <i>rpict</i>, which produces a picture from a scene
86 description.
87 <i>Rview</i> is a variation of rpict that computes and displays images
88 interactively, and rtrace computes single ray values.
89 Other programs (not shown) connect many of these elements together,
90 such as the executive programs
91 <i>rad</i>
92 and
93 <i>ranimate</i>,
94 the interactive rendering program
95 <i>rholo</i>,
96 and the animation program
97 <i>ranimove</i>.
98 The program
99 <i>obj2mesh</i>
100 acts as both a converter and scene compiler, converting a Wavefront .OBJ
101 file into a compiled mesh octree for efficient rendering.
102
103 <p>
104 A scene description file lists the surfaces and materials
105 that make up a specific environment.
106 The current surface types are spheres, polygons, cones, and cylinders.
107 There is also a composite surface type, called mesh, and a pseudosurface
108 type, called instance, which facilitates very complex geometries.
109 Surfaces can be made from materials such as plastic, metal, and glass.
110 Light sources can be distant disks as well as local spheres, disks
111 and polygons.
112
113 <p>
114 From a three-dimensional scene description and a specified view,
115 <i>rpict</i> produces a two-dimensional image.
116 A picture file is a compressed binary representation of the
117 pixels in the image.
118 This picture can be scaled in size and brightness,
119 anti-aliased, and sent to a graphics output device.
120
121 <p>
122 A header in each picture file lists the program(s)
123 and parameters that produced it.
124 This is useful for identifying a picture without having to display it.
125 The information can be read by the program <i>getinfo</i>.
126
127 <p>
128 <hr>
129
130 <h2>
131 <a name="Scene">2. Scene Description</a>
132 </h2>
133
134 A scene description file represents a three-dimensional physical environment in Cartesian (rectilinear) world coordinates.
135 It is stored as ASCII text, with the following basic format:
136
137 <pre>
138 # comment
139
140 modifier type identifier
141 n S1 S2 &quot;S 3&quot; .. Sn
142 0
143 m R1 R2 R3 .. Rm
144
145 modifier alias identifier reference
146
147 ! command
148
149 ...
150 </pre>
151
152 A comment line begins with a pound sign, `#'.
153
154 <p>
155 The <a NAME="scene_desc">scene description primitives</a>
156 all have the same general format, and can be either surfaces or modifiers.
157 A primitive has a modifier, a type, and an identifier.
158 <p>
159 A <a NAME="modifier"><b>modifier</b></a> is either the
160 identifier of a previously defined primitive, or &quot;void&quot;.
161 <br>
162 [ The most recent definition of a modifier is the
163 one used, and later definitions do not cause relinking
164 of loaded primitives.
165 Thus, the same identifier may be used repeatedly,
166 and each new definition will apply to the primitives following it. ]
167 <p>
168 An <a NAME="identifier"><b>identifier</b></a> can be any string
169 (i.e., any sequence of non-white characters).
170 <p>
171 The arguments associated with a primitive can be strings or real numbers.
172 <ul>
173 <li> The first integer following the identifier is the number of <b>string arguments</b>,
174 and it is followed by the arguments themselves (separated by white space or enclosed in quotes).
175 <li> The next integer is the number of integer arguments, and is followed by the <b>integer arguments</b>.
176 (There are currently no primitives that use them, however.)
177 <li> The next integer is the real argument count, and it is followed by the <b>real arguments</b>.
178 </ul>
179
180 <p>
181 An <a NAME="alias"><b>alias</b></a> gets its type and arguments from
182 a previously defined primitive.
183 This is useful when the same material is
184 used with a different modifier, or as a convenient naming mechanism.
185 The reserved modifier name &quot;inherit&quot; may be used to specificy that
186 an alias will inherit its modifier from the original.
187 Surfaces cannot be aliased.
188
189 <p>
190 A line beginning with an exclamation point, `!',
191 is interpreted as a command.
192 It is executed by the shell, and its output is read as input to the program.
193 The command must not try to read from its standard input, or confusion
194 will result.
195 A command may be continued over multiple lines using a
196 backslash, `\', to escape the newline.
197
198 <p>
199 White space is generally ignored, except as a separator.
200 The exception is the newline character after a command or comment.
201 Commands, comments and primitives may appear in any
202 combination, so long as they are not intermingled.
203
204 <p>
205 <hr>
206
207 <h3>
208 <a NAME="Primitive">2.1. Primitive Types</a>
209 </h3>
210
211 Primitives can be <a HREF="#Surfaces">surfaces</a>,
212 <a HREF="#Materials">materials</a>,
213 <a HREF="#Textures">textures</a> or
214 <a HREF="#Patterns">patterns</a>.
215 Modifiers can be <a HREF="#Materials">materials</a>,
216 <a HREF="#Mixtures">mixtures</a>,
217 <a HREF="#Textures">textures</a> or <a HREF="#Patterns">patterns</a>.
218 Simple surfaces must have one material in their modifier list.
219
220 <p>
221 <hr>
222
223 <h4>
224 <a NAME="Surfaces">2.1.1. Surfaces</a>
225 </h4>
226 <dl>
227
228 A scene description will consist mostly of surfaces.
229 The basic types are given below.
230
231 <p>
232
233 <dt>
234 <a NAME="Source">
235 <b>Source </b>
236 </a>
237 <dd>
238 A source is not really a surface, but a solid angle.
239 It is used for specifying light sources that are very distant.
240 The direction to the center of the source and the number of degrees subtended by its disk are given as follows:
241
242 <pre>
243 mod source id
244 0
245 0
246 4 xdir ydir zdir angle
247 </pre>
248
249 <p>
250
251 <dt>
252 <a NAME="Sphere">
253 <b>Sphere</b>
254 </a>
255 <dd>
256 A sphere is given by its center and radius:
257
258 <pre>
259 mod sphere id
260 0
261 0
262 4 xcent ycent zcent radius
263 </pre>
264
265 <p>
266
267 <dt>
268 <a NAME="Bubble">
269 <b>Bubble</b>
270 </a>
271
272 <dd>
273 A bubble is simply a sphere whose surface normal points inward.
274
275 <p>
276
277 <dt>
278 <a NAME="Polygon">
279 <b>Polygon</b>
280 </a>
281 <dd>
282 A polygon is given by a list of three-dimensional vertices,
283 which are ordered counter-clockwise as viewed from the
284 front side (into the surface normal).
285 The last vertex is automatically connected to the first.
286 Holes are represented in polygons as interior vertices
287 connected to the outer perimeter by coincident edges (seams).
288
289 <pre>
290 mod polygon id
291 0
292 0
293 3n
294 x1 y1 z1
295 x2 y2 z2
296 ...
297 xn yn zn
298 </pre>
299
300 <p>
301
302 <dt>
303 <a NAME="Cone">
304 <b>Cone</b>
305 </a>
306 <dd>
307 A cone is a megaphone-shaped object.
308 It is truncated by two planes perpendicular to its axis,
309 and one of its ends may come to a point.
310 It is given as two axis endpoints, and the starting and ending radii:
311
312 <pre>
313 mod cone id
314 0
315 0
316 8
317 x0 y0 z0
318 x1 y1 z1
319 r0 r1
320 </pre>
321
322 <p>
323
324 <dt>
325 <a NAME="Cup">
326 <b>Cup</b>
327 </a>
328 <dd>
329 A cup is an inverted <a HREF="#Cone">cone</a> (i.e., has an
330 inward surface normal).
331
332 <p>
333
334 <dt>
335 <a NAME="Cylinder">
336 <b>Cylinder</b>
337 </a>
338 <dd>
339 A cylinder is like a <a HREF="#Cone">cone</a>, but its
340 starting and ending radii are equal.
341
342 <pre>
343 mod cylinder id
344 0
345 0
346 7
347 x0 y0 z0
348 x1 y1 z1
349 rad
350 </pre>
351
352 <p>
353
354 <dt>
355 <a NAME="Tube">
356 <b>Tube</b>
357 </a>
358 <dd>
359 A tube is an inverted <a HREF="#Cylinder">cylinder</a>.
360
361 <p>
362
363 <dt>
364 <a NAME="Ring">
365 <b>Ring</b>
366 </a>
367 <dd>
368 A ring is a circular disk given by its center,
369 surface normal, and inner and outer radii:
370
371 <pre>
372 mod ring id
373 0
374 0
375 8
376 xcent ycent zcent
377 xdir ydir zdir
378 r0 r1
379 </pre>
380
381 <p>
382
383 <dt>
384 <a NAME="Instance">
385 <b>Instance</b>
386 </a>
387 <dd>
388 An instance is a compound surface, given
389 by the contents of an octree file (created by oconv).
390
391 <pre>
392 mod instance id
393 1+ octree transform
394 0
395 0
396 </pre>
397
398 If the modifier is &quot;void&quot;, then surfaces will
399 use the modifiers given in the original description.
400 Otherwise, the modifier specified is used in their place.
401 The transform moves the octree to the desired location in the scene.
402 Multiple instances using the same octree take
403 little extra memory, hence very complex
404 descriptions can be rendered using this primitive.
405
406 <p>
407 There are a number of important limitations to be aware of
408 when using instances.
409 First, the scene description used to generate the octree must
410 stand on its own, without referring to modifiers in the
411 parent description.
412 This is necessary for oconv to create the octree.
413 Second, light sources in the octree will not be
414 incorporated correctly in the calculation,
415 and they are not recommended.
416 Finally, there is no advantage (other than
417 convenience) to using a single instance of an octree,
418 or an octree containing only a few surfaces.
419 An <a HREF="../man_html/xform.1.html">xform</a> command
420 on the subordinate description is prefered in such cases.
421 </dl>
422
423 <p>
424
425 <dt>
426 <a NAME="Mesh">
427 <b>Mesh</b>
428 </a>
429 <dd>
430 A mesh is a compound surface, made up of many triangles and
431 an octree data structure to accelerate ray intersection.
432 It is typically converted from a Wavefront .OBJ file using the
433 <i>obj2mesh</i> program.
434
435 <pre>
436 mod mesh id
437 1+ meshfile transform
438 0
439 0
440 </pre>
441
442 If the modifier is &quot;void&quot;, then surfaces will
443 use the modifiers given in the original mesh description.
444 Otherwise, the modifier specified is used in their place.
445 The transform moves the mesh to the desired location in the scene.
446 Multiple instances using the same meshfile take little extra memory,
447 and the compiled mesh itself takes much less space than individual
448 polygons would.
449 In the case of an unsmoothed mesh, using the mesh primitive reduces
450 memory requirements by a factor of 30 relative to individual triangles.
451 If a mesh has smoothed surfaces, we save a factor of 50 or more,
452 permitting very detailed geometries that would otherwise exhaust the
453 available memory.
454 In addition, the mesh primitive can have associated (u,v) coordinates
455 for pattern and texture mapping.
456 These are made available to function files via the Lu and Lv variables.
457
458 </dl>
459
460 <p>
461 <hr>
462
463 <h4>
464 <a NAME="Materials">2.1.2. Materials</a>
465 </h4>
466
467 A material defines the way light interacts with a surface. The basic types are given below.
468
469 <p>
470
471 <dl>
472
473 <dt>
474 <a NAME="Light">
475 <b>Light</b>
476 </a>
477 <dd>
478 Light is the basic material for self-luminous surfaces (i.e.,
479 light sources).
480 In addition to the <a HREF="#Source">source</a> surface type,
481 <a HREF="#Sphere">spheres</a>,
482 discs (<a HREF="#Ring">rings</a> with zero inner radius),
483 <a HREF="#Cylinder">cylinders</a> (provided they are long enough), and <a HREF="#Polygon">polygons</a> can act as light sources.
484 Polygons work best when they are rectangular.
485 Cones cannot be used at this time.
486 A pattern may be used to specify a light output distribution.
487 Light is defined simply as a RGB radiance value (watts/steradian/m2):
488
489 <pre>
490 mod light id
491 0
492 0
493 3 red green blue
494 </pre>
495
496 <p>
497
498 <dt>
499 <a NAME="Illum">
500 <b>Illum</b>
501 </a>
502
503 <dd>
504 Illum is used for secondary light sources with broad distributions.
505 A secondary light source is treated like any other light source, except when viewed directly.
506 It then acts like it is made of a different material (indicated by
507 the string argument), or becomes invisible (if no string argument is given,
508 or the argument is &quot;void&quot;).
509 Secondary sources are useful when modeling windows or brightly illuminated surfaces.
510
511 <pre>
512 mod illum id
513 1 material
514 0
515 3 red green blue
516 </pre>
517
518 <p>
519
520 <dt>
521 <a NAME="Glow">
522 <b>Glow</b>
523 </a>
524
525 <dd>
526 Glow is used for surfaces that are self-luminous, but limited in their effect.
527 In addition to the radiance value, a maximum radius for shadow testing is given:
528
529 <pre>
530 mod glow id
531 0
532 0
533 4 red green blue maxrad
534 </pre>
535
536 If maxrad is zero, then the surface will never be tested for shadow, although it may participate in an interreflection calculation.
537 If maxrad is negative, then the surface will never contribute to scene illumination.
538 Glow sources will never illuminate objects on the other side of an illum surface.
539 This provides a convenient way to illuminate local light fixture geometry without overlighting nearby objects.
540
541 <p>
542
543 <dt>
544 <a NAME="Spotlight">
545 <b>Spotlight</b>
546 </a>
547
548 <dd>
549 Spotlight is used for self-luminous surfaces having directed output.
550 As well as radiance, the full cone angle (in degrees) and orientation (output direction) vector are given.
551 The length of the orientation vector is the distance of the effective
552 focus behind the source center (i.e., the focal length).
553
554 <pre>
555 mod spotlight id
556 0
557 0
558 7 red green blue angle xdir ydir zdir
559 </pre>
560
561 <p>
562
563 <dt>
564 <a NAME="Mirror">
565 <b>Mirror</b>
566 </a>
567
568 <dd>
569 Mirror is used for planar surfaces that produce secondary source reflections.
570 This material should be used sparingly, as it may cause the light source calculation to blow up if it is applied to many small surfaces.
571 This material is only supported for flat surfaces such as <a HREF="#Polygon">polygons</a> and <a HREF="#Ring">rings</a>.
572 The arguments are simply the RGB reflectance values, which should be between 0 and 1.
573 An optional string argument may be used like the illum type to specify a different material to be used for shading non-source rays.
574 If this alternate material is given as &quot;void&quot;, then the mirror surface will be invisible.
575 This is only appropriate if the surface hides other (more detailed) geometry with the same overall reflectance.
576
577 <pre>
578 mod mirror id
579 1 material
580 0
581 3 red green blue
582 </pre>
583
584 <p>
585
586 <dt>
587 <a NAME="Prism1">
588 <b>Prism1</b>
589 </a>
590
591 <dd>
592 The prism1 material is for general light redirection from prismatic glazings, generating secondary light sources.
593 It can only be used to modify a planar surface
594 (i.e., a <a HREF="#Polygon">polygon</a> or <a HREF="#Ring">disk</a>)
595 and should not result in either light concentration or scattering.
596 The new direction of the ray can be on either side of the material,
597 and the definitions must have the correct bidirectional properties to work properly with secondary light sources.
598 The arguments give the coefficient for the redirected light and its direction.
599
600 <pre>
601 mod prism1 id
602 5+ coef dx dy dz funcfile transform
603 0
604 n A1 A2 .. An
605 </pre>
606
607 The new direction variables dx, dy and dz need not produce a normalized vector.
608 For convenience, the variables DxA, DyA and DzA are defined as the normalized direction to the target light source.
609 See <a HREF="#Function">section 2.2.1</a> on function files for further information.
610
611 <p>
612
613 <dt>
614 <a NAME="Prism2">
615 <b>Prism2</b>
616 </a>
617
618 <dd>
619 The material prism2 is identical to <a HREF="#Prism1">prism1</a> except that it provides for two ray redirections rather than one.
620
621 <pre>
622 mod prism2 id
623 9+ coef1 dx1 dy1 dz1 coef2 dx2 dy2 dz2 funcfile transform
624 0
625 n A1 A2 .. An
626 </pre>
627
628 <p>
629
630 <dt>
631 <a NAME="Mist">
632 <b>Mist</b>
633 </a>
634
635 <dd>
636 Mist is a virtual material used to delineate a volume
637 of participating atmosphere.
638 A list of important light sources may be given, along with an
639 extinction coefficient, scattering albedo and scattering eccentricity
640 parameter.
641 The light sources named by the string argument list
642 will be tested for scattering within the volume.
643 Sources are identified by name, and virtual light sources may be indicated
644 by giving the relaying object followed by '&gt;' followed by the source, i.e:
645
646 <pre>
647 3 source1 mirror1&gt;source10 mirror2&gt;mirror1&gt;source3
648 </pre>
649
650 Normally, only one source is given per mist material, and there is an
651 upper limit of 32 to the total number of active scattering sources.
652 The extinction coefficient, if given, is added the the global
653 coefficient set on the command line.
654 Extinction is in units of 1/distance (distance based on the world coordinates),
655 and indicates the proportional loss of radiance over one unit distance.
656 The scattering albedo, if present, will override the global setting within
657 the volume.
658 An albedo of 0 0 0 means a perfectly absorbing medium, and an albedo of
659 1 1 1 means
660 a perfectly scattering medium (no absorption).
661 The scattering eccentricity parameter will likewise override the global
662 setting if it is present.
663 Scattering eccentricity indicates how much scattered light favors the
664 forward direction, as fit by the Heyney-Greenstein function:
665
666 <pre>
667 P(theta) = (1 - g*g) / (1 + g*g - 2*g*cos(theta))^1.5
668 </pre>
669
670 A perfectly isotropic scattering medium has a g parameter of 0, and
671 a highly directional material has a g parameter close to 1.
672 Fits to the g parameter may be found along with typical extinction
673 coefficients and scattering albedos for various atmospheres and
674 cloud types in USGS meteorological tables.
675 (A pattern will be applied to the extinction values.)
676
677 <pre>
678 mod mist id
679 N src1 src2 .. srcN
680 0
681 0|3|6|7 [ rext gext bext [ ralb galb balb [ g ] ] ]
682 </pre>
683
684 There are two usual uses of the mist type.
685 One is to surround a beam from a spotlight or laser so that it is
686 visible during rendering.
687 For this application, it is important to use a <a HREF="#Cone">cone</a>
688 (or <a HREF="#Cylinder">cylinder</a>) that
689 is long enough and wide enough to contain the important visible portion.
690 Light source photometry and intervening objects will have the desired
691 effect, and crossing beams will result in additive scattering.
692 For this application, it is best to leave off the real arguments, and
693 use the global rendering parameters to control the atmosphere.
694 The second application is to model clouds or other localized media.
695 Complex boundary geometry may be used to give shape to a uniform medium,
696 so long as the boundary encloses a proper volume.
697 Alternatively, a pattern may be used to set the line integral value
698 through the cloud for a ray entering or exiting a point in a given
699 direction.
700 For this application, it is best if cloud volumes do not overlap each other,
701 and opaque objects contained within them may not be illuminated correctly
702 unless the line integrals consider enclosed geometry.
703
704 <dt>
705 <a NAME="Plastic">
706 <b>Plastic</b>
707 </a>
708
709 <dd>
710 Plastic is a material with uncolored highlights.
711 It is given by its RGB reflectance, its fraction of specularity, and its roughness value.
712 Roughness is specified as the rms slope of surface facets.
713 A value of 0 corresponds to a perfectly smooth surface, and a value of 1 would be a very rough surface.
714 Specularity fractions greater than 0.1 and roughness values greater than 0.2 are not very realistic.
715 (A pattern modifying plastic will affect the material color.)
716
717 <pre>
718 mod plastic id
719 0
720 0
721 5 red green blue spec rough
722 </pre>
723
724 <p>
725
726 <dt>
727 <a NAME="Metal">
728 <b>Metal</b>
729 </a>
730
731 <dd>
732 Metal is similar to <a HREF="#Plastic">plastic</a>, but specular highlights are modified by the material color.
733 Specularity of metals is usually .9 or greater.
734 As for plastic, roughness values above .2 are uncommon.
735
736 <p>
737
738 <dt>
739 <a NAME="Trans">
740 <b>Trans</b>
741 </a>
742
743 <dd>
744 Trans is a translucent material, similar to <a HREF="#Plastic">plastic</a>.
745 The transmissivity is the fraction of penetrating light that travels all the way through the material.
746 The transmitted specular component is the fraction of transmitted light that is not diffusely scattered.
747 Transmitted and diffusely reflected light is modified by the material color.
748 Translucent objects are infinitely thin.
749
750 <pre>
751 mod trans id
752 0
753 0
754 7 red green blue spec rough trans tspec
755 </pre>
756
757 <p>
758
759 <dt>
760 <a NAME="Plastic2">
761 <b>Plastic2</b>
762 </a>
763
764 <dd>
765 Plastic2 is similar to <a HREF="#Plastic">plastic</a>, but with anisotropic roughness.
766 This means that highlights in the surface will appear elliptical rather than round.
767 The orientation of the anisotropy is determined by the unnormalized direction vector ux uy uz.
768 These three expressions (separated by white space) are evaluated in the context of the function file funcfile.
769 If no function file is required (i.e., no special variables or functions are required), a period (`.') may be given in its place.
770 (See the discussion of <a HREF="#Function">Function Files</a> in the Auxiliary Files section).
771 The urough value defines the roughness along the u vector given projected onto the surface.
772 The vrough value defines the roughness perpendicular to this vector.
773 Note that the highlight will be narrower in the direction of the smaller roughness value.
774 Roughness values of zero are not allowed for efficiency reasons since the behavior would be the same as regular plastic in that case.
775
776 <pre>
777 mod plastic2 id
778 4+ ux uy uz funcfile transform
779 0
780 6 red green blue spec urough vrough
781 </pre>
782
783 <p>
784
785 <dt>
786 <a NAME="Metal2">
787 <b>Metal2</b>
788 </a>
789
790 <dd>
791 Metal2 is the same as <a HREF="#Plastic2">plastic2</a>, except that the highlights are modified by the material color.
792
793 <p>
794
795 <dt>
796 <a NAME="Trans2">
797 <b>Trans2</b>
798 </a>
799
800 <dd>
801 Trans2 is the anisotropic version of <a HREF="#Trans">trans</a>.
802 The string arguments are the same as for plastic2, and the real arguments are the same as for trans but with an additional roughness value.
803
804 <pre>
805 mod trans2 id
806 4+ ux uy uz funcfile transform
807 0
808 8 red green blue spec urough vrough trans tspec
809 </pre>
810
811 <p>
812
813 <dt>
814 <a NAME="Dielectric">
815 <b>Dielectric</b>
816 </a>
817
818 <dd>
819 A dielectric material is transparent, and it refracts light as well as reflecting it.
820 Its behavior is determined by the index of refraction and transmission coefficient in each wavelength band per unit length.
821 Common glass has a index of refraction (n) around 1.5, and a transmission coefficient of roughly 0.92 over an inch.
822 An additional number, the Hartmann constant, describes how the index of refraction changes as a function of wavelength.
823 It is usually zero. (A <a HREF="#Patterns">pattern</a> modifies only the refracted value.)
824
825 <pre>
826 mod dielectric id
827 0
828 0
829 5 rtn gtn btn n hc
830 </pre>
831
832 <p>
833
834 <dt>
835 <a NAME="Interface">
836 <b>Interface</b>
837 </a>
838
839 <dd>
840 An interface is a boundary between two dielectrics.
841 The first transmission coefficient and refractive index are for the inside; the second ones are for the outside.
842 Ordinary dielectrics are surrounded by a vacuum (1 1 1 1).
843
844 <pre>
845 mod interface id
846 0
847 0
848 8 rtn1 gtn1 btn1 n1 rtn2 gtn2 btn2 n2
849 </pre>
850
851 <p>
852
853 <dt>
854 <a NAME="Glass">
855 <b>Glass</b>
856 </a>
857
858 <dd>
859 Glass is similar to <a HREF="#Dielectric">dielectric</a>, but it is optimized for thin glass surfaces (n = 1.52).
860 One transmitted ray and one reflected ray is produced.
861 By using a single surface is in place of two, internal reflections are avoided.
862 The surface orientation is irrelevant, as it is for <a HREF="#Plastic">plastic</a>, <a HREF="#Metal">metal</a>, and <a HREF="#Trans">trans</a>.
863 The only specification required is the transmissivity at normal incidence.
864 (Transmissivity is the amount of light not absorbed in one traversal
865 of the material.
866 Transmittance -- the value usually measured -- is the total light
867 transmitted through the pane including multiple reflections.)
868 To compute transmissivity (tn) from transmittance (Tn) use:
869
870 <pre>
871 tn = (sqrt(.8402528435+.0072522239*Tn*Tn)-.9166530661)/.0036261119/Tn
872 </pre>
873
874 Standard 88% transmittance glass has a transmissivity of 0.96.
875 (A <a HREF="#Patterns">pattern</a> modifying glass will affect the transmissivity.)
876 If a fourth real argument is given, it is interpreted as the index of refraction to use instead of 1.52.
877
878 <pre>
879 mod glass id
880 0
881 0
882 3 rtn gtn btn
883 </pre>
884
885 <p>
886
887 <dt>
888 <a NAME="Plasfunc">
889 <b>Plasfunc</b>
890 </a>
891
892 <dd>
893 Plasfunc in used for the procedural definition of plastic-like materials
894 with arbitrary bidirectional reflectance distribution functions (BRDF's).
895 The arguments to this material include the color and specularity,
896 as well as the function defining the specular distribution and the auxiliary file where it may be found.
897
898 <pre>
899 mod plasfunc id
900 2+ refl funcfile transform
901 0
902 4+ red green blue spec A5 ..
903 </pre>
904
905 The function refl takes four arguments, the x, y and z
906 direction towards the incident light, and the solid angle
907 subtended by the source.
908 The solid angle is provided to facilitate averaging, and is usually
909 ignored.
910 The refl function should integrate to 1 over
911 the projected hemisphere to maintain energy balance.
912 At least four real arguments must be given, and these are made available along with any additional values to the reflectance function.
913 Currently, only the contribution from direct light sources is considered in the specular calculation.
914 As in most material types, the surface normal is always altered to face the incoming ray.
915
916 <p>
917
918 <dt>
919 <a NAME="Metfunc">
920 <b>Metfunc</b>
921 </a>
922
923 <dd>
924 Metfunc is identical to <a HREF="#Plasfunc">plasfunc</a> and takes the same arguments,
925 but the specular component is multiplied also by the material color.
926
927 <p>
928
929 <dt>
930 <a NAME="Transfunc">
931 <b>Transfunc</b>
932 </a>
933
934 <dd>
935 Transfunc is similar to <a HREF="#Plasfunc">plasfunc</a> but with an arbitrary bidirectional transmittance distribution
936 as well as a reflectance distribution.
937 Both reflectance and transmittance are specified with the same function.
938
939 <pre>
940 mod transfunc id
941 2+ brtd funcfile transform
942 0
943 6+ red green blue rspec trans tspec A7 ..
944 </pre>
945
946 Where trans is the total light transmitted and tspec is the non-Lambertian fraction of transmitted light.
947 The function brtd should integrate to 1 over each projected hemisphere.
948
949 <p>
950
951 <dt>
952 <a NAME="BRTDfunc">
953 <b>BRTDfunc</b>
954 </a>
955
956 <dd>
957 The material BRTDfunc gives the maximum flexibility over surface reflectance and transmittance,
958 providing for spectrally-dependent specular rays and reflectance and transmittance distribution functions.
959
960 <pre>
961 mod BRTDfunc id
962 10+ rrefl grefl brefl
963 rtrns gtrns btrns
964 rbrtd gbrtd bbrtd
965 funcfile transform
966 0
967 9+ rfdif gfdif bfdif
968 rbdif gbdif bbdif
969 rtdif gtdif btdif
970 A10 ..
971 </pre>
972
973 The variables rrefl, grefl and brefl specify the color coefficients for the ideal specular (mirror) reflection of the surface.
974 The variables rtrns, gtrns and btrns specify the color coefficients for the ideal specular transmission.
975 The functions rbrtd, gbrtd and bbrtd take the direction to the incident light (and its solid angle) and
976 compute the color coefficients for the directional diffuse part of reflection and transmission.
977 As a special case, three identical values of '0' may be given in place of these function names to indicate no directional diffuse component.
978
979 <p>
980 Unlike most other material types, the surface normal is not altered to face the incoming ray.
981 Thus, functions and variables must pay attention to the orientation of the surface and make adjustments appropriately.
982 However, the special variables for the perturbed dot product and surface normal, RdotP, NxP, NyP and NzP are reoriented
983 as if the ray hit the front surface for convenience.
984
985 <p>
986 A diffuse reflection component may be given for the front side with rfdif, gfdif and bfdif for the front side of the surface
987 or rbdif, gbdif and bbdif for the back side.
988 The diffuse transmittance (must be the same for both sides by physical law) is given by rtdif, gtdif and btdif.
989 A pattern will modify these diffuse scattering values, and will be available through the special variables CrP, CgP and CbP.
990
991 <p>
992 Care must be taken when using this material type to produce a physically valid reflection model.
993 The reflectance functions should be bidirectional, and under no circumstances should the sum of reflected diffuse,
994 transmitted diffuse, reflected specular, transmitted specular and the integrated directional diffuse component be greater than one.
995
996 <p>
997
998 <dt>
999 <a NAME="Plasdata">
1000 <b>Plasdata</b>
1001 </a>
1002
1003 <dd>
1004 Plasdata is used for arbitrary BRDF's that are most conveniently given as interpolated data.
1005 The arguments to this material are the <a HREF="#Data">data file</a> and coordinate index functions,
1006 as well as a function to optionally modify the data values.
1007
1008 <pre>
1009 mod plasdata id
1010 3+n+
1011 func datafile
1012 funcfile x1 x2 .. xn transform
1013 0
1014 4+ red green blue spec A5 ..
1015 </pre>
1016
1017 The coordinate indices (x1, x2, etc.) are themselves functions of the x, y and z direction to the incident light, plus the solid angle
1018 subtended by the light source (usually ignored).
1019 The data function (func) takes five variables, the
1020 interpolated value from the n-dimensional data file, followed by the
1021 x, y and z direction to the incident light and the solid angle of the source.
1022 The light source direction and size may of course be ignored by the function.
1023
1024 <p>
1025
1026 <dt>
1027 <a NAME="Metdata">
1028 <b>Metdata</b>
1029 </a>
1030
1031 <dd>
1032 As metfunc is to plasfunc, metdata is to <a HREF="#Plasdata">plasdata</a>.
1033 Metdata takes the same arguments as plasdata, but the specular component is modified by the given material color.
1034
1035 <p>
1036
1037 <dt>
1038 <a NAME="Transdata">
1039 <b>Transdata</b>
1040 </a>
1041
1042 <dd>
1043 Transdata is like <a HREF="#Plasdata">plasdata</a> but the specification includes transmittance as well as reflectance.
1044 The parameters are as follows.
1045
1046 <pre>
1047 mod transdata id
1048 3+n+
1049 func datafile
1050 funcfile x1 x2 .. xn transform
1051 0
1052 6+ red green blue rspec trans tspec A7 ..
1053 </pre>
1054
1055 <p>
1056
1057 <dt>
1058 <a NAME="Antimatter">
1059 <b>Antimatter</b>
1060 </a>
1061
1062 <dd>
1063 Antimatter is a material that can &quot;subtract&quot; volumes from other volumes.
1064 A ray passing into an antimatter object becomes blind to all the specified modifiers:
1065
1066 <pre>
1067 mod antimatter id
1068 N mod1 mod2 .. modN
1069 0
1070 0
1071 </pre>
1072
1073 The first modifier will also be used to shade the area leaving the antimatter volume and entering the regular volume.
1074 If mod1 is void, the antimatter volume is completely invisible.
1075 Antimatter does not work properly with the material type <a HREF="#Trans">&quot;trans&quot;</a>,
1076 and multiple antimatter surfaces should be disjoint.
1077 The viewpoint must be outside all volumes concerned for a correct rendering.
1078
1079 </dl>
1080
1081 <p>
1082 <hr>
1083
1084 <h4>
1085 <a NAME="Textures">2.1.3. Textures</a>
1086 </h4>
1087
1088 A texture is a perturbation of the surface normal, and is given by either a function or data.
1089
1090 <p>
1091
1092 <dl>
1093
1094 <dt>
1095 <a NAME="Texfunc">
1096 <b>Texfunc</b>
1097 </a>
1098
1099 <dd>
1100 A texfunc uses an auxiliary function file to specify a procedural texture:
1101
1102 <pre>
1103 mod texfunc id
1104 4+ xpert ypert zpert funcfile transform
1105 0
1106 n A1 A2 .. An
1107 </pre>
1108
1109 <p>
1110
1111 <dt>
1112 <a NAME="Texdata">
1113 <b>Texdata</b>
1114 </a>
1115
1116 <dd>
1117 A texdata texture uses three data files to get the surface normal perturbations.
1118 The variables xfunc, yfunc and zfunc take three arguments each from the interpolated values in xdfname, ydfname and zdfname.
1119
1120 <pre>
1121 mod texdata id
1122 8+ xfunc yfunc zfunc xdfname ydfname zdfname vfname x0 x1 .. xf
1123 0
1124 n A1 A2 .. An
1125 </pre>
1126
1127 </dl>
1128
1129 <p>
1130 <hr>
1131
1132 <h4>
1133 <a NAME="Patterns">2.1.4. Patterns</a>
1134 </h4>
1135
1136 Patterns are used to modify the reflectance of materials. The basic types are given below.
1137
1138 <p>
1139
1140 <dl>
1141
1142 <dt>
1143 <a NAME="Colorfunc">
1144 <b>Colorfunc</b>
1145 </a>
1146
1147 <dd>
1148 A colorfunc is a procedurally defined color pattern. It is specified as follows:
1149
1150 <pre>
1151 mod colorfunc id
1152 4+ red green blue funcfile transform
1153 0
1154 n A1 A2 .. An
1155 </pre>
1156
1157 <p>
1158
1159 <dt>
1160 <a NAME="Brightfunc">
1161 <b>Brightfunc</b>
1162 </a>
1163
1164 <dd>
1165 A brightfunc is the same as a colorfunc, except it is monochromatic.
1166
1167 <pre>
1168 mod brightfunc id
1169 2+ refl funcfile transform
1170 0
1171 n A1 A2 .. An
1172 </pre>
1173
1174 <p>
1175
1176 <dt>
1177 <a NAME="Colordata">
1178 <b>Colordata</b>
1179 </a>
1180
1181 <dd>
1182 Colordata uses an interpolated data map to modify a material's color.
1183 The map is n-dimensional, and is stored in three auxiliary files, one for each color.
1184 The coordinates used to look up and interpolate the data are defined in another auxiliary file.
1185 The interpolated data values are modified by functions of one or three variables.
1186 If the functions are of one variable, then they are passed the corresponding color component (red or green or blue).
1187 If the functions are of three variables, then they are passed the original red, green, and blue values as parameters.
1188
1189 <pre>
1190 mod colordata id
1191 7+n+
1192 rfunc gfunc bfunc rdatafile gdatafile bdatafile
1193 funcfile x1 x2 .. xn transform
1194 0
1195 m A1 A2 .. Am
1196 </pre>
1197
1198 <p>
1199
1200 <dt>
1201 <a NAME="Brightdata">
1202 <b>Brightdata</b>
1203 </a>
1204
1205 <dd>
1206 Brightdata is like colordata, except monochromatic.
1207
1208 <pre>
1209 mod brightdata id
1210 3+n+
1211 func datafile
1212 funcfile x1 x2 .. xn transform
1213 0
1214 m A1 A2 .. Am
1215 </pre>
1216
1217 <p>
1218
1219 <dt>
1220 <a NAME="Colorpict">
1221 <b>Colorpict</b>
1222 </a>
1223
1224 <dd>
1225 Colorpict is a special case of colordata, where the pattern is a two-dimensional image stored in the RADIANCE picture format.
1226 The dimensions of the image data are determined by the picture such that the smaller dimension is always 1,
1227 and the other is the ratio between the larger and the smaller.
1228 For example, a 500x338 picture would have coordinates (u,v) in the rectangle between (0,0) and (1.48,1).
1229
1230 <pre>
1231 mod colorpict id
1232 7+
1233 rfunc gfunc bfunc pictfile
1234 funcfile u v transform
1235 0
1236 m A1 A2 .. Am
1237 </pre>
1238
1239 <p>
1240
1241 <dt>
1242 <a NAME="Colortext">
1243 <b>Colortext</b>
1244 </a>
1245
1246 <dd>
1247 Colortext is dichromatic writing in a polygonal font.
1248 The font is defined in an auxiliary file, such as helvet.fnt.
1249 The text itself is also specified in a separate file, or can be part of the material arguments.
1250 The character size, orientation, aspect ratio and slant is determined by right and down motion vectors.
1251 The upper left origin for the text block as well as the foreground and background colors must also be given.
1252
1253 <pre>
1254 mod colortext id
1255 2 fontfile textfile
1256 0
1257 15+
1258 Ox Oy Oz
1259 Rx Ry Rz
1260 Dx Dy Dz
1261 rfore gfore bfore
1262 rback gback bback
1263 [spacing]
1264 </pre>
1265
1266 or:
1267
1268 <pre>
1269 mod colortext id
1270 2+N fontfile . This is a line with N words ...
1271 0
1272 15+
1273 Ox Oy Oz
1274 Rx Ry Rz
1275 Dx Dy Dz
1276 rfore gfore bfore
1277 rback gback bback
1278 [spacing]
1279 </pre>
1280
1281 <p>
1282
1283 <dt>
1284 <a NAME="Brighttext">
1285 <b>Brighttext</b>
1286 </a>
1287
1288 <dd>
1289 Brighttext is like colortext, but the writing is monochromatic.
1290
1291 <pre>
1292 mod brighttext id
1293 2 fontfile textfile
1294 0
1295 11+
1296 Ox Oy Oz
1297 Rx Ry Rz
1298 Dx Dy Dz
1299 foreground background
1300 [spacing]
1301 </pre>
1302
1303 or:
1304
1305 <pre>
1306 mod brighttext id
1307 2+N fontfile . This is a line with N words ...
1308 0
1309 11+
1310 Ox Oy Oz
1311 Rx Ry Rz
1312 Dx Dy Dz
1313 foreground background
1314 [spacing]
1315 </pre>
1316
1317 <p>
1318
1319 By default, a uniform spacing algorithm is used that guarantees every character will appear in a precisely determined position.
1320 Unfortunately, such a scheme results in rather unattractive and difficult to read text with most fonts.
1321 The optional spacing value defines the distance between characters for proportional spacing.
1322 A positive value selects a spacing algorithm that preserves right margins and indentation,
1323 but does not provide the ultimate in proportionally spaced text.
1324 A negative value insures that characters are properly spaced, but the placement of words then varies unpredictably.
1325 The choice depends on the relative importance of spacing versus formatting.
1326 When presenting a section of formatted text, a positive spacing value is usually preferred.
1327 A single line of text will often be accompanied by a negative spacing value.
1328 A section of text meant to depict a picture, perhaps using a special purpose font such as hexbit4x1.fnt, calls for uniform spacing.
1329 Reasonable magnitudes for proportional spacing are between 0.1 (for tightly spaced characters) and 0.3 (for wide spacing).
1330
1331 </dl>
1332
1333 <p>
1334 <hr>
1335
1336 <h4>
1337 <a NAME="Mixtures">2.1.5. Mixtures</a>
1338 </h4>
1339
1340 A mixture is a blend of one or more materials or textures and patterns.
1341 The basic types are given below.
1342
1343 <p>
1344
1345 <dl>
1346
1347 <dt>
1348 <a NAME="Mixfunc">
1349 <b>Mixfunc</b>
1350 </a>
1351
1352 <dd>
1353 A mixfunc mixes two modifiers procedurally. It is specified as follows:
1354
1355 <pre>
1356 mod mixfunc id
1357 4+ foreground background vname funcfile transform
1358 0
1359 n A1 A2 .. An
1360 </pre>
1361
1362 Foreground and background are modifier names that must be
1363 defined earlier in the scene description.
1364 If one of these is a material, then
1365 the modifier of the mixfunc must be &quot;void&quot;.
1366 (Either the foreground or background modifier may be &quot;void&quot;,
1367 which serves as a form of opacity control when used with a material.)
1368 Vname is the coefficient defined in funcfile that determines the influence of foreground.
1369 The background coefficient is always (1-vname).
1370 Since the references are not resolved until run-time, the last definitions of the modifier id's will be used.
1371 This can result in modifier loops, which are detected by the renderer.
1372
1373 <p>
1374
1375 <dt>
1376 <a NAME="Mixdata">
1377 <b>Mixdata</b>
1378 </a>
1379
1380 <dd>
1381 Mixdata combines two modifiers using an auxiliary data file:
1382
1383 <pre>
1384 mod mixdata id
1385 5+n+
1386 foreground background func datafile
1387 funcfile x1 x2 .. xn transform
1388 0
1389 m A1 A2 .. Am
1390 </pre>
1391
1392 <dt>
1393 <a NAME="Mixpict">
1394 <b>Mixpict</b>
1395 </a>
1396
1397 <dd>
1398 Mixpict combines two modifiers based on a picture:
1399
1400 <pre>
1401 mod mixpict id
1402 7+
1403 foreground background func pictfile
1404 funcfile u v transform
1405 0
1406 m A1 A2 .. Am
1407 </pre>
1408
1409 <p>
1410
1411 The mixing coefficient function &quot;func&quot; takes three
1412 arguments, the red, green and blue values
1413 corresponding to the pixel at (u,v).
1414
1415 </dl>
1416 <p>
1417
1418 <dt>
1419 <a NAME="Mixtext">
1420 <b>Mixtext</b>
1421 </a>
1422
1423 <dd>
1424 Mixtext uses one modifier for the text foreground, and one for the background:
1425
1426 <pre>
1427 mod mixtext id
1428 4 foreground background fontfile textfile
1429 0
1430 9+
1431 Ox Oy Oz
1432 Rx Ry Rz
1433 Dx Dy Dz
1434 [spacing]
1435 </pre>
1436
1437 or:
1438
1439 <pre>
1440 mod mixtext id
1441 4+N
1442 foreground background fontfile .
1443 This is a line with N words ...
1444 0
1445 9+
1446 Ox Oy Oz
1447 Rx Ry Rz
1448 Dx Dy Dz
1449 [spacing]
1450 </pre>
1451
1452 </dl>
1453
1454 <p>
1455 <hr>
1456
1457 <h3>
1458 <a NAME="Auxiliary">2.2. Auxiliary Files</a>
1459 </h3>
1460
1461 Auxiliary files used in <a HREF="#Textures">textures</a> and <a HREF="#Patterns">patterns</a>
1462 are accessed by the programs during image generation.
1463 These files may be located in the working directory, or in a library directory.
1464 The environment variable RAYPATH can be assigned an alternate set of search directories.
1465 Following is a brief description of some common file types.
1466
1467 <p>
1468
1469 <h4>
1470 <a NAME="Function">12.2.1. Function Files</a>
1471 </h4>
1472
1473 A function file contains the definitions of variables, functions and constants used by a primitive.
1474 The transformation that accompanies the file name contains the necessary rotations, translations and scalings
1475 to bring the coordinates of the function file into agreement with the world coordinates.
1476 The transformation specification is the same as for the <a HREF="#Generators">xform</a> command.
1477 An example function file is given below:
1478
1479 <pre>
1480 {
1481 This is a comment, enclosed in curly braces.
1482 {Comments can be nested.}
1483 }
1484 { standard expressions use +,-,*,/,^,(,) }
1485 vname = Ny * func(A1) ;
1486 { constants are defined with a colon }
1487 const : sqrt(PI/2) ;
1488 { user-defined functions add to library }
1489 func(x) = 5 + A1*sin(x/3) ;
1490 { functions may be passed and recursive }
1491 rfunc(f,x) = if(x,f(x),f(-x)*rfunc(f,x+1)) ;
1492 { constant functions may also be defined }
1493 cfunc(x) : 10*x / sqrt(x) ;
1494 </pre>
1495
1496 Many variables and functions are already defined by the program, and they are listed in the file rayinit.cal.
1497 The following variables are particularly important:
1498
1499 <pre>
1500 Dx, Dy, Dz - incident ray direction
1501 Nx, Ny, Nz - surface normal at intersection point
1502 Px, Py, Pz - intersection point
1503 T - distance from start
1504 Ts - single ray (shadow) distance
1505 Rdot - cosine between ray and normal
1506 arg(0) - number of real arguments
1507 arg(i) - i'th real argument
1508 </pre>
1509
1510 For mesh objects, the local surface coordinates are available:
1511
1512 <pre>
1513 Lu, Lv - local (u,v) coordinates
1514 </pre>
1515
1516 For BRDF types, the following variables are defined as well:
1517
1518 <pre>
1519 NxP, NyP, NzP - perturbed surface normal
1520 RdotP - perturbed dot product
1521 CrP, CgP, CbP - perturbed material color
1522 </pre>
1523
1524 A unique context is set up for each file so
1525 that the same variable may appear in different
1526 function files without conflict.
1527 The variables listed above and any others defined in
1528 rayinit.cal are available globally.
1529 If no file is needed by a given primitive because all
1530 the required variables are global,
1531 a period (`.') can be given in place of the file name.
1532 It is also possible to give an expression instead
1533 of a straight variable name in a scene file,
1534 although such expressions should be kept
1535 simple if possible.
1536 Also, functions (requiring parameters) must be given
1537 as names and not as expressions.
1538
1539 <p>
1540 Constant expressions are used as an optimization in function files.
1541 They are replaced wherever they occur in an expression by their value.
1542 Constant expressions are evaluated only once, so they must not contain any variables or values that can change,
1543 such as the ray variables Px and Ny or the primitive argument function arg().
1544 All the math library functions such as sqrt() and cos() have the constant attribute,
1545 so they will be replaced by immediate values whenever they are given constant arguments.
1546 Thus, the subexpression cos(PI*sqrt(2)) is immediately replaced by its value, -.266255342,
1547 and does not cause any additional overhead in the calculation.
1548
1549 <p>
1550 It is generally a good idea to define constants and variables before they are referred to in a function file.
1551 Although evaluation does not take place until later, the interpreter does variable scoping and
1552 constant subexpression evaluation based on what it has compiled already.
1553 For example, a variable that is defined globally in rayinit.cal
1554 then referenced in the local context of a function file
1555 cannot subsequently be redefined in the same file
1556 because the compiler has already determined the scope of the referenced variable as global.
1557 To avoid such conflicts, one can state the scope of a variable explicitly by
1558 preceding the variable name with a context mark (a back-quote) for a local variable,
1559 or following the name with a context mark for a global variable.
1560
1561 <p>
1562
1563 <h4>
1564 <a NAME="Data">2.2.2. Data Files</a>
1565 </h4>
1566
1567 Data files contain n-dimensional arrays of real numbers used for interpolation.
1568 Typically, definitions in a function file determine how to index and use interpolated data values.
1569 The basic data file format is as follows:
1570
1571 <pre>
1572 N
1573 beg1 end1 m1
1574 0 0 m2 x2.1 x2.2 x2.3 x2.4 .. x2.m2
1575 ...
1576 begN endN mN
1577 DATA, later dimensions changing faster.
1578 </pre>
1579
1580 N is the number of dimensions.
1581 For each dimension, the beginning and ending coordinate values and the dimension size is given.
1582 Alternatively, individual coordinate values can be given when the points are not evenly spaced.
1583 These values must either be increasing or decreasing monotonically.
1584 The data is m1*m2*...*mN real numbers in ASCII form.
1585 Comments may appear anywhere in the file, beginning with a pound
1586 sign ('#') and continuing to the end of line.
1587
1588 <p>
1589
1590 <h4>
1591 <a NAME="Font">2.2.3. Font Files</a>
1592 </h4>
1593
1594 A font file lists the polygons which make up a character set.
1595 Comments may appear anywhere in the file, beginning with a pound
1596 sign ('#') and continuing to the end of line.
1597 All numbers are decimal integers:
1598
1599 <pre>
1600 code n
1601 x0 y0
1602 x1 y1
1603 ...
1604 xn yn
1605 ...
1606 </pre>
1607
1608 The ASCII codes can appear in any order. N is the number of vertices, and the last is automatically connected to the first.
1609 Separate polygonal sections are joined by coincident sides.
1610 The character coordinate system is a square with lower left corner at (0,0), lower right at (255,0) and upper right at (255,255).
1611
1612 <p>
1613
1614 <hr>
1615
1616 <h3>
1617 <a NAME="Generators">2.3. Generators</a>
1618 </h3>
1619
1620 A generator is any program that produces a scene description as its output.
1621 They usually appear as commands in a scene description file.
1622 An example of a simple generator is genbox.
1623
1624 <ul>
1625
1626 <li>
1627 <a NAME="Genbox" HREF="../man_html/genbox.1.html">
1628 <b>Genbox</b>
1629 </a>
1630 takes the arguments of width, height and depth to produce a parallelepiped description.
1631 <li>
1632 <a NAME="Genprism" HREF="../man_html/genprism.1.html">
1633 <b>Genprism</b>
1634 </a>
1635 takes a list of 2-dimensional coordinates and extrudes them along a vector to
1636 produce a 3-dimensional prism.
1637 <li>
1638 <a NAME="Genrev" HREF="../man_html/genrev.1.html">
1639 <b>Genrev</b>
1640 </a>
1641 is a more sophisticated generator that produces an object of rotation from parametric functions for radius and axis position.
1642 <li>
1643 <a NAME="Gensurf" HREF="../man_html/gensurf.1.html">
1644 <b>Gensurf</b>
1645 </a>
1646 tessellates a surface defined by the parametric functions x(s,t), y(s,t), and z(s,t).
1647 <li>
1648 <a NAME="Genworm" HREF="../man_html/genworm.1.html">
1649 <b>Genworm</b>
1650 </a>
1651 links cylinders and spheres along a curve.
1652 <li>
1653 <a NAME="Gensky" HREF="../man_html/gensky.1.html">
1654 <b>Gensky</b>
1655 </a>
1656 produces a sun and sky distribution corresponding to a given time and date.
1657 <li>
1658 <a NAME="Xform" HREF="../man_html/xform.1.html">
1659 <b>Xform</b>
1660 </a>
1661 is a program that transforms a scene description from one coordinate space to another.
1662 Xform does rotation, translation, scaling, and mirroring.
1663
1664 </ul>
1665
1666 <p>
1667 <hr>
1668
1669 <h2>
1670 <a NAME="Image">3. Image Generation</a>
1671 </h2>
1672
1673 Once the scene has been described in three-dimensions, it is possible to generate a two-dimensional image from a given perspective.
1674
1675 <p>
1676 The image generating programs use an <a NAME="octree"><b>octree</b></a> to efficiently trace rays through the scene.
1677 An octree subdivides space into nested octants which contain sets of surfaces.
1678 In RADIANCE, an octree is created from a scene description by <a NAME="oconv1" HREF="../man_html/oconv.1.html"><b>oconv</b></a>.
1679 The details of this process are not important, but the octree will serve as input to the ray-tracing programs and
1680 directs the use of a scene description.
1681 <ul>
1682 <li>
1683 <a NAME="rvu" HREF="../man_html/rvu.1.html"><b>Rview</b></a> is ray-tracing program for viewing a scene interactively.
1684 When the user specifies a new perspective, rvu quickly displays a rough image on the terminal,
1685 then progressively increases the resolution as the user looks on.
1686 He can select a particular section of the image to improve, or move to a different view and start over.
1687 This mode of interaction is useful for debugging scenes as well as determining the best view for a final image.
1688
1689 <li>
1690 <a NAME="rpict" HREF="../man_html/rpict.1.html"><b>Rpict</b></a> produces a high-resolution picture of a scene from a particular perspective.
1691 This program features adaptive sampling, crash recovery and progress reporting, all of which are important for time-consuming images.
1692 </ul>
1693 <p>
1694 A number of <a NAME="filters"><b>filters</b></a> are available for manipulating picture files:
1695 <ul>
1696 <li> <a HREF="../man_html/pfilt.1.html"><b>Pfilt</b></a>
1697 sets the exposure and performs antialiasing.
1698 <li> <a HREF="../man_html/pcompos.1.html"><b>Pcompos</b></a>
1699 composites (cuts and pastes) pictures.
1700 <li> <a HREF="../man_html/pcomb.1.html"><b>Pcomb</b></a>
1701 performs arbitrary math on one or more pictures.
1702 <li> <a HREF="../man_html/pcond.1.html"><b>Pcond</b></a>
1703 conditions a picture for a specific display device.
1704 <li> <a HREF="../man_html/protate.1.html"><b>Protate</b></a>
1705 rotates a picture 90 degrees clockwise.
1706 <li> <a HREF="../man_html/pflip.1.html"><b>Pflip</b></a>
1707 flips a picture horizontally, vertically, or both
1708 (180 degree rotation).
1709 <li> <a HREF="../man_html/pvalue.1.html"><b>Pvalue</b></a>
1710 converts a picture to and from simpler formats.
1711 </ul>
1712
1713 <p>
1714 Pictures may be displayed directly under X11 using the program
1715 <a HREF="../man_html/ximage.1.html">ximage</a>,
1716 or converted a standard image format using one of the following
1717 <b>translators</b>:
1718 <ul>
1719 <li> <b>Ra_avs</b>
1720 converts to and from AVS image format.
1721 <li> <a HREF="../man_html/ra_pict.1.html"><b>Ra_pict</b></a>
1722 converts to Macintosh 32-bit PICT2 format.
1723 <li> <a HREF="../man_html/ra_ppm.1.html"><b>Ra_ppm</b></a>
1724 converts to and from Poskanzer Portable Pixmap formats.
1725 <li> <a HREF="../man_html/ra_pr.1.html"><b>Ra_pr</b></a>
1726 converts to and from Sun 8-bit rasterfile format.
1727 <li> <a HREF="../man_html/ra_pr24.1.html"><b>Ra_pr24</b></a>
1728 converts to and from Sun 24-bit rasterfile format.
1729 <li> <a HREF="../man_html/ra_ps.1.html"><b>Ra_ps</b></a>
1730 converts to PostScript color and greyscale formats.
1731 <li> <a HREF="../man_html/ra_rgbe.1.html"><b>Ra_rgbe</b></a>
1732 converts to and from Radiance uncompressed picture format.
1733 <li> <a HREF="../man_html/ra_t16.1.html"><b>Ra_t16</b></a>
1734 converts to and from Targa 16 and 24-bit image formats.
1735 <li> <a HREF="../man_html/ra_t8.1.html"><b>Ra_t8</b></a>
1736 converts to and from Targa 8-bit image format.
1737 <li> <a HREF="../man_html/ra_tiff.1.html"><b>Ra_tiff</b></a>
1738 converts to and from TIFF.
1739 <li> <a HREF="../man_html/ra_xyze.1.html"><b>Ra_xyze</b></a>
1740 converts to and from Radiance CIE picture format.
1741 </ul>
1742
1743 <p>
1744
1745 <hr>
1746
1747 <h2>
1748 <a NAME="License">4. License</a>
1749 </h2>
1750
1751 <pre>
1752 The Radiance Software License, Version 1.0
1753
1754 Copyright (c) 1990 - 2002 The Regents of the University of California,
1755 through Lawrence Berkeley National Laboratory. All rights reserved.
1756
1757 Redistribution and use in source and binary forms, with or without
1758 modification, are permitted provided that the following conditions
1759 are met:
1760
1761 1. Redistributions of source code must retain the above copyright
1762 notice, this list of conditions and the following disclaimer.
1763
1764 2. Redistributions in binary form must reproduce the above copyright
1765 notice, this list of conditions and the following disclaimer in
1766 the documentation and/or other materials provided with the
1767 distribution.
1768
1769 3. The end-user documentation included with the redistribution,
1770 if any, must include the following acknowledgment:
1771 &quot;This product includes Radiance software
1772 (<a HREF="http://radsite.lbl.gov/">http://radsite.lbl.gov/</a>)
1773 developed by the Lawrence Berkeley National Laboratory
1774 (<a HREF="http://www.lbl.gov/">http://www.lbl.gov/</a>).&quot;
1775 Alternately, this acknowledgment may appear in the software itself,
1776 if and wherever such third-party acknowledgments normally appear.
1777
1778 4. The names &quot;Radiance,&quot; &quot;Lawrence Berkeley National Laboratory&quot;
1779 and &quot;The Regents of the University of California&quot; must
1780 not be used to endorse or promote products derived from this
1781 software without prior written permission. For written
1782 permission, please contact [email protected].
1783
1784 5. Products derived from this software may not be called &quot;Radiance&quot;,
1785 nor may &quot;Radiance&quot; appear in their name, without prior written
1786 permission of Lawrence Berkeley National Laboratory.
1787
1788 THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
1789 WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
1790 OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
1791 DISCLAIMED. IN NO EVENT SHALL Lawrence Berkeley National Laboratory OR
1792 ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
1793 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
1794 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
1795 USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
1796 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
1797 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
1798 OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
1799 SUCH DAMAGE.
1800 </pre>
1801
1802 <hr>
1803
1804 <h2>
1805 <a NAME="Ack">5. Acknowledgements</a>
1806 </h2>
1807
1808 This work was supported by the Assistant Secretary of Conservation and Renewable Energy,
1809 Office of Building Energy Research and Development,
1810 Buildings Equipment Division of the U.S. Department of Energy under Contract No. DE-AC03-76SF00098.
1811
1812 <p>
1813 Additional work was sponsored by the Swiss federal government
1814 under the Swiss LUMEN Project and was carried out in the
1815 Laboratoire d'Energie Solaire (LESO Group) at the
1816 Ecole Polytechnique Federale de Lausanne (EPFL University) in Lausanne, Switzerland.
1817
1818 <p>
1819
1820 <hr>
1821
1822 <h2>
1823 <a NAME="Ref">6.</a> References
1824 </h2>
1825 <p>
1826 <ul>
1827 <li>Ward, Greg, Elena Eydelberg-Vileshin,
1828 ``<a HREF="http://viz.cs.berkeley.edu/~gwlarson/papers/egwr02/index.html">Picture Perfect RGB
1829 Rendering Using Spectral Prefiltering and Sharp Color Primaries</a>,''
1830 Thirteenth Eurographics Workshop on Rendering (2002),
1831 P. Debevec and S. Gibson (Editors), June 2002.
1832 <li>Ward, Gregory,
1833 ``<a HREF="http://viz.cs.berkeley.edu/~gwlarson/papers/cic01.pdf">High Dynamic Range Imaging</a>,''
1834 Proceedings of the Ninth Color Imaging Conference, November 2001.
1835 <li>Ward, Gregory and Maryann Simmons,
1836 ``<a HREF="http://viz.cs.berkeley.edu/~gwlarson/papers/tog99.pdf">
1837 The Holodeck Ray Cache: An Interactive Rendering System for Global Illumination in Nondiffuse
1838 Environments</a>,'' ACM Transactions on Graphics, 18(4):361-98, October 1999.
1839 <li>Larson, G.W., ``<a HREF="http://viz.cs.berkeley.edu/~gwlarson/papers/ewp98.pdf">The Holodeck: A Parallel
1840 Ray-caching Rendering System</a>,'' Proceedings of the Second
1841 Eurographics Workshop on Parallel Graphics and Visualisation,
1842 September 1998.
1843 <li>Larson, G.W. and R.A. Shakespeare,
1844 <a HREF="http://radsite.lbl.gov/radiance/book/index.html"><em>Rendering with Radiance:
1845 the Art and Science of Lighting Visualization</em></a>,
1846 Morgan Kaufmann Publishers, 1998.
1847 <li>Larson, G.W., H. Rushmeier, C. Piatko,
1848 ``<a HREF="http://radsite.lbl.gov/radiance/papers/lbnl39882/tonemap.pdf">A Visibility
1849 Matching Tone Reproduction Operator for
1850 High Dynamic Range Scenes</a>,'' LBNL Technical Report 39882,
1851 January 1997.
1852 <li>Ward, G., ``<a HREF="http://radsite.lbl.gov/radiance/papers/erw95.1/paper.html">Making
1853 Global Illumination User-Friendly</a>,'' Sixth
1854 Eurographics Workshop on Rendering, Springer-Verlag,
1855 Dublin, Ireland, June 1995.</li>
1856 <li>Rushmeier, H., G. Ward, C. Piatko, P. Sanders, B. Rust,
1857 ``<a HREF="http://radsite.lbl.gov/mgf/compare.html">
1858 Comparing Real and Synthetic Images: Some Ideas about
1859 Metrics</a>,'' Sixth Eurographics Workshop on Rendering,
1860 Springer-Verlag, Dublin, Ireland, June 1995.</li>
1861 <li>Ward, G., ``<a HREF="http://radsite.lbl.gov/radiance/papers/sg94.1/paper.html">The RADIANCE
1862 Lighting Simulation and Rendering System</a>,'' <em>Computer
1863 Graphics</em>, July 1994.</li>
1864 <li>Rushmeier, H., G. Ward, ``<a HREF="http://radsite.lbl.gov/radiance/papers/sg94.2/energy.html">Energy
1865 Preserving Non-Linear Filters</a>,'' <em>Computer
1866 Graphics</em>, July 1994.</li>
1867 <li>Ward, G., ``A Contrast-Based Scalefactor for Luminance
1868 Display,'' <em>Graphics Gems IV</em>, Edited by Paul Heckbert,
1869 Academic Press 1994.</li>
1870 <li>Ward, G., ``<a HREF="http://radsite.lbl.gov/radiance/papers/sg92/paper.html">Measuring and
1871 Modeling Anisotropic Reflection</a>,'' <em>Computer
1872 Graphics</em>, Vol. 26, No. 2, July 1992. </li>
1873 <li>Ward, G., P. Heckbert, ``<a HREF="http://radsite.lbl.gov/radiance/papers/erw92/paper.html">Irradiance
1874 Gradients</a>,'' Third Annual Eurographics Workshop on
1875 Rendering, Springer-Verlag, May 1992. </li>
1876 <li>Ward, G., ``<a HREF="http://radsite.lbl.gov/radiance/papers/erw91/erw91.html">Adaptive Shadow
1877 Testing for Ray Tracing</a>'' Photorealistic Rendering in
1878 Computer Graphics, proceedings of 1991 Eurographics
1879 Rendering Workshop, edited by P. Brunet and F.W. Jansen,
1880 Springer-Verlag. </li>
1881 <li>Ward, G., ``Visualization,'' <em>Lighting Design and
1882 Application</em>, Vol. 20, No. 6, June 1990. </li>
1883 <li>Ward, G., F. Rubinstein, R. Clear, ``<a HREF="http://radsite.lbl.gov/radiance/papers/sg88/paper.html">A Ray Tracing Solution for
1884 Diffuse Interreflection</a>,'' <em>Computer Graphics</em>,
1885 Vol. 22, No. 4, August 1988. </li>
1886 <li>Ward, G., F. Rubinstein, ``A New Technique for Computer
1887 Simulation of Illuminated Spaces,'' <em>Journal of the
1888 Illuminating Engineering Society</em>, Vol. 17, No. 1,
1889 Winter 1988. </li>
1890 </ul>
1891 <p>
1892 See the <a HREF="index.html">RADIANCE Reference Materials</a> page
1893 for additional information.
1894 <hr>
1895
1896 <a NAME="Index"><h2>7. Types Index</h2></a>
1897
1898 <pre>
1899 <h4>
1900 SURFACES MATERIALS TEXTURES PATTERNS MIXTURES</h4>
1901 <a HREF="#Source">Source</a> <a HREF="#Light">Light</a> <a HREF="#Texfunc">Texfunc</a> <a HREF="#Colorfunc">Colorfunc</a> <a HREF="#Mixfunc">Mixfunc</a>
1902 <a HREF="#Sphere">Sphere</a> <a HREF="#Illum">Illum</a> <a HREF="#Texdata">Texdata</a> <a HREF="#Brightfunc">Brightfunc</a> <a HREF="#Mixdata">Mixdata</a>
1903 <a HREF="#Bubble">Bubble</a> <a HREF="#Glow">Glow</a> <a HREF="#Colordata">Colordata</a> <a HREF="#Mixtext">Mixtext</a>
1904 <a HREF="#Polygon">Polygon</a> <a HREF="#Spotlight">Spotlight</a> <a HREF="#Brightdata">Brightdata</a>
1905 <a HREF="#Cone">Cone</a> <a HREF="#Mirror">Mirror</a> <a HREF="#Colorpict">Colorpict</a>
1906 <a HREF="#Cup">Cup</a> <a HREF="#Prism1">Prism1</a> <a HREF="#Colortext">Colortext</a>
1907 <a HREF="#Cylinder">Cylinder</a> <a HREF="#Prism2">Prism2</a> <a HREF="#Brighttext">Brighttext</a>
1908 <a HREF="#Tube">Tube</a> <a HREF="#Plastic">Plastic</a>
1909 <a HREF="#Ring">Ring</a> <a HREF="#Metal">Metal</a>
1910 <a HREF="#Instance">Instance</a> <a HREF="#Trans">Trans</a>
1911 <a HREF="#Mesh">Mesh</a> <a HREF="#Plastic2">Plastic2</a>
1912 <a HREF="#Metal2">Metal2</a>
1913 <a HREF="#Trans2">Trans2</a>
1914 <a HREF="#Mist">Mist</a>
1915 <a HREF="#Dielectric">Dielectric</a>
1916 <a HREF="#Interface">Interface</a>
1917 <a HREF="#Glass">Glass</a>
1918 <a HREF="#Plasfunc">Plasfunc</a>
1919 <a HREF="#Metfunc">Metfunc</a>
1920 <a HREF="#Transfunc">Transfunc</a>
1921 <a HREF="#BRTDfunc">BRTDfunc</a>
1922 <a HREF="#Plasdata">Plasdata</a>
1923 <a HREF="#Metdata">Metdata</a>
1924 <a HREF="#Transdata">Transdata</a>
1925 <a HREF="#Antimatter">Antimatter</a>
1926
1927 </pre>
1928
1929 <p>
1930
1931
1932 <hr>
1933 <center>Last Update: October 22, 1997</center>
1934 </body>
1935 </html>
1936