--- ray/doc/man/man1/rtcontrib.1	2005/05/26 21:03:22	1.4
+++ ray/doc/man/man1/rtcontrib.1	2009/06/14 18:21:58	1.22
@@ -1,21 +1,34 @@
-.\" RCSid "$Id: rtcontrib.1,v 1.4 2005/05/26 21:03:22 greg Exp $"
+.\" RCSid "$Id: rtcontrib.1,v 1.22 2009/06/14 18:21:58 greg Exp $"
 .TH RTCONTRIB 1 5/25/05 RADIANCE
 .SH NAME
-rtcontrib - compute contributions in a RADIANCE scene
+rtcontrib - compute contribution coefficients in a RADIANCE scene
 .SH SYNOPSIS
 .B rtcontrib
 [
 .B "\-n nprocs"
 ][
+.B \-V
+][
+.B "\-c count"
+][
+.B \-fo
+|
+.B \-r
+][
 .B "\-e expr"
 ][
 .B "\-f source"
 ][
-.B "\-o fspec"
+.B "\-o ospec"
 ][
 .B "\-b binv"
+][
+.B "\-bn nbins"
 ]
-.B "\-m mod .."
+{
+.B "\-m mod | \-M file"
+}
+..
 [
 .B $EVAR
 ]
@@ -30,13 +43,80 @@ rtrace options
 .B "rtcontrib [ options ] \-defaults"
 .SH DESCRIPTION
 .I Rtcontrib
-computes ray contributions (i.e., color coefficients)
+computes ray coefficients
 for objects whose modifiers are named in one or more
 .I \-m
 settings.
 These modifiers are usually materials associated with
 light sources or sky domes, and must directly modify some geometric
 primitives to be considered in the output.
+A modifier list may also be read from a file using the
+.I \-M
+option.
+The RAYPATH environment variable determines directories to search for
+this file.
+(No search takes place if a file name begins with a '.', '/' or '~'
+character.)\0
+.PP
+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
+than there are local CPUs available to do the work, and the
+.I rtcontrib
+process itself may use a considerable amount of CPU time.
+.PP
+By setting the boolean
+.I \-V
+option, you may instruct
+.I rtcontrib
+to report the contribution from each material rather than the ray
+coefficient.
+This is particularly useful for light sources with directional output
+distributions, whose value would otherwise be lost in the shuffle.
+With the default
+.I -V-
+setting, the output of rtcontrib is a coefficient that must be multiplied
+by the radiance of each material to arrive at a final contribution.
+This is more convenient for computing daylight coefficeints, or cases
+where the actual radiance is not desired.
+Use the
+.I -V+
+setting when you wish to simply sum together contributions
+(with possible adjustment factors) to obtain a final radiance value.
+Combined with the
+.I \-i
+or
+.I \-I
+option, irradiance contributions are reported by
+.I \-V+
+rather than radiance, and 
+.I \-V-
+coefficients contain an additonal factor of PI.
+.PP
+The
+.I \-c
+option tells
+.I rtcontrib
+how many rays to accumulate for each record.
+The default value is 1, meaning a full record will be produced for
+each input ray.
+For values greater than 1, 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
+(rather than the average).
+This is equivalent to passing all the output records through a program like
+.I total(1)
+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.
+.PP
 The output of
 .I rtcontrib
 has many potential uses.
@@ -51,10 +131,27 @@ systems, such as luminaires, light pipes, and shading 
 .I Rtcontrib
 calls
 .I rtrace(1)
-to calculate the contributions for each input ray,
-and the output tallies are sent to one or more files according to the
+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 \-o
 specification.
+If a destination begins with an exclamation mark ('!'), then
+a pipe is opened to a command and data is sent to its standard input.
+Otherwise, the destination is treated as a file.
+An existing file of the same name will not be clobbered, unless the
+.I \-fo
+option is given.
+If instead the
+.I \-r
+option is specified, data recovery is attempted on existing files.
+(If 
+.I "\-c 0"
+is used together with the
+.I \-r
+option, existing files are read in and new ray evaluations are added
+to the previous results, providing a convenient means for
+progressive simulation.)\0
 If an output specification contains a "%s" format, this will be
 replaced by the modifier name.
 The
