--- ray/doc/man/man1/rpict.1 2014/01/25 18:27:39 1.16 +++ ray/doc/man/man1/rpict.1 2020/05/19 16:00:58 1.26 @@ -1,4 +1,4 @@ -.\" RCSid "$Id: rpict.1,v 1.16 2014/01/25 18:27:39 greg Exp $" +.\" RCSid "$Id: rpict.1,v 1.26 2020/05/19 16:00:58 greg Exp $" .TH RPICT 1 2/26/99 RADIANCE .SH NAME rpict - generate a RADIANCE picture @@ -211,10 +211,10 @@ Set the pixel sample jitter to Distributed ray-tracing performs anti-aliasing by randomly sampling over pixels. A value of one will randomly distribute samples over full -pixels. +pixels, and is not really recommended due to the tendency of +samples to (nearly) coincide. A value of zero samples pixel centers only. -A value between zero and one is usually best -for low-resolution images. +A value around 0.5-0.8 is typical. .TP .BI -pm \ frac Set the pixel motion blur to @@ -405,9 +405,17 @@ indirect contributions, such as when both indoor and o .BI -ab \ N Set the number of ambient bounces to .I N. -This is the maximum number of diffuse bounces -computed by the indirect calculation. -A value of zero implies no indirect calculation. +This is the maximum number of diffuse bounces computed by the indirect +calculation. A value of zero implies no indirect calculation. +.IP +This value defaults to 1 in photon mapping mode (see +.I -ap +below), implying that global photon irradiance is always computed via +.I one +ambient bounce; this behaviour applies to any positive number of ambient +bounces, regardless of the actual value specified. A negative value enables +a preview mode that directly visualises the irradiance from the global +photon map without any ambient bounces. .TP .BI -ar \ res Set the ambient resolution to @@ -456,8 +464,10 @@ Normally, indirect illuminance values are kept in memo lost when the program finishes or dies. By using a file, different invocations can share illuminance values, saving time in the computation. -Also, by creating an ambient file during a low resolution rendering, -better results can be obtained in a second high resolution pass. +Also, by creating an ambient file during a low-resolution rendering, +better results can be obtained in a second high-resolution pass. +(It is a good idea to keep all of the calculation parameters the same, +changing only the dimensions of the output picture.)\0 The ambient file is in a machine-independent binary format which may be examined with .I lookamb(1). @@ -516,6 +526,82 @@ Same as except read modifiers to be included from .I file. .TP +.BI -ap " file [bwidth1 [bwidth2]]" +Enable photon mapping mode. Loads a photon map generated with +.I mkpmap(1) +from +.I file, +and evaluates the indirect irradiance depending on the photon type +(automagically detected) using density estimates with a bandwidth of +.I bwidth1 +photons, or the default bandwidth if none is specified (a warning will be +issued in this case). +.IP +Global photon irradiance is evaluated as part of the ambient calculation (see +.I \-ab +above), caustic photon irradiance is evaluated at primary rays, and +indirect inscattering in +.I mist +is accounted for by volume photons. Contribution photons are treated as +global photons by +.I rpict. +.IP +Additionally specifying +.I bwidth2 +enables bias compensation for the density estimates with a +minimum and maximum bandwidth of +.I bwidth1 +and +.I bwidth2, +respectively. +.IP +Global photon irradiance may be optionally precomputed by +.I mkpmap(1), +in which case the bandwidth, if specified, is ignored, as the nearest photon +is invariably looked up. +.IP +Using direct photons replaces the direct calculation with density estimates +for debugging and validation of photon emission. +.TP +.BI -am " frac" +Maximum search radius for photon map lookups. Without this option, an +initial maximum search radius is estimated for each photon map from the +average photon distance to the distribution's centre of gravity. It is then +adapted to the photon density in subsequent lookups. This option imposes a +global fixed maximum search radius for +.I all +photon maps, thus defeating the automatic adaptation. It is useful when +multiple warnings about short photon lookups are issued. Note that this +option does not conflict with the bandwidth specified with the +.I \-ap +option; the number of photons found will not exceed the latter, but may be +lower if the maximum search radius contains fewer photons, thus resulting in +short lookups. Setting this radius too large, on the other hand, may +degrade performance. +.TP +.BI -ac " pagesize" +Set the photon cache page size when using out-of-core photon mapping. The +photon cache reduces disk I/O incurred by on-demand loading (paging) of +photons, and thus increases performance. This +is expressed as a (float) multiple of the density estimate bandwidth +specified with +.I \-ap +under the assumption that photon lookups are local to a cache page. Cache +performance is sensitive to this parameter: larger pagesizes will reduce the +paging frequency at the expense of higher latency when paging does occur. +Sensible values are in the range 4 (default) to 16. +.TP +.BI -aC " cachesize" +Set the total number of photons cached when using out-of-core photon +mapping, taking into account the pagesize specified by +.I \-ac. +Note that this is approximate as the number of cache pages is rounded to +the nearest prime. This allows adapting the cache to the available physical +memory. Cache performance is less sensitive to this parameter, and reasonable +performance can obtained with as few as 10k photons. The default is 1M. This +option recognises multiplier suffixes (k = 1e3, M = 1e6), both in upper and +lower case. +.TP .BI -me " rext gext bext" Set the global medium extinction coefficient to the indicated color, in units of 1/distance (distance in world coordinates). @@ -565,7 +651,7 @@ option (above) may be used to override this. .BR \-u Boolean switch to control uncorrelated random sampling. When "off", a low-discrepancy sequence is used, which reduces -variance but can result in a brushed appearance in specular highlights. +variance but can result in a dithered appearance in specular highlights. When "on", pure Monte Carlo sampling is used in all calculations. .TP .BI -lr \ N @@ -578,8 +664,8 @@ is zero, then Russian roulette is used for ray termination, and the .I -lw setting (below) must be positive. -If N is a negative integer, then this sets the upper limit -of reflections past which Russian roulette will be used. +If N is a negative integer, then this limits the maximum +number of reflections even with Russian roulette. In scenes with dielectrics and total internal reflection, a setting of 0 (no limit) may cause a stack overflow. .TP @@ -799,6 +885,13 @@ this option turns them off. rpict \-vp 10 5 3 \-vd 1 \-.5 0 scene.oct > scene.hdr .PP rpict \-S 1 \-o frame%02d.hdr scene.oct < keyframes.vf +.PP +To render ambient illuminance in photon mapping mode from a global photon +map global.pm via one ambient bounce, and from a caustic photon map +caustic.pm: +.IP "" .2i +rpict -ab 1 -ap global.pm 50 -ap caustic.pm 50 -vf scene.vf scene.oct > +scene.hdr .SH ENVIRONMENT RAYPATH the directories to check for auxiliary files. .SH FILES @@ -818,5 +911,5 @@ option. .SH AUTHOR Greg Ward .SH "SEE ALSO" -getinfo(1), lookamb(1), oconv(1), pdfblur(1), pfilt(1), pinterp(1), pmblur(1), -printf(3), ra_rgbe(1), rad(1), rtrace(1), rvu(1) +getinfo(1), lookamb(1), mkpmap(1), oconv(1), pdfblur(1), pfilt(1), +pinterp(1), pmblur(1), printf(3), ra_rgbe(1), rad(1), rpiece(1), rtpict(1), rtrace(1), rvu(1)