--- ray/doc/ray.1 2017/12/24 22:01:00 1.33 +++ ray/doc/ray.1 2025/05/30 16:35:52 1.49 @@ -1,8 +1,8 @@ -.\" RCSid "$Id: ray.1,v 1.33 2017/12/24 22:01:00 greg Exp $" +.\" RCSid "$Id: ray.1,v 1.49 2025/05/30 16:35:52 greg Exp $" .\" Print using the -ms macro package -.DA 07/10/2016 +.DA 12/09/2024 .LP -.tl """Copyright \(co 2017 Regents, University of California +.tl """Copyright \(co 2024 Regents, University of California .sp 2 .TL The @@ -422,6 +422,25 @@ mod mirror id 0 3 red green blue .DE +While alternate materials that are reflective will appear as normal, +indirect rays will use the mirror's reflectance rather than the +alternate type. +Transmitting materials are an exception, where both transmission and +reflection will use the alternate type for all rays not specifically +targeting virtual light sources. +In this case, it is important that any reflections be purely specular +(mirror-like) and equal to the mirror's reflectivity +to maintain a valid result. +A pure diffuse reflection may be added if desired. +.PP +The mirror material type reflects light sources only from the front side +of a surface, regardless of any alternate material. +If virtual source generation is desired on both sides, two coincident +surfaces with opposite normal orientations may be employed to achieve +this effect. +The reflectance and alternate material type may be +different for the overlapped surfaces, +and the two sides will behave accordingly. .LP .UL Prism1 .PP @@ -630,6 +649,8 @@ arguments have additional flexibility to specify the s Also, rather than roughness, specular power is used, which has no physical meaning other than larger numbers are equivalent to a smoother surface. +Unlike other material types, total reflectance is the sum of +diffuse and specular colors, and should be adjusted accordingly. .DS mod ashik2 id 4+ ux uy uz funcfile transform @@ -637,6 +658,64 @@ mod ashik2 id 8 dred dgrn dblu sred sgrn sblu u-power v-power .DE .LP +.UL WGMDfunc +.PP +WGMDfunc is a more programmable version of trans2, +with separate modifier paths and variables to control each component. +(WGMD stands for Ward-Geisler-Moroder-Duer, which is the basis for +this empirical model, similar to the previous ones beside Ashik2.)\0 +The specification of this material is given below. +.DS +mod WGMDfunc id +13+ rs_mod rs rs_urough rs_vrough + ts_mod ts ts_urough ts_vrough + td_mod + ux uy uz funcfile transform +0 +9+ rfdif gfdif bfdif + rbdif gbdif bbdif + rtdif gtdif btdif + A10 .. +.DE +The sum of specular reflectance ( +.I rs +), specular transmittance ( +.I ts +), diffuse reflectance ( +.I "rfdif gfdif bfdif" +for front and +.I "rbdif gbdif bbdif" +for back) +and diffuse transmittance ( +.I "rtdif gtdif btdif" +) should be less than 1 for each +channel. +.PP +Unique to this material, separate modifier channels are +provided for each component. +The main modifier is used on the diffuse reflectance, both +front and back. +The +.I rs_mod +modifier is used for specular reflectance. +If "void" is given for +.I rs_mod, +then the specular reflection color will be white. +The special "inherit" keyword may also be given, in which case +specular reflectance will share the main modifier. +This behavior is replicated for the specular transmittance modifier +.I ts_mod, +which has its own independent roughness expressions. +Finally, the diffuse transmittance modifier is given as +.I td_mod, +which may also be "void" or "inherit". +Note that any spectra or color for specular components must be +carried by the named modifier(s). +.PP +The main advantage to this material over BRTDfunc and +other programmable types described below is that the specular sampling is +well-defined, so that all components are fully computed. +.LP .UL Dielectric .PP A dielectric material is transparent, and it refracts light @@ -947,6 +1026,30 @@ invisible from behind. Unlike other data-driven material types, the BSDF type is fully supported and all parts of the distribution are properly sampled. .LP +.UL aBSDF +.PP +The aBSDF material is identical to the BSDF type with two important +differences. +First, proxy geometry is not supported, so there is no thickness parameter. +Second, an aBSDF is assumed to have some specular through component +(the 'a' stands for "aperture"), which +is treated specially during the direct calculation and when viewing the +material. +Based on the BSDF data, the coefficient of specular transmission is +determined and used for modifying unscattered shadow and view rays. +.DS +mod aBSDF id +5+ BSDFfile ux uy uz funcfile transform +0 +0|3|6|9 + rfdif gfdif bfdif + rbdif gbdif bbdif + rtdif gtdif btdif +.DE +.LP +If a material has no specular transmitted component, it is much better +to use the BSDF type with a zero thickness than to use aBSDF. +.LP .UL Antimatter .PP Antimatter is a material that can "subtract" volumes from other volumes. @@ -1168,6 +1271,112 @@ A section of text meant to depict a picture, perhaps u font such as hexbit4x1.fnt, calls for uniform spacing. Reasonable magnitudes for proportional spacing are between 0.1 (for tightly spaced characters) and 0.3 (for wide spacing). +.LP +.UL Spectrum +.PP +The spectrum primitive is the most basic type for introducing spectral +color to a material. +Since materials only provide RGB parameters, spectral patterns +are the only way to superimpose wavelength-dependent behavior. +.DS +mod spectrum id +0 +0 +5+ nmA nmB s1 s2 .. sN +.DE +The first two real arguments indicate the extrema of the +spectral range in nanometers. +Subsequent real values correspond to multipliers at each wavelength. +The nmA wavelength may be greater or less than nmB, +but they may not be equal, and their ordering matches +the order of the spectral values. +A minimum of 3 values must be given, which would act +more or less the same as a constant RGB multiplier. +As with RGB values, spectral quantities normally range between 0 +and 1 at each wavelength, or average to 1.0 against a standard +sensitivity functions such as V(lambda). +The best results obtain when the spectral range and number +of samples match rendering options, though resampling will handle +any differences, zero-filling wavelenths outside the nmA to nmB +range. +A warning will be issued if the given wavelength range does not +adequately cover the visible spectrum. +.LP +.UL Specfile +.PP +The specfile primitive is equivalent to the spectrum type, but +the wavelength range and values are contained in a 1-dimensional +data file. +This may be a more convenient way to specify a spectral color, +especially one corresponding to a standard illuminant such as D65 +or a library of measured spectra. +.DS +mod specfile id +1 datafile +0 +0 +.DE +As with the spectrum type, rendering wavelengths outside the defined +range will be zero-filled. +Unlike the spectrum type, the file may contain non-uniform samples. +.LP +.UL Specfunc +.PP +The specfunc primitive offers dynamic control over a spectral +pattern, similar to the colorfunc type. +.DS +mod specfunc id +2+ sfunc funcfile transform +0 +2+ nmA nmB A3 .. +.DE +Like the spectrum primitive, the wavelength range is specified +in the first two real arguments, and additional real values are +set in the evaluation context. +This function is fed a wavelenth sample +between nmA and nmB as its only argument, +and it returns the corresponding spectral intensity. +.LP +.UL Specdata +.PP +Specdata is like brightdata and colordata, but with more +than 3 specular samples. +.DS +mod specdata id +3+n+ + func datafile + funcfile x1 x2 .. xn transform +0 +m A1 A2 .. Am +.DE +The data file must have one more dimension than the coordinate +variable count, as this final dimension corresponds to the covered +spectrum. +The starting and ending wavelengths are specified in "datafile" +as well as the number of spectral samples. +The function "func" will be called with two parameters, the +interpolated spectral value for the current coordinate and the +associated wavelength. +If the spectrum is broken into 12 components, then 12 calls +will be made to "func" for the relevant ray evaluation. +.LP +.UL Specpict +.PP +Specpict is a special case of specdata, where the pattern is +a hyperspectral image stored in the common-exponent file format. +The dimensions of the image data are determined by the picture +just as with the colorpict primitive. +.DS +mod specpict id +5+ + func specfile + funcfile u v transform +0 +m A1 A2 .. Am +.DE +The function "func" is called with the interpolated pixel value +and the wavelength sample in nanometers, the same as specdata, +with as many calls made as there are components in "specfile". .NH 3 Mixtures .PP @@ -1569,6 +1778,20 @@ the Ecole Polytechnique Federale de Lausanne (EPFL Uni in Lausanne, Switzerland. .NH 1 References +.LP +Ward, Gregory J., Bruno Bueno, David Geisler-Moroder, +Lars O. Grobe, Jacob C. Jonsson, Eleanor +S. Lee, Taoning Wang, Helen Rose Wilson, +``Daylight Simulation Workflows Incorporating +Measured Bidirectional Scattering Distribution Functions,'' +.I "Energy & Buildings", +Vol. 259, No. 111890, 2022. +.LP +Wang, Taoning, Gregory Ward, Eleanor Lee, +``Efficient modeling of optically-complex, non-coplanar +exterior shading: Validation of matrix algebraic methods,'' +.I "Energy & Buildings", +vol. 174, pp. 464-83, Sept. 2018. .LP Lee, Eleanor S., David Geisler-Moroder, Gregory Ward, ``Modeling the direct sun component in buildings using matrix