[ViewVC] Diff of: Development/ray/doc/man/man1/rcontrib.1

Comparing ray/doc/man/man1/rcontrib.1 (file contents):
Revision 1.1 by greg, Thu Jun 14 22:42:21 2012 UTC vs.
Revision 1.18 by greg, Wed Sep 9 21:28:19 2020 UTC

+.\" RCSid "$Id$"
-<
+.TH RTCONTRIB 1 5/25/05 RADIANCE
->
+.TH RCONTRIB 1 5/25/05 RADIANCE
+.SH NAME
+rcontrib - compute contribution coefficients in a RADIANCE scene
+.SH SYNOPSIS
+][
+.B \-V
+][
-+
+.B "\-t secs"
-+
+][
+.B "\-c count"
+][
+.B \-fo
+][
+.B "\-o ospec"
+][
-+
+.B "\-p p1=V1,p2=V2"
-+
+][
+.B "\-b binv"
+][
+.B "\-bn nbins"
+.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
+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
+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
+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
-+
+If progress reports are desired, the
-+
+.I \-t
-+
+option specifies a time interval in seconds for reports sent to
-+
+standard error.
-+
+.PP
+The output of
+.I rcontrib
+has many potential uses.
+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
+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.
+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
+.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.
+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, colons, 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
+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
+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:
+.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)
->

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines (old)
->
+Changed lines (new)

Comparing ray/doc/man/man1/rcontrib.1 (file contents): Revision 1.1 by greg, Thu Jun 14 22:42:21 2012 UTC vs. Revision 1.18 by greg, Wed Sep 9 21:28:19 2020 UTC

Diff Legend

Comparing ray/doc/man/man1/rcontrib.1 (file contents):
Revision 1.1 by greg, Thu Jun 14 22:42:21 2012 UTC vs.
Revision 1.18 by greg, Wed Sep 9 21:28:19 2020 UTC