--- ray/doc/ray.1 2016/05/25 18:52:45 1.29 +++ ray/doc/ray.1 2025/05/30 16:35:52 1.49 @@ -1,8 +1,8 @@ -.\" RCSid "$Id: ray.1,v 1.29 2016/05/25 18:52:45 greg Exp $" +.\" RCSid "$Id: ray.1,v 1.49 2025/05/30 16:35:52 greg Exp $" .\" Print using the -ms macro package -.DA 09/18/2015 +.DA 12/09/2024 .LP -.tl """Copyright \(co 2015 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 @@ -622,6 +641,81 @@ mod trans2 id 8 red green blue spec urough vrough trans tspec .DE .LP +.UL Ashik2 +.PP +Ashik2 is the anisotropic reflectance model by Ashikhmin & Shirley. +The string arguments are the same as for plastic2, but the real +arguments have additional flexibility to specify the specular color. +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 +0 +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 @@ -932,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. @@ -946,8 +1064,10 @@ N mod1 mod2 .. modN The first modifier will also be used to shade the area leaving the antimatter volume and entering the regular volume. If mod1 is void, the antimatter volume is completely invisible. -Antimatter does not work properly with the material type "trans", -and multiple antimatter surfaces should be disjoint. +If shading is desired at antimatter surfaces, it is important +that the related volumes are closed with outward-facing normals. +Antimatter surfaces should not intersect with other antimatter boundaries, +and it is unwise to use the same modifier in nested antimatter volumes. The viewpoint must be outside all volumes concerned for a correct rendering. .NH 3 @@ -1151,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 @@ -1552,6 +1778,26 @@ 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 +algebraic approaches: Methods and validation,'' +.I Solar Energy, +vol. 160, 15 January 2018, pp 380-395. .LP Ward, G., M. Kurt & N. Bonneel, ``Reducing Anisotropic BSDF Measurement to Common Practice,''