ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/radiance/ray/doc/ray.1
(Generate patch)

Comparing ray/doc/ray.1 (file contents):
Revision 1.5 by greg, Thu Jan 1 19:31:44 2004 UTC vs.
Revision 1.41 by greg, Wed Nov 15 18:28:09 2023 UTC

# Line 1 | Line 1
1 < .\" RCSid "$Id"
1 > .\" RCSid "$Id$"
2   .\" Print using the -ms macro package
3 < .DA 1/20/99
3 > .DA 11/13/2023
4   .LP
5 < .tl """Copyright \(co 2003 Regents, University of California
5 > .tl """Copyright \(co 2023 Regents, University of California
6   .sp 2
7   .TL
8   The
# Line 402 | Line 402 | mod spotlight id
402   .LP
403   .UL Mirror
404   .PP
405 < Mirror is used for planar surfaces that produce secondary
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.
# Line 426 | Line 426 | mod mirror id
426   .UL Prism1
427   .PP
428   The prism1 material is for general light redirection from prismatic
429 < glazings, generating secondary light sources.
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 secondary light sources.
434 > to work properly with virtual light sources.
435   The arguments give the coefficient for the redirected light
436   and its direction.
437   .DS
# Line 491 | Line 491 | 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 Heyney-Greenstein function:
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
# Line 622 | Line 622 | mod trans2 id
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
# Line 865 | Line 882 | mod transdata id
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.
# Line 879 | Line 987 | N mod1 mod2 .. modN
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 < Antimatter does not work properly with the material type "trans",
991 < and multiple antimatter surfaces should be disjoint.
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
# Line 1084 | Line 1194 | A section of text meant to depict a picture, perhaps u
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
# Line 1109 | Line 1287 | which serves as a form of opacity control when used wi
1287   Vname is the coefficient defined in funcfile that determines the influence
1288   of foreground.
1289   The background coefficient is always (1-vname).
1112 – Since the references are not resolved until runtime, the last
1113 – definitions of the modifier id's will be used.
1114 – This can result in modifier loops, which are detected by the
1115 – renderer.
1290   .LP
1291   .UL Mixdata
1292   .PP
# Line 1239 | Line 1413 | If no file is needed by a given primitive because all
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, although such expressions should
1417 < be kept simple if possible.
1244 < Also, functions (requiring parameters)
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
# Line 1370 | Line 1543 | programs and directs the use of a scene description.
1543   .I Rview
1544   is ray-tracing program for viewing a scene interactively.
1545   When the user specifies a new perspective,
1546 < .I rvu
1546 > .I rview
1547   quickly displays a rough
1548   image on the terminal, then progressively
1549   increases the resolution as the user looks on.
# Line 1405 | Line 1578 | converts a picture to and from simpler formats.
1578   Pictures may be displayed directly under X11 using the program
1579   .I ximage,
1580   or converted a standard image format.
1581 < .I Ra_avs
1582 < converts to and from AVS image format.
1410 < .I Ra_pict
1411 < converts to Macintosh 32-bit PICT2 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.
1414 – .I Ra_pr
1415 – converts to and from Sun 8-bit rasterfile format.
1416 – .I Ra_pr24
1417 – converts to and from Sun 24-bit rasterfile format.
1585   .I Ra_ps
1586   converts to PostScript color and greyscale formats.
1587   .I Ra_rgbe
# Line 1433 | Line 1600 | License
1600   .DS
1601   The Radiance Software License, Version 1.0
1602  
1603 < Copyright (c) 1990 - 2002 The Regents of the University of California,
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
# Line 1495 | Line 1662 | the Ecole Polytechnique Federale de Lausanne (EPFL Uni
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

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines