ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/radiance/ray/doc/man/man1/rpict.1
Revision: 1.20
Committed: Fri Jun 5 08:49:01 2015 UTC (9 years, 11 months ago) by rschregle
Branch: MAIN
CVS Tags: rad5R0
Changes since 1.19: +21 -11 lines
Log Message:
Revised -am and -ab options, the latter defaulting to 1 in pmap mode

File Contents

# Content
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)