ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/radiance/ray/doc/man/man1/rpict.1
(Generate patch)

Comparing ray/doc/man/man1/rpict.1 (file contents):
Revision 1.5 by greg, Tue Jan 18 01:13:23 2005 UTC vs.
Revision 1.30 by greg, Wed Nov 15 19:21:54 2023 UTC

# Line 18 | Line 18 | rpict - generate a RADIANCE picture
18   ]
19   .br
20   .B "rpict [ options ] \-defaults"
21 + .br
22 + .B "rpict \-features [feat1 ..]"
23   .SH DESCRIPTION
24   .I Rpict
25   generates a picture from the RADIANCE scene given in
# Line 41 | Line 43 | In the second form shown above, the default values
43   for the options (modified by those options present)
44   are printed with a brief explanation.
45   .PP
46 + In the third form, a list of supported features is sent
47 + to the standard output, one per line.
48 + If additional arguments follow, they are checked for presence in
49 + this list.
50 + If a feature includes subfeatures, these may be checked as well by
51 + specifying:
52 + .nf
53 +
54 +        rpict -features FeatName=subfeat1,subfeat2
55 +
56 + .fi
57 + If any named feature or subfeature is missing, an error is
58 + reported and the program returns an error status.
59 + If all of the named features are present, a zero status is returned.
60 + .PP
61   Most options are followed by one or more arguments, which must be
62   separated from the option and each other by white space.
63   The exceptions to this rule are the
# Line 70 | Line 87 | A cylindrical panorma may be selected by setting
87   to the letter 'c'.
88   This view is like a standard perspective vertically, but projected
89   on a cylinder horizontally (like a soupcan's-eye view).
90 < Two fisheye views are provided as well; 'h' yields a hemispherical fisheye
91 < view and 'a' results in angular fisheye distortion.
90 > Three fisheye views are provided as well; 'h' yields a hemispherical fisheye
91 > view, 'a' results in angular fisheye distortion, and 's'
92 > results in a planisphere (stereographic) projection.
93   A hemispherical fisheye is a projection of the hemisphere onto a circle.
94   The maximum view angle for this type is 180 degrees.
95   An angular fisheye view is defined such that distance from the center of
96   the image is proportional to the angle from the central view direction.
97   An angular fisheye can display a full 360 degrees.
98 + A planisphere fisheye view maintains angular relationships between lines,
99 + and is commonly used for sun path analysis.
100 + This is more commonly known as a
101 + "stereographic projection," but we avoid the term here so as not to
102 + confuse it with a stereoscopic pair.
103 + A planisphere fisheye can display up to (but not including) 360 degrees,
104 + although distortion becomes extreme as this limit is approached.
105   Note that there is no space between the view type
106   option and its single letter argument.
107   .TP
# Line 152 | Line 177 | This is option is useful for generating skewed perspec
177   rendering an image a piece at a time.
178   A value of 1 means that the rendered image starts just to the right of
179   the normal view.
180 < A value of -1 would be to the left.
180 > A value of \-1 would be to the left.
181   Larger or fractional values are permitted as well.
182   .TP
183   .BI -vl \ val
# Line 203 | Line 228 | Set the pixel sample jitter to
228   Distributed ray-tracing performs anti-aliasing by randomly sampling
229   over pixels.
230   A value of one will randomly distribute samples over full
231 < pixels.
231 > pixels, and is not really recommended due to the tendency of
232 > samples to (nearly) coincide.
233   A value of zero samples pixel centers only.
234 < A value between zero and one is usually best
209 < for low-resolution images.
234 > A value around 0.5-0.8 is typical.
235   .TP
236   .BI -pm \ frac
237   Set the pixel motion blur to
# Line 246 | Line 271 | to use a very small fraction with the
271   .I \-pd
272   option, to avoid the ghosting effect of too few samples.
273   .TP
274 + .BI -pc " xr yr xg yg xb yb xw yw"
275 + Use the specified chromaticity pairs for output primaries and white
276 + point rather than the standard RGB color space.
277 + .TP
278 + .BR \-pRGB
279 + Output standard RGB values (the default).
280 + .TP
281 + .BR \-pXYZ
282 + Output standard CIE XYZ tristimulus values rather than RGB.
283 + .TP
284   .BI -dj \ frac
285   Set the direct jittering to
286   .I frac.
# Line 263 | Line 298 | A warning about aiming failure will issued if
298   .I frac
299   is too large.
300   It is usually wise to turn off image sampling when using
301 < direct jitter by setting -ps to 1.
301 > direct jitter by setting \-ps to 1.
302   .TP
303   .BI -ds \ frac
304   Set the direct sampling ratio to
# Line 302 | Line 337 | change greater than the
337   specification will be calculated.
338   .TP
339   .BI -dr \ N
340 < Set the number of relays for secondary sources to
340 > Set the number of relays for virtual sources to
341   .I N.
342 < A value of 0 means that secondary sources will be ignored.
342 > A value of 0 means that virtual sources will be ignored.
343   A value of 1 means that sources will be made into first generation
344 < secondary sources; a value of 2 means that first generation
345 < secondary sources will also be made into second generation secondary
344 > virtual sources; a value of 2 means that first generation
345 > virtual sources will also be made into second generation virtual
346   sources, and so on.
347   .TP
348   .BI -dp \ D
349 < Set the secondary source presampling density to D.
349 > Set the virtual source presampling density to D.
350   This is the number of samples per steradian
351   that will be used to determine ahead of time whether or not
352   it is worth following shadow rays through all the reflections and/or
353 < transmissions associated with a secondary source path.
354 < A value of 0 means that the full secondary source path will always
353 > transmissions associated with a virtual source path.
354 > A value of 0 means that the full virtual source path will always
355   be tested for shadows if it is tested at all.
356   .TP
357   .BR \-dv
# Line 327 | Line 362 | This option may be desirable in conjunction with the
362   .I \-i
363   option so that light sources do not appear in the output.
364   .TP
365 < .BI -sj \ frac
366 < Set the specular sampling jitter to
367 < .I frac.
368 < This is the degree to which the highlights are sampled
369 < for rough specular materials.
370 < A value of one means that all highlights will be fully sampled
371 < using distributed ray tracing.
365 > .BI -ss \ samp
366 > Set the specular sampling to
367 > .I samp.
368 > For values less than 1, this is the degree to which the highlights
369 > are sampled for rough specular materials.
370 > A value greater than one causes multiple ray samples to be sent
371 > to reduce noise at a commmesurate cost.
372   A value of zero means that no jittering will take place, and all
373   reflections will appear sharp even when they should be diffuse.
374   This may be desirable when used in combination with image sampling
# Line 357 | Line 392 | accuracy and rendering time.
392   .TP
393   .BR -bv
394   Boolean switch for back face visibility.
395 < With this switch off, back faces of opaque objects will be invisible
396 < to all rays.
395 > With this switch off, back faces of all objects will be invisible
396 > to view rays.
397   This is dangerous unless the model was constructed such that
398 < all surface normals on opaque objects face outward.
398 > all surface normals face outward.
399   Although turning off back face visibility does not save much
400   computation time under most circumstances, it may be useful as a
401   tool for scene debugging, or for seeing through one-sided walls from
402   the outside.
368 This option has no effect on transparent or translucent materials.
403   .TP
404   .BI -av " red grn blu"
405   Set the ambient value to a radiance of
# Line 398 | Line 432 | indirect contributions, such as when both indoor and o
432   .BI -ab \ N
433   Set the number of ambient bounces to
434   .I N.
435 < This is the maximum number of diffuse bounces
436 < computed by the indirect calculation.
437 < A value of zero implies no indirect calculation.
435 > This is the maximum number of diffuse bounces computed by the indirect
436 > calculation. A value of zero implies no indirect calculation.
437 > .IP
438 > This value defaults to 1 in photon mapping mode (see
439 > .I -ap
440 > below), implying that global photon irradiance is always computed via
441 > .I one
442 > ambient bounce; this behaviour applies to any positive number of ambient
443 > bounces, regardless of the actual value specified.  A negative value enables
444 > a preview mode that directly visualises the irradiance from the global
445 > photon map without any ambient bounces.
446   .TP
447   .BI -ar \ res
448   Set the ambient resolution to
# Line 424 | Line 466 | A value of zero is interpreted as unlimited resolution
466   Set the ambient accuracy to
467   .I acc.
468   This value will approximately equal the error
469 < from indirect illuminance interpolation.
469 > from indirect irradiance interpolation.
470   A value of zero implies no interpolation.
471   .TP
472   .BI -ad \ N
473   Set the number of ambient divisions to
474   .I N.
475   The error in the Monte Carlo calculation of indirect
476 < illuminance will be inversely proportional to the square
476 > irradiance will be inversely proportional to the square
477   root of this number.
478   A value of zero implies no indirect calculation.
479   .TP
# Line 444 | Line 486 | show a significant change.
486   .BI -af \ fname
487   Set the ambient file to
488   .I fname.
489 < This is where indirect illuminance will be stored and retrieved.
490 < Normally, indirect illuminance values are kept in memory and
489 > This is where indirect irradiance will be stored and retrieved.
490 > Normally, indirect irradiance values are kept in memory and
491   lost when the program finishes or dies.
492 < By using a file, different invocations can share illuminance
492 > By using a file, different invocations can share irradiance
493   values, saving time in the computation.
494 < Also, by creating an ambient file during a low resolution rendering,
495 < better results can be obtained in a second high resolution pass.
494 > Also, by creating an ambient file during a low-resolution rendering,
495 > better results can be obtained in a second high-resolution pass.
496 > (It is a good idea to keep all of the calculation parameters the same,
497 > changing only the dimensions of the output picture.)\0
498   The ambient file is in a machine-independent binary format
499   which may be examined with
500   .I lookamb(1).
# Line 472 | Line 516 | header of the ambient file.
516   .I Getinfo(1)
517   may be used to print out this information.
518   .TP
519 < .BI -ae \ mat
519 > .BI -ae \ mod
520   Append
521 < .I mat
521 > .I mod
522   to the ambient exclude list,
523   so that it will not be considered during the indirect calculation.
524   This is a hack for speeding the indirect computation by
525   ignoring certain objects.
526   Any object having
527 < .I mat
527 > .I mod
528   as its modifier will get the default ambient
529   level rather than a calculated value.
530 < Any number of excluded materials may be given, but each
530 > Any number of excluded modifiers may be given, but each
531   must appear in a separate option.
532   .TP
533 < .BI -ai \ mat
533 > .BI -ai \ mod
534   Add
535 < .I mat
535 > .I mod
536   to the ambient include list,
537   so that it will be considered during the indirect calculation.
538   The program can use either an include list or an exclude
# Line 497 | Line 541 | list, but not both.
541   .BI -aE \ file
542   Same as
543   .I \-ae,
544 < except read materials to be excluded from
544 > except read modifiers to be excluded from
545   .I file.
546   The RAYPATH environment variable determines which directories are
547   searched for this file.
548 < The material names are separated by white space in the file.
548 > The modifier names are separated by white space in the file.
549   .TP
550   .BI -aI \ file
551   Same as
552   .I \-ai,
553 < except read materials to be included from
553 > except read modifiers to be included from
554   .I file.
555   .TP
556 + .BI -ap " file [bwidth1 [bwidth2]]"
557 + Enable photon mapping mode. Loads a photon map generated with
558 + .I mkpmap(1)
559 + from
560 + .I file,
561 + and evaluates the indirect irradiance depending on the photon type
562 + (automagically detected) using density estimates with a bandwidth of
563 + .I bwidth1
564 + photons, or the default bandwidth if none is specified (a warning will be
565 + issued in this case).
566 + .IP
567 + Global photon irradiance is evaluated as part of the ambient calculation (see
568 + .I \-ab
569 + above), caustic photon irradiance is evaluated at primary rays, and
570 + indirect inscattering in
571 + .I mist
572 + is accounted for by volume photons. Contribution photons are treated as
573 + global photons by
574 + .I rpict.
575 + .IP
576 + Additionally specifying
577 + .I bwidth2
578 + enables bias compensation for the density estimates with a
579 + minimum and maximum bandwidth of
580 + .I bwidth1
581 + and
582 + .I bwidth2,
583 + respectively.
584 + .IP
585 + Global photon irradiance may be optionally precomputed by
586 + .I mkpmap(1),
587 + in which case the bandwidth, if specified, is ignored, as the nearest photon
588 + is invariably looked up.
589 + .IP
590 + Using direct photons replaces the direct calculation with density estimates
591 + for debugging and validation of photon emission.
592 + .TP
593 + .BI -am " frac"
594 + Maximum search radius for photon map lookups.  Without this option, an
595 + initial maximum search radius is estimated for each photon map from the
596 + average photon distance to the distribution's centre of gravity.  It is then
597 + adapted to the photon density in subsequent lookups.  This option imposes a
598 + global fixed maximum search radius for
599 + .I all
600 + photon maps, thus defeating the automatic adaptation.  It is useful when
601 + multiple warnings about short photon lookups are issued.  Note that this
602 + option does not conflict with the bandwidth specified with the
603 + .I \-ap
604 + option; the number of photons found will not exceed the latter, but may be
605 + lower if the maximum search radius contains fewer photons, thus resulting in
606 + short lookups.  Setting this radius too large, on the other hand, may
607 + degrade performance.
608 + .TP
609 + .BI -ac " pagesize"
610 + Set the photon cache page size when using out-of-core photon mapping. The
611 + photon cache reduces disk I/O incurred by on-demand loading (paging) of
612 + photons, and thus increases performance. This
613 + is expressed as a (float) multiple of the density estimate bandwidth
614 + specified with
615 + .I \-ap
616 + under the assumption that photon lookups are local to a cache page. Cache
617 + performance is sensitive to this parameter: larger pagesizes will reduce the
618 + paging frequency at the expense of higher latency when paging does occur.
619 + Sensible values are in the range 4 (default) to 16.
620 + .TP
621 + .BI -aC " cachesize"
622 + Set the total number of photons cached when using out-of-core photon
623 + mapping, taking into account the pagesize specified by
624 + .I \-ac.
625 + Note that this is approximate as the number of cache pages is rounded to
626 + the nearest prime. This allows adapting the cache to the available physical
627 + memory. Cache performance is less sensitive to this parameter, and reasonable
628 + performance can obtained with as few as 10k photons. The default is 1M. This
629 + option recognises multiplier suffixes (k = 1e3, M = 1e6), both in upper and
630 + lower case.
631 + .TP
632   .BI -me " rext gext bext"
633   Set the global medium extinction coefficient to the indicated color,
634   in units of 1/distance (distance in world coordinates).
# Line 555 | Line 675 | though the
675   .I \-dv
676   option (above) may be used to override this.
677   .TP
678 + .BR \-u
679 + Boolean switch to control uncorrelated random sampling.
680 + When "off", a low-discrepancy sequence is used, which reduces
681 + variance but can result in a dithered appearance in specular highlights.
682 + When "on", pure Monte Carlo sampling is used in all calculations.
683 + .TP
684   .BI -lr \ N
685   Limit reflections to a maximum of
686 < .I N.
686 > .I N,
687 > if N is a positive integer.
688 > If
689 > .I N
690 > is zero, then Russian roulette is used for ray
691 > termination, and the
692 > .I -lw
693 > setting (below) must be positive.
694 > If N is a negative integer, then this limits the maximum
695 > number of reflections even with Russian roulette.
696 > In scenes with dielectrics and total internal reflection,
697 > a setting of 0 (no limit) may cause a stack overflow.
698   .TP
699   .BI -lw \ frac
700   Limit the weight of each ray to a minimum of
701   .I frac.
702 < During ray-tracing, a record is kept of the final contribution
703 < a ray would have to the image.
704 < If it is less then the specified minimum, the ray is not traced.
702 > During ray-tracing, a record is kept of the estimated contribution
703 > (weight) a ray would have in the image.
704 > If this weight is less than the specified minimum and the
705 > .I -lr
706 > setting (above) is positive, the ray is not traced.
707 > Otherwise, Russian roulette is used to
708 > continue rays with a probability equal to the ray weight
709 > divided by the given
710 > .I frac.
711   .TP
712 + .BI -cs \ Ns
713 + Use
714 + .I Ns
715 + bands for spectral sampling rather than the default RGB calculation space.
716 + The maximum setting is controlled by the compiler macro MAXCSAMP, and
717 + defaults to 24.
718 + Larger values for Ns will be reduced to MAXCSAMP.
719 + .TP
720 + .BI -cw " nmA nmB"
721 + Set extrema to the given wavelengths for spectral sampling.
722 + The default is 380 and 780 nanometers.
723 + The order specified does not matter.
724 + .TP
725   .BI -S \ seqstart
726   Instead of generating a single picture based only on the view
727   parameters given on the command line, this option causes
# Line 752 | Line 908 | Set the time between progress reports to
908   A progress report writes the number of rays traced, the percentage
909   completed, and the CPU usage to the standard error.
910   Reports are given either automatically after the specified interval,
911 < or when the process receives a continue (-CONT) signal (see
911 > or when the process receives a continue (\-CONT) signal (see
912   .I kill(1)).
913   A value of zero turns automatic reporting off.
914   .TP
# Line 766 | Line 922 | Boolean switch for warning messages.
922   The default is to print warnings, so the first appearance of
923   this option turns them off.
924   .SH EXAMPLE
925 < rpict -vp 10 5 3 -vd 1 -.5 0 scene.oct > scene.pic
925 > rpict \-vp 10 5 3 \-vd 1 \-.5 0 scene.oct > scene.hdr
926   .PP
927 < rpict -S 1 -o frame%02d.pic scene.oct < keyframes.vf
927 > rpict \-S 1 \-o frame%02d.hdr scene.oct < keyframes.vf
928 > .PP
929 > To render ambient irradiance in photon mapping mode from a global photon
930 > map global.pm via one ambient bounce, and from a caustic photon map
931 > caustic.pm:
932 > .IP "" .2i
933 > rpict -ab 1 -ap global.pm 50 -ap caustic.pm 50 -vf scene.vf scene.oct >
934 > scene.hdr
935   .SH ENVIRONMENT
936   RAYPATH         the directories to check for auxiliary files.
937   .SH FILES
938 < /usr/tmp/rtXXXXXX               common header information for picture sequence
938 > /tmp/rtXXXXXX           common header information for picture sequence
939   .br
940   rfXXXXXX                temporary name for recover file
941   .SH DIAGNOSTICS
# Line 788 | Line 951 | option.
951   .SH AUTHOR
952   Greg Ward
953   .SH "SEE ALSO"
954 < getinfo(1), lookamb(1), oconv(1), pdfblur(1), pfilt(1), pinterp(1), pmblur(1),
955 < printf(3), ra_rgbe(1), rad(1), rtrace(1), rvu(1)
954 > getinfo(1), lookamb(1), mkpmap(1), oconv(1), pdfblur(1), pfilt(1),
955 > pinterp(1), pmblur(1), printf(3), ra_rgbe(1), rad(1), rpiece(1), rtpict(1), rtrace(1), rvu(1)

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines