1 |
.\" RCSid "$Id: rpict.1,v 1.19 2015/05/26 10:00:46 greg Exp $" |
2 |
.TH RPICT 1 2/26/99 RADIANCE |
3 |
.SH NAME |
4 |
rpict - generate a RADIANCE picture |
5 |
.SH SYNOPSIS |
6 |
.B rpict |
7 |
[ |
8 |
.B options |
9 |
] |
10 |
[ |
11 |
.B $EVAR |
12 |
] |
13 |
[ |
14 |
.B @file |
15 |
] |
16 |
[ |
17 |
.B octree |
18 |
] |
19 |
.br |
20 |
.B "rpict [ options ] \-defaults" |
21 |
.SH DESCRIPTION |
22 |
.I Rpict |
23 |
generates a picture from the RADIANCE scene given in |
24 |
.I octree |
25 |
and sends it to the standard output. |
26 |
If no |
27 |
.I octree |
28 |
is given, the standard input is read. |
29 |
(The octree may also be specified as the output of a command |
30 |
enclosed in quotes and preceded by a `!'.)\0 |
31 |
Options specify the viewing parameters as well as |
32 |
giving some control over the calculation. |
33 |
Options may be given on the command line and/or read from the |
34 |
environment and/or read from a file. |
35 |
A command argument beginning with a dollar sign ('$') is immediately |
36 |
replaced by the contents of the given environment variable. |
37 |
A command argument beginning with an at sign ('@') is immediately |
38 |
replaced by the contents of the given file. |
39 |
.PP |
40 |
In the second form shown above, the default values |
41 |
for the options (modified by those options present) |
42 |
are printed with a brief explanation. |
43 |
.PP |
44 |
Most options are followed by one or more arguments, which must be |
45 |
separated from the option and each other by white space. |
46 |
The exceptions to this rule are the |
47 |
.I \-vt |
48 |
option and the boolean options. |
49 |
Normally, the appearance of a boolean option causes a feature to |
50 |
be "toggled", that is switched from off to on or on to off |
51 |
depending on its previous state. |
52 |
Boolean options may also be set |
53 |
explicitly by following them immediately with a '+' or '-', meaning |
54 |
on or off, respectively. |
55 |
Synonyms for '+' are any of the characters "yYtT1", and synonyms |
56 |
for '-' are any of the characters "nNfF0". |
57 |
All other characters will generate an error. |
58 |
.TP 10n |
59 |
.BI -vt t |
60 |
Set view type to |
61 |
.I t. |
62 |
If |
63 |
.I t |
64 |
is 'v', a perspective view is selected. |
65 |
If |
66 |
.I t |
67 |
is 'l', a parallel view is used. |
68 |
A cylindrical panorma may be selected by setting |
69 |
.I t |
70 |
to the letter 'c'. |
71 |
This view is like a standard perspective vertically, but projected |
72 |
on a cylinder horizontally (like a soupcan's-eye view). |
73 |
Three fisheye views are provided as well; 'h' yields a hemispherical fisheye |
74 |
view, 'a' results in angular fisheye distortion, and 's' |
75 |
results in a planisphere (stereographic) projection. |
76 |
A hemispherical fisheye is a projection of the hemisphere onto a circle. |
77 |
The maximum view angle for this type is 180 degrees. |
78 |
An angular fisheye view is defined such that distance from the center of |
79 |
the image is proportional to the angle from the central view direction. |
80 |
An angular fisheye can display a full 360 degrees. |
81 |
A planisphere fisheye view maintains angular relationships between lines, |
82 |
and is commonly used for sun path analysis. |
83 |
This is more commonly known as a |
84 |
"stereographic projection," but we avoid the term here so as not to |
85 |
confuse it with a stereoscopic pair. |
86 |
A planisphere fisheye can display up to (but not including) 360 degrees, |
87 |
although distortion becomes extreme as this limit is approached. |
88 |
Note that there is no space between the view type |
89 |
option and its single letter argument. |
90 |
.TP |
91 |
.BI -vp " x y z" |
92 |
Set the view point to |
93 |
.I "x y z". |
94 |
This is the focal point of a perspective view or the |
95 |
center of a parallel projection. |
96 |
.TP |
97 |
.BI -vd " xd yd zd" |
98 |
Set the view direction vector to |
99 |
.I "xd yd zd". |
100 |
The length of this vector indicates the focal distance as needed by the |
101 |
.I \-pd |
102 |
option, described below. |
103 |
.TP |
104 |
.BI -vu " xd yd zd" |
105 |
Set the view up vector (vertical direction) to |
106 |
.I "xd yd zd". |
107 |
.TP |
108 |
.BI -vh \ val |
109 |
Set the view horizontal size to |
110 |
.I val. |
111 |
For a perspective projection (including fisheye views), |
112 |
.I val |
113 |
is the horizontal field of view (in degrees). |
114 |
For a parallel projection, |
115 |
.I val |
116 |
is the view width in world coordinates. |
117 |
.TP |
118 |
.BI -vv \ val |
119 |
Set the view vertical size to |
120 |
.I val. |
121 |
.TP |
122 |
.BI -vo \ val |
123 |
Set the view fore clipping plane at a distance of |
124 |
.I val |
125 |
from the view point. |
126 |
The plane will be perpendicular to the view direction for |
127 |
perspective and parallel view types. |
128 |
For fisheye view types, the clipping plane is actually a clipping |
129 |
sphere, centered on the view point with radius |
130 |
.I val. |
131 |
Objects in front of this imaginary surface will not be visible. |
132 |
This may be useful for seeing through walls (to get a longer |
133 |
perspective from an exterior view point) or for incremental |
134 |
rendering. |
135 |
A value of zero implies no foreground clipping. |
136 |
A negative value produces some interesting effects, since it creates an |
137 |
inverted image for objects behind the viewpoint. |
138 |
This possibility is provided mostly for the purpose of rendering |
139 |
stereographic holograms. |
140 |
.TP |
141 |
.BI -va \ val |
142 |
Set the view aft clipping plane at a distance of |
143 |
.I val |
144 |
from the view point. |
145 |
Like the view fore plane, it will be perpendicular to the view |
146 |
direction for perspective and parallel view types. |
147 |
For fisheye view types, the clipping plane is actually a clipping |
148 |
sphere, centered on the view point with radius |
149 |
.I val. |
150 |
Objects behind this imaginary surface will not be visible. |
151 |
A value of zero means no aft clipping, and is the only way to see |
152 |
infinitely distant objects such as the sky. |
153 |
.TP |
154 |
.BI -vs \ val |
155 |
Set the view shift to |
156 |
.I val. |
157 |
This is the amount the actual image will be shifted to the right of |
158 |
the specified view. |
159 |
This is option is useful for generating skewed perspectives or |
160 |
rendering an image a piece at a time. |
161 |
A value of 1 means that the rendered image starts just to the right of |
162 |
the normal view. |
163 |
A value of \-1 would be to the left. |
164 |
Larger or fractional values are permitted as well. |
165 |
.TP |
166 |
.BI -vl \ val |
167 |
Set the view lift to |
168 |
.I val. |
169 |
This is the amount the actual image will be lifted up from the |
170 |
specified view, similar to the |
171 |
.I \-vs |
172 |
option. |
173 |
.TP |
174 |
.BI -vf \ file |
175 |
Get view parameters from |
176 |
.I file, |
177 |
which may be a picture or a file created by rvu (with the "view" command). |
178 |
.TP |
179 |
.BI -x \ res |
180 |
Set the maximum x resolution to |
181 |
.I res. |
182 |
.TP |
183 |
.BI -y \ res |
184 |
Set the maximum y resolution to |
185 |
.I res. |
186 |
.TP |
187 |
.BI -pa \ rat |
188 |
Set the pixel aspect ratio (height over width) to |
189 |
.I rat. |
190 |
Either the x or the y resolution will be reduced so that the pixels have |
191 |
this ratio for the specified view. |
192 |
If |
193 |
.I rat |
194 |
is zero, then the x and y resolutions will adhere to the given maxima. |
195 |
.TP |
196 |
.BI -ps \ size |
197 |
Set the pixel sample spacing to the integer |
198 |
.I size. |
199 |
This specifies the sample spacing (in pixels) for adaptive subdivision |
200 |
on the image plane. |
201 |
.TP |
202 |
.BI -pt \ frac |
203 |
Set the pixel sample tolerance to |
204 |
.I frac. |
205 |
If two samples differ by more than this amount, a third |
206 |
sample is taken between them. |
207 |
.TP |
208 |
.BI -pj \ frac |
209 |
Set the pixel sample jitter to |
210 |
.I frac. |
211 |
Distributed ray-tracing performs anti-aliasing by randomly sampling |
212 |
over pixels. |
213 |
A value of one will randomly distribute samples over full |
214 |
pixels. |
215 |
A value of zero samples pixel centers only. |
216 |
A value between zero and one is usually best |
217 |
for low-resolution images. |
218 |
.TP |
219 |
.BI -pm \ frac |
220 |
Set the pixel motion blur to |
221 |
.I frac. |
222 |
In an animated sequence, the exact view will be blurred between the previous |
223 |
view and the next view as though a shutter were open this fraction of a |
224 |
frame time. |
225 |
(See the |
226 |
.I \-S |
227 |
option regarding animated sequences.)\0 |
228 |
The first view will be blurred according to the difference between the |
229 |
initial view set on the command line and the first view taken from the |
230 |
standard input. |
231 |
It is not advisable to use this option in combination with the |
232 |
.I pmblur(1) |
233 |
program, since one takes the place of the other. |
234 |
However, it may improve results with |
235 |
.I pmblur |
236 |
to use a very small fraction with the |
237 |
.I \-pm |
238 |
option, to avoid the ghosting effect of too few time samples. |
239 |
.TP |
240 |
.BI -pd \ dia |
241 |
Set the pixel depth-of-field aperture to a diameter of |
242 |
.I dia |
243 |
(in world coordinates). |
244 |
This will be used in conjunction with the view focal distance, indicated |
245 |
by the length of the view direction vector given in the |
246 |
.I \-vd |
247 |
option. |
248 |
It is not advisable to use this option in combination with the |
249 |
.I pdfblur(1) |
250 |
program, since one takes the place of the other. |
251 |
However, it may improve results with |
252 |
.I pdfblur |
253 |
to use a very small fraction with the |
254 |
.I \-pd |
255 |
option, to avoid the ghosting effect of too few samples. |
256 |
.TP |
257 |
.BI -dj \ frac |
258 |
Set the direct jittering to |
259 |
.I frac. |
260 |
A value of zero samples each source at specific sample points |
261 |
(see the |
262 |
.I \-ds |
263 |
option below), giving a smoother but somewhat less accurate |
264 |
rendering. |
265 |
A positive value causes rays to be distributed over each |
266 |
source sample according to its size, resulting in more accurate |
267 |
penumbras. |
268 |
This option should never be greater than 1, and may even |
269 |
cause problems (such as speckle) when the value is smaller. |
270 |
A warning about aiming failure will issued if |
271 |
.I frac |
272 |
is too large. |
273 |
It is usually wise to turn off image sampling when using |
274 |
direct jitter by setting \-ps to 1. |
275 |
.TP |
276 |
.BI -ds \ frac |
277 |
Set the direct sampling ratio to |
278 |
.I frac. |
279 |
A light source will be subdivided until |
280 |
the width of each sample area divided by the distance |
281 |
to the illuminated point is below this ratio. |
282 |
This assures accuracy in regions close to large area sources |
283 |
at a slight computational expense. |
284 |
A value of zero turns source subdivision off, sending at most one |
285 |
shadow ray to each light source. |
286 |
.TP |
287 |
.BI -dt \ frac |
288 |
Set the direct threshold to |
289 |
.I frac. |
290 |
Shadow testing will stop when the potential contribution of at least |
291 |
the next and at most all remaining light source samples is less than |
292 |
this fraction of the accumulated value. |
293 |
(See the |
294 |
.I \-dc |
295 |
option below.)\0 |
296 |
The remaining light source contributions are approximated |
297 |
statistically. |
298 |
A value of zero means that all light source samples will be tested for shadow. |
299 |
.TP |
300 |
.BI \-dc \ frac |
301 |
Set the direct certainty to |
302 |
.I frac. |
303 |
A value of one guarantees that the absolute accuracy of the direct calculation |
304 |
will be equal to or better than that given in the |
305 |
.I \-dt |
306 |
specification. |
307 |
A value of zero only insures that all shadow lines resulting in a contrast |
308 |
change greater than the |
309 |
.I \-dt |
310 |
specification will be calculated. |
311 |
.TP |
312 |
.BI -dr \ N |
313 |
Set the number of relays for secondary sources to |
314 |
.I N. |
315 |
A value of 0 means that secondary sources will be ignored. |
316 |
A value of 1 means that sources will be made into first generation |
317 |
secondary sources; a value of 2 means that first generation |
318 |
secondary sources will also be made into second generation secondary |
319 |
sources, and so on. |
320 |
.TP |
321 |
.BI -dp \ D |
322 |
Set the secondary source presampling density to D. |
323 |
This is the number of samples per steradian |
324 |
that will be used to determine ahead of time whether or not |
325 |
it is worth following shadow rays through all the reflections and/or |
326 |
transmissions associated with a secondary source path. |
327 |
A value of 0 means that the full secondary source path will always |
328 |
be tested for shadows if it is tested at all. |
329 |
.TP |
330 |
.BR \-dv |
331 |
Boolean switch for light source visibility. |
332 |
With this switch off, sources will be black when viewed directly |
333 |
although they will still participate in the direct calculation. |
334 |
This option may be desirable in conjunction with the |
335 |
.I \-i |
336 |
option so that light sources do not appear in the output. |
337 |
.TP |
338 |
.BI -ss \ samp |
339 |
Set the specular sampling to |
340 |
.I samp. |
341 |
For values less than 1, this is the degree to which the highlights |
342 |
are sampled for rough specular materials. |
343 |
A value greater than one causes multiple ray samples to be sent |
344 |
to reduce noise at a commmesurate cost. |
345 |
A value of zero means that no jittering will take place, and all |
346 |
reflections will appear sharp even when they should be diffuse. |
347 |
This may be desirable when used in combination with image sampling |
348 |
(see |
349 |
.I \-ps |
350 |
option above) to obtain faster renderings. |
351 |
.TP |
352 |
.BI -st \ frac |
353 |
Set the specular sampling threshold to |
354 |
.I frac. |
355 |
This is the minimum fraction of reflection or transmission, under which |
356 |
no specular sampling is performed. |
357 |
A value of zero means that highlights will always be sampled by |
358 |
tracing reflected or transmitted rays. |
359 |
A value of one means that specular sampling is never used. |
360 |
Highlights from light sources will always be correct, but |
361 |
reflections from other surfaces will be approximated using an |
362 |
ambient value. |
363 |
A sampling threshold between zero and one offers a compromise between image |
364 |
accuracy and rendering time. |
365 |
.TP |
366 |
.BR -bv |
367 |
Boolean switch for back face visibility. |
368 |
With this switch off, back faces of all objects will be invisible |
369 |
to view rays. |
370 |
This is dangerous unless the model was constructed such that |
371 |
all surface normals face outward. |
372 |
Although turning off back face visibility does not save much |
373 |
computation time under most circumstances, it may be useful as a |
374 |
tool for scene debugging, or for seeing through one-sided walls from |
375 |
the outside. |
376 |
.TP |
377 |
.BI -av " red grn blu" |
378 |
Set the ambient value to a radiance of |
379 |
.I "red grn blu". |
380 |
This is the final value used in place of an |
381 |
indirect light calculation. |
382 |
If the number of ambient bounces is one or greater and the ambient |
383 |
value weight is non-zero (see |
384 |
.I -aw |
385 |
and |
386 |
.I -ab |
387 |
below), this value may be modified by the computed indirect values |
388 |
to improve overall accuracy. |
389 |
.TP |
390 |
.BI -aw \ N |
391 |
Set the relative weight of the ambient value given with the |
392 |
.I -av |
393 |
option to |
394 |
.I N. |
395 |
As new indirect irradiances are computed, they will modify the |
396 |
default ambient value in a moving average, with the specified weight |
397 |
assigned to the initial value given on the command and all other |
398 |
weights set to 1. |
399 |
If a value of 0 is given with this option, then the initial ambient |
400 |
value is never modified. |
401 |
This is the safest value for scenes with large differences in |
402 |
indirect contributions, such as when both indoor and outdoor |
403 |
(daylight) areas are visible. |
404 |
.TP |
405 |
.BI -ab \ N |
406 |
Set the number of ambient bounces to |
407 |
.I N. |
408 |
This is the maximum number of diffuse bounces computed by the indirect |
409 |
calculation. A value of zero implies no indirect calculation. |
410 |
.IP |
411 |
This value defaults to 1 in photon mapping mode (see |
412 |
.I -ap |
413 |
below), implying that global photon irradiance is always computed via |
414 |
.I one |
415 |
ambient bounce; this behaviour applies to any positive number of ambient |
416 |
bounces, regardless of the actual value specified. A negative value enables |
417 |
a preview mode that directly visualises the irradiance from the global |
418 |
photon map without any ambient bounces. |
419 |
.TP |
420 |
.BI -ar \ res |
421 |
Set the ambient resolution to |
422 |
.I res. |
423 |
This number will determine the maximum density of ambient values |
424 |
used in interpolation. |
425 |
Error will start to increase on surfaces spaced closer than |
426 |
the scene size divided by the ambient resolution. |
427 |
The maximum ambient value density is the scene size times the |
428 |
ambient accuracy (see the |
429 |
.I \-aa |
430 |
option below) divided by the ambient resolution. |
431 |
The scene size can be determined using |
432 |
.I getinfo(1) |
433 |
with the |
434 |
.I \-d |
435 |
option on the input octree. |
436 |
A value of zero is interpreted as unlimited resolution. |
437 |
.TP |
438 |
.BI -aa \ acc |
439 |
Set the ambient accuracy to |
440 |
.I acc. |
441 |
This value will approximately equal the error |
442 |
from indirect illuminance interpolation. |
443 |
A value of zero implies no interpolation. |
444 |
.TP |
445 |
.BI -ad \ N |
446 |
Set the number of ambient divisions to |
447 |
.I N. |
448 |
The error in the Monte Carlo calculation of indirect |
449 |
illuminance will be inversely proportional to the square |
450 |
root of this number. |
451 |
A value of zero implies no indirect calculation. |
452 |
.TP |
453 |
.BI -as \ N |
454 |
Set the number of ambient super-samples to |
455 |
.I N. |
456 |
Super-samples are applied only to the ambient divisions which |
457 |
show a significant change. |
458 |
.TP |
459 |
.BI -af \ fname |
460 |
Set the ambient file to |
461 |
.I fname. |
462 |
This is where indirect illuminance will be stored and retrieved. |
463 |
Normally, indirect illuminance values are kept in memory and |
464 |
lost when the program finishes or dies. |
465 |
By using a file, different invocations can share illuminance |
466 |
values, saving time in the computation. |
467 |
Also, by creating an ambient file during a low resolution rendering, |
468 |
better results can be obtained in a second high resolution pass. |
469 |
The ambient file is in a machine-independent binary format |
470 |
which may be examined with |
471 |
.I lookamb(1). |
472 |
.IP |
473 |
The ambient file may also be used as a means of communication and |
474 |
data sharing between simultaneously executing processes. |
475 |
The same file may be used by multiple processes, possibly running on |
476 |
different machines and accessing the file via the network (ie. |
477 |
.I nfs(4)). |
478 |
The network lock manager |
479 |
.I lockd(8) |
480 |
is used to insure that this information is used consistently. |
481 |
.IP |
482 |
If any calculation parameters are changed or the scene |
483 |
is modified, the old ambient file should be removed so that |
484 |
the calculation can start over from scratch. |
485 |
For convenience, the original ambient parameters are listed in the |
486 |
header of the ambient file. |
487 |
.I Getinfo(1) |
488 |
may be used to print out this information. |
489 |
.TP |
490 |
.BI -ae \ mod |
491 |
Append |
492 |
.I mod |
493 |
to the ambient exclude list, |
494 |
so that it will not be considered during the indirect calculation. |
495 |
This is a hack for speeding the indirect computation by |
496 |
ignoring certain objects. |
497 |
Any object having |
498 |
.I mod |
499 |
as its modifier will get the default ambient |
500 |
level rather than a calculated value. |
501 |
Any number of excluded modifiers may be given, but each |
502 |
must appear in a separate option. |
503 |
.TP |
504 |
.BI -ai \ mod |
505 |
Add |
506 |
.I mod |
507 |
to the ambient include list, |
508 |
so that it will be considered during the indirect calculation. |
509 |
The program can use either an include list or an exclude |
510 |
list, but not both. |
511 |
.TP |
512 |
.BI -aE \ file |
513 |
Same as |
514 |
.I \-ae, |
515 |
except read modifiers to be excluded from |
516 |
.I file. |
517 |
The RAYPATH environment variable determines which directories are |
518 |
searched for this file. |
519 |
The modifier names are separated by white space in the file. |
520 |
.TP |
521 |
.BI -aI \ file |
522 |
Same as |
523 |
.I \-ai, |
524 |
except read modifiers to be included from |
525 |
.I file. |
526 |
.TP |
527 |
.BI -ap " file [bwidth1 [bwidth2]]" |
528 |
Enable photon mapping mode. Loads a photon map generated with |
529 |
.I mkpmap(1) |
530 |
from |
531 |
.I file, |
532 |
and evaluates the indirect irradiance depending on the photon type |
533 |
(automagically detected) using density estimates with a bandwidth of |
534 |
.I bwidth1 |
535 |
photons, or the default bandwidth if none is specified (a warning will be |
536 |
issued in this case). |
537 |
.IP |
538 |
Global photon irradiance is evaluated as part of the ambient calculation (see |
539 |
.I \-ab |
540 |
above), caustic photon irradiance is evaluated at primary rays, and |
541 |
indirect inscattering in |
542 |
.I mist |
543 |
is accounted for by volume photons. |
544 |
.IP |
545 |
Additionally specifying |
546 |
.I bwidth2 |
547 |
enables bias compensation for the density estimates with a |
548 |
minimum and maximum bandwidth of |
549 |
.I bwidth1 |
550 |
and |
551 |
.I bwidth2, |
552 |
respectively. |
553 |
.IP |
554 |
Global photon irradiance may be optionally precomputed by |
555 |
.I mkpmap(1), |
556 |
in which case the bandwidth, if specified, is ignored, as the nearest photon |
557 |
is invariably looked up. |
558 |
.IP |
559 |
Using direct photons replaces the direct calculation with density estimates |
560 |
for debugging and validation of photon emission. |
561 |
.TP |
562 |
.BI -am " frac" |
563 |
Maximum search radius for photon map lookups. Without this option, an |
564 |
initial maximum search radius is estimated for each photon map from the |
565 |
average photon distance to the distribution's centre of gravity. It is then |
566 |
adapted to the photon density in subsequent lookups. This option imposes a |
567 |
global fixed maximum search radius for |
568 |
.I all |
569 |
photon maps, thus defeating the automatic adaptation. It is useful when |
570 |
multiple warnings about short photon lookups are issued. Note that this |
571 |
option does not conflict with the bandwidth specified with the |
572 |
.I \-ap |
573 |
option; the number of photons found will not exceed the latter, but may be |
574 |
lower if the maximum search radius contains fewer photons, thus resulting in |
575 |
short lookups. Setting this radius too large, on the other hand, may |
576 |
degrade performance. |
577 |
.TP |
578 |
.BI -me " rext gext bext" |
579 |
Set the global medium extinction coefficient to the indicated color, |
580 |
in units of 1/distance (distance in world coordinates). |
581 |
Light will be scattered or absorbed over distance according to |
582 |
this value. |
583 |
The ratio of scattering to total scattering plus absorption is set |
584 |
by the albedo parameter, described below. |
585 |
.TP |
586 |
.BI -ma " ralb galb balb" |
587 |
Set the global medium albedo to the given value between 0\00\00 |
588 |
and 1\01\01. |
589 |
A zero value means that all light not transmitted by the medium |
590 |
is absorbed. |
591 |
A unitary value means that all light not transmitted by the medium |
592 |
is scattered in some new direction. |
593 |
The isotropy of scattering is determined by the Heyney-Greenstein |
594 |
parameter, described below. |
595 |
.TP |
596 |
.BI \-mg \ gecc |
597 |
Set the medium Heyney-Greenstein eccentricity parameter to |
598 |
.I gecc. |
599 |
This parameter determines how strongly scattering favors the forward |
600 |
direction. |
601 |
A value of 0 indicates perfectly isotropic scattering. |
602 |
As this parameter approaches 1, scattering tends to prefer the |
603 |
forward direction. |
604 |
.TP |
605 |
.BI \-ms \ sampdist |
606 |
Set the medium sampling distance to |
607 |
.I sampdist, |
608 |
in world coordinate units. |
609 |
During source scattering, this will be the average distance between |
610 |
adjacent samples. |
611 |
A value of 0 means that only one sample will be taken per light |
612 |
source within a given scattering volume. |
613 |
.TP |
614 |
.BR \-i |
615 |
Boolean switch to compute irradiance rather than radiance values. |
616 |
This only affects the final result, substituting a Lambertian |
617 |
surface and multiplying the radiance by pi. |
618 |
Glass and other transparent surfaces are ignored during this stage. |
619 |
Light sources still appear with their original radiance values, |
620 |
though the |
621 |
.I \-dv |
622 |
option (above) may be used to override this. |
623 |
.TP |
624 |
.BR \-u |
625 |
Boolean switch to control uncorrelated random sampling. |
626 |
When "off", a low-discrepancy sequence is used, which reduces |
627 |
variance but can result in a dithered appearance in specular highlights. |
628 |
When "on", pure Monte Carlo sampling is used in all calculations. |
629 |
.TP |
630 |
.BI -lr \ N |
631 |
Limit reflections to a maximum of |
632 |
.I N, |
633 |
if N is a positive integer. |
634 |
If |
635 |
.I N |
636 |
is zero, then Russian roulette is used for ray |
637 |
termination, and the |
638 |
.I -lw |
639 |
setting (below) must be positive. |
640 |
If N is a negative integer, then this sets the upper limit |
641 |
of reflections past which Russian roulette will be used. |
642 |
In scenes with dielectrics and total internal reflection, |
643 |
a setting of 0 (no limit) may cause a stack overflow. |
644 |
.TP |
645 |
.BI -lw \ frac |
646 |
Limit the weight of each ray to a minimum of |
647 |
.I frac. |
648 |
During ray-tracing, a record is kept of the estimated contribution |
649 |
(weight) a ray would have in the image. |
650 |
If this weight is less than the specified minimum and the |
651 |
.I -lr |
652 |
setting (above) is positive, the ray is not traced. |
653 |
Otherwise, Russian roulette is used to |
654 |
continue rays with a probability equal to the ray weight |
655 |
divided by the given |
656 |
.I frac. |
657 |
.TP |
658 |
.BI -S \ seqstart |
659 |
Instead of generating a single picture based only on the view |
660 |
parameters given on the command line, this option causes |
661 |
.I rpict |
662 |
to read view options from the standard input and for each line |
663 |
containing a valid view specification, generate a corresponding |
664 |
picture. |
665 |
This option is most useful for generating animated sequences, though |
666 |
it may also be used to control rpict from a remote process for |
667 |
network-distributed rendering. |
668 |
.I Seqstart |
669 |
is a positive integer that will be associated with the first output |
670 |
frame, and incremented for successive output frames. |
671 |
By default, each frame is concatenated to the output stream, but it |
672 |
is possible to change this action using the |
673 |
.I \-o |
674 |
option (described below). |
675 |
Multiple frames may be later extracted from the output using |
676 |
.I ra_rgbe(1). |
677 |
.IP |
678 |
Note that the octree may not be read from the standard input when |
679 |
using this option. |
680 |
.TP |
681 |
.BI -o \ fspec |
682 |
Send the picture(s) to the file(s) given by |
683 |
.I fspec |
684 |
instead of the standard output. |
685 |
If this option is used in combination with |
686 |
.I \-S |
687 |
and |
688 |
.I fspec |
689 |
contains an integer field for |
690 |
.I printf(3) |
691 |
(eg. "%03d") then the actual output file name will include |
692 |
the current frame number. |
693 |
.I Rpict |
694 |
will not allow a picture file to be clobbered (overwritten) |
695 |
with this option. |
696 |
If an image in a sequence already exists |
697 |
.I (\-S |
698 |
option), |
699 |
.I rpict |
700 |
will skip until it reaches an image that doesn't, or the end of |
701 |
the sequence. |
702 |
This is useful for running rpict on multiple machines or processors |
703 |
to render the same sequence, as each process will skip to the next |
704 |
frame that needs rendering. |
705 |
.TP |
706 |
.BI -r \ fn |
707 |
Recover pixel information from the file |
708 |
.I fn. |
709 |
If the program gets killed during picture generation, the information |
710 |
may be recovered using this option. |
711 |
The view parameters and picture dimensions are also recovered from |
712 |
.I fn |
713 |
if possible. |
714 |
The other options should be identical to those which created |
715 |
.I fn, |
716 |
or an inconsistent picture may result. |
717 |
If |
718 |
.I fn |
719 |
is identical to the file specification given with the |
720 |
.I \-o |
721 |
option, |
722 |
.I rpict |
723 |
will rename the file prior to copying its contents. |
724 |
This insures that the old file is not overwritten accidentally. |
725 |
(See also the |
726 |
.I \-ro |
727 |
option, below.)\0 |
728 |
.IP |
729 |
If |
730 |
.I fn |
731 |
is an integer and the recover option is used in combination with the |
732 |
.I \-S |
733 |
option, then |
734 |
.I rpict |
735 |
skips a number of view specifications on its input equal to the |
736 |
difference between |
737 |
.I fn |
738 |
and |
739 |
.I seqstart. |
740 |
.I Rpict |
741 |
then performs a recovery operation on the file constructed from the |
742 |
frame number |
743 |
.I fn |
744 |
and the output file specification given with the |
745 |
.I \-o |
746 |
option. |
747 |
This provides a convenient mechanism for recovering in the middle of |
748 |
an aborted picture sequence. |
749 |
.IP |
750 |
The recovered file |
751 |
will be removed if the operation is successful. |
752 |
If the recover operation fails (due to lack of disk space) |
753 |
and the output file and recover file specifications |
754 |
are the same, then the original information may be left in a |
755 |
renamed temporary file. |
756 |
(See FILES section, below.)\0 |
757 |
.TP |
758 |
.BI -ro \ fspec |
759 |
This option causes pixel information to be recovered from and |
760 |
subsequently returned to the picture file |
761 |
.I fspec. |
762 |
The effect is the same as specifying identical recover and output |
763 |
file names with the |
764 |
.I \-r |
765 |
and |
766 |
.I \-o |
767 |
options. |
768 |
.TP |
769 |
.BI -z \ fspec |
770 |
Write pixel distances out to the file |
771 |
.I fspec. |
772 |
The values are written as short floats, one per pixel in scanline order, |
773 |
as required by |
774 |
.I pinterp(1). |
775 |
Similar to the |
776 |
.I \-o |
777 |
option, the actual file name will be constructed using |
778 |
.I printf |
779 |
and the frame number from the |
780 |
.I \-S |
781 |
option. |
782 |
If used with the |
783 |
.I \-r |
784 |
option, |
785 |
.I \-z |
786 |
also recovers information from an aborted rendering. |
787 |
.TP |
788 |
.BI \-P \ pfile |
789 |
Execute in a persistent mode, using |
790 |
.I pfile |
791 |
as the control file. |
792 |
This option must be used together with |
793 |
.I \-S, |
794 |
and is incompatible with the recover option |
795 |
.I (\-r). |
796 |
Persistent execution means that after reaching end-of-file on |
797 |
its input, |
798 |
.I rpict |
799 |
will fork a child process that will wait for another |
800 |
.I rpict |
801 |
command with the same |
802 |
.I \-P |
803 |
option to attach to it. |
804 |
(Note that since the rest of the command line options will be those |
805 |
of the original invocation, it is not necessary to give any arguments |
806 |
besides |
807 |
.I \-P |
808 |
for subsequent calls.) |
809 |
Killing the process is achieved with the |
810 |
.I kill(1) |
811 |
command. |
812 |
(The process ID in the first line of |
813 |
.I pfile |
814 |
may be used to identify the waiting |
815 |
.I rpict |
816 |
process.) |
817 |
This option may be less useful than the |
818 |
.I \-PP |
819 |
variation, explained below. |
820 |
.TP |
821 |
.BI \-PP \ pfile |
822 |
Execute in continuous-forking persistent mode, using |
823 |
.I pfile |
824 |
as the control file. |
825 |
The difference between this option and the |
826 |
.I \-P |
827 |
option described above is the creation of multiple duplicate |
828 |
processes to handle any number of attaches. |
829 |
This provides a simple and reliable mechanism of memory sharing |
830 |
on most multiprocessing platforms, since the |
831 |
.I fork(2) |
832 |
system call will share memory on a copy-on-write basis. |
833 |
This option may be used with |
834 |
.I rpiece(1) |
835 |
to efficiently render a single image using multiple processors |
836 |
on the same host. |
837 |
.TP |
838 |
.BI -t \ sec |
839 |
Set the time between progress reports to |
840 |
.I sec. |
841 |
A progress report writes the number of rays traced, the percentage |
842 |
completed, and the CPU usage to the standard error. |
843 |
Reports are given either automatically after the specified interval, |
844 |
or when the process receives a continue (\-CONT) signal (see |
845 |
.I kill(1)). |
846 |
A value of zero turns automatic reporting off. |
847 |
.TP |
848 |
.BI -e \ efile |
849 |
Send error messages and progress reports to |
850 |
.I efile |
851 |
instead of the standard error. |
852 |
.TP |
853 |
.BR \-w |
854 |
Boolean switch for warning messages. |
855 |
The default is to print warnings, so the first appearance of |
856 |
this option turns them off. |
857 |
.SH EXAMPLE |
858 |
rpict \-vp 10 5 3 \-vd 1 \-.5 0 scene.oct > scene.hdr |
859 |
.PP |
860 |
rpict \-S 1 \-o frame%02d.hdr scene.oct < keyframes.vf |
861 |
.PP |
862 |
To render ambient illuminance in photon mapping mode from a global photon |
863 |
map global.pm via one ambient bounce, and from a caustic photon map |
864 |
caustic.pm: |
865 |
.IP "" .2i |
866 |
rpict -ab 1 -ap global.pm 50 -ap caustic.pm 50 -vf scene.vf scene.oct > |
867 |
scene.hdr |
868 |
.SH ENVIRONMENT |
869 |
RAYPATH the directories to check for auxiliary files. |
870 |
.SH FILES |
871 |
/tmp/rtXXXXXX common header information for picture sequence |
872 |
.br |
873 |
rfXXXXXX temporary name for recover file |
874 |
.SH DIAGNOSTICS |
875 |
If the program terminates from an input related error, the exit status |
876 |
will be 1. |
877 |
A system related error results in an exit status of 2. |
878 |
If the program receives a signal that is caught, it will exit with a status |
879 |
of 3. |
880 |
In each case, an error message will be printed to the standard error, or |
881 |
to the file designated by the |
882 |
.I \-e |
883 |
option. |
884 |
.SH AUTHOR |
885 |
Greg Ward |
886 |
.SH "SEE ALSO" |
887 |
getinfo(1), lookamb(1), mkpmap(1), oconv(1), pdfblur(1), pfilt(1), |
888 |
pinterp(1), pmblur(1), printf(3), ra_rgbe(1), rad(1), rtrace(1), rvu(1) |