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

Comparing ray/doc/man/man1/rtcontrib.1 (file contents):
Revision 1.13 by greg, Thu Oct 6 16:28:59 2005 UTC vs.
Revision 1.18 by greg, Fri Apr 18 18:06:29 2008 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
17   ][
18   .B "\-e expr"
# Line 37 | 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 52 | 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 66 | 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 74 | Line 139 | specification.
139   If a destination begins with an exclamation mark ('!'), then
140   a pipe is opened to a command and data is sent to its standard input.
141   Otherwise, the destination is treated as a file.
142 < An existing file of the same name is clobbered, unless the
142 > An existing file of the same name will not be clobbered, unless the
143 > .I \-fo
144 > option is given.
145 > If instead the
146   .I \-r
147 < option is specified, in which case data recovery is attempted.
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 102 | Line 177 | and
177   options to the left of each
178   .I \-m
179   setting affect only that modifier.
180 < (The ordering of other options is unimportant.)\0
180 > The ordering of other options is unimportant, except for
181 > .I \-x
182 > and
183 > .I \-y
184 > if the
185 > .I \-c
186 > is present, when they control the resolution string
187 > produced in the corresponding output.
188   .PP
189   If a
190   .I \-b
# Line 177 | Line 259 | suitable for manipulation with
259   .I pcomb(1)
260   and related tools.
261   .PP
180 – If the
181 – .I \-n
182 – option is specified with a value greater than 1, multiple
183 – .I rtrace
184 – processes will be used to accelerate computation on a shared
185 – memory machine.
186 – Note that there is no benefit to using more processes
187 – than there are local CPUs available to do the work, and the
188 – .I rtcontrib
189 – process itself may use a considerable amount of CPU time.
190 – .PP
262   Options may be given on the command line and/or read from the
263   environment and/or read from a file.
264   A command argument beginning with a dollar sign ('$') is immediately
# Line 198 | Line 269 | replaced by the contents of the given file.
269   To compute the proportional contributions from sources modified
270   by "light1" vs. "light2" on a set of illuminance values:
271   .IP "" .2i
272 < rtcontrib -I+ @render.opt -o c_%s.dat -m light1 -m light2 scene.oct < test.dat
272 > rtcontrib \-I+ @render.opt \-o c_%s.dat \-m light1 \-m light2 scene.oct < test.dat
273   .PP
274   To generate a pair of images corresponding to these two lights'
275   contributions:
276   .IP "" .2i
277 < vwrays -ff -x 1024 -y 1024 -vf best.vf |
278 < rtcontrib -ffc `vwrays -d -x 1024 -y 1024 -vf best.vf`
279 < @render.opt -o c_%s.pic -m light1 -m light2 scene.oct
277 > vwrays \-ff \-x 1024 \-y 1024 \-vf best.vf |
278 > rtcontrib \-ffc `vwrays \-d \-x 1024 \-y 1024 \-vf best.vf`
279 > @render.opt \-o c_%s.pic \-m light1 \-m light2 scene.oct
280   .PP
281   These images may then be recombined using the desired outputs
282   of light1 and light2:
283   .IP "" .2i
284 < pcomb -c 100 90 75 c_light1.pic -c 50 55 57 c_light2.pic > combined.pic
284 > pcomb \-c 100 90 75 c_light1.pic \-c 50 55 57 c_light2.pic > combined.pic
285   .PP
286   To compute an array of illuminance contributions according to a Tregenza sky:
287   .IP "" .2i
288 < rtcontrib -I+ -b tbin -o sky.dat -m skyglow -b 0 -o ground.dat -m groundglow
289 < @render.opt -f tregenza.cal scene.oct < test.dat
288 > rtcontrib \-I+ \-b tbin \-o sky.dat \-m skyglow \-b 0 \-o ground.dat \-m groundglow
289 > @render.opt \-f tregenza.cal scene.oct < test.dat
290   .SH ENVIRONMENT
291 < RAYPATH         path to search for -f and -M files
291 > RAYPATH         path to search for \-f and \-M files
292   .SH AUTHOR
293   Greg Ward
294   .SH "SEE ALSO"
295   cnt(1), getinfo(1), pcomb(1), pfilt(1), ra_rgbe(1),
296 < rcalc(1), rpict(1), rtrace(1), vwrays(1), ximage(1)
296 > rcalc(1), rpict(1), rtrace(1), total(1), vwrays(1), ximage(1)

Diff Legend

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