[ViewVC] Diff of: Development/ray/doc/ray.1

Comparing ray/doc/ray.1 (file contents):
Revision 1.38 by greg, Mon Aug 31 21:54:55 2020 UTC vs.
Revision 1.51 by greg, Thu Aug 14 18:16:17 2025 UTC

+.\" RCSid "$Id$"
+.\" Print using the -ms macro package
-<
+.DA 8/31/2020
->
+.DA 07/22/2025
+.LP
-<
+.tl """Copyright \(co 2020 Regents, University of California
->
+.tl """Copyright \(co 2025 Regents, University of California
+.sp 2
+.TL
+The
+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
+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
++ ux uy uz funcfile transform
+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
-+
++ rs_mod  rs  rs_urough rs_vrough
-+
+    ts_mod  ts  ts_urough ts_vrough
-+
+    td_mod
-+
+    ux uy uz  funcfile  transform
-+
-+
++  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
+.I zdfname.
+.DS
+mod texdata id
-<
++ xfunc yfunc zfunc xdfname ydfname zdfname vfname x0 x1 .. xf
->
++ xfunc yfunc zfunc xdfname ydfname zdfname funcfile x0 x1 .. xf
+n A1 A2 .. An
+.DE
+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
-+
-+
-+
++ 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
-+
+datafile
-+
-+
-+
+.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
-+
++ sfunc funcfile transform
-+
-+
++ 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
-+
++n+
-+
+        func datafile
-+
+        funcfile x1 x2 .. xn transform
-+
-+
+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
 +
-+
+        func specfile
-+
+        funcfile u v transform
-+
-+
+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
+sign ('#') and continuing to the end of line.
+All numbers are decimal integers:
+.DS
-<
+code n
-<
+        x0 y0
->
+code N
+        x1 y1
-+
+        x2 y2
+         ...
+        xn yn
+ ...
+License
+.PP
+.DS
-<
+The Radiance Software License, Version 1.0
->
+The Radiance Software License, Version 2.0
-<
+Copyright (c) 1990 - 2008 The Regents of the University of California,
-<
+through Lawrence Berkeley National Laboratory.   All rights reserved.
->
+Radiance v6.0 Copyright (c) 1990 to 2025, The Regents of the University of
->
+California, through Lawrence Berkeley National Laboratory (subject to receipt
->
+of any required approvals from the U.S. Dept. of Energy).  All rights reserved.
+Redistribution and use in source and binary forms, with or without
-<
+modification, are permitted provided that the following conditions
-<
+are met:
->
+modification, are permitted provided that the following conditions are met:
-<
+. Redistributions of source code must retain the above copyright
-<
+        notice, this list of conditions and the following disclaimer.
->
+(1) Redistributions of source code must retain the above copyright notice,
->
+this list of conditions and the following disclaimer.
-<
+. Redistributions in binary form must reproduce the above copyright
-<
+      notice, this list of conditions and the following disclaimer in
-<
+      the documentation and/or other materials provided with the
-<
+      distribution.
->
+(2) Redistributions in binary form must reproduce the above copyright
->
+notice, this list of conditions and the following disclaimer in the
->
+documentation and/or other materials provided with the distribution.
-<
+. The end-user documentation included with the redistribution,
-<
+          if any, must include the following acknowledgment:
-<
+            "This product includes Radiance software
-<
+                (http://radsite.lbl.gov/)
-<
+                developed by the Lawrence Berkeley National Laboratory
-<
+              (http://www.lbl.gov/)."
-<
+      Alternately, this acknowledgment may appear in the software itself,
-<
+      if and wherever such third-party acknowledgments normally appear.
->
+(3) Neither the name of the University of California, Lawrence Berkeley
->
+National Laboratory, U.S. Dept. of Energy nor the names of its contributors
->
+may be used to endorse or promote products derived from this software
->
+without specific prior written permission.
-<
+. The names "Radiance," "Lawrence Berkeley National Laboratory"
-<
+      and "The Regents of the University of California" must
-<
+      not be used to endorse or promote products derived from this
-<
+      software without prior written permission. For written
-<
+      permission, please contact [email protected].
->
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
->
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
->
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
->
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
->
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
->
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
->
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
->
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
->
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
->
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
->
+POSSIBILITY OF SUCH DAMAGE.
-<
+. Products derived from this software may not be called "Radiance",
-<
+      nor may "Radiance" appear in their name, without prior written
-<
+      permission of Lawrence Berkeley National Laboratory.
-<
-<
+THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
-<
+WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
-<
+OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-<
+DISCLAIMED.   IN NO EVENT SHALL Lawrence Berkeley National Laboratory OR
-<
+ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-<
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-<
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
-<
+USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
-<
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-<
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
-<
+OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
-<
+SUCH DAMAGE.
->
+You are under no obligation whatsoever to provide any bug fixes, patches,
->
+or upgrades to the features, functionality or performance of the source
->
+code ("Enhancements") to anyone; however, if you choose to make your
->
+Enhancements available either publicly, or directly to Lawrence Berkeley
->
+National Laboratory, without imposing a separate written license agreement
->
+for such Enhancements, then you hereby grant the following license: a
->
+non-exclusive, royalty-free perpetual license to install, use, modify,
->
+prepare derivative works, incorporate into other computer software,
->
+distribute, and sublicense such enhancements or derivative works thereof,
->
+in binary and source code form.
+.DE
+.NH 1
+Acknowledgements
+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

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines (old)
->
+Changed lines (new)

Comparing ray/doc/ray.1 (file contents): Revision 1.38 by greg, Mon Aug 31 21:54:55 2020 UTC vs. Revision 1.51 by greg, Thu Aug 14 18:16:17 2025 UTC

Diff Legend

Comparing ray/doc/ray.1 (file contents):
Revision 1.38 by greg, Mon Aug 31 21:54:55 2020 UTC vs.
Revision 1.51 by greg, Thu Aug 14 18:16:17 2025 UTC