1 |
.\" RCSid "$Id: rtrace.1,v 1.5 2005/02/16 05:40:07 greg Exp $" |
2 |
.TH RTRACE 1 10/17/97 RADIANCE |
3 |
.SH NAME |
4 |
rtrace - trace rays in RADIANCE scene |
5 |
.SH SYNOPSIS |
6 |
.B rtrace |
7 |
[ |
8 |
.B options |
9 |
] |
10 |
[ |
11 |
.B $EVAR |
12 |
] |
13 |
[ |
14 |
.B @file |
15 |
] |
16 |
.B octree |
17 |
.br |
18 |
.B "rtrace [ options ] \-defaults" |
19 |
.SH DESCRIPTION |
20 |
.I Rtrace |
21 |
traces rays from the standard input through the RADIANCE scene given by |
22 |
.I octree |
23 |
and sends the results to the standard output. |
24 |
(The octree may be given as the output of a command enclosed in quotes |
25 |
and preceded by a `!'.)\0 |
26 |
Input for each ray is: |
27 |
|
28 |
xorg yorg zorg xdir ydir zdir |
29 |
|
30 |
If the direction vector is (0,0,0), a bogus record |
31 |
is printed and the output is flushed if the |
32 |
.I -x |
33 |
value is unset or zero. |
34 |
(See the notes on this option below.)\0 |
35 |
This may be useful for programs that run |
36 |
.I rtrace |
37 |
as a separate process. |
38 |
In the second form, the default values |
39 |
for the options (modified by those options present) |
40 |
are printed with a brief explanation. |
41 |
.PP |
42 |
Options may be given on the command line and/or read from the |
43 |
environment and/or read from a file. |
44 |
A command argument beginning with a dollar sign ('$') is immediately |
45 |
replaced by the contents of the given environment variable. |
46 |
A command argument beginning with an at sign ('@') is immediately |
47 |
replaced by the contents of the given file. |
48 |
Most options are followed by one or more arguments, which must be |
49 |
separated from the option and each other by white space. |
50 |
The exceptions to this rule are the boolean options. |
51 |
Normally, the appearance of a boolean option causes a feature to |
52 |
be "toggled", that is switched from off to on or on to off |
53 |
depending on its previous state. |
54 |
Boolean options may also be set |
55 |
explicitly by following them immediately with a '+' or '-', meaning |
56 |
on or off, respectively. |
57 |
Synonyms for '+' are any of the characters "yYtT1", and synonyms |
58 |
for '-' are any of the characters "nNfF0". |
59 |
All other characters will generate an error. |
60 |
.TP 10n |
61 |
.BI -f io |
62 |
Format input according to the character |
63 |
.I i |
64 |
and output according to the character |
65 |
.I o. |
66 |
.I Rtrace |
67 |
understands the following input and output formats: 'a' for |
68 |
ascii, 'f' for single-precision floating point, |
69 |
and 'd' for double-precision floating point. |
70 |
In addition to these three choices, the character 'c' may be used |
71 |
to denote 4-byte floating point (Radiance) color format |
72 |
for the output of values only |
73 |
.I (\-ov |
74 |
option, below). |
75 |
If the output character is missing, the input format is used. |
76 |
.IP |
77 |
Note that there is no space between this option and its argument. |
78 |
.TP |
79 |
.BI -o spec |
80 |
Produce output fields according to |
81 |
.I spec. |
82 |
Characters are interpreted as follows: |
83 |
.IP |
84 |
o origin (input) |
85 |
.IP |
86 |
d direction (normalized) |
87 |
.IP |
88 |
v value (radiance) |
89 |
.IP |
90 |
w weight |
91 |
.IP |
92 |
l effective length of ray |
93 |
.IP |
94 |
L first intersection distance |
95 |
.IP |
96 |
c local (u,v) coordinates |
97 |
.IP |
98 |
p point of intersection |
99 |
.IP |
100 |
n normal at intersection (perturbed) |
101 |
.IP |
102 |
N normal at intersection (unperturbed) |
103 |
.IP |
104 |
s surface name |
105 |
.IP |
106 |
m modifier name |
107 |
.IP |
108 |
M material name |
109 |
.IP |
110 |
If the letter 't' appears in |
111 |
.I spec, |
112 |
then the fields following will be printed for every ray traced, |
113 |
not just the final result. |
114 |
Spawned rays are indented one tab for each level. |
115 |
.IP |
116 |
Note that there is no space between this option and its argument. |
117 |
.TP |
118 |
.BI -te \ mod |
119 |
Append |
120 |
.I mod |
121 |
to the trace exclude list, |
122 |
so that it will not be reported by the trace option |
123 |
.I (\-o*t*). |
124 |
Any ray striking an object having |
125 |
.I mod |
126 |
as its modifier will not be reported to the standard output with |
127 |
the rest of the rays being traced. |
128 |
This option has no effect unless the 't' option has been given as |
129 |
part of the output specifier. |
130 |
Any number of excluded modifiers may be given, but each |
131 |
must appear in a separate option. |
132 |
.TP |
133 |
.BI -ti \ mod |
134 |
Add |
135 |
.I mod |
136 |
to the trace include list, |
137 |
so that it will be considered during the indirect calculation. |
138 |
The program can use either an include list or an exclude |
139 |
list, but not both. |
140 |
.TP |
141 |
.BI -tE \ file |
142 |
Same as |
143 |
.I \-te, |
144 |
except read modifiers to be excluded from |
145 |
.I file. |
146 |
The RAYPATH environment variable determines which directories are |
147 |
searched for this file. |
148 |
The modifier names are separated by white space in the file. |
149 |
.TP |
150 |
.BI -tI \ file |
151 |
Same as |
152 |
.I \-ti, |
153 |
except read modifiers to be included from |
154 |
.I file. |
155 |
.TP |
156 |
.BR \-i |
157 |
Boolean switch to compute irradiance rather than radiance values. |
158 |
This only affects the final result, substituting a Lambertian |
159 |
surface and multiplying the radiance by pi. |
160 |
Glass and other transparent surfaces are ignored during this stage. |
161 |
Light sources still appear with their original radiance values, |
162 |
though the |
163 |
.I \-dv |
164 |
option (below) may be used to override this. |
165 |
This option is especially useful in |
166 |
conjunction with ximage(1) for computing illuminance at scene points. |
167 |
.TP |
168 |
.BR \-I |
169 |
Boolean switch to compute irradiance rather than radiance, |
170 |
with the input origin and direction interpreted instead |
171 |
as measurement point and orientation. |
172 |
.TP |
173 |
.BR \-h |
174 |
Boolean switch for information header on output. |
175 |
.TP |
176 |
.BI -x \ res |
177 |
Set the x resolution to |
178 |
.I res. |
179 |
The output will be flushed after every |
180 |
.I res |
181 |
input rays. |
182 |
A value of zero means that no output flushing will take place. |
183 |
.TP |
184 |
.BI -y \ res |
185 |
Set the y resolution to |
186 |
.I res. |
187 |
The program will exit after |
188 |
.I res |
189 |
scanlines have been processed, where a scanline is the number of rays |
190 |
given by the |
191 |
.I \-x |
192 |
option, or 1 if |
193 |
.I \-x |
194 |
is zero. |
195 |
A value of zero means the program will not halt until the end |
196 |
of file is reached. |
197 |
.IP |
198 |
If both |
199 |
.I \-x |
200 |
and |
201 |
.I \-y |
202 |
options are given, a resolution string is printed at the beginning |
203 |
of the output. |
204 |
This is mostly useful for recovering image dimensions with |
205 |
.I pvalue(1), |
206 |
and for creating valid Radiance picture files using the color output |
207 |
format. |
208 |
(See the |
209 |
.I \-f |
210 |
option, above.) |
211 |
.TP |
212 |
.BI -dj \ frac |
213 |
Set the direct jittering to |
214 |
.I frac. |
215 |
A value of zero samples each source at specific sample points |
216 |
(see the |
217 |
.I \-ds |
218 |
option below), giving a smoother but somewhat less accurate |
219 |
rendering. |
220 |
A positive value causes rays to be distributed over each |
221 |
source sample according to its size, resulting in more accurate |
222 |
penumbras. |
223 |
This option should never be greater than 1, and may even |
224 |
cause problems (such as speckle) when the value is smaller. |
225 |
A warning about aiming failure will issued if |
226 |
.I frac |
227 |
is too large. |
228 |
.TP |
229 |
.BI -ds \ frac |
230 |
Set the direct sampling ratio to |
231 |
.I frac. |
232 |
A light source will be subdivided until |
233 |
the width of each sample area divided by the distance |
234 |
to the illuminated point is below this ratio. |
235 |
This assures accuracy in regions close to large area sources |
236 |
at a slight computational expense. |
237 |
A value of zero turns source subdivision off, sending at most one |
238 |
shadow ray to each light source. |
239 |
.TP |
240 |
.BI -dt \ frac |
241 |
Set the direct threshold to |
242 |
.I frac. |
243 |
Shadow testing will stop when the potential contribution of at least |
244 |
the next and at most all remaining light sources is less than |
245 |
this fraction of the accumulated value. |
246 |
(See the |
247 |
.I \-dc |
248 |
option below.) |
249 |
The remaining light source contributions are approximated |
250 |
statistically. |
251 |
A value of zero means that all light sources will be tested for shadow. |
252 |
.TP |
253 |
.BI \-dc \ frac |
254 |
Set the direct certainty to |
255 |
.I frac. |
256 |
A value of one guarantees that the absolute accuracy of the direct calculation |
257 |
will be equal to or better than that given in the |
258 |
.I \-dt |
259 |
specification. |
260 |
A value of zero only insures that all shadow lines resulting in a contrast |
261 |
change greater than the |
262 |
.I \-dt |
263 |
specification will be calculated. |
264 |
.TP |
265 |
.BI -dr \ N |
266 |
Set the number of relays for secondary sources to |
267 |
.I N. |
268 |
A value of 0 means that secondary sources will be ignored. |
269 |
A value of 1 means that sources will be made into first generation |
270 |
secondary sources; a value of 2 means that first generation |
271 |
secondary sources will also be made into second generation secondary |
272 |
sources, and so on. |
273 |
.TP |
274 |
.BI -dp \ D |
275 |
Set the secondary source presampling density to D. |
276 |
This is the number of samples per steradian |
277 |
that will be used to determine ahead of time whether or not |
278 |
it is worth following shadow rays through all the reflections and/or |
279 |
transmissions associated with a secondary source path. |
280 |
A value of 0 means that the full secondary source path will always |
281 |
be tested for shadows if it is tested at all. |
282 |
.TP |
283 |
.BR \-dv |
284 |
Boolean switch for light source visibility. |
285 |
With this switch off, sources will be black when viewed directly |
286 |
although they will still participate in the direct calculation. |
287 |
This option is mostly for the program |
288 |
.I mkillum(1) |
289 |
to avoid inappropriate counting of light sources, but it |
290 |
may also be desirable in conjunction with the |
291 |
.I \-i |
292 |
option. |
293 |
.TP |
294 |
.BI -sj \ frac |
295 |
Set the specular sampling jitter to |
296 |
.I frac. |
297 |
This is the degree to which the highlights are sampled |
298 |
for rough specular materials. |
299 |
A value of one means that all highlights will be fully sampled |
300 |
using distributed ray tracing. |
301 |
A value of zero means that no jittering will take place, and all |
302 |
reflections will appear sharp even when they should be diffuse. |
303 |
.TP |
304 |
.BI -st \ frac |
305 |
Set the specular sampling threshold to |
306 |
.I frac. |
307 |
This is the minimum fraction of reflection or transmission, under which |
308 |
no specular sampling is performed. |
309 |
A value of zero means that highlights will always be sampled by |
310 |
tracing reflected or transmitted rays. |
311 |
A value of one means that specular sampling is never used. |
312 |
Highlights from light sources will always be correct, but |
313 |
reflections from other surfaces will be approximated using an |
314 |
ambient value. |
315 |
A sampling threshold between zero and one offers a compromise between image |
316 |
accuracy and rendering time. |
317 |
.TP |
318 |
.BR -bv |
319 |
Boolean switch for back face visibility. |
320 |
With this switch off, back faces of opaque objects will be invisible |
321 |
to all rays. |
322 |
This is dangerous unless the model was constructed such that |
323 |
all surface normals on opaque objects face outward. |
324 |
Although turning off back face visibility does not save much |
325 |
computation time under most circumstances, it may be useful as a |
326 |
tool for scene debugging, or for seeing through one-sided walls from |
327 |
the outside. |
328 |
This option has no effect on transparent or translucent materials. |
329 |
.TP |
330 |
.BI -av " red grn blu" |
331 |
Set the ambient value to a radiance of |
332 |
.I "red grn blu". |
333 |
This is the final value used in place of an |
334 |
indirect light calculation. |
335 |
If the number of ambient bounces is one or greater and the ambient |
336 |
value weight is non-zero (see |
337 |
.I -aw |
338 |
and |
339 |
.I -ab |
340 |
below), this value may be modified by the computed indirect values |
341 |
to improve overall accuracy. |
342 |
.TP |
343 |
.BI -aw \ N |
344 |
Set the relative weight of the ambient value given with the |
345 |
.I -av |
346 |
option to |
347 |
.I N. |
348 |
As new indirect irradiances are computed, they will modify the |
349 |
default ambient value in a moving average, with the specified weight |
350 |
assigned to the initial value given on the command and all other |
351 |
weights set to 1. |
352 |
If a value of 0 is given with this option, then the initial ambient |
353 |
value is never modified. |
354 |
This is the safest value for scenes with large differences in |
355 |
indirect contributions, such as when both indoor and outdoor |
356 |
(daylight) areas are visible. |
357 |
.TP |
358 |
.BI -ab \ N |
359 |
Set the number of ambient bounces to |
360 |
.I N. |
361 |
This is the maximum number of diffuse bounces |
362 |
computed by the indirect calculation. |
363 |
A value of zero implies no indirect calculation. |
364 |
.TP |
365 |
.BI -ar \ res |
366 |
Set the ambient resolution to |
367 |
.I res. |
368 |
This number will determine the maximum density of ambient values |
369 |
used in interpolation. |
370 |
Error will start to increase on surfaces spaced closer than |
371 |
the scene size divided by the ambient resolution. |
372 |
The maximum ambient value density is the scene size times the |
373 |
ambient accuracy (see the |
374 |
.I \-aa |
375 |
option below) divided by the ambient resolution. |
376 |
The scene size can be determined using |
377 |
.I getinfo(1) |
378 |
with the |
379 |
.I \-d |
380 |
option on the input octree. |
381 |
.TP |
382 |
.BI -aa \ acc |
383 |
Set the ambient accuracy to |
384 |
.I acc. |
385 |
This value will approximately equal the error |
386 |
from indirect illuminance interpolation. |
387 |
A value of zero implies no interpolation. |
388 |
.TP |
389 |
.BI -ad \ N |
390 |
Set the number of ambient divisions to |
391 |
.I N. |
392 |
The error in the Monte Carlo calculation of indirect |
393 |
illuminance will be inversely proportional to the square |
394 |
root of this number. |
395 |
A value of zero implies no indirect calculation. |
396 |
.TP |
397 |
.BI -as \ N |
398 |
Set the number of ambient super-samples to |
399 |
.I N. |
400 |
Super-samples are applied only to the ambient divisions which |
401 |
show a significant change. |
402 |
.TP |
403 |
.BI -af \ fname |
404 |
Set the ambient file to |
405 |
.I fname. |
406 |
This is where indirect illuminance will be stored and retrieved. |
407 |
Normally, indirect illuminance values are kept in memory and |
408 |
lost when the program finishes or dies. |
409 |
By using a file, different invocations can share illuminance |
410 |
values, saving time in the computation. |
411 |
The ambient file is in a machine-independent binary format |
412 |
which can be examined with |
413 |
.I lookamb(1). |
414 |
.IP |
415 |
The ambient file may also be used as a means of communication and |
416 |
data sharing between simultaneously executing processes. |
417 |
The same file may be used by multiple processes, possibly running on |
418 |
different machines and accessing the file via the network (ie. |
419 |
.I nfs(4)). |
420 |
The network lock manager |
421 |
.I lockd(8) |
422 |
is used to insure that this information is used consistently. |
423 |
.IP |
424 |
If any calculation parameters are changed or the scene |
425 |
is modified, the old ambient file should be removed so that |
426 |
the calculation can start over from scratch. |
427 |
For convenience, the original ambient parameters are listed in the |
428 |
header of the ambient file. |
429 |
.I Getinfo(1) |
430 |
may be used to print out this information. |
431 |
.TP |
432 |
.BI -ae \ mod |
433 |
Append |
434 |
.I mod |
435 |
to the ambient exclude list, |
436 |
so that it will not be considered during the indirect calculation. |
437 |
This is a hack for speeding the indirect computation by |
438 |
ignoring certain objects. |
439 |
Any object having |
440 |
.I mod |
441 |
as its modifier will get the default ambient |
442 |
level rather than a calculated value. |
443 |
Any number of excluded modifiers may be given, but each |
444 |
must appear in a separate option. |
445 |
.TP |
446 |
.BI -ai \ mod |
447 |
Add |
448 |
.I mod |
449 |
to the ambient include list, |
450 |
so that it will be considered during the indirect calculation. |
451 |
The program can use either an include list or an exclude |
452 |
list, but not both. |
453 |
.TP |
454 |
.BI -aE \ file |
455 |
Same as |
456 |
.I \-ae, |
457 |
except read modifiers to be excluded from |
458 |
.I file. |
459 |
The RAYPATH environment variable determines which directories are |
460 |
searched for this file. |
461 |
The modifier names are separated by white space in the file. |
462 |
.TP |
463 |
.BI -aI \ file |
464 |
Same as |
465 |
.I \-ai, |
466 |
except read modifiers to be included from |
467 |
.I file. |
468 |
.TP |
469 |
.BI -me " rext gext bext" |
470 |
Set the global medium extinction coefficient to the indicated color, |
471 |
in units of 1/distance (distance in world coordinates). |
472 |
Light will be scattered or absorbed over distance according to |
473 |
this value. |
474 |
The ratio of scattering to total scattering plus absorption is set |
475 |
by the albedo parameter, described below. |
476 |
.TP |
477 |
.BI -ma " ralb galb balb" |
478 |
Set the global medium albedo to the given value between 0\00\00 |
479 |
and 1\01\01. |
480 |
A zero value means that all light not transmitted by the medium |
481 |
is absorbed. |
482 |
A unitary value means that all light not transmitted by the medium |
483 |
is scattered in some new direction. |
484 |
The isotropy of scattering is determined by the Heyney-Greenstein |
485 |
parameter, described below. |
486 |
.TP |
487 |
.BI \-mg \ gecc |
488 |
Set the medium Heyney-Greenstein eccentricity parameter to |
489 |
.I gecc. |
490 |
This parameter determines how strongly scattering favors the forward |
491 |
direction. |
492 |
A value of 0 indicates perfectly isotropic scattering. |
493 |
As this parameter approaches 1, scattering tends to prefer the |
494 |
forward direction. |
495 |
.TP |
496 |
.BI \-ms \ sampdist |
497 |
Set the medium sampling distance to |
498 |
.I sampdist, |
499 |
in world coordinate units. |
500 |
During source scattering, this will be the average distance between |
501 |
adjacent samples. |
502 |
A value of 0 means that only one sample will be taken per light |
503 |
source within a given scattering volume. |
504 |
.TP |
505 |
.BI -lr \ N |
506 |
Limit reflections to a maximum of |
507 |
.I N. |
508 |
.TP |
509 |
.BI -lw \ frac |
510 |
Limit the weight of each ray to a minimum of |
511 |
.I frac. |
512 |
During ray-tracing, a record is kept of the final contribution |
513 |
a ray would have to the image. |
514 |
If it is less then the specified minimum, the ray is not traced. |
515 |
.TP |
516 |
.BR -ld |
517 |
Boolean switch to limit ray distance. |
518 |
If this option is set, then rays will only be traced as far as the |
519 |
magnitude of each direction vector. |
520 |
Otherwise, vector magnitude is ignored and rays are traced to infinity. |
521 |
.TP |
522 |
.BI -e \ efile |
523 |
Send error messages and progress reports to |
524 |
.I efile |
525 |
instead of the standard error. |
526 |
.TP |
527 |
.BR \-w |
528 |
Boolean switch to suppress warning messages. |
529 |
.TP |
530 |
.BI \-P \ pfile |
531 |
Execute in a persistent mode, using |
532 |
.I pfile |
533 |
as the control file. |
534 |
Persistent execution means that after reaching end-of-file on |
535 |
its input, |
536 |
.I rtrace |
537 |
will fork a child process that will wait for another |
538 |
.I rtrace |
539 |
command with the same |
540 |
.I \-P |
541 |
option to attach to it. |
542 |
(Note that since the rest of the command line options will be those |
543 |
of the original invocation, it is not necessary to give any arguments |
544 |
besides |
545 |
.I \-P |
546 |
for subsequent calls.) |
547 |
Killing the process is achieved with the |
548 |
.I kill(1) |
549 |
command. |
550 |
(The process ID in the first line of |
551 |
.I pfile |
552 |
may be used to identify the waiting |
553 |
.I rtrace |
554 |
process.) |
555 |
This option may be used with the |
556 |
.I \-fr |
557 |
option of |
558 |
.I pinterp(1) |
559 |
to avoid the cost of starting up |
560 |
.I rtrace |
561 |
many times. |
562 |
.TP |
563 |
.BI \-PP \ pfile |
564 |
Execute in continuous-forking persistent mode, using |
565 |
.I pfile |
566 |
as the control file. |
567 |
The difference between this option and the |
568 |
.I \-P |
569 |
option described above is the creation of multiple duplicate |
570 |
processes to handle any number of attaches. |
571 |
This provides a simple and reliable mechanism of memory sharing |
572 |
on most multiprocessing platforms, since the |
573 |
.I fork(2) |
574 |
system call will share memory on a copy-on-write basis. |
575 |
.SH EXAMPLES |
576 |
To compute radiance values for the rays listed in samples.inp: |
577 |
.IP "" .2i |
578 |
rtrace -ov scene.oct < samples.inp > radiance.out |
579 |
.PP |
580 |
To compute illuminance values at locations selected with the 't' |
581 |
command of |
582 |
.I ximage(1): |
583 |
.IP "" .2i |
584 |
ximage scene.pic | rtrace -h -x 1 -i scene.oct | rcalc -e '$1=47.4*$1+120*$2+11.6*$3' |
585 |
.PP |
586 |
To record the object identifier corresponding to each pixel in an image: |
587 |
.IP "" .2i |
588 |
vwrays -fd scene.pic | rtrace -fda `vwrays -d scene.pic` -os scene.oct |
589 |
.PP |
590 |
To compute an image with an unusual view mapping: |
591 |
.IP "" .2i |
592 |
cnt 640 480 | rcalc -e 'xr:640;yr:480' -f unusual_view.cal | rtrace |
593 |
-x 640 -y 480 -fac scene.oct > unusual.pic |
594 |
.SH ENVIRONMENT |
595 |
RAYPATH the directories to check for auxiliary files. |
596 |
.SH FILES |
597 |
/tmp/rtXXXXXX common header information for picture sequence |
598 |
.SH DIAGNOSTICS |
599 |
If the program terminates from an input related error, the exit status |
600 |
will be 1. |
601 |
A system related error results in an exit status of 2. |
602 |
If the program receives a signal that is caught, it will exit with a status |
603 |
of 3. |
604 |
In each case, an error message will be printed to the standard error, or |
605 |
to the file designated by the |
606 |
.I \-e |
607 |
option. |
608 |
.SH AUTHOR |
609 |
Greg Ward |
610 |
.SH "SEE ALSO" |
611 |
getinfo(1), lookamb(1), oconv(1), pfilt(1), pinterp(1), |
612 |
pvalue(1), rpict(1), rvu(1), vwrays(1), ximage(1) |