| 1 |
|
.\" RCSid "$Id$" |
| 2 |
< |
.TH RPIECE 1 5/25/05 RADIANCE |
| 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 "\-c count" |
| 13 |
+ |
][ |
| 14 |
+ |
.B \-fo |
| 15 |
+ |
| |
| 16 |
+ |
.B \-r |
| 17 |
+ |
][ |
| 18 |
|
.B "\-e expr" |
| 19 |
|
][ |
| 20 |
|
.B "\-f source" |
| 21 |
|
][ |
| 22 |
< |
.B "\-o fspec" |
| 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 |
|
] |
| 38 |
|
[ |
| 39 |
|
rtrace options |
| 40 |
|
] |
| 27 |
– |
.B "\-m mod .." |
| 41 |
|
.B octree |
| 42 |
+ |
.br |
| 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. |
| 50 |
< |
These modifiers are usually materials associated with specific |
| 51 |
< |
light sources, though they could correspond to intermediate objects as well. |
| 52 |
< |
The resulting contributions may then be used in linear combination to |
| 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 |
> |
.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. |
| 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 rtcontrib |
| 128 |
< |
can compute general input-output relationships in optical |
| 129 |
< |
systems, such as light pipes and shading devices. |
| 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 Rtrace(1) |
| 132 |
< |
is called to calculate the contributions for each input ray, |
| 133 |
< |
and the output tallies are sent to one or more files according to the |
| 131 |
> |
.I Rtcontrib |
| 132 |
> |
calls |
| 133 |
> |
.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 |
| 137 |
|
.I \-o |
| 138 |
|
specification. |
| 139 |
< |
If the output file specification contains a "%s" format, this will be |
| 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 will not be clobbered, unless the |
| 143 |
> |
.I \-fo |
| 144 |
> |
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 |
| 158 |
|
.I \-b |
| 159 |
|
option may be used to further define |
| 160 |
< |
a "bin number" within each object if finer resolution is desired, and |
| 161 |
< |
will be applied to a "%d" format in the output file |
| 160 |
> |
a "bin number" within each object if finer resolution is needed, and |
| 161 |
> |
this will be applied to a "%d" format in the output file |
| 162 |
|
specification if present. |
| 163 |
< |
(The actual bin number is computed at run time based on ray direction |
| 164 |
< |
and surface intersection, as described below.)\0 |
| 163 |
> |
The actual bin number is computed at run time based on ray direction |
| 164 |
> |
and surface intersection, as described below. |
| 165 |
> |
If the number of bins is known in advance, it should be specified with the |
| 166 |
> |
.I \-bn |
| 167 |
> |
option, and this is critical for output files containing multiple values |
| 168 |
> |
per record. |
| 169 |
> |
Since bin numbers start from 0, the bin count is always equal to |
| 170 |
> |
the last bin plus 1. |
| 171 |
> |
Set the this value to 0 if the bin count is unknown (the default). |
| 172 |
|
The most recent |
| 173 |
< |
.I \-b |
| 173 |
> |
.I \-b, |
| 174 |
> |
.I \-bn |
| 175 |
|
and |
| 176 |
|
.I \-o |
| 177 |
< |
options (to the left) of each |
| 177 |
> |
options to the left of each |
| 178 |
|
.I \-m |
| 179 |
< |
setting affect only that modifier, and the ordering |
| 180 |
< |
of other options is unimportant. |
| 68 |
< |
.PP |
| 69 |
< |
Input and output format defaults to plain text, where each ray's |
| 70 |
< |
origin and direction (6 real values) must appear together per |
| 71 |
< |
line of input, and one line of output is produced per output file |
| 72 |
< |
file per ray. |
| 73 |
< |
Alternative input and output formats may be specified using the |
| 74 |
< |
.I \-f[io] |
| 75 |
< |
option, which is explained in the |
| 76 |
< |
.I rtrace |
| 77 |
< |
man page along with the associated |
| 179 |
> |
setting affect only that modifier. |
| 180 |
> |
The ordering of other options is unimportant, except for |
| 181 |
|
.I \-x |
| 182 |
|
and |
| 183 |
|
.I \-y |
| 184 |
< |
resolution settings. |
| 185 |
< |
In particular, the 'c' output setting |
| 186 |
< |
together with positive dimensions for |
| 187 |
< |
.I \-x |
| 85 |
< |
and |
| 86 |
< |
.I \-y |
| 87 |
< |
will produce an uncompressed RADIANCE picture, |
| 88 |
< |
suitable for manipulation with |
| 89 |
< |
.I pcomb(1) |
| 90 |
< |
and related tools. |
| 184 |
> |
if the |
| 185 |
> |
.I \-c |
| 186 |
> |
is 0, when they control the resolution string |
| 187 |
> |
produced in the corresponding output. |
| 188 |
|
.PP |
| 189 |
+ |
If a |
| 190 |
+ |
.I \-b |
| 191 |
+ |
expression is defined for a particular modifier, |
| 192 |
+ |
the bin number will be evaluated at run time for each |
| 193 |
+ |
ray contribution from |
| 194 |
+ |
.I rtrace. |
| 195 |
+ |
Specifically, each ray's world intersection point will be assigned to |
| 196 |
+ |
the variables Px, Py, and Pz, and the normalized ray direction |
| 197 |
+ |
will be assigned to Dx, Dy, and Dz. |
| 198 |
+ |
These parameters may be combined with definitions given in |
| 199 |
+ |
.I \-e |
| 200 |
+ |
arguments and files read using the |
| 201 |
+ |
.I \-f |
| 202 |
+ |
option. |
| 203 |
+ |
The computed bin value will be |
| 204 |
+ |
rounded to the nearest whole number. |
| 205 |
+ |
This mechanism allows the user to define precise regions or directions |
| 206 |
+ |
they wish to accumulate, such as the Tregenza sky discretization, |
| 207 |
+ |
which would be otherwise impossible to specify |
| 208 |
+ |
as a set of RADIANCE primitives. |
| 209 |
+ |
The rules and predefined functions available for these expressions are |
| 210 |
+ |
described in the |
| 211 |
+ |
.I rcalc(1) |
| 212 |
+ |
man page. |
| 213 |
+ |
Unlike |
| 214 |
+ |
.I rcalc, |
| 215 |
+ |
.I rtcontrib |
| 216 |
+ |
will search the RADIANCE library directories for each file given in a |
| 217 |
+ |
.I \-f |
| 218 |
+ |
option. |
| 219 |
+ |
.PP |
| 220 |
|
If no |
| 221 |
|
.I \-o |
| 222 |
|
specification is given, results are written on the standard output in order |
| 223 |
|
of modifier (as given on the command line) then bin number. |
| 224 |
< |
The same format is used for a simple file name specification |
| 225 |
< |
without any embedded "%s" or "%d" formats. |
| 224 |
> |
Concatenated data is also sent to a single destination (i.e., an initial |
| 225 |
> |
.I \-o |
| 226 |
> |
specification without formatting strings). |
| 227 |
|
If a "%s" format appears but no "%d" in the |
| 228 |
|
.I \-o |
| 229 |
|
specification, then each modifier will have its own output file, with |
| 237 |
|
For binary output formats, there is no such delimiter to mark |
| 238 |
|
the end of each record. |
| 239 |
|
.PP |
| 240 |
< |
If a |
| 241 |
< |
.I \-b |
| 242 |
< |
expression is defined for a particular modifier, |
| 243 |
< |
the bin number will be evaluated at run time for each |
| 244 |
< |
ray contribution from |
| 245 |
< |
.I rtrace. |
| 246 |
< |
Specifically, each ray's world intersection point will be assigned to |
| 247 |
< |
the variables Px, Py, and Pz, and the normalized ray direction |
| 248 |
< |
will be assigned to Dx, Dy, and Dz. |
| 249 |
< |
These ray parameters may be combined with any definitions given in |
| 250 |
< |
.I \-e |
| 251 |
< |
options, or any files read in from |
| 252 |
< |
.I \-f |
| 253 |
< |
options, to compute the bin, which will be |
| 254 |
< |
rounded to the closest whole number. |
| 255 |
< |
This mechanism allows the user to define precise regions (or directions) |
| 256 |
< |
they wish to accumulate, such as the Tregenza sky grid, which would be |
| 257 |
< |
otherwise impossible to specify as a set of RADIANCE primitives. |
| 240 |
> |
Input and output format defaults to plain text, where each ray's |
| 241 |
> |
origin and direction (6 real values) are given on input, |
| 242 |
> |
and one line is produced per output file per ray. |
| 243 |
> |
Alternative data representations may be specified by the |
| 244 |
> |
.I \-f[io] |
| 245 |
> |
option, which is described in the |
| 246 |
> |
.I rtrace |
| 247 |
> |
man page along with the associated |
| 248 |
> |
.I \-x |
| 249 |
> |
and |
| 250 |
> |
.I \-y |
| 251 |
> |
resolution settings. |
| 252 |
> |
In particular, the color ('c') output data representation |
| 253 |
> |
together with positive dimensions for |
| 254 |
> |
.I \-x |
| 255 |
> |
and |
| 256 |
> |
.I \-y |
| 257 |
> |
will produce an uncompressed RADIANCE picture, |
| 258 |
> |
suitable for manipulation with |
| 259 |
> |
.I pcomb(1) |
| 260 |
> |
and related tools. |
| 261 |
|
.PP |
| 130 |
– |
If the |
| 131 |
– |
.I \-n |
| 132 |
– |
option is specified with a value greater than 1, multiple |
| 133 |
– |
.I rtrace(1) |
| 134 |
– |
processes will be used to accelerate computation on a shared |
| 135 |
– |
memory machine. |
| 136 |
– |
Note that there is no benefit to using more processes |
| 137 |
– |
than there are local CPUs available to do the work. |
| 138 |
– |
.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 |
| 265 |
|
replaced by the contents of the given environment variable. |
| 266 |
|
A command argument beginning with an at sign ('@') is immediately |
| 267 |
|
replaced by the contents of the given file. |
| 268 |
< |
.SH EXAMPLE |
| 269 |
< |
First |
| 270 |
< |
.I rpiece |
| 148 |
< |
process is started on the machine "goober": |
| 268 |
> |
.SH EXAMPLES |
| 269 |
> |
To compute the proportional contributions from sources modified |
| 270 |
> |
by "light1" vs. "light2" on a set of illuminance values: |
| 271 |
|
.IP "" .2i |
| 272 |
< |
goober% echo 1 8 > syncfile |
| 151 |
< |
.br |
| 152 |
< |
goober% echo -F syncfile -x 1024 -y 1024 -vf view -o picture octree > args |
| 153 |
< |
.br |
| 154 |
< |
goober% rpiece @args & |
| 272 |
> |
rtcontrib \-I+ @render.opt \-o c_%s.dat \-m light1 \-m light2 scene.oct < test.dat |
| 273 |
|
.PP |
| 274 |
< |
Second |
| 275 |
< |
.I rpiece |
| 158 |
< |
processes is started on the machine "sucker": |
| 274 |
> |
To generate a pair of images corresponding to these two lights' |
| 275 |
> |
contributions: |
| 276 |
|
.IP "" .2i |
| 277 |
< |
sucker% rpiece @args & |
| 278 |
< |
.SH NOTES |
| 279 |
< |
Due to NFS file buffering, the network lock manager is employed to |
| 163 |
< |
guarantee consistency in the output file even though non-overlapping |
| 164 |
< |
writes are used. |
| 165 |
< |
This would tend to slow the process down if |
| 166 |
< |
.I rpiece |
| 167 |
< |
were to wait for this I/O to complete before starting on the next |
| 168 |
< |
piece, so |
| 169 |
< |
.I rpiece |
| 170 |
< |
forks separate processes to hang around waiting for I/O completion. |
| 171 |
< |
The number of processes thus designated is set by the MAXFORK macro |
| 172 |
< |
in the program (compiled in the src/util directory). |
| 173 |
< |
If the fork call is slow on a system, it may actually be better to |
| 174 |
< |
set MAXFORK to zero. |
| 175 |
< |
In other cases, the network lock manager may be so slow that this |
| 176 |
< |
value should be increased to get the best utilization. |
| 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.hdr \-m light1 \-m light2 scene.oct |
| 280 |
|
.PP |
| 281 |
< |
The output picture is not run-length encoded, and can be quite |
| 282 |
< |
large. |
| 180 |
< |
The approximate size (in kilobytes) can be computed by the simple |
| 181 |
< |
formula: |
| 281 |
> |
These images may then be recombined using the desired outputs |
| 282 |
> |
of light1 and light2: |
| 283 |
|
.IP "" .2i |
| 284 |
< |
filesize = xres*yres/256 |
| 284 |
> |
pcomb \-c 100 90 75 c_light1.hdr \-c 50 55 57 c_light2.hdr > combined.hdr |
| 285 |
|
.PP |
| 286 |
< |
Make sure that there is enough space on the filesystem to hold the |
| 287 |
< |
entire picture before beginning. |
| 288 |
< |
Once the picture is finished, the |
| 289 |
< |
.I ra_rgbe(1) |
| 290 |
< |
program with the -r option may be used to convert to a run-length |
| 291 |
< |
encoded picture for more efficient storage, although |
| 191 |
< |
.I pfilt(1) |
| 192 |
< |
or any of the other Radiance picture filters will do the same |
| 193 |
< |
thing. |
| 194 |
< |
.PP |
| 195 |
< |
The ALRM signal may be used to gracefully terminate an |
| 196 |
< |
.I rpiece |
| 197 |
< |
process after it finishes the current piece. |
| 198 |
< |
This permits other currently running or subsequently started |
| 199 |
< |
.I rpiece |
| 200 |
< |
process(es) to continue rendering the picture without loss. |
| 201 |
< |
The |
| 202 |
< |
.I \-T |
| 203 |
< |
option will send the ALRM signal to |
| 204 |
< |
.I rpiece |
| 205 |
< |
after the specified number of (decimal) hours. |
| 206 |
< |
This is the best way to force a time limit on the computation, |
| 207 |
< |
since information will not be lost, though the process may continue |
| 208 |
< |
for some time afterwards to finish its current piece. |
| 209 |
< |
.SH BUGS |
| 210 |
< |
This program may not work on some systems whose NFS lock manager is |
| 211 |
< |
unreliable. |
| 212 |
< |
In particular, some System V derivative UNIX systems often have |
| 213 |
< |
problems with the network lock manager. |
| 214 |
< |
If the output is scrambled or rpict aborts with some ambient file |
| 215 |
< |
related problem, you should just remove the ambient file and go |
| 216 |
< |
back to normal rendering. |
| 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 |
| 290 |
> |
.SH ENVIRONMENT |
| 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) |
