ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/radiance/ray/doc/ray.1
Revision: 1.41
Committed: Wed Nov 15 18:28:09 2023 UTC (5 months, 2 weeks ago) by greg
Branch: MAIN
Changes since 1.40: +69 -2 lines
Log Message:
docs: Updated manuals with new hyperspectral pattern primitives

File Contents

# Content
1 .\" RCSid "$Id: ray.1,v 1.40 2023/11/03 17:41:27 greg Exp $"
2 .\" Print using the -ms macro package
3 .DA 11/13/2023
4 .LP
5 .tl """Copyright \(co 2023 Regents, University of California
6 .sp 2
7 .TL
8 The
9 .so ../src/rt/VERSION
10 .br
11 Synthetic Imaging System
12 .AU
13 Building Technologies Department
14 .br
15 Lawrence Berkeley Laboratory
16 .br
17 1 Cyclotron Rd., MS 90-3111
18 .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 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 .PP
64 A scene description file lists the surfaces and materials
65 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 .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 n S1 S2 "S 3" .. Sn
99 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 An identifier can be any string (i.e., any sequence of non-white characters).
127 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 (separated by white space or enclosed in quotes).
133 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 The reserved modifier name "inherit" may be used to specificy that
143 an alias will inherit its modifier from the original.
144 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 White space is generally ignored, except as a separator.
156 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 Modifiers can be materials, mixtures, textures or patterns.
164 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 A cup is an inverted cone (i.e., has an inward surface normal).
237 .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 .I obj2mesh
276 program.
277 .DS
278 mod mesh id
279 1+ meshfile transform
280 0
281 0
282 .DE
283 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 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 These are made available to function files via the Lu and Lv variables.
298 .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 Light is the basic material for self-luminous surfaces (i.e., light
336 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 of the effective focus behind the source center (i.e., the focal length).
396 .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 Mirror is used for planar surfaces that produce virtual
406 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 glazings, generating virtual light sources.
430 It can only be used to modify a planar surface (i.e., a polygon or disk)
431 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 to work properly with virtual light sources.
435 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 forward direction, as fit by the Henyey-Greenstein function:
495 .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 If no function file is required (i.e., no special variables or
584 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 .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 Unlike other material types, total reflectance is the sum of
634 diffuse and specular colors, and should be adjusted accordingly.
635 .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 .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 .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 String arguments are used to define thickness for proxied
892 surfaces and the "up" orientation for the material.
893 .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 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 Similar to the illum type, this permits direct viewing and
907 shadow testing of complex geometry.
908 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 The sign of the thickness is important, as it indicates whether the
919 proxied geometry is behind the BSDF surface (when thickness is positive)
920 or in front (when thickness is negative).
921 .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 .UL aBSDF
953 .PP
954 The aBSDF material is identical to the BSDF type with two important
955 differences.
956 First, proxy geometry is not supported, so there is no thickness parameter.
957 Second, an aBSDF is assumed to have some specular through component
958 (the 'a' stands for "aperture"), which
959 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 mod aBSDF id
965 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 to use the BSDF type with a zero thickness than to use aBSDF.
975 .LP
976 .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 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 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 .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 The first two real arguments indicate the limits of the covered
1211 spectral range in nanometers.
1212 Subsequent real values correspond to multipliers in each wavelength band,
1213 where the first band goes from nmA to nmA+(nmB-nmA)/N, and N is the
1214 number of bands (i.e., the number of real arguments minus 2).
1215 The nmA wavelength may be greater or less than the nmB wavelength,
1216 but they may not be equal, and their ordering must correspond to
1217 the ordering of the spectral values.
1218 A minimum of 3 values must be given, which would act
1219 more or less the same as a constant RGB multiplier.
1220 As with RGB values, spectral quantities normally range between 0
1221 and 1 at each wavelength, or average to 1.0 against a standard
1222 sensitivity functions such as V(lambda).
1223 The best results obtain when the spectral range and number
1224 of samples match rendering options, though resampling will handle
1225 any differences, zero-filling wavelenths outside the nmA to nmB
1226 range.
1227 A warning will be issued if the given wavelength range does not
1228 adequately cover the visible spectrum.
1229 .LP
1230 .UL Specfile
1231 .PP
1232 The specfile primitive is equivalent to the spectrum type, but
1233 the wavelength range and values are contained in a 1-dimensional
1234 data file.
1235 This may be a more convenient way to specify a spectral color,
1236 especially one corresponding to a standard illuminant such as D65
1237 or a library of measured spectra.
1238 .DS
1239 mod specfile id
1240 1 datafile
1241 0
1242 0
1243 .DE
1244 As with the spectrum type, rendering wavelengths outside the defined
1245 range will be zero-filled.
1246 Unlike the spectrum type, the file may contain non-uniform samples.
1247 .LP
1248 .UL Specfunc
1249 .PP
1250 The specfunc primitive offers dynamic control over a spectral
1251 pattern, similar to the colorfunc type.
1252 .DS
1253 mod specfunc id
1254 2+ sval funcfile transform
1255 0
1256 2+ nmA nmB A3 ..
1257 .DE
1258 Like the spectrum primitive, the wavelength range is specified
1259 in the first two real arguments, and additional real values are
1260 accessible to the sval function.
1261 This function is fed a wavelenth sample
1262 between nmA and nmB as its only argument,
1263 and it returns the corresponding spectral intensity.
1264 .NH 3
1265 Mixtures
1266 .PP
1267 A mixture is a blend of one or more materials or textures and patterns.
1268 Blended materials should not be light source types or virtual source types.
1269 The basic types are given below.
1270 .LP
1271 .UL Mixfunc
1272 .PP
1273 A mixfunc mixes two modifiers procedurally.
1274 It is specified as follows:
1275 .DS
1276 mod mixfunc id
1277 4+ foreground background vname funcfile transform
1278 0
1279 n A1 A2 .. An
1280 .DE
1281 Foreground and background are modifier names that must be
1282 defined earlier in the scene description.
1283 If one of these is a material, then
1284 the modifier of the mixfunc must be "void".
1285 (Either the foreground or background modifier may be "void",
1286 which serves as a form of opacity control when used with a material.)\0
1287 Vname is the coefficient defined in funcfile that determines the influence
1288 of foreground.
1289 The background coefficient is always (1-vname).
1290 .LP
1291 .UL Mixdata
1292 .PP
1293 Mixdata combines two modifiers using an auxiliary data file:
1294 .DS
1295 mod mixdata id
1296 5+n+
1297 foreground background func datafile
1298 funcfile x1 x2 .. xn transform
1299 0
1300 m A1 A2 .. Am
1301 .DE
1302 .LP
1303 .UL Mixpict
1304 .PP
1305 Mixpict combines two modifiers based on a picture:
1306 .DS
1307 mod mixpict id
1308 7+
1309 foreground background func pictfile
1310 funcfile u v transform
1311 0
1312 m A1 A2 .. Am
1313 .DE
1314 The mixing coefficient function "func" takes three
1315 arguments, the red, green and blue values
1316 corresponding to the pixel at (u,v).
1317 .LP
1318 .UL Mixtext
1319 .PP
1320 Mixtext uses one modifier for the text foreground, and one for the
1321 background:
1322 .DS
1323 mod mixtext id
1324 4 foreground background fontfile textfile
1325 0
1326 9+
1327 Ox Oy Oz
1328 Rx Ry Rz
1329 Dx Dy Dz
1330 [spacing]
1331 .DE
1332 or:
1333 .DS
1334 mod mixtext id
1335 4+N
1336 foreground background fontfile .
1337 This is a line with N words ...
1338 0
1339 9+
1340 Ox Oy Oz
1341 Rx Ry Rz
1342 Dx Dy Dz
1343 [spacing]
1344 .DE
1345 .NH 2
1346 Auxiliary Files
1347 .PP
1348 Auxiliary files used in textures and patterns
1349 are accessed by the programs during image generation.
1350 These files may be located in the working directory, or in
1351 a library directory.
1352 The environment variable
1353 .I RAYPATH
1354 can be assigned an alternate set of search directories.
1355 Following is a brief description of some common file types.
1356 .NH 3
1357 Function Files
1358 .PP
1359 A function file contains the definitions of variables, functions
1360 and constants used by a primitive.
1361 The transformation that accompanies the file name contains the necessary
1362 rotations, translations and scalings to bring the coordinates of
1363 the function file into agreement with the world coordinates.
1364 The transformation specification is the same as for the
1365 .I xform
1366 command.
1367 An example function file is given below:
1368 .DS
1369 {
1370 This is a comment, enclosed in curly braces.
1371 {Comments can be nested.}
1372 }
1373 { standard expressions use +,-,*,/,^,(,) }
1374 vname = Ny * func(A1) ;
1375 { constants are defined with a colon }
1376 const : sqrt(PI/2) ;
1377 { user-defined functions add to library }
1378 func(x) = 5 + A1*sin(x/3) ;
1379 { functions may be passed and recursive }
1380 rfunc(f,x) = if(x,f(x),f(-x)*rfunc(f,x+1)) ;
1381 { constant functions may also be defined }
1382 cfunc(x) : 10*x / sqrt(x) ;
1383 .DE
1384 Many variables and functions are already defined by the program,
1385 and they are listed in the file
1386 .I rayinit.cal.
1387 The following variables are particularly important:
1388 .DS
1389 Dx, Dy, Dz - incident ray direction
1390 Nx, Ny, Nz - surface normal at intersection point
1391 Px, Py, Pz - intersection point
1392 T - distance from start
1393 Ts - single ray (shadow) distance
1394 Rdot - cosine between ray and normal
1395 arg(0) - number of real arguments
1396 arg(i) - i'th real argument
1397 .DE
1398 For mesh objects, the local surface coordinates are available:
1399 .DS
1400 Lu, Lv - local (u,v) coordinates
1401 .DE
1402 For BRDF types, the following variables are defined as well:
1403 .DS
1404 NxP, NyP, NzP - perturbed surface normal
1405 RdotP - perturbed dot product
1406 CrP, CgP, CbP - perturbed material color
1407 .DE
1408 A unique context is set up for each file so that the same variable
1409 may appear in different function files without conflict.
1410 The variables listed above and any others defined in
1411 rayinit.cal are available globally.
1412 If no file is needed by a given primitive because all the required
1413 variables are global, a period (`.') can be given in
1414 place of the file name.
1415 It is also possible to give an expression instead of a straight
1416 variable name in a scene file.
1417 Functions (requiring parameters)
1418 must be given as names and not as expressions.
1419 .PP
1420 Constant expressions are used as an optimization in function
1421 files.
1422 They are replaced wherever they occur in an expression by their
1423 value.
1424 Constant expressions are evaluated only once, so they must not
1425 contain any variables or values that can change, such as the ray
1426 variables Px and Ny or the primitive argument function arg().
1427 All the math library functions such as sqrt() and cos() have the
1428 constant attribute, so they will be replaced by immediate values
1429 whenever they are given constant arguments.
1430 Thus, the subexpression cos(PI*sqrt(2)) is immediately replaced
1431 by its value, -.266255342, and does not cause any additional overhead
1432 in the calculation.
1433 .PP
1434 It is generally a good idea to define constants and variables before
1435 they are referred to in a function file.
1436 Although evaluation does not take place until later, the interpreter
1437 does variable scoping and constant subexpression evaluation based on
1438 what it has compiled already.
1439 For example, a variable that is defined globally in rayinit.cal then
1440 referenced in the local context of a function file cannot
1441 subsequently be redefined in the same file because the compiler
1442 has already determined the scope of the referenced variable as global.
1443 To avoid such conflicts, one can state the scope of a variable explicitly
1444 by preceding the variable name with a context mark (a back-quote) for
1445 a local variable, or following the name with a context mark for a global
1446 variable.
1447 .NH 3
1448 Data Files
1449 .PP
1450 Data files contain n-dimensional arrays of real numbers used
1451 for interpolation.
1452 Typically, definitions in a function file determine how
1453 to index and use interpolated data values.
1454 The basic data file format is as follows:
1455 .DS
1456 N
1457 beg1 end1 m1
1458 0 0 m2 x2.1 x2.2 x2.3 x2.4 .. x2.m2
1459 ...
1460 begN endN mN
1461 DATA, later dimensions changing faster.
1462 .DE
1463 N is the number of dimensions.
1464 For each dimension, the beginning and ending coordinate
1465 values and the dimension size is given.
1466 Alternatively, individual coordinate values can be given when
1467 the points are not evenly spaced.
1468 These values must either be increasing or decreasing monotonically.
1469 The data is m1*m2*...*mN real numbers in ASCII form.
1470 Comments may appear anywhere in the file, beginning with a pound
1471 sign ('#') and continuing to the end of line.
1472 .NH 3
1473 Font Files
1474 .PP
1475 A font file lists the polygons which make up a character set.
1476 Comments may appear anywhere in the file, beginning with a pound
1477 sign ('#') and continuing to the end of line.
1478 All numbers are decimal integers:
1479 .DS
1480 code n
1481 x0 y0
1482 x1 y1
1483 ...
1484 xn yn
1485 ...
1486 .DE
1487 The ASCII codes can appear in any order.
1488 N is the number of vertices, and the last is automatically
1489 connected to the first.
1490 Separate polygonal sections are joined by coincident sides.
1491 The character coordinate system is a square with lower left corner at
1492 (0,0), lower right at (255,0) and upper right at (255,255).
1493 .NH 2
1494 Generators
1495 .PP
1496 A generator is any program that produces a scene description
1497 as its output.
1498 They usually appear as commands in a scene description file.
1499 An example of a simple generator is
1500 .I genbox.
1501 .I Genbox
1502 takes the arguments of width, height and depth to produce
1503 a parallelepiped description.
1504 .I Genprism
1505 takes a list of 2-dimensional coordinates and extrudes them along a vector to
1506 produce a 3-dimensional prism.
1507 .I Genrev
1508 is a more sophisticated generator
1509 that produces an object of rotation from parametric functions
1510 for radius and axis position.
1511 .I Gensurf
1512 tessellates a surface defined by the
1513 parametric functions x(s,t), y(s,t), and z(s,t).
1514 .I Genworm
1515 links cylinders and spheres along a curve.
1516 .I Gensky
1517 produces a sun and sky distribution corresponding
1518 to a given time and date.
1519 .PP
1520 .I Xform
1521 is a program that transforms a scene description from one
1522 coordinate space to another.
1523 .I Xform
1524 does rotation, translation, scaling, and mirroring.
1525 .NH 1
1526 Image Generation
1527 .PP
1528 Once the scene has been described in three-dimensions, it
1529 is possible to generate a two-dimensional image from a
1530 given perspective.
1531 .PP
1532 The image generating programs use an
1533 .I octree
1534 to efficiently trace rays through the scene.
1535 An octree subdivides space into nested octants which
1536 contain sets of surfaces.
1537 In RADIANCE, an octree is created from a scene description by
1538 .I oconv.
1539 The details of this process are not important,
1540 but the octree will serve as input to the ray-tracing
1541 programs and directs the use of a scene description.
1542 .PP
1543 .I Rview
1544 is ray-tracing program for viewing a scene interactively.
1545 When the user specifies a new perspective,
1546 .I rview
1547 quickly displays a rough
1548 image on the terminal, then progressively
1549 increases the resolution as the user looks on.
1550 He can select a particular section of the image to improve,
1551 or move to a different view and start over.
1552 This mode of interaction is useful for debugging scenes
1553 as well as determining the best view for a final image.
1554 .PP
1555 .I Rpict
1556 produces a high-resolution picture of a scene from
1557 a particular perspective.
1558 This program features adaptive sampling, crash
1559 recovery and progress reporting, all of which are important
1560 for time-consuming images.
1561 .PP
1562 A number of filters are available for manipulating picture files.
1563 .I Pfilt
1564 sets the exposure and performs anti-aliasing.
1565 .I Pcompos
1566 composites (cuts and pastes) pictures.
1567 .I Pcond
1568 conditions a picture for a specific display device.
1569 .I Pcomb
1570 performs arbitrary math on one or more pictures.
1571 .I Protate
1572 rotates a picture 90 degrees clockwise.
1573 .I Pflip
1574 flips a picture horizontally, vertically, or both (180 degree rotation).
1575 .I Pvalue
1576 converts a picture to and from simpler formats.
1577 .PP
1578 Pictures may be displayed directly under X11 using the program
1579 .I ximage,
1580 or converted a standard image format.
1581 .I Ra_bmp
1582 converts to and from Microsoft Bitmap images.
1583 .I Ra_ppm
1584 converts to and from Poskanzer Portable Pixmap formats.
1585 .I Ra_ps
1586 converts to PostScript color and greyscale formats.
1587 .I Ra_rgbe
1588 converts to and from Radiance uncompressed picture format.
1589 .I Ra_t16
1590 converts to and from Targa 16 and 24-bit image formats.
1591 .I Ra_t8
1592 converts to and from Targa 8-bit image format.
1593 .I Ra_tiff
1594 converts to and from TIFF.
1595 .I Ra_xyze
1596 converts to and from Radiance CIE picture format.
1597 .NH 1
1598 License
1599 .PP
1600 .DS
1601 The Radiance Software License, Version 1.0
1602
1603 Copyright (c) 1990 - 2008 The Regents of the University of California,
1604 through Lawrence Berkeley National Laboratory. All rights reserved.
1605
1606 Redistribution and use in source and binary forms, with or without
1607 modification, are permitted provided that the following conditions
1608 are met:
1609
1610 1. Redistributions of source code must retain the above copyright
1611 notice, this list of conditions and the following disclaimer.
1612
1613 2. Redistributions in binary form must reproduce the above copyright
1614 notice, this list of conditions and the following disclaimer in
1615 the documentation and/or other materials provided with the
1616 distribution.
1617
1618 3. The end-user documentation included with the redistribution,
1619 if any, must include the following acknowledgment:
1620 "This product includes Radiance software
1621 (http://radsite.lbl.gov/)
1622 developed by the Lawrence Berkeley National Laboratory
1623 (http://www.lbl.gov/)."
1624 Alternately, this acknowledgment may appear in the software itself,
1625 if and wherever such third-party acknowledgments normally appear.
1626
1627 4. The names "Radiance," "Lawrence Berkeley National Laboratory"
1628 and "The Regents of the University of California" must
1629 not be used to endorse or promote products derived from this
1630 software without prior written permission. For written
1631 permission, please contact [email protected].
1632
1633 5. Products derived from this software may not be called "Radiance",
1634 nor may "Radiance" appear in their name, without prior written
1635 permission of Lawrence Berkeley National Laboratory.
1636
1637 THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
1638 WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
1639 OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
1640 DISCLAIMED. IN NO EVENT SHALL Lawrence Berkeley National Laboratory OR
1641 ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
1642 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
1643 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
1644 USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
1645 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
1646 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
1647 OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
1648 SUCH DAMAGE.
1649 .DE
1650 .NH 1
1651 Acknowledgements
1652 .PP
1653 This work was supported by the Assistant Secretary of Conservation
1654 and Renewable Energy, Office of Building Energy Research and
1655 Development, Buildings Equipment Division of the U.S. Department of
1656 Energy under Contract No. DE-AC03-76SF00098.
1657 .PP
1658 Additional work was sponsored by the Swiss federal government
1659 under the Swiss LUMEN Project and was
1660 carried out in the Laboratoire d'Energie Solaire (LESO Group) at
1661 the Ecole Polytechnique Federale de Lausanne (EPFL University)
1662 in Lausanne, Switzerland.
1663 .NH 1
1664 References
1665 .LP
1666 Ward, Gregory J., Bruno Bueno, David Geisler-Moroder,
1667 Lars O. Grobe, Jacob C. Jonsson, Eleanor
1668 S. Lee, Taoning Wang, Helen Rose Wilson,
1669 ``Daylight Simulation Workflows Incorporating
1670 Measured Bidirectional Scattering Distribution Functions,''
1671 .I "Energy & Buildings",
1672 Vol. 259, No. 111890, 2022.
1673 .LP
1674 Wang, Taoning, Gregory Ward, Eleanor Lee,
1675 ``Efficient modeling of optically-complex, non-coplanar
1676 exterior shading: Validation of matrix algebraic methods,''
1677 .I "Energy & Buildings",
1678 vol. 174, pp. 464-83, Sept. 2018.
1679 .LP
1680 Lee, Eleanor S., David Geisler-Moroder, Gregory Ward,
1681 ``Modeling the direct sun component in buildings using matrix
1682 algebraic approaches: Methods and validation,''
1683 .I Solar Energy,
1684 vol. 160, 15 January 2018, pp 380-395.
1685 .LP
1686 Ward, G., M. Kurt & N. Bonneel,
1687 ``Reducing Anisotropic BSDF Measurement to Common Practice,''
1688 .I Workshop on Material Appearance Modeling,
1689 2014.
1690 .LP
1691 McNeil, A., C.J. Jonsson, D. Appelfeld, G. Ward, E.S. Lee,
1692 ``A validation of a ray-tracing tool used to generate
1693 bi-directional scattering distribution functions for
1694 complex fenestration systems,''
1695 .I "Solar Energy",
1696 98, 404-14, November 2013.
1697 .LP
1698 Ward, G., R. Mistrick, E.S. Lee, A. McNeil, J. Jonsson,
1699 ``Simulating the Daylight Performance of Complex Fenestration Systems
1700 Using Bidirectional Scattering Distribution Functions within Radiance,''
1701 .I "Leukos",
1702 7(4),
1703 April 2011.
1704 .LP
1705 Cater, K., A. Chalmers, G. Ward,
1706 ``Detail to Attention: Exploiting Visual Tasks for Selective Rendering,''
1707 .I "Eurograhics Symposium on Rendering",
1708 June 2003.
1709 .LP
1710 Ward, G., Elena Eydelberg-Vileshin,
1711 ``Picture Perfect RGB Rendering Using Spectral Prefiltering and
1712 Sharp Color Primaries,''
1713 13th Eurographics Workshop on Rendering, P. Debevec and
1714 S. Gibson (Editors), June 2002.
1715 .LP
1716 Ward, G. and M. Simmons,
1717 ``The Holodeck Ray Cache: An Interactive Rendering System for Global
1718 Illumination in Nondiffuse Environments,''
1719 .I "ACM Transactions on Graphics,"
1720 18(4):361-98, October 1999.
1721 .LP
1722 Larson, G.W., H. Rushmeier, C. Piatko,
1723 ``A Visibility Matching Tone Reproduction Operator for High Dynamic
1724 Range Scenes,''
1725 .I "IEEE Transactions on Visualization and Computer Graphics",
1726 3(4), 291-306, December 1997.
1727 .LP
1728 Ward, G.,
1729 ``Making Global Illumination User Friendly,''
1730 .I "Sixth Eurographics Workshop on Rendering",
1731 proceedings to be published by Springer-Verlag,
1732 Dublin, Ireland, June 1995.
1733 .LP
1734 Rushmeier, H., G. Ward, C. Piatko, P. Sanders, B. Rust,
1735 ``Comparing Real and Synthetic Images: Some Ideas about Metrics,''
1736 .I "Sixth Eurographics Workshop on Rendering",
1737 proceedings to be published by Springer-Verlag,
1738 Dublin, Ireland, June 1995.
1739 .LP
1740 Ward, G.,
1741 ``The Radiance Lighting Simulation and Rendering System,''
1742 .I "Computer Graphics",
1743 Orlando, July 1994.
1744 .LP
1745 Rushmeier, H., G. Ward,
1746 ``Energy-Preserving Non-Linear Filters,''
1747 .I "Computer Graphics",
1748 Orlando, July 1994.
1749 .LP
1750 Ward, G.,
1751 ``A Contrast-Based Scalefactor for Luminance Display,''
1752 .I "Graphics Gems IV",
1753 Edited by Paul Heckbert,
1754 Academic Press 1994.
1755 .LP
1756 Ward, G.,
1757 ``Measuring and Modeling Anisotropic Reflection,''
1758 .I "Computer Graphics",
1759 Chicago, July 1992.
1760 .LP
1761 Ward, G., P. Heckbert,
1762 ``Irradiance Gradients,''
1763 .I "Third Annual Eurographics Workshop on Rendering",
1764 to be published by Springer-Verlag, held in Bristol, UK, May 1992.
1765 .LP
1766 Ward, G.,
1767 ``Adaptive Shadow Testing for Ray Tracing,''
1768 .I "Second Annual Eurographics Workshop on Rendering",
1769 to be published by Springer-Verlag, held in Barcelona, SPAIN, May 1991.
1770 .LP
1771 Ward, G.,
1772 ``Visualization,''
1773 .I "Lighting Design and Application",
1774 Vol. 20, No. 6, June 1990.
1775 .LP
1776 Ward, G., F. Rubinstein, R. Clear,
1777 ``A Ray Tracing Solution for Diffuse Interreflection,''
1778 .I "Computer Graphics",
1779 Vol. 22, No. 4, August 1988.
1780 .LP
1781 Ward, G., F. Rubinstein,
1782 ``A New Technique for Computer Simulation of Illuminated Spaces,''
1783 .I "Journal of the Illuminating Engineering Society",
1784 Vol. 17, No. 1, Winter 1988.