--- ray/doc/man/man1/rcontrib.1	2012/06/14 22:42:21	1.1
+++ ray/doc/man/man1/rcontrib.1	2019/02/22 19:42:27	1.16
@@ -1,5 +1,5 @@
-.\" RCSid "$Id: rcontrib.1,v 1.1 2012/06/14 22:42:21 greg Exp $"
-.TH RTCONTRIB 1 5/25/05 RADIANCE
+.\" RCSid "$Id: rcontrib.1,v 1.16 2019/02/22 19:42:27 greg Exp $"
+.TH RCONTRIB 1 5/25/05 RADIANCE
 .SH NAME
 rcontrib - compute contribution coefficients in a RADIANCE scene
 .SH SYNOPSIS
@@ -21,6 +21,8 @@ rcontrib - compute contribution coefficients in a RADI
 ][
 .B "\-o ospec"
 ][
+.B "\-p p1=V1,p2=V2"
+][
 .B "\-b binv"
 ][
 .B "\-bn nbins"
@@ -42,7 +44,7 @@ rtrace options
 .br
 .B "rcontrib [ options ] \-defaults"
 .SH DESCRIPTION
-.I Rtcontrib
+.I Rcontrib
 computes ray coefficients
 for objects whose modifiers are named in one or more
 .I \-m
@@ -61,7 +63,6 @@ character.)\0
 If the
 .I \-n
 option is specified with a value greater than 1, multiple
-.I rtrace
 processes will be used to accelerate computation on a shared
 memory machine.
 Note that there is no benefit to using more processes
@@ -102,9 +103,9 @@ The
 option tells
 .I rcontrib
 how many rays to accumulate for each record.
-The default value is 1, meaning a full record will be produced for
+The default value is one, meaning a full record will be produced for
 each input ray.
-For values greater than 1, contributions will be averaged together
+For values greater than one, contributions will be averaged together
 over the given number of input rays.
 If set to zero, only a single record will be produced at the very
 end, corresponding to the sum of all rays given on the input
@@ -114,8 +115,9 @@ This is equivalent to passing all the output records t
 to sum RGB values together, but is much more efficient.
 Using this option, it is possible to reverse sampling, sending rays from
 a parallel source such as the sun to a diffuse surface, for example.
-Note that output flushing via zero-direction rays is disabled
-for accumulated evaluations.
+Note that output flushing via zero-direction rays is disabled with
+.I \-c
+set to zero.
 .PP
 The output of
 .I rcontrib
@@ -128,12 +130,9 @@ More generally,
 can be used to compute arbitrary input-output relationships in optical
 systems, such as luminaires, light pipes, and shading devices.
 .PP
-.I Rtcontrib
-calls
-.I rtrace(1)
-with the \-oTW (or \-oTV) option to calculate the daughter ray
-contributions for each input ray, and the output tallies
-are sent to one or more destinations according to the given
+.I Rcontrib
+sends the accumulated rays tallies
+to one or more destinations according to the given
 .I \-o
 specification.
 If a destination begins with an exclamation mark ('!'), then
@@ -159,10 +158,13 @@ The
 option may be used to further define
 a "bin number" within each object if finer resolution is needed, and
 this will be applied to a "%d" format in the output file
-specification if present.
+specification if present. 
+(The final integer will be offset incrementally
+if the output is a RADIANCE picture and more than one modifier has
+the same format specification.)\0
 The actual bin number is computed at run time based on ray direction
 and surface intersection, as described below.
-If the number of bins is known in advance, it should be specified with the
+The number of bins must be specified in advance with the
 .I \-bn
 option, and this is critical for output files containing multiple values
 per record.
@@ -172,10 +174,10 @@ it has been defined via a previous
 or
 .I \-e
 option.
-Since bin numbers start from 0, the bin count is always equal to
-the last bin plus 1.
-Set the this value to 0 if the bin count is unknown (the default).
+Since bin numbers start from zero, the bin count is always equal to
+the last bin plus one.
 The most recent
+.I \-p,
 .I \-b,
 .I \-bn
 and
@@ -189,15 +191,14 @@ and
 .I \-y
 if the
 .I \-c
