| 1 |
|
.\" RCSid "$Id$" |
| 2 |
< |
.TH RTCONTRIB 1 5/25/05 RADIANCE |
| 2 |
> |
.TH RCONTRIB 1 5/25/05 RADIANCE |
| 3 |
|
.SH NAME |
| 4 |
|
rcontrib - compute contribution coefficients in a RADIANCE scene |
| 5 |
|
.SH SYNOPSIS |
| 9 |
|
][ |
| 10 |
|
.B \-V |
| 11 |
|
][ |
| 12 |
+ |
.B "\-t secs" |
| 13 |
+ |
][ |
| 14 |
|
.B "\-c count" |
| 15 |
|
][ |
| 16 |
|
.B \-fo |
| 23 |
|
][ |
| 24 |
|
.B "\-o ospec" |
| 25 |
|
][ |
| 26 |
+ |
.B "\-p p1=V1,p2=V2" |
| 27 |
+ |
][ |
| 28 |
|
.B "\-b binv" |
| 29 |
|
][ |
| 30 |
|
.B "\-bn nbins" |
| 45 |
|
.B octree |
| 46 |
|
.br |
| 47 |
|
.B "rcontrib [ options ] \-defaults" |
| 48 |
+ |
.br |
| 49 |
+ |
.B "rcontrib \-features [feat1 ..]" |
| 50 |
|
.SH DESCRIPTION |
| 51 |
< |
.I Rtcontrib |
| 51 |
> |
.I Rcontrib |
| 52 |
|
computes ray coefficients |
| 53 |
|
for objects whose modifiers are named in one or more |
| 54 |
|
.I \-m |
| 67 |
|
If the |
| 68 |
|
.I \-n |
| 69 |
|
option is specified with a value greater than 1, multiple |
| 64 |
– |
.I rtrace |
| 70 |
|
processes will be used to accelerate computation on a shared |
| 71 |
|
memory machine. |
| 72 |
|
Note that there is no benefit to using more processes |
| 107 |
|
option tells |
| 108 |
|
.I rcontrib |
| 109 |
|
how many rays to accumulate for each record. |
| 110 |
< |
The default value is 1, meaning a full record will be produced for |
| 110 |
> |
The default value is one, meaning a full record will be produced for |
| 111 |
|
each input ray. |
| 112 |
< |
For values greater than 1, contributions will be averaged together |
| 112 |
> |
For values greater than one, contributions will be averaged together |
| 113 |
|
over the given number of input rays. |
| 114 |
|
If set to zero, only a single record will be produced at the very |
| 115 |
|
end, corresponding to the sum of all rays given on the input |
| 119 |
|
to sum RGB values together, but is much more efficient. |
| 120 |
|
Using this option, it is possible to reverse sampling, sending rays from |
| 121 |
|
a parallel source such as the sun to a diffuse surface, for example. |
| 122 |
< |
Note that output flushing via zero-direction rays is disabled |
| 123 |
< |
for accumulated evaluations. |
| 122 |
> |
Note that output flushing via zero-direction rays is disabled with |
| 123 |
> |
.I \-c |
| 124 |
> |
set to zero. |
| 125 |
|
.PP |
| 126 |
+ |
Output flushing at fixed intervals may be enabled with the |
| 127 |
+ |
.I \-x |
| 128 |
+ |
option, which specifies the number of records |
| 129 |
+ |
(-c accumulations) before each flush. |
| 130 |
+ |
If the |
| 131 |
+ |
.I \-y |
| 132 |
+ |
option is also set, then periodic flushing is disabled and the |
| 133 |
+ |
output size for an RGB image is the taken from the x and y dimensions. |
| 134 |
+ |
In lieu of periodic flushing, a flush may be forced as mentioned above |
| 135 |
+ |
by sending a sample with a zero direction vector, although you |
| 136 |
+ |
must still send a full record of rays before output occurs. |
| 137 |
+ |
.PP |
| 138 |
+ |
If progress reports are desired, the |
| 139 |
+ |
.I \-t |
| 140 |
+ |
option specifies a time interval in seconds for reports sent to |
| 141 |
+ |
standard error. |
| 142 |
+ |
This requires that the number of input samples is known, meaning a |
| 143 |
+ |
.I \-y |
| 144 |
+ |
parameter has been specified. |
| 145 |
+ |
.PP |
| 146 |
|
The output of |
| 147 |
|
.I rcontrib |
| 148 |
|
has many potential uses. |
| 154 |
|
can be used to compute arbitrary input-output relationships in optical |
| 155 |
|
systems, such as luminaires, light pipes, and shading devices. |
| 156 |
|
.PP |
| 157 |
< |
.I Rtcontrib |
| 158 |
< |
calls |
| 159 |
< |
.I rtrace(1) |
| 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 |
| 157 |
> |
.I Rcontrib |
| 158 |
> |
sends the accumulated rays tallies |
| 159 |
> |
to one or more destinations according to the given |
| 160 |
|
.I \-o |
| 161 |
|
specification. |
| 162 |
|
If a destination begins with an exclamation mark ('!'), then |
| 182 |
|
option may be used to further define |
| 183 |
|
a "bin number" within each object if finer resolution is needed, and |
| 184 |
|
this will be applied to a "%d" format in the output file |
| 185 |
< |
specification if present. |
| 185 |
> |
specification if present. |
| 186 |
> |
(The final integer will be offset incrementally |
| 187 |
> |
if the output is a RADIANCE picture and more than one modifier has |
| 188 |
> |
the same format specification.)\0 |
| 189 |
|
The actual bin number is computed at run time based on ray direction |
| 190 |
|
and surface intersection, as described below. |
| 191 |
< |
If the number of bins is known in advance, it should be specified with the |
| 191 |
> |
The number of bins must be specified in advance with the |
| 192 |
|
.I \-bn |
| 193 |
|
option, and this is critical for output files containing multiple values |
| 194 |
|
per record. |
| 198 |
|
or |
| 199 |
|
.I \-e |
| 200 |
|
option. |
| 201 |
< |
Since bin numbers start from 0, the bin count is always equal to |
| 202 |
< |
the last bin plus 1. |
| 177 |
< |
Set the this value to 0 if the bin count is unknown (the default). |
| 201 |
> |
Since bin numbers start from zero, the bin count is always equal to |
| 202 |
> |
the last bin plus one. |
| 203 |
|
The most recent |
| 204 |
+ |
.I \-p, |
| 205 |
|
.I \-b, |
| 206 |
|
.I \-bn |
| 207 |
|
and |
| 208 |
|
.I \-o |
| 209 |
|
options to the left of each |
| 210 |
|
.I \-m |
| 211 |
< |
setting are the ones used for that modifier. |
| 211 |
> |
name are the ones used for that modifier. |
| 212 |
> |
Any |
| 213 |
> |
.I \-cs |
| 214 |
> |
option changing the number of spectral color |
| 215 |
> |
samples must appear before the first modifier. |
| 216 |
|
The ordering of other options is unimportant, except for |
| 217 |
|
.I \-x |
| 218 |
|
and |
| 219 |
|
.I \-y |
| 220 |
|
if the |
| 221 |
|
.I \-c |
| 222 |
< |
is 0, when they control the resolution string |
| 222 |
> |
is zero, when they control the resolution string |
| 223 |
|
produced in the corresponding output. |
| 224 |
|
.PP |
| 225 |
|
If a |
| 226 |
|
.I \-b |
| 227 |
|
expression is defined for a particular modifier, |
| 228 |
|
the bin number will be evaluated at run time for each |
| 229 |
< |
ray contribution from |
| 200 |
< |
.I rtrace. |
| 229 |
> |
ray contribution. |
| 230 |
|
Specifically, each ray's world intersection point will be assigned to |
| 231 |
|
the variables Px, Py, and Pz, and the normalized ray direction |
| 232 |
|
will be assigned to Dx, Dy, and Dz. |
| 235 |
|
arguments and files read using the |
| 236 |
|
.I \-f |
| 237 |
|
option. |
| 238 |
+ |
Additional parameter values that apply only to this modifier may be specified |
| 239 |
+ |
with a |
| 240 |
+ |
.I \-p |
| 241 |
+ |
option, which contains a list of variable names and assigned values, separated |
| 242 |
+ |
by commas, colons, or semicolons. |
| 243 |
|
The computed bin value will be |
| 244 |
|
rounded to the nearest whole number. |
| 245 |
+ |
(Negative bin values will be silently ignored.)\0 |
| 246 |
+ |
For a single bin, you may specify |
| 247 |
+ |
.I "\-b 0", |
| 248 |
+ |
which is the default. |
| 249 |
|
This mechanism allows the user to define precise regions or directions |
| 250 |
|
they wish to accumulate, such as the Tregenza sky discretization, |
| 251 |
|
which would be otherwise impossible to specify |
| 254 |
|
described in the |
| 255 |
|
.I rcalc(1) |
| 256 |
|
man page. |
| 257 |
< |
Unlike |
| 257 |
> |
Like |
| 258 |
|
.I rcalc, |
| 259 |
|
.I rcontrib |
| 260 |
|
will search the RADIANCE library directories for each file given in a |
| 309 |
|
replaced by the contents of the given environment variable. |
| 310 |
|
A command argument beginning with an at sign ('@') is immediately |
| 311 |
|
replaced by the contents of the given file. |
| 312 |
+ |
.PP |
| 313 |
+ |
.I Rcontrib |
| 314 |
+ |
supports light source contributions from photon maps generated by |
| 315 |
+ |
.I mkpmap(1) |
| 316 |
+ |
with its |
| 317 |
+ |
.I -apC |
| 318 |
+ |
option. Enabling photon mapping is described in the |
| 319 |
+ |
.I rtrace |
| 320 |
+ |
man page along with its relevant settings. In photon mapping mode, |
| 321 |
+ |
.I rcontrib |
| 322 |
+ |
only supports contributions from light sources, not arbitrary modifiers. |
| 323 |
+ |
The |
| 324 |
+ |
.I -b |
| 325 |
+ |
option is supported along with its associated ray variables, as |
| 326 |
+ |
discussed above. Ray coefficients are also supported via the |
| 327 |
+ |
.I \-V- |
| 328 |
+ |
option. Using fewer photons than there are light sources for the photon |
| 329 |
+ |
density estimates results in omitted contributions, thus the bandwidth |
| 330 |
+ |
is clamped accordingly and a warning is issued. |
| 331 |
|
.SH EXAMPLES |
| 332 |
|
To compute the proportional contributions from sources modified |
| 333 |
< |
by "light1" vs. "light2" on a set of illuminance values: |
| 333 |
> |
by "light1" vs. "light2" on a set of irradiance values: |
| 334 |
|
.IP "" .2i |
| 335 |
|
rcontrib \-I+ @render.opt \-o c_%s.dat \-m light1 \-m light2 scene.oct < test.dat |
| 336 |
|
.PP |
| 346 |
|
.IP "" .2i |
| 347 |
|
pcomb \-c 100 90 75 c_light1.hdr \-c 50 55 57 c_light2.hdr > combined.hdr |
| 348 |
|
.PP |
| 349 |
< |
To compute an array of illuminance contributions according to a Tregenza sky: |
| 349 |
> |
To compute an array of irradiance contributions according to a Tregenza sky: |
| 350 |
|
.IP "" .2i |
| 351 |
< |
rcontrib \-I+ \-b tbin \-o sky.dat \-m skyglow \-b 0 \-o ground.dat \-m groundglow |
| 352 |
< |
@render.opt \-f tregenza.cal scene.oct < test.dat |
| 351 |
> |
rcontrib \-I+ \-f tregenza.cal \-b tbin \-bn Ntbins \-o sky.dat \-m skyglow |
| 352 |
> |
\-b 0 \-o ground.dat \-m groundglow @render.opt scene.oct < test.dat |
| 353 |
> |
.PP |
| 354 |
> |
To perform an annual simulation of 365 daily sun positions in photon mapping |
| 355 |
> |
mode: |
| 356 |
> |
.IP "" .2i |
| 357 |
> |
rcontrib \-I+ \-h \-V \-fo \-o c_%s.dat \-M lights \-ap contrib.pm 365 |
| 358 |
> |
scene.oct < test.dat, |
| 359 |
|
.SH ENVIRONMENT |
| 360 |
|
RAYPATH path to search for \-f and \-M files |
| 361 |
+ |
.SH BUGS |
| 362 |
+ |
We do not currently compute contributions or coefficients properly |
| 363 |
+ |
in scenes with participating media. |
| 364 |
+ |
A single warning will be issued if a scattering or absorbing medium |
| 365 |
+ |
is detected. |
| 366 |
|
.SH AUTHOR |
| 367 |
|
Greg Ward |
| 368 |
|
.SH "SEE ALSO" |
| 369 |
< |
cnt(1), genklemsamp(1), getinfo(1), pcomb(1), pfilt(1), ra_rgbe(1), |
| 370 |
< |
rcalc(1), rpict(1), rsensor(1), rtrace(1), total(1), vwrays(1), ximage(1) |
| 369 |
> |
cnt(1), genklemsamp(1), getinfo(1), mkpmap(1), pcomb(1), pfilt(1), |
| 370 |
> |
ra_rgbe(1), rcalc(1), rcomb(1), rfluxmtx(1), rmtxop(1), rpict(1), |
| 371 |
> |
rsensor(1), rtrace(1), total(1), vwrays(1), ximage(1) |
| 372 |
> |
|
