--- ray/doc/man/man1/rpict.1	2005/05/31 18:01:08	1.8
+++ ray/doc/man/man1/rpict.1	2019/01/11 21:12:24	1.24
@@ -1,4 +1,4 @@
-.\" RCSid "$Id: rpict.1,v 1.8 2005/05/31 18:01:08 greg Exp $"
+.\" RCSid "$Id: rpict.1,v 1.24 2019/01/11 21:12:24 greg Exp $"
 .TH RPICT 1 2/26/99 RADIANCE
 .SH NAME
 rpict - generate a RADIANCE picture
@@ -70,13 +70,21 @@ A cylindrical panorma may be selected by setting
 to the letter 'c'.
 This view is like a standard perspective vertically, but projected
 on a cylinder horizontally (like a soupcan's-eye view).
-Two fisheye views are provided as well; 'h' yields a hemispherical fisheye
-view and 'a' results in angular fisheye distortion.
+Three fisheye views are provided as well; 'h' yields a hemispherical fisheye
+view, 'a' results in angular fisheye distortion, and 's'
+results in a planisphere (stereographic) projection.
 A hemispherical fisheye is a projection of the hemisphere onto a circle.
 The maximum view angle for this type is 180 degrees.
 An angular fisheye view is defined such that distance from the center of
 the image is proportional to the angle from the central view direction.
 An angular fisheye can display a full 360 degrees.
+A planisphere fisheye view maintains angular relationships between lines,
+and is commonly used for sun path analysis.
+This is more commonly known as a
+"stereographic projection," but we avoid the term here so as not to
+confuse it with a stereoscopic pair.
+A planisphere fisheye can display up to (but not including) 360 degrees,
+although distortion becomes extreme as this limit is approached.
 Note that there is no space between the view type
 option and its single letter argument.
 .TP
@@ -152,7 +160,7 @@ This is option is useful for generating skewed perspec
 rendering an image a piece at a time.
 A value of 1 means that the rendered image starts just to the right of
 the normal view.
-A value of -1 would be to the left.
+A value of \-1 would be to the left.
 Larger or fractional values are permitted as well.
 .TP
 .BI -vl \ val
@@ -263,7 +271,7 @@ A warning about aiming failure will issued if
 .I frac
 is too large.
 It is usually wise to turn off image sampling when using
-direct jitter by setting -ps to 1.
+direct jitter by setting \-ps to 1.
 .TP
 .BI -ds \ frac
 Set the direct sampling ratio to
@@ -327,13 +335,13 @@ This option may be desirable in conjunction with the
 .I \-i
 option so that light sources do not appear in the output.
 .TP
-.BI -sj \ frac
-Set the specular sampling jitter to
-.I frac.
-This is the degree to which the highlights are sampled
-for rough specular materials.
-A value of one means that all highlights will be fully sampled
-using distributed ray tracing.
+.BI -ss \ samp
+Set the specular sampling to
+.I samp.
+For values less than 1, this is the degree to which the highlights
+are sampled for rough specular materials.
+A value greater than one causes multiple ray samples to be sent
+to reduce noise at a commmesurate cost.
 A value of zero means that no jittering will take place, and all
 reflections will appear sharp even when they should be diffuse.
 This may be desirable when used in combination with image sampling
@@ -357,15 +365,14 @@ accuracy and rendering time.
 .TP
 .BR -bv
 Boolean switch for back face visibility.
-With this switch off, back faces of opaque objects will be invisible
-to all rays.
+With this switch off, back faces of all objects will be invisible
+to view rays.
 This is dangerous unless the model was constructed such that
-all surface normals on opaque objects face outward.
+all surface normals face outward.
 Although turning off back face visibility does not save much
 computation time under most circumstances, it may be useful as a
 tool for scene debugging, or for seeing through one-sided walls from
 the outside.
-This option has no effect on transparent or translucent materials.
 .TP
 .BI -av " red grn blu"
 Set the ambient value to a radiance of
@@ -398,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
@@ -509,6 +524,86 @@ 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. In conjunction with the
+.I \-n
+option, this is the cache size
+.I per parallel process. 
+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).
@@ -555,17 +650,24 @@ though the
 .I \-dv
 option (above) may be used to override this.
 .TP
+.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 dithered appearance in specular highlights.
+When "on", pure Monte Carlo sampling is used in all calculations.
+.TP
 .BI -lr \ N
 Limit reflections to a maximum of
-.I N.
+.I N,
+if N is a positive integer.
 If
 .I N
 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 not 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
@@ -768,7 +870,7 @@ Set the time between progress reports to
 A progress report writes the number of rays traced, the percentage
 completed, and the CPU usage to the standard error.
 Reports are given either automatically after the specified interval,
-or when the process receives a continue (-CONT) signal (see
+or when the process receives a continue (\-CONT) signal (see
 .I kill(1)).
 A value of zero turns automatic reporting off.
 .TP
@@ -782,9 +884,16 @@ Boolean switch for warning messages.
 The default is to print warnings, so the first appearance of
 this option turns them off.
 .SH EXAMPLE
-rpict -vp 10 5 3 -vd 1 -.5 0 scene.oct > scene.pic
+rpict \-vp 10 5 3 \-vd 1 \-.5 0 scene.oct > scene.hdr
 .PP
-rpict -S 1 -o frame%02d.pic scene.oct < keyframes.vf
+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
@@ -804,5 +913,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)