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

Comparing ray/doc/man/man1/rtcontrib.1 (file contents):
Revision 1.2 by greg, Thu May 26 18:53:04 2005 UTC vs.
Revision 1.16 by greg, Tue Sep 4 17:36:41 2007 UTC

# Line 1 | Line 1
1   .\" RCSid "$Id$"
2 < .TH RPIECE 1 5/25/05 RADIANCE
2 > .TH RTCONTRIB 1 5/25/05 RADIANCE
3   .SH NAME
4 < rtcontrib - compute contributions in a RADIANCE scene
4 > rtcontrib - compute contribution coefficients in a RADIANCE scene
5   .SH SYNOPSIS
6   .B rtcontrib
7   [
8   .B "\-n nprocs"
9   ][
10 + .B \-V
11 + ][
12 + .B \-fo
13 + |
14 + .B \-r
15 + ][
16   .B "\-e expr"
17   ][
18   .B "\-f source"
19   ][
20 < .B "\-o fspec"
20 > .B "\-o ospec"
21   ][
22   .B "\-b binv"
23 + ][
24 + .B "\-bn nbins"
25   ]
26 < .B "\-m mod .."
26 > {
27 > .B "\-m mod | \-M file"
28 > }
29 > ..
30   [
31   .B $EVAR
32   ]
# Line 26 | Line 37 | rtcontrib - compute contributions in a RADIANCE scene
37   rtrace options
38   ]
39   .B octree
40 + .br
41 + .B "rtcontrib [ options ] \-defaults"
42   .SH DESCRIPTION
43   .I Rtcontrib
44 < computes ray contributions (i.e., color coefficients)
44 > computes ray coefficients
45   for objects whose modifiers are named in one or more
46   .I \-m
47   settings.
48   These modifiers are usually materials associated with
49   light sources or sky domes, and must directly modify some geometric
50   primitives to be considered in the output.
51 < The computed contributions can then be used in linear combination to
51 > A modifier list may also be read from a file using the
52 > .I \-M
53 > option.
54 > The RAYPATH environment variable determines directories to search for
55 > this file.
56 > (No search takes place if a file name begins with a '.', '/' or '~'
57 > character.)\0
58 > .PP
59 > By setting the boolean
60 > .I \-V
61 > option, you may instruct
62 > .I rtcontrib
63 > to report the contribution from each material rather than the ray
64 > coefficient.
65 > This is particularly useful for light sources with directional output
66 > distributions, whose value would otherwise be lost in the shuffle.
67 > With the default
68 > .I -V-
69 > setting, the output of rtcontrib is a coefficient that must be multiplied
70 > by the radiance of each material to arrive at a final contribution.
71 > This is more convenient for computing daylight coefficeints, or cases
72 > where the actual radiance is not desired.
73 > Use the
74 > .I -V+
75 > setting when you wish to simply sum together contributions
76 > (with possible adjustment factors) to obtain a final radiance value.
77 > Combined with the
78 > .I \-i
79 > or
80 > .I \-I
81 > option, irradiance contributions are reported by
82 > .I \-V+
83 > rather than radiance, and
84 > .I \-V-
85 > coefficients contain an additonal factor of PI.
86 > .PP
87 > The output of
88 > .I rtcontrib
89 > has many potential uses.
90 > Source contributions can be used as components in linear combination to
91   reproduce any desired variation, e.g., simulating lighting controls or
92   changing sky conditions via daylight coefficients.
93   More generally,
94   .I rtcontrib
95 < may be used to compute input-output relationships in optical
96 < systems, such as light pipes and shading devices.
95 > can be used to compute arbitrary input-output relationships in optical
96 > systems, such as luminaires, light pipes, and shading devices.
97   .PP
98   .I Rtcontrib
99   calls
100   .I rtrace(1)
101 < to calculate the contributions for each input ray,
102 < and the output tallies are sent to one or more files according to the
101 > with the \-oTW (or \-oTV) option to calculate the daughter ray
102 > contributions for each input ray, and the output tallies
103 > are sent to one or more destinations according to the given
104   .I \-o
105   specification.
106 + If a destination begins with an exclamation mark ('!'), then
107 + a pipe is opened to a command and data is sent to its standard input.
108 + Otherwise, the destination is treated as a file.
109 + An existing file of the same name will not be clobbered, unless the
110 + .I \-fo
111 + option is given.
112 + If instead the
113 + .I \-r
114 + option is specified, data recovery is attempted on existing files.
115   If an output specification contains a "%s" format, this will be
116   replaced by the modifier name.
117   The
# Line 58 | Line 120 | option may be used to further define
120   a "bin number" within each object if finer resolution is needed, and
121   this will be applied to a "%d" format in the output file
122   specification if present.
123 < (The actual bin number is computed at run time based on ray direction
124 < and surface intersection, as described below.)\0
123 > The actual bin number is computed at run time based on ray direction
124 > and surface intersection, as described below.
125 > If the number of bins is known in advance, it should be specified with the
126 > .I \-bn
127 > option, and this is critical for output files containing multiple values
128 > per record.
129 > Since bin numbers start from 0, the bin count is always equal to
130 > the last bin plus 1.
131 > Set the this value to 0 if the bin count is unknown (the default).
132   The most recent
133 < .I \-b
133 > .I \-b,
134 > .I \-bn
135   and
136   .I \-o
137   options to the left of each
# Line 80 | Line 150 | the variables Px, Py, and Pz, and the normalized ray d
150   will be assigned to Dx, Dy, and Dz.
151   These parameters may be combined with definitions given in
152   .I \-e
153 < options and files read in
153 > arguments and files read using the
154   .I \-f
155 < options, to compute the bin, which will be
155 > option.
156 > The computed bin value will be
157   rounded to the nearest whole number.
158   This mechanism allows the user to define precise regions or directions
159   they wish to accumulate, such as the Tregenza sky discretization,
160   which would be otherwise impossible to specify
161   as a set of RADIANCE primitives.
162 + The rules and predefined functions available for these expressions are
163 + described in the
164 + .I rcalc(1)
165 + man page.
166 + Unlike
167 + .I rcalc,
168 + .I rtcontrib
169 + will search the RADIANCE library directories for each file given in a
170 + .I \-f
171 + option.
172   .PP
173   If no
174   .I \-o
175   specification is given, results are written on the standard output in order
176   of modifier (as given on the command line) then bin number.
177 < Concatenated data is also sent to a lone output file (i.e., an initial
177 > Concatenated data is also sent to a single destination (i.e., an initial
178   .I \-o
179   specification without formatting strings).
180   If a "%s" format appears but no "%d" in the
# Line 152 | Line 233 | replaced by the contents of the given file.
233   To compute the proportional contributions from sources modified
234   by "light1" vs. "light2" on a set of illuminance values:
235   .IP "" .2i
236 < rtcontrib -I+ @render.opt -o c_%s.dat -m light1 -m light2 scene.oct < test.dat
236 > rtcontrib \-I+ @render.opt \-o c_%s.dat \-m light1 \-m light2 scene.oct < test.dat
237   .PP
238   To generate a pair of images corresponding to these two lights'
239   contributions:
240   .IP "" .2i
241 < vwrays -ff -x 1024 -y 1024 -vf best.vf |
242 < rtcontrib -ffc `vwrays -d -x 1024 -y 1024 -vf best.vf`
243 < @render.opt -o c_%s.pic -m light1 -m light2 scene.oct
241 > vwrays \-ff \-x 1024 \-y 1024 \-vf best.vf |
242 > rtcontrib \-ffc `vwrays \-d \-x 1024 \-y 1024 \-vf best.vf`
243 > @render.opt \-o c_%s.pic \-m light1 \-m light2 scene.oct
244   .PP
245   These images may then be recombined using the desired outputs
246   of light1 and light2:
247   .IP "" .2i
248 < pcomb -c 100 90 75 c_light1.pic -c 50 55 57 c_light2.pic > combined.pic
248 > pcomb \-c 100 90 75 c_light1.pic \-c 50 55 57 c_light2.pic > combined.pic
249   .PP
250   To compute an array of illuminance contributions according to a Tregenza sky:
251   .IP "" .2i
252 < rtcontrib -b tbin -o sky.dat -m skyglow -b 0 -o ground.dat -m groundglow
253 < @render.opt -f tregenza.cal scene.oct < test.dat
252 > rtcontrib \-I+ \-b tbin \-o sky.dat \-m skyglow \-b 0 \-o ground.dat \-m groundglow
253 > @render.opt \-f tregenza.cal scene.oct < test.dat
254 > .SH ENVIRONMENT
255 > RAYPATH         path to search for \-f and \-M files
256   .SH AUTHOR
257   Greg Ward
258   .SH "SEE ALSO"

Diff Legend

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