--- ray/doc/man/man1/rtcontrib.1	2005/05/26 18:53:04	1.2
+++ ray/doc/man/man1/rtcontrib.1	2005/10/11 16:54:26	1.14
@@ -1,21 +1,30 @@
-.\" RCSid "$Id: rtcontrib.1,v 1.2 2005/05/26 18:53:04 greg Exp $"
-.TH RPIECE 1 5/25/05 RADIANCE
+.\" RCSid "$Id: rtcontrib.1,v 1.14 2005/10/11 16:54:26 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 \-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
 ]
@@ -26,6 +35,8 @@ rtcontrib - compute contributions in a RADIANCE scene
 rtrace options
 ]
 .B octree
+.br
+.B "rtcontrib [ options ] \-defaults"
 .SH DESCRIPTION
 .I Rtcontrib
 computes ray contributions (i.e., color coefficients)
@@ -35,21 +46,42 @@ 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.
-The computed contributions can then be used in linear combination to
+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
+The output of
+.I rtcontrib
+has many potential uses.
+Source contributions can be used as components in linear combination to
 reproduce any desired variation, e.g., simulating lighting controls or
 changing sky conditions via daylight coefficients.
 More generally,
 .I rtcontrib
-may be used to compute input-output relationships in optical
-systems, such as light pipes and shading devices.
+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)
-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 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 an output specification contains a "%s" format, this will be
 replaced by the modifier name.
 The
@@ -58,10 +90,18 @@ 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.
-(The actual bin number is computed at run time based on ray direction
-and surface intersection, as described below.)\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
+.I \-bn
+option, and this is critical for output files containing multiple values
+per record.
+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
@@ -80,20 +120,31 @@ the variables Px, Py, and Pz, and the normalized ray d
 will be assigned to Dx, Dy, and Dz.
 These parameters may be combined with definitions given in
 .I \-e
-options and files read in
+arguments and files read using the
 .I \-f
-options, to compute the bin, which will be
+option.
+The computed bin value will be
 rounded to the nearest whole number.
 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
 as a set of RADIANCE primitives.
+The rules and predefined functions available for these expressions are
+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
@@ -168,8 +219,10 @@ pcomb -c 100 90 75 c_light1.pic -c 50 55 57 c_light2.p
 .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
+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"