--- ray/doc/man/man1/rpict.1	2014/02/18 12:13:38	1.17
+++ ray/doc/man/man1/rpict.1	2015/02/24 19:39:26	1.18
@@ -1,4 +1,4 @@
-.\" RCSid "$Id: rpict.1,v 1.17 2014/02/18 12:13:38 greg Exp $"
+.\" RCSid "$Id: rpict.1,v 1.18 2015/02/24 19:39:26 greg Exp $"
 .TH RPICT 1 2/26/99 RADIANCE
 .SH NAME
 rpict - generate a RADIANCE picture
@@ -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
+In photon mapping mode (see
+.I -ap
+below), a positive value implies that global photon irradiance is
+always computed via
+.I one
+ambient bounce. 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
@@ -516,6 +524,47 @@ 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.
+.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"
+Coefficient for maximum search radius for photon map lookups. The search 
+radius is automatically determined based on the average photon distance to the
+distribution's centre of gravity, and scaled by this coefficient. Increase this
+value if multiple warnings about short photon lookups are issued.
+.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).
@@ -799,6 +848,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 +874,6 @@ 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), rtrace(1), rvu(1)
+