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.4 by greg, Thu May 26 21:03:22 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 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 30 | Line 41 | rtrace options
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 + 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.
# Line 51 | Line 98 | systems, such as luminaires, light pipes, and shading
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 65 | Line 122 | this will be applied to a "%d" format in the output fi
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.
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 98 | Line 163 | The rules and predefined functions available for these
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 162 | 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