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.3 by greg, Fri Mar 14 21:27:45 2003 UTC vs.
Revision 1.21 by greg, Wed Jun 22 00:13:25 2011 UTC

# Line 1 | Line 1
1   .\" RCSid "$Id"
2   .\" Print using the -ms macro package
3 < .DA 1/20/99
3 > .DA 2/17/2011
4   .LP
5 < .tl """Copyright \(co 1996 Regents, University of California
5 > .tl """Copyright \(co 2011 Regents, University of California
6   .sp 2
7   .TL
8   The
# Line 10 | Line 10 | The
10   .br
11   Synthetic Imaging System
12   .AU
13 < Greg Ward
13 > Building Technologies Department
14   .br
15   Lawrence Berkeley Laboratory
16   .br
17 < 1 Cyclotron Rd.
17 > 1 Cyclotron Rd., MS 90-3111
18   .br
19   Berkeley, CA  94720
20 – .br
21 – (510) 486-4757
20   .NH 1
21   Introduction
22   .PP
# Line 49 | Line 47 | which produces a picture from a scene description.
47   is a variation of
48   .I rpict
49   that computes and displays images interactively.
50 + Other programs (not shown) connect many of these elements together,
51 + such as the executive programs
52 + .I rad
53 + and
54 + .I ranimate,
55 + the interactive rendering program
56 + .I rholo,
57 + and the animation program
58 + .I ranimove.
59 + The program
60 + .I obj2mesh
61 + acts as both a converter and scene compiler, converting a Wavefront .OBJ
62 + file into a compiled mesh octree for efficient rendering.
63   .PP
64   A scene description file lists the surfaces and materials
65 < that make up a specific environment.
66 < The current surface types are spheres, polygons, cones,
67 < and cylinders.
68 < They can be made from materials such as plastic, metal,
69 < and glass.
70 < Light sources can be distant disks as well as local spheres, discs and
71 < polygons.
65 > that  make up a specific environment.  
66 > The current surface types are  spheres,  polygons,  cones,  and  cylinders.
67 > There is also a composite surface type, called mesh, and a pseudosurface
68 > type, called instance, which facilitates very complex geometries.
69 > Surfaces can be made from materials such as plastic, metal, and glass.  
70 > Light sources can be distant disks as well as  local spheres, disks
71 > and polygons.
72   .PP
73   From a three-dimensional scene description and a specified view,
74   .I rpict
# Line 84 | Line 95 | It is stored as ASCII text, with the following basic f
95   # comment
96  
97   modifier type identifier
98 < n S1 S2 S3 .. Sn
98 > n S1 S2 "S 3" .. Sn
99   0
100   m R1 R2 R3 .. Rm
101  
# Line 112 | Line 123 | primitives.
123   Thus, the same identifier may be used repeatedly, and each new
124   definition will apply to the primitives following it.
125   .FE
126 < An identifier can be any string (i.e. sequence of non-blank
116 < characters).
126 > An identifier can be any string (i.e., any sequence of non-white characters).
127   The
128   .I arguments
129   associated with a primitive can be strings or real numbers.
130   The first integer following the identifier is the number
131   of string arguments, and it is followed by the arguments themselves
132 < (separated by white space).
132 > (separated by white space or enclosed in quotes).
133   The next integer is the number of integer arguments, and is followed
134   by the integer arguments.
135   (There are currently no primitives that use them, however.)
# Line 142 | Line 152 | confusion will result.
152   A command may be continued over multiple lines using a backslash, `\\',
153   to escape the newline.
154   .PP
155 < Blank space is generally ignored, except as a separator.
155 > White space is generally ignored, except as a separator.
156   The exception is the newline character after a command or comment.
157   Commands, comments and primitives may appear in any combination, so long
158   as they are not intermingled.
# Line 150 | Line 160 | as they are not intermingled.
160   Primitive Types
161   .PP
162   Primitives can be surfaces, materials, textures or patterns.
163 < Modifiers can be materials, textures or patterns.
163 > Modifiers can be materials, mixtures, textures or patterns.
164   Simple surfaces must have one material in their modifier list.
165   .NH 3
166   Surfaces
# Line 223 | Line 233 | mod cone id
233   .LP
234   .UL Cup
235   .PP
236 < A cup is an inverted cone (i.e. has an inward surface normal).
236 > A cup is an inverted cone (i.e., has an inward surface normal).
237   .LP
238   .UL Cylinder
239   .PP
# Line 262 | Line 272 | mod ring id
272   A mesh is a compound surface, made up of many triangles and
273   an octree data structure to accelerate ray intersection.
274   It is typically converted from a Wavefront .OBJ file using the
275 < obj2mesh program.
275 > .I obj2mesh
276 > program.
277   .DS
278   mod mesh id
279   1+ meshfile transform
# Line 283 | Line 294 | permitting very detailed geometries that would otherwi
294   available memory.
295   In addition, the mesh primitive can have associated (u,v) coordinates
296   for pattern and texture mapping.
297 < These are made available to function files via the Lu and Lu variables.
297 > These are made available to function files via the Lu and Lv variables.
298   .LP
299   .UL Instance
300   .PP
# Line 321 | Line 332 | The basic types are given below.
332   .LP
333   .UL Light
334   .PP
335 < Light is the basic material for self-luminous surfaces (i.e. light
335 > Light is the basic material for self-luminous surfaces (i.e., light
336   sources).
337   In addition to the source surface type, spheres, discs (rings with zero
338   inner radius), cylinders (provided they are long enough), and
# Line 381 | Line 392 | Spotlight is used for self-luminous surfaces having di
392   As well as radiance, the full cone angle (in degrees)
393   and orientation (output direction) vector are given.
394   The length of the orientation vector is the distance
395 < of the effective focus behind the source center (i.e. the focal length).
395 > of the effective focus behind the source center (i.e., the focal length).
396   .DS
397   mod spotlight id
398   0
# Line 391 | 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 415 | 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.
430 < It can only be used to modify a planar surface (i.e. a polygon or disk)
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 480 | 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 569 | Line 580 | direction vector
580   These three expressions (separated by white space) are evaluated in
581   the context of the function file
582   .I funcfile.
583 < If no function file is required (i.e. no special variables or
583 > If no function file is required (i.e., no special variables or
584   functions are required), a period (`.') may be given in its
585   place.
586   (See the discussion of Function Files in the Auxiliary Files section).
# Line 854 | Line 865 | mod transdata id
865   6+ red green blue rspec trans tspec A7 ..
866   .DE
867   .LP
868 + .UL BSDF
869 + .PP
870 + The BSDF material type loads an XML (eXtensible Markup Language)
871 + file describing a bidirectional scattering distribution function.
872 + Real arguments to this material may define additional
873 + diffuse components that augment the BSDF data.
874 + String arguments are used to define thickness for proxied
875 + surfaces and the "up" orientation for the material.
876 + .DS
877 + mod BSDF id
878 + 6+ thick BSDFfile ux uy uz funcfile transform
879 + 0
880 + 0|3|6|9
881 +     rfdif gfdif bfdif
882 +     rbdif gbdif bbdif
883 +     rtdif gtdif btdif
884 + .DE
885 + The first string argument is a "thickness" parameter that may be used
886 + to hide detail geometry being proxied by an aggregate BSDF material.
887 + If a view or shadow ray hits a BSDF proxy with non-zero thickness,
888 + it will pass directly through as if the surface were not there.
889 + Similar to the illum type, this permits direct viewing and
890 + shadow testing of complex geometry.
891 + The BSDF is used when a scattered (indirect) ray hits the surface,
892 + and any transmitted sample rays will be offset by the thickness amount
893 + to avoid the hidden geometry and gather samples from the other side.
894 + In this manner, BSDF surfaces can improve the results for indirect
895 + scattering from complex systems without sacrificing appearance or
896 + shadow accuracy.
897 + If the BSDF has transmission and back-side reflection data,
898 + a parallel BSDF surface may be
899 + placed slightly less than the given thickness away from the front surface
900 + to enclose the complex geometry on both sides.
901 + The sign of the thickness is important, as it indicates whether the
902 + proxied geometry is behind the BSDF surface (when thickness is positive)
903 + or in front (when thickness is negative).
904 + .LP
905 + The second string argument is the name of the BSDF file, which is
906 + found in the usual auxiliary locations.
907 + The following three string parameters name variables for an "up" vector,
908 + which together with the surface normal, define the
909 + local coordinate system that orients the BSDF.
910 + These variables, along with the thickness, are defined in a function
911 + file given as the next string argument.
912 + An optional transform is used to scale the thickness and reorient the up vector.
913 + .LP
914 + If no real arguments are given, the BSDF is used by itself to determine
915 + reflection and transmission.
916 + If there are at least 3 real arguments, the first triplet is an
917 + additional diffuse reflectance for the front side.
918 + At least 6 real arguments adds diffuse reflectance to the rear side of the surface.
919 + If there are 9 real arguments, the final triplet will be taken as an additional
920 + diffuse transmittance.
921 + All diffuse components as well as the non-diffuse transmission are
922 + modified by patterns applied to this material.
923 + The non-diffuse reflection from either side are unaffected.
924 + Textures perturb the effective surface normal in the usual way.
925 + .LP
926 + The surface normal of this type is not altered to face the incoming ray,
927 + so the front and back BSDF reflections may differ.
928 + (Transmission is identical front-to-back by physical law.)\0
929 + If back visibility is turned off during rendering and there is no
930 + transmission or back-side reflection, only then the surface will be
931 + invisible from behind.
932 + Unlike other data-driven material types, the BSDF type is fully
933 + supported and all parts of the distribution are properly sampled.
934 + .LP
935   .UL Antimatter
936   .PP
937   Antimatter is a material that can "subtract" volumes from other volumes.
# Line 1098 | Line 1176 | which serves as a form of opacity control when used wi
1176   Vname is the coefficient defined in funcfile that determines the influence
1177   of foreground.
1178   The background coefficient is always (1-vname).
1101 – Since the references are not resolved until runtime, the last
1102 – definitions of the modifier id's will be used.
1103 – This can result in modifier loops, which are detected by the
1104 – renderer.
1179   .LP
1180   .UL Mixdata
1181   .PP
# Line 1202 | Line 1276 | and they are listed in the file
1276   The following variables are particularly important:
1277   .DS
1278          Dx, Dy, Dz              - incident ray direction
1205 –        Px, Py, Pz              - intersection point
1279          Nx, Ny, Nz              - surface normal at intersection point
1280 +        Px, Py, Pz              - intersection point
1281 +        T                       - distance from start
1282 +        Ts                      - single ray (shadow) distance
1283          Rdot                    - cosine between ray and normal
1284          arg(0)                  - number of real arguments
1285          arg(i)                  - i'th real argument
1286   .DE
1287 + For mesh objects, the local surface coordinates are available:
1288 + .DS
1289 +        Lu, Lv                  - local (u,v) coordinates
1290 + .DE
1291   For BRDF types, the following variables are defined as well:
1292   .DS
1293          NxP, NyP, NzP           - perturbed surface normal
# Line 1222 | Line 1302 | If no file is needed by a given primitive because all
1302   variables are global, a period (`.') can be given in
1303   place of the file name.
1304   It is also possible to give an expression instead of a straight
1305 < variable name in a scene file, although such expressions should
1306 < be kept simple as they cannot contain any white space.
1227 < Also, functions (requiring parameters)
1305 > variable name in a scene file.
1306 > Functions (requiring parameters)
1307   must be given as names and not as expressions.
1308   .PP
1309   Constant expressions are used as an optimization in function
# Line 1388 | Line 1467 | converts a picture to and from simpler formats.
1467   Pictures may be displayed directly under X11 using the program
1468   .I ximage,
1469   or converted a standard image format.
1470 < .I Ra_avs
1471 < converts to and from AVS image format.
1393 < .I Ra_pict
1394 < converts to Macintosh 32-bit PICT2 format.
1470 > .I Ra_bmp
1471 > converts to and from Microsoft Bitmap images.
1472   .I Ra_ppm
1473   converts to and from Poskanzer Portable Pixmap formats.
1397 – .I Ra_pr
1398 – converts to and from Sun 8-bit rasterfile format.
1399 – .I Ra_pr24
1400 – converts to and from Sun 24-bit rasterfile format.
1474   .I Ra_ps
1475   converts to PostScript color and greyscale formats.
1476   .I Ra_rgbe
# Line 1413 | Line 1486 | converts to and from Radiance CIE picture format.
1486   .NH 1
1487   License
1488   .PP
1489 < Radiance is a registered copyright of The Regents of the University of
1490 < California ("The Regents"). The Regents grant to you a nonexclusive,
1491 < nontransferable license ("License") to use Radiance source code without fee.
1492 < You may not sell or distribute Radiance to others without the prior express
1493 < written permission of The Regents.
1494 < You may compile and use this software on any machines to which you have
1495 < personal access, and may share its use with others who have access to the
1496 < same machines.
1497 < .PP
1498 < NEITHER THE UNITED STATES NOR THE UNITED STATES DEPARTMENT OF ENERGY, NOR ANY
1499 < OF THEIR EMPLOYEES, MAKES ANY WARRANTY, EXPRESS OR IMPLIED, OR ASSUMES ANY
1500 < LEGAL LIABILITY OR RESPONSIBILITY FOR THE ACCURACY, COMPLETENESS, OR
1501 < USEFULNESS OF ANY INFORMATION, APPARATUS, PRODUCT, OR PROCESS DISCLOSED, OR
1502 < REPRESENTS THAT ITS USE WOULD NOT INFRINGE PRIVATELY OWNED RIGHTS.
1503 < By downloading, using or copying this software, you agree to abide by the
1504 < intellectual property laws and all other applicable laws of the United
1505 < States, and by the terms of this License Agreement. Ownership of the software
1506 < shall remain solely in The Regents.
1507 < The Regents shall have the right to terminate this License immediately by
1508 < written notice upon your breach of, or noncompliance with, any of its terms.
1509 < You shall be liable for any infringement or damages resulting from your
1510 < failure to abide by the terms of this License Agreement.
1511 < .PP
1512 < NOTICE: The Government is granted for itself and others acting on its behalf
1513 < a paid-up, nonexclusive irrevocable worldwide license in this data to
1514 < reproduce, prepare derivative works, and perform publicly and display
1515 < publicly. Beginning five (5) years after permission to assert copyright is
1516 < granted, subject to two possible five year renewals, the Government is
1517 < granted for itself and others acting on its behalf a paid-up, non-exclusive,
1518 < irrevocable worldwide license in this data to reproduce, prepare derivative
1519 < works, distribute copies to the public, perform publicly and display
1520 < publicly, and to permit others to do so.
1489 > .DS
1490 > The Radiance Software License, Version 1.0
1491 >
1492 > Copyright (c) 1990 - 2008 The Regents of the University of California,
1493 > through Lawrence Berkeley National Laboratory.   All rights reserved.
1494 >
1495 > Redistribution and use in source and binary forms, with or without
1496 > modification, are permitted provided that the following conditions
1497 > are met:
1498 >
1499 > 1. Redistributions of source code must retain the above copyright
1500 >        notice, this list of conditions and the following disclaimer.
1501 >
1502 > 2. Redistributions in binary form must reproduce the above copyright
1503 >      notice, this list of conditions and the following disclaimer in
1504 >      the documentation and/or other materials provided with the
1505 >      distribution.
1506 >
1507 > 3. The end-user documentation included with the redistribution,
1508 >          if any, must include the following acknowledgment:
1509 >            "This product includes Radiance software
1510 >                (http://radsite.lbl.gov/)
1511 >                developed by the Lawrence Berkeley National Laboratory
1512 >              (http://www.lbl.gov/)."
1513 >      Alternately, this acknowledgment may appear in the software itself,
1514 >      if and wherever such third-party acknowledgments normally appear.
1515 >
1516 > 4. The names "Radiance," "Lawrence Berkeley National Laboratory"
1517 >      and "The Regents of the University of California" must
1518 >      not be used to endorse or promote products derived from this
1519 >      software without prior written permission. For written
1520 >      permission, please contact [email protected].
1521 >
1522 > 5. Products derived from this software may not be called "Radiance",
1523 >      nor may "Radiance" appear in their name, without prior written
1524 >      permission of Lawrence Berkeley National Laboratory.
1525 >
1526 > THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
1527 > WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
1528 > OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
1529 > DISCLAIMED.   IN NO EVENT SHALL Lawrence Berkeley National Laboratory OR
1530 > ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
1531 > SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
1532 > LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
1533 > USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
1534 > ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
1535 > OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
1536 > OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
1537 > SUCH DAMAGE.
1538 > .DE
1539   .NH 1
1540   Acknowledgements
1541   .PP
# Line 1460 | Line 1551 | the Ecole Polytechnique Federale de Lausanne (EPFL Uni
1551   in Lausanne, Switzerland.
1552   .NH 1
1553   References
1554 + .LP
1555 + Cater, K., A. Chalmers, G. Ward,
1556 + ``Detail to Attention: Exploiting Visual Tasks for Selective Rendering,''
1557 + .I "Eurograhics Symposium on Rendering",
1558 + June 2003.
1559 + .LP
1560 + Ward, G., Elena Eydelberg-Vileshin,
1561 + ``Picture Perfect RGB Rendering Using Spectral Prefiltering and
1562 + Sharp Color Primaries,''
1563 + 13th Eurographics Workshop on Rendering, P. Debevec and
1564 + S. Gibson (Editors), June 2002.
1565 + .LP
1566 + Ward, G. and M. Simmons,
1567 + ``The Holodeck Ray Cache: An Interactive Rendering System for Global
1568 + Illumination in Nondiffuse Environments,''
1569 + .I "ACM Transactions on Graphics,"
1570 + 18(4):361-98, October 1999.
1571 + .LP
1572 + Larson, G.W., H. Rushmeier, C. Piatko,
1573 + ``A Visibility Matching Tone Reproduction Operator for High Dynamic
1574 + Range Scenes,''
1575 + .I "IEEE Transactions on Visualization and Computer Graphics",
1576 + 3(4), 291-306, December 1997.
1577 + .LP
1578 + Ward, G.,
1579 + ``Making Global Illumination User Friendly,''
1580 + .I "Sixth Eurographics Workshop on Rendering",
1581 + proceedings to be published by Springer-Verlag,
1582 + Dublin, Ireland, June 1995.
1583 + .LP
1584 + Rushmeier, H., G. Ward, C. Piatko, P. Sanders, B. Rust,
1585 + ``Comparing Real and Synthetic Images: Some Ideas about Metrics,''
1586 + .I "Sixth Eurographics Workshop on Rendering",
1587 + proceedings to be published by Springer-Verlag,
1588 + Dublin, Ireland, June 1995.
1589   .LP
1590   Ward, G.,
1591   ``The Radiance Lighting Simulation and Rendering System,''

Diff Legend

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