--- ray/doc/ray.1 2007/06/01 19:46:07 1.12 +++ ray/doc/ray.1 2023/11/16 21:57:39 1.42 @@ -1,8 +1,8 @@ -.\" RCSid "$Id" +.\" RCSid "$Id: ray.1,v 1.42 2023/11/16 21:57:39 greg Exp $" .\" Print using the -ms macro package -.DA 10/17/2006 +.DA 11/13/2023 .LP -.tl """Copyright \(co 2006 Regents, University of California +.tl """Copyright \(co 2023 Regents, University of California .sp 2 .TL The @@ -491,7 +491,7 @@ a perfectly scattering medium (no absorption). The scattering eccentricity parameter will likewise override the global setting if it is present. Scattering eccentricity indicates how much scattered light favors the -forward direction, as fit by the Heyney-Greenstein function: +forward direction, as fit by the Henyey-Greenstein function: .DS P(theta) = (1 - g*g) / (1 + g*g - 2*g*cos(theta))^1.5 .DE @@ -622,6 +622,23 @@ 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 Dielectric .PP A dielectric material is transparent, and it refracts light @@ -865,6 +882,97 @@ mod transdata id 6+ red green blue rspec trans tspec A7 .. .DE .LP +.UL BSDF +.PP +The BSDF material type loads an XML (eXtensible Markup Language) +file describing a bidirectional scattering distribution function. +Real arguments to this material may define additional +diffuse components that augment the BSDF data. +String arguments are used to define thickness for proxied +surfaces and the "up" orientation for the material. +.DS +mod BSDF id +6+ thick BSDFfile ux uy uz funcfile transform +0 +0|3|6|9 + rfdif gfdif bfdif + rbdif gbdif bbdif + rtdif gtdif btdif +.DE +The first string argument is a "thickness" parameter that may be used +to hide detail geometry being proxied by an aggregate BSDF material. +If a view or shadow ray hits a BSDF proxy with non-zero thickness, +it will pass directly through as if the surface were not there. +Similar to the illum type, this permits direct viewing and +shadow testing of complex geometry. +The BSDF is used when a scattered (indirect) ray hits the surface, +and any transmitted sample rays will be offset by the thickness amount +to avoid the hidden geometry and gather samples from the other side. +In this manner, BSDF surfaces can improve the results for indirect +scattering from complex systems without sacrificing appearance or +shadow accuracy. +If the BSDF has transmission and back-side reflection data, +a parallel BSDF surface may be +placed slightly less than the given thickness away from the front surface +to enclose the complex geometry on both sides. +The sign of the thickness is important, as it indicates whether the +proxied geometry is behind the BSDF surface (when thickness is positive) +or in front (when thickness is negative). +.LP +The second string argument is the name of the BSDF file, which is +found in the usual auxiliary locations. +The following three string parameters name variables for an "up" vector, +which together with the surface normal, define the +local coordinate system that orients the BSDF. +These variables, along with the thickness, are defined in a function +file given as the next string argument. +An optional transform is used to scale the thickness and reorient the up vector. +.LP +If no real arguments are given, the BSDF is used by itself to determine +reflection and transmission. +If there are at least 3 real arguments, the first triplet is an +additional diffuse reflectance for the front side. +At least 6 real arguments adds diffuse reflectance to the rear side of the surface. +If there are 9 real arguments, the final triplet will be taken as an additional +diffuse transmittance. +All diffuse components as well as the non-diffuse transmission are +modified by patterns applied to this material. +The non-diffuse reflection from either side are unaffected. +Textures perturb the effective surface normal in the usual way. +.LP +The surface normal of this type is not altered to face the incoming ray, +so the front and back BSDF reflections may differ. +(Transmission is identical front-to-back by physical law.)\0 +If back visibility is turned off during rendering and there is no +transmission or back-side reflection, only then the surface will be +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. @@ -879,8 +987,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 @@ -1084,10 +1194,78 @@ 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 limits of the covered +spectral range in nanometers. +Subsequent real values correspond to multipliers in each wavelength band, +where the first band goes from nmA to nmA+(nmB-nmA)/N, and N is the +number of bands (i.e., the number of real arguments minus 2). +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+ sval 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 +accessible to the sval function. +This function is fed a wavelenth sample +between nmA and nmB as its only argument, +and it returns the corresponding spectral intensity. .NH 3 Mixtures .PP A mixture is a blend of one or more materials or textures and patterns. +Blended materials should not be light source types or virtual source types. The basic types are given below. .LP .UL Mixfunc @@ -1235,9 +1413,8 @@ If no file is needed by a given primitive because all variables are global, a period (`.') can be given in place of the file name. It is also possible to give an expression instead of a straight -variable name in a scene file, although such expressions should -be kept simple if possible. -Also, functions (requiring parameters) +variable name in a scene file. +Functions (requiring parameters) must be given as names and not as expressions. .PP Constant expressions are used as an optimization in function @@ -1401,16 +1578,10 @@ converts a picture to and from simpler formats. Pictures may be displayed directly under X11 using the program .I ximage, or converted a standard image format. -.I Ra_avs -converts to and from AVS image format. -.I Ra_pict -converts to Macintosh 32-bit PICT2 format. +.I Ra_bmp +converts to and from Microsoft Bitmap images. .I Ra_ppm converts to and from Poskanzer Portable Pixmap formats. -.I Ra_pr -converts to and from Sun 8-bit rasterfile format. -.I Ra_pr24 -converts to and from Sun 24-bit rasterfile format. .I Ra_ps converts to PostScript color and greyscale formats. .I Ra_rgbe @@ -1429,7 +1600,7 @@ License .DS The Radiance Software License, Version 1.0 -Copyright (c) 1990 - 2002 The Regents of the University of California, +Copyright (c) 1990 - 2008 The Regents of the University of California, through Lawrence Berkeley National Laboratory. All rights reserved. Redistribution and use in source and binary forms, with or without @@ -1491,6 +1662,45 @@ 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,'' +.I Workshop on Material Appearance Modeling, +2014. +.LP +McNeil, A., C.J. Jonsson, D. Appelfeld, G. Ward, E.S. Lee, +``A validation of a ray-tracing tool used to generate +bi-directional scattering distribution functions for +complex fenestration systems,'' +.I "Solar Energy", +98, 404-14, November 2013. +.LP +Ward, G., R. Mistrick, E.S. Lee, A. McNeil, J. Jonsson, +``Simulating the Daylight Performance of Complex Fenestration Systems +Using Bidirectional Scattering Distribution Functions within Radiance,'' +.I "Leukos", +7(4), +April 2011. .LP Cater, K., A. Chalmers, G. Ward, ``Detail to Attention: Exploiting Visual Tasks for Selective Rendering,''