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.14 by greg, Tue Oct 11 16:54:26 2005 UTC vs.
Revision 1.22 by greg, Sun Jun 14 18:21:58 2009 UTC

# Line 7 | Line 7 | rtcontrib - compute contribution coefficients in a RAD
7   [
8   .B "\-n nprocs"
9   ][
10 + .B \-V
11 + ][
12 + .B "\-c count"
13 + ][
14   .B \-fo
15   |
16   .B \-r
# Line 39 | Line 43 | rtrace options
43   .B "rtcontrib [ options ] \-defaults"
44   .SH DESCRIPTION
45   .I Rtcontrib
46 < computes ray contributions (i.e., color coefficients)
46 > computes ray coefficients
47   for objects whose modifiers are named in one or more
48   .I \-m
49   settings.
# Line 54 | Line 58 | this file.
58   (No search takes place if a file name begins with a '.', '/' or '~'
59   character.)\0
60   .PP
61 + If the
62 + .I \-n
63 + option is specified with a value greater than 1, multiple
64 + .I rtrace
65 + processes will be used to accelerate computation on a shared
66 + memory machine.
67 + Note that there is no benefit to using more processes
68 + than there are local CPUs available to do the work, and the
69 + .I rtcontrib
70 + process itself may use a considerable amount of CPU time.
71 + .PP
72 + By setting the boolean
73 + .I \-V
74 + option, you may instruct
75 + .I rtcontrib
76 + to report the contribution from each material rather than the ray
77 + coefficient.
78 + This is particularly useful for light sources with directional output
79 + distributions, whose value would otherwise be lost in the shuffle.
80 + With the default
81 + .I -V-
82 + setting, the output of rtcontrib is a coefficient that must be multiplied
83 + by the radiance of each material to arrive at a final contribution.
84 + This is more convenient for computing daylight coefficeints, or cases
85 + where the actual radiance is not desired.
86 + Use the
87 + .I -V+
88 + setting when you wish to simply sum together contributions
89 + (with possible adjustment factors) to obtain a final radiance value.
90 + Combined with the
91 + .I \-i
92 + or
93 + .I \-I
94 + option, irradiance contributions are reported by
95 + .I \-V+
96 + rather than radiance, and
97 + .I \-V-
98 + coefficients contain an additonal factor of PI.
99 + .PP
100 + The
101 + .I \-c
102 + option tells
103 + .I rtcontrib
104 + how many rays to accumulate for each record.
105 + The default value is 1, meaning a full record will be produced for
106 + each input ray.
107 + For values greater than 1, contributions will be averaged together
108 + over the given number of input rays.
109 + If set to zero, only a single record will be produced at the very
110 + end, corresponding to the sum of all rays given on the input
111 + (rather than the average).
112 + This is equivalent to passing all the output records through a program like
113 + .I total(1)
114 + to sum RGB values together, but is much more efficient.
115 + Using this option, it is possible to reverse sampling, sending rays from
116 + a parallel source such as the sun to a diffuse surface, for example.
117 + Note that output flushing via zero-direction rays is disabled
118 + for accumulated evaluations.
119 + .PP
120   The output of
121   .I rtcontrib
122   has many potential uses.
# Line 68 | Line 131 | systems, such as luminaires, light pipes, and shading
131   .I Rtcontrib
132   calls
133   .I rtrace(1)
134 < with the -oTW option to calculate the daughter ray
134 > with the \-oTW (or \-oTV) option to calculate the daughter ray
135   contributions for each input ray, and the output tallies
136   are sent to one or more destinations according to the given
137   .I \-o
# Line 82 | Line 145 | option is given.
145   If instead the
146   .I \-r
147   option is specified, data recovery is attempted on existing files.
148 + (If
149 + .I "\-c 0"
150 + is used together with the
151 + .I \-r
152 + option, existing files are read in and new ray evaluations are added
153 + to the previous results, providing a convenient means for
154 + progressive simulation.)\0
155   If an output specification contains a "%s" format, this will be
156   replaced by the modifier name.
157   The
# Line 96 | Line 166 | If the number of bins is known in advance, it should b
166   .I \-bn
167   option, and this is critical for output files containing multiple values
168   per record.
169 + A variable or constant name may be given for this parameter if
170 + it has been defined via a previous
171 + .I \-f
172 + or
173 + .I \-e
174 + option.
175   Since bin numbers start from 0, the bin count is always equal to
176   the last bin plus 1.
177   Set the this value to 0 if the bin count is unknown (the default).
# Line 106 | Line 182 | and
182   .I \-o
183   options to the left of each
184   .I \-m
185 < setting affect only that modifier.
186 < (The ordering of other options is unimportant.)\0
185 > setting are the ones used for that modifier.
186 > The ordering of other options is unimportant, except for
187 > .I \-x
188 > and
189 > .I \-y
190 > if the
191 > .I \-c
192 > is 0, when they control the resolution string
193 > produced in the corresponding output.
194   .PP
195   If a
196   .I \-b
# Line 182 | Line 265 | suitable for manipulation with
265   .I pcomb(1)
266   and related tools.
267   .PP
185 – If the
186 – .I \-n
187 – option is specified with a value greater than 1, multiple
188 – .I rtrace
189 – processes will be used to accelerate computation on a shared
190 – memory machine.
191 – Note that there is no benefit to using more processes
192 – than there are local CPUs available to do the work, and the
193 – .I rtcontrib
194 – process itself may use a considerable amount of CPU time.
195 – .PP
268   Options may be given on the command line and/or read from the
269   environment and/or read from a file.
270   A command argument beginning with a dollar sign ('$') is immediately
# Line 203 | Line 275 | replaced by the contents of the given file.
275   To compute the proportional contributions from sources modified
276   by "light1" vs. "light2" on a set of illuminance values:
277   .IP "" .2i
278 < rtcontrib -I+ @render.opt -o c_%s.dat -m light1 -m light2 scene.oct < test.dat
278 > rtcontrib \-I+ @render.opt \-o c_%s.dat \-m light1 \-m light2 scene.oct < test.dat
279   .PP
280   To generate a pair of images corresponding to these two lights'
281   contributions:
282   .IP "" .2i
283 < vwrays -ff -x 1024 -y 1024 -vf best.vf |
284 < rtcontrib -ffc `vwrays -d -x 1024 -y 1024 -vf best.vf`
285 < @render.opt -o c_%s.pic -m light1 -m light2 scene.oct
283 > vwrays \-ff \-x 1024 \-y 1024 \-vf best.vf |
284 > rtcontrib \-ffc `vwrays \-d \-x 1024 \-y 1024 \-vf best.vf`
285 > @render.opt \-o c_%s.hdr \-m light1 \-m light2 scene.oct
286   .PP
287   These images may then be recombined using the desired outputs
288   of light1 and light2:
289   .IP "" .2i
290 < pcomb -c 100 90 75 c_light1.pic -c 50 55 57 c_light2.pic > combined.pic
290 > pcomb \-c 100 90 75 c_light1.hdr \-c 50 55 57 c_light2.hdr > combined.hdr
291   .PP
292   To compute an array of illuminance contributions according to a Tregenza sky:
293   .IP "" .2i
294 < rtcontrib -I+ -b tbin -o sky.dat -m skyglow -b 0 -o ground.dat -m groundglow
295 < @render.opt -f tregenza.cal scene.oct < test.dat
294 > rtcontrib \-I+ \-b tbin \-o sky.dat \-m skyglow \-b 0 \-o ground.dat \-m groundglow
295 > @render.opt \-f tregenza.cal scene.oct < test.dat
296   .SH ENVIRONMENT
297 < RAYPATH         path to search for -f and -M files
297 > RAYPATH         path to search for \-f and \-M files
298   .SH AUTHOR
299   Greg Ward
300   .SH "SEE ALSO"
301 < cnt(1), getinfo(1), pcomb(1), pfilt(1), ra_rgbe(1),
302 < rcalc(1), rpict(1), rtrace(1), vwrays(1), ximage(1)
301 > cnt(1), genklemsamp(1), getinfo(1), pcomb(1), pfilt(1), ra_rgbe(1),
302 > rcalc(1), rpict(1), rtrace(1), total(1), vwrays(1), ximage(1)

Diff Legend

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