ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/radiance/ray/doc/man/man1/rcontrib.1
Revision: 1.6
Committed: Thu Nov 15 19:41:03 2012 UTC (12 years, 6 months ago) by greg
Branch: MAIN
Changes since 1.5: +10 -9 lines
Log Message:
Tweaks and fixes related to flushing with -c >1

File Contents

# Content
1 .\" RCSid "$Id: rcontrib.1,v 1.5 2012/06/14 22:51:04 greg Exp $"
2 .TH RCONTRIB 1 5/25/05 RADIANCE
3 .SH NAME
4 rcontrib - compute contribution coefficients in a RADIANCE scene
5 .SH SYNOPSIS
6 .B rcontrib
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"
19 ][
20 .B "\-f source"
21 ][
22 .B "\-o ospec"
23 ][
24 .B "\-b binv"
25 ][
26 .B "\-bn nbins"
27 ]
28 {
29 .B "\-m mod | \-M file"
30 }
31 ..
32 [
33 .B $EVAR
34 ]
35 [
36 .B @file
37 ]
38 [
39 rtrace options
40 ]
41 .B octree
42 .br
43 .B "rcontrib [ options ] \-defaults"
44 .SH DESCRIPTION
45 .I Rcontrib
46 computes ray coefficients
47 for objects whose modifiers are named in one or more
48 .I \-m
49 settings.
50 These modifiers are usually materials associated with
51 light sources or sky domes, and must directly modify some geometric
52 primitives to be considered in the output.
53 A modifier list may also be read from a file using the
54 .I \-M
55 option.
56 The RAYPATH environment variable determines directories to search for
57 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 processes will be used to accelerate computation on a shared
65 memory machine.
66 Note that there is no benefit to using more processes
67 than there are local CPUs available to do the work, and the
68 .I rcontrib
69 process itself may use a considerable amount of CPU time.
70 .PP
71 By setting the boolean
72 .I \-V
73 option, you may instruct
74 .I rcontrib
75 to report the contribution from each material rather than the ray
76 coefficient.
77 This is particularly useful for light sources with directional output
78 distributions, whose value would otherwise be lost in the shuffle.
79 With the default
80 .I -V-
81 setting, the output of rcontrib is a coefficient that must be multiplied
82 by the radiance of each material to arrive at a final contribution.
83 This is more convenient for computing daylight coefficeints, or cases
84 where the actual radiance is not desired.
85 Use the
86 .I -V+
87 setting when you wish to simply sum together contributions
88 (with possible adjustment factors) to obtain a final radiance value.
89 Combined with the
90 .I \-i
91 or
92 .I \-I
93 option, irradiance contributions are reported by
94 .I \-V+
95 rather than radiance, and
96 .I \-V-
97 coefficients contain an additonal factor of PI.
98 .PP
99 The
100 .I \-c
101 option tells
102 .I rcontrib
103 how many rays to accumulate for each record.
104 The default value is one, meaning a full record will be produced for
105 each input ray.
106 For values greater than one, contributions will be averaged together
107 over the given number of input rays.
108 If set to zero, only a single record will be produced at the very
109 end, corresponding to the sum of all rays given on the input
110 (rather than the average).
111 This is equivalent to passing all the output records through a program like
112 .I total(1)
113 to sum RGB values together, but is much more efficient.
114 Using this option, it is possible to reverse sampling, sending rays from
115 a parallel source such as the sun to a diffuse surface, for example.
116 Note that output flushing via zero-direction rays is disabled with
117 .I \-c
118 set to zero.
119 .PP
120 The output of
121 .I rcontrib
122 has many potential uses.
123 Source contributions can be used as components in linear combination to
124 reproduce any desired variation, e.g., simulating lighting controls or
125 changing sky conditions via daylight coefficients.
126 More generally,
127 .I rcontrib
128 can be used to compute arbitrary input-output relationships in optical
129 systems, such as luminaires, light pipes, and shading devices.
130 .PP
131 .I Rcontrib
132 sends the accumulated rays tallies
133 to one or more destinations according to the given
134 .I \-o
135 specification.
136 If a destination begins with an exclamation mark ('!'), then
137 a pipe is opened to a command and data is sent to its standard input.
138 Otherwise, the destination is treated as a file.
139 An existing file of the same name will not be clobbered, unless the
140 .I \-fo
141 option is given.
142 If instead the
143 .I \-r
144 option is specified, data recovery is attempted on existing files.
145 (If
146 .I "\-c 0"
147 is used together with the
148 .I \-r
149 option, existing files are read in and new ray evaluations are added
150 to the previous results, providing a convenient means for
151 progressive simulation.)\0
152 If an output specification contains a "%s" format, this will be
153 replaced by the modifier name.
154 The
155 .I \-b
156 option may be used to further define
157 a "bin number" within each object if finer resolution is needed, and
158 this will be applied to a "%d" format in the output file
159 specification if present.
160 The actual bin number is computed at run time based on ray direction
161 and surface intersection, as described below.
162 The number of bins must be specified in advance with the
163 .I \-bn
164 option, and this is critical for output files containing multiple values
165 per record.
166 A variable or constant name may be given for this parameter if
167 it has been defined via a previous
168 .I \-f
169 or
170 .I \-e
171 option.
172 Since bin numbers start from zero, the bin count is always equal to
173 the last bin plus one.
174 Set the this value to zero if the bin count is unknown (the default).
175 The most recent
176 .I \-b,
177 .I \-bn
178 and
179 .I \-o
180 options to the left of each
181 .I \-m
182 setting are the ones used for that modifier.
183 The ordering of other options is unimportant, except for
184 .I \-x
185 and
186 .I \-y
187 if the
188 .I \-c
189 is zero, when they control the resolution string
190 produced in the corresponding output.
191 .PP
192 If a
193 .I \-b
194 expression is defined for a particular modifier,
195 the bin number will be evaluated at run time for each
196 ray contribution.
197 Specifically, each ray's world intersection point will be assigned to
198 the variables Px, Py, and Pz, and the normalized ray direction
199 will be assigned to Dx, Dy, and Dz.
200 These parameters may be combined with definitions given in
201 .I \-e
202 arguments and files read using the
203 .I \-f
204 option.
205 The computed bin value will be
206 rounded to the nearest whole number.
207 This mechanism allows the user to define precise regions or directions
208 they wish to accumulate, such as the Tregenza sky discretization,
209 which would be otherwise impossible to specify
210 as a set of RADIANCE primitives.
211 The rules and predefined functions available for these expressions are
212 described in the
213 .I rcalc(1)
214 man page.
215 Unlike
216 .I rcalc,
217 .I rcontrib
218 will search the RADIANCE library directories for each file given in a
219 .I \-f
220 option.
221 .PP
222 If no
223 .I \-o
224 specification is given, results are written on the standard output in order
225 of modifier (as given on the command line) then bin number.
226 Concatenated data is also sent to a single destination (i.e., an initial
227 .I \-o
228 specification without formatting strings).
229 If a "%s" format appears but no "%d" in the
230 .I \-o
231 specification, then each modifier will have its own output file, with
232 multiple values per record in the case of a non-zero
233 .I \-b
234 definition.
235 If a "%d" format appears but no "%s", then each bin will get its own
236 output file, with modifiers output in order in each record.
237 For text output, each RGB coefficient triple is separated by a tab,
238 with a newline at the end of each ray record.
239 For binary output formats, there is no such delimiter to mark
240 the end of each record.
241 .PP
242 Input and output format defaults to plain text, where each ray's
243 origin and direction (6 real values) are given on input,
244 and one line is produced per output file per ray.
245 Alternative data representations may be specified by the
246 .I \-f[io]
247 option, which is described in the
248 .I rtrace
249 man page along with the associated
250 .I \-x
251 and
252 .I \-y
253 resolution settings.
254 In particular, the color ('c') output data representation
255 together with positive dimensions for
256 .I \-x
257 and
258 .I \-y
259 will produce an uncompressed RADIANCE picture,
260 suitable for manipulation with
261 .I pcomb(1)
262 and related tools.
263 .PP
264 Options may be given on the command line and/or read from the
265 environment and/or read from a file.
266 A command argument beginning with a dollar sign ('$') is immediately
267 replaced by the contents of the given environment variable.
268 A command argument beginning with an at sign ('@') is immediately
269 replaced by the contents of the given file.
270 .SH EXAMPLES
271 To compute the proportional contributions from sources modified
272 by "light1" vs. "light2" on a set of illuminance values:
273 .IP "" .2i
274 rcontrib \-I+ @render.opt \-o c_%s.dat \-m light1 \-m light2 scene.oct < test.dat
275 .PP
276 To generate a pair of images corresponding to these two lights'
277 contributions:
278 .IP "" .2i
279 vwrays \-ff \-x 1024 \-y 1024 \-vf best.vf |
280 rcontrib \-ffc `vwrays \-d \-x 1024 \-y 1024 \-vf best.vf`
281 @render.opt \-o c_%s.hdr \-m light1 \-m light2 scene.oct
282 .PP
283 These images may then be recombined using the desired outputs
284 of light1 and light2:
285 .IP "" .2i
286 pcomb \-c 100 90 75 c_light1.hdr \-c 50 55 57 c_light2.hdr > combined.hdr
287 .PP
288 To compute an array of illuminance contributions according to a Tregenza sky:
289 .IP "" .2i
290 rcontrib \-I+ \-b tbin \-o sky.dat \-m skyglow \-b 0 \-o ground.dat \-m groundglow
291 @render.opt \-f tregenza.cal scene.oct < test.dat
292 .SH ENVIRONMENT
293 RAYPATH path to search for \-f and \-M files
294 .SH AUTHOR
295 Greg Ward
296 .SH "SEE ALSO"
297 cnt(1), genklemsamp(1), getinfo(1), pcomb(1), pfilt(1), ra_rgbe(1),
298 rcalc(1), rpict(1), rsensor(1), rtrace(1), total(1), vwrays(1), ximage(1)