@@ -65,14 +162,35 @@ this will be applied to a "%d" format in the output fi
 specification if present.
 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
+.I \-bn
+option, and this is critical for output files containing multiple values
+per record.
+A variable or constant name may be given for this parameter if
+it has been defined via a previous
+.I \-f
+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).
 The most recent
-.I \-b
+.I \-b,
+.I \-bn
 and
 .I \-o
 options to the left of each
 .I \-m
-setting affect only that modifier.
-(The ordering of other options is unimportant.)\0
+setting are the ones used for that modifier.
+The ordering of other options is unimportant, except for
+.I \-x
+and
+.I \-y
+if the
+.I \-c
+is 0, when they control the resolution string
+produced in the corresponding output.
 .PP
 If a
 .I \-b
@@ -98,12 +216,18 @@ The rules and predefined functions available for these
 described in the
 .I rcalc(1)
 man page.
+Unlike
+.I rcalc,
+.I rtcontrib
+will search the RADIANCE library directories for each file given in a
+.I \-f
+option.
 .PP
 If no
 .I \-o
 specification is given, results are written on the standard output in order
 of modifier (as given on the command line) then bin number.
-Concatenated data is also sent to a lone output file (i.e., an initial
+Concatenated data is also sent to a single destination (i.e., an initial
 .I \-o
 specification without formatting strings).
 If a "%s" format appears but no "%d" in the
@@ -141,17 +265,6 @@ suitable for manipulation with
 .I pcomb(1)
 and related tools.
 .PP
-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
-than there are local CPUs available to do the work, and the
-.I rtcontrib
-process itself may use a considerable amount of CPU time.
-.PP
 Options may be given on the command line and/or read from the
 environment and/or read from a file.
 A command argument beginning with a dollar sign ('$') is immediately
@@ -162,26 +275,28 @@ replaced by the contents of the given file.
 To compute the proportional contributions from sources modified
 by "light1" vs. "light2" on a set of illuminance values:
 .IP "" .2i
-rtcontrib -I+ @render.opt -o c_%s.dat -m light1 -m light2 scene.oct < test.dat
+rtcontrib \-I+ @render.opt \-o c_%s.dat \-m light1 \-m light2 scene.oct < test.dat
 .PP
 To generate a pair of images corresponding to these two lights'
 contributions:
 .IP "" .2i
-vwrays -ff -x 1024 -y 1024 -vf best.vf |
-rtcontrib -ffc `vwrays -d -x 1024 -y 1024 -vf best.vf`
-@render.opt -o c_%s.pic -m light1 -m light2 scene.oct
+vwrays \-ff \-x 1024 \-y 1024 \-vf best.vf |
+rtcontrib \-ffc `vwrays \-d \-x 1024 \-y 1024 \-vf best.vf`
+@render.opt \-o c_%s.hdr \-m light1 \-m light2 scene.oct
 .PP
 These images may then be recombined using the desired outputs
 of light1 and light2:
 .IP "" .2i
-pcomb -c 100 90 75 c_light1.pic -c 50 55 57 c_light2.pic > combined.pic
+pcomb \-c 100 90 75 c_light1.hdr \-c 50 55 57 c_light2.hdr > combined.hdr
 .PP
 To compute an array of illuminance contributions according to a Tregenza sky:
 .IP "" .2i
-rtcontrib -b tbin -o sky.dat -m skyglow -b 0 -o ground.dat -m groundglow
-@render.opt -f tregenza.cal scene.oct < test.dat
+rtcontrib \-I+ \-b tbin \-o sky.dat \-m skyglow \-b 0 \-o ground.dat \-m groundglow
+@render.opt \-f tregenza.cal scene.oct < test.dat
+.SH ENVIRONMENT
+RAYPATH		path to search for \-f and \-M files
 .SH AUTHOR
 Greg Ward
 .SH "SEE ALSO"
-cnt(1), getinfo(1), pcomb(1), pfilt(1), ra_rgbe(1),
-rcalc(1), rpict(1), rtrace(1), vwrays(1), ximage(1)
+cnt(1), genklemsamp(1), getinfo(1), pcomb(1), pfilt(1), ra_rgbe(1),
+rcalc(1), rpict(1), rtrace(1), total(1), vwrays(1), ximage(1)