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

Comparing ray/doc/man/man1/rcontrib.1 (file contents):
Revision 1.4 by greg, Thu Jun 14 22:49:34 2012 UTC vs.
Revision 1.28 by greg, Thu Nov 13 20:31:53 2025 UTC

+][
+.B \-V
+][
-+
+.B "\-t secs"
-+
+][
+.B "\-c count"
+][
+.B \-fo
+.B \-r
+][
-–
+.B "\-e expr"
-–
+][
-–
+.B "\-f source"
-–
+][
+.B "\-o ospec"
+][
-+
+.B "\-p p1=V1,p2=V2"
-+
+][
+.B "\-b binv"
+][
+.B "\-bn nbins"
+.B octree
+.br
+.B "rcontrib [ options ] \-defaults"
-+
+.br
-+
+.B "rcontrib \-features [feat1 ..]"
+.SH DESCRIPTION
+.I Rcontrib
+computes ray coefficients
+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
-+
+Output flushing at fixed intervals may be enabled with the
-+
+.I \-x
-+
+option, which specifies the number of records
-+
+(-c accumulations) before each flush.
-+
+If the
-+
+.I \-y
-+
+option is also set, then periodic flushing is disabled and the
-+
+output size for an RGB image is the taken from the x and y dimensions.
-+
+In lieu of periodic flushing, a flush may be forced as mentioned above
-+
+by sending a sample with a zero direction vector, although you
-+
+must still send a full record of rays before output occurs.
-+
+.PP
-+
+If progress reports are desired, the
-+
+.I \-t
-+
+option specifies a time interval in seconds for reports sent to
-+
+standard error.
-+
+This requires that the number of input samples is known, meaning a
-+
+.I \-y
-+
+parameter has been specified.
-+
+.PP
+The output of
+.I rcontrib
+has many potential uses.
+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 \-o
+options to the left of each
+.I \-m
-<
+setting are the ones used for that modifier.
->
+name are the ones used for that modifier.
->
+Any
->
+.I \-cs
->
+option changing the number of spectral color
->
+samples must appear before the first 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
->
+is zero, when they control the resolution string
+produced in the corresponding output.
+.PP
+If a
+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
-<
+.I rcalc,
->
+Like the other rendering tools,
+.I rcontrib
-<
+will search the RADIANCE library directories for each file given in a
->
+will search the
->
+.I RAYPATH
->
+library directories for each file given in a
+.I \-f
+option.
-+
+However, a special evaluation context is set for the
-+
+.I \-f
-+
+and
-+
+.I \-e
-+
+definitions, so append a back-quote ('`') to variable and function names
-+
+you wish these to apply at the global evaluation level and used by all
-+
+materials and modifiers during rendering.
+.PP
+If no
+.I \-o
+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:
->
+by "light1" vs. "light2" on a set of irradiance values:
+.IP "" .2i
+rcontrib \-I+ @render.opt \-o c_%s.dat \-m light1 \-m light2 scene.oct < test.dat
+.PP
+.IP "" .2i
+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:
->
+To compute an array of irradiance 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), dctimestep(1), genklemsamp(1), getinfo(1), mkpmap(1), pcomb(1), pfilt(1),
->
+pvsum(1), ra_rgbe(1), rcalc(1), rcomb(1), rfluxmtx(1), rmtxop(1), rpict(1),
->
+rsensor(1), rtrace(1), rxfluxmtx(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.4 by greg, Thu Jun 14 22:49:34 2012 UTC vs. Revision 1.28 by greg, Thu Nov 13 20:31:53 2025 UTC

Diff Legend

Comparing ray/doc/man/man1/rcontrib.1 (file contents):
Revision 1.4 by greg, Thu Jun 14 22:49:34 2012 UTC vs.
Revision 1.28 by greg, Thu Nov 13 20:31:53 2025 UTC