-is 0, when they control the resolution string
+is zero, when they control the resolution string
 produced in the corresponding output.
 .PP
 If a
 .I \-b
 expression is defined for a particular modifier,
 the bin number will be evaluated at run time for each
-ray contribution from
-.I rtrace.
+ray contribution.
 Specifically, each ray's world intersection point will be assigned to
 the variables Px, Py, and Pz, and the normalized ray direction
 will be assigned to Dx, Dy, and Dz.
@@ -206,8 +207,17 @@ These parameters may be combined with definitions give
 arguments and files read using the
 .I \-f
 option.
+Additional parameter values that apply only to this modifier may be specified
+with a
+.I \-p
+option, which contains a list of variable names and assigned values, separated
+by commas or semicolons.
 The computed bin value will be
 rounded to the nearest whole number.
+(Negative bin values will be silently ignored.)\0
+For a single bin, you may specify
+.I "\-b 0",
+which is the default.
 This mechanism allows the user to define precise regions or directions
 they wish to accumulate, such as the Tregenza sky discretization,
 which would be otherwise impossible to specify
@@ -216,7 +226,7 @@ The rules and predefined functions available for these
 described in the
 .I rcalc(1)
 man page.
-Unlike
+Like
 .I rcalc,
 .I rcontrib
 will search the RADIANCE library directories for each file given in a
@@ -271,6 +281,25 @@ A command argument beginning with a dollar sign ('$') 
 replaced by the contents of the given environment variable.
 A command argument beginning with an at sign ('@') is immediately
 replaced by the contents of the given file.
+.PP
+.I Rcontrib
+supports light source contributions from photon maps generated by
+.I mkpmap(1)
+with its
+.I -apC
+option. Enabling photon mapping is described in the
+.I rtrace 
+man page along with its relevant settings. In photon mapping mode,
+.I rcontrib
+only supports contributions from light sources, not arbitrary modifiers.
+The
+.I -b
+option is supported along with its associated ray variables, as
+discussed above. Ray coefficients are also supported via the
+.I \-V-
+option. Using fewer photons than there are light sources for the photon
+density estimates results in omitted contributions, thus the bandwidth
+is clamped accordingly and a warning is issued. 
 .SH EXAMPLES
 To compute the proportional contributions from sources modified
 by "light1" vs. "light2" on a set of illuminance values:
@@ -291,12 +320,25 @@ pcomb \-c 100 90 75 c_light1.hdr \-c 50 55 57 c_light2
 .PP
 To compute an array of illuminance contributions according to a Tregenza sky:
 .IP "" .2i
-rcontrib \-I+ \-b tbin \-o sky.dat \-m skyglow \-b 0 \-o ground.dat \-m groundglow
-@render.opt \-f tregenza.cal scene.oct < test.dat
+rcontrib \-I+ \-f tregenza.cal \-b tbin \-bn Ntbins \-o sky.dat \-m skyglow
+\-b 0 \-o ground.dat \-m groundglow @render.opt scene.oct < test.dat
+.PP
+To perform an annual simulation of 365 daily sun positions in photon mapping
+mode:
+.IP "" .2i
+rcontrib \-I+ \-h \-V \-fo \-o c_%s.dat \-M lights \-ap contrib.pm 365
+scene.oct < test.dat,
 .SH ENVIRONMENT
 RAYPATH		path to search for \-f and \-M files
+.SH BUGS
+We do not currently compute contributions or coefficients properly
+in scenes with participating media.
+A single warning will be issued if a scattering or absorbing medium
+is detected.
 .SH AUTHOR
 Greg Ward
 .SH "SEE ALSO"
-cnt(1), genklemsamp(1), getinfo(1), pcomb(1), pfilt(1), ra_rgbe(1),
-rcalc(1), rpict(1), rsensor(1), rtrace(1), total(1), vwrays(1), ximage(1)
+cnt(1), genklemsamp(1), getinfo(1), mkpmap(1), pcomb(1), pfilt(1), 
+ra_rgbe(1), rcalc(1), rfluxmtx(1), rmtxop(1), rpict(1), rsensor(1), 
+rtrace(1), total(1), vwrays(1), ximage(1)
+