ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/radiance/ray/doc/ray.html
Revision: 1.4
Committed: Thu Oct 21 16:16:14 2004 UTC (19 years, 5 months ago) by greg
Content type: text/html
Branch: MAIN
CVS Tags: rad3R6, rad3R6P1
Changes since 1.3: +3 -5 lines
Log Message:
Update for 3.6 official release

File Contents

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