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

# User Rev Content
1 rschregle 1.20 .\" RCSid "$Id: rpict.1,v 1.19 2015/05/26 10:00:46 greg Exp $"
2 greg 1.1 .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 greg 1.12 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 greg 1.1 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 greg 1.12 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 greg 1.1 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 greg 1.5 The length of this vector indicates the focal distance as needed by the
101     .I \-pd
102     option, described below.
103 greg 1.1 .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 greg 1.11 A value of \-1 would be to the left.
164 greg 1.1 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 greg 1.3 which may be a picture or a file created by rvu (with the "view" command).
178 greg 1.1 .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 greg 1.4 .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 greg 1.1 .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 greg 1.11 direct jitter by setting \-ps to 1.
275 greg 1.1 .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 greg 1.15 .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 greg 1.1 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 greg 1.16 With this switch off, back faces of all objects will be invisible
369     to view rays.
370 greg 1.1 This is dangerous unless the model was constructed such that
371 greg 1.16 all surface normals face outward.
372 greg 1.1 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 greg 1.18 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 rschregle 1.20 This value defaults to 1 in photon mapping mode (see
412 greg 1.18 .I -ap
413 rschregle 1.20 below), implying that global photon irradiance is always computed via
414 greg 1.18 .I one
415 rschregle 1.20 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 greg 1.1 .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 greg 1.7 .BI -ae \ mod
491 greg 1.1 Append
492 greg 1.7 .I mod
493 greg 1.1 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 greg 1.7 .I mod
499 greg 1.1 as its modifier will get the default ambient
500     level rather than a calculated value.
501 greg 1.7 Any number of excluded modifiers may be given, but each
502 greg 1.1 must appear in a separate option.
503     .TP
504 greg 1.7 .BI -ai \ mod
505 greg 1.1 Add
506 greg 1.7 .I mod
507 greg 1.1 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 greg 1.7 except read modifiers to be excluded from
516 greg 1.1 .I file.
517     The RAYPATH environment variable determines which directories are
518     searched for this file.
519 greg 1.7 The modifier names are separated by white space in the file.
520 greg 1.1 .TP
521     .BI -aI \ file
522     Same as
523     .I \-ai,
524 greg 1.7 except read modifiers to be included from
525 greg 1.1 .I file.
526     .TP
527 greg 1.18 .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 rschregle 1.20 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 greg 1.18 .TP
578 greg 1.1 .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 greg 1.10 .BR \-u
625     Boolean switch to control uncorrelated random sampling.
626 greg 1.9 When "off", a low-discrepancy sequence is used, which reduces
627 greg 1.17 variance but can result in a dithered appearance in specular highlights.
628 greg 1.9 When "on", pure Monte Carlo sampling is used in all calculations.
629     .TP
630 greg 1.1 .BI -lr \ N
631     Limit reflections to a maximum of
632 greg 1.14 .I N,
633     if N is a positive integer.
634 greg 1.8 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 greg 1.14 of reflections past which Russian roulette will be used.
642 greg 1.8 In scenes with dielectrics and total internal reflection,
643     a setting of 0 (no limit) may cause a stack overflow.
644 greg 1.1 .TP
645     .BI -lw \ frac
646     Limit the weight of each ray to a minimum of
647     .I frac.
648 greg 1.8 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 greg 1.1 .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 greg 1.11 or when the process receives a continue (\-CONT) signal (see
845 greg 1.1 .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 greg 1.13 rpict \-vp 10 5 3 \-vd 1 \-.5 0 scene.oct > scene.hdr
859 greg 1.1 .PP
860 greg 1.13 rpict \-S 1 \-o frame%02d.hdr scene.oct < keyframes.vf
861 greg 1.18 .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 greg 1.1 .SH ENVIRONMENT
869     RAYPATH the directories to check for auxiliary files.
870     .SH FILES
871 greg 1.6 /tmp/rtXXXXXX common header information for picture sequence
872 greg 1.1 .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 greg 1.18 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)