ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/radiance/ray/doc/ray.1
Revision: 1.46
Committed: Wed Dec 13 23:26:16 2023 UTC (5 months ago) by greg
Branch: MAIN
CVS Tags: HEAD
Changes since 1.45: +42 -1 lines
Log Message:
feat(rpict,rvu,rtrace,rcontrib): Added "specdata" and "specpict" pattern primitives

File Contents

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