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