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

Comparing ray/doc/man/man1/rtrace.1 (file contents):
Revision 1.7 by greg, Tue Apr 19 01:15:06 2005 UTC vs.
Revision 1.43 by greg, Fri Jun 27 15:19:58 2025 UTC

+.B octree
+.br
+.B "rtrace [ options ] \-defaults"
-+
+.br
-+
+.B "rtrace \-features [feat1 ..]"
+.SH DESCRIPTION
+.I Rtrace
+traces rays from the standard input through the RADIANCE scene given by
+If the direction vector is (0,0,0), a bogus record
+is printed and the output is flushed if the
+.I -x
-<
+value is unset or zero.
->
+value is one or zero.
+(See the notes on this option below.)\0
+This may be useful for programs that run
+.I rtrace
+as a separate process.
-<
+In the second form, the default values
->
+.PP
->
+In the second form shown above, the default values
+for the options (modified by those options present)
+are printed with a brief explanation.
+.PP
-+
+In the third form, a list of supported features is sent
-+
+to the standard output, one per line.
-+
+If additional arguments follow, they are checked for presence in
-+
+this list.
-+
+If a feature includes subfeatures, these may be checked as well by
-+
+specifying:
-+
+.nf
-+
-+
+        rtrace -features FeatName=subfeat1,subfeat2
-+
-+
+.fi
-+
+If any named feature or subfeature is missing, an error is
-+
+reported and the program returns an error status.
-+
+If all of the named features are present, a zero status is returned.
-+
+.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
+ascii, 'f' for single-precision floating point,
+and 'd' for double-precision floating point.
+In addition to these three choices, the character 'c' may be used
-<
+to denote 4-byte floating point (Radiance) color format
-<
+for the output of values only
-<
+.I (\-ov
-<
+option, below).
->
+to denote 4-byte RGBE (Radiance) color format
->
+for the output of individual color values only, and the
->
+.I \-x
->
+and
->
+.I \-y
->
+options should also be specified to create a valid output picture.
+If the output character is missing, the input format is used.
+.IP
+Note that there is no space between this option and its argument.
+.IP
+v       value (radiance)
+.IP
-+
+V       contribution (radiance)
-+
+.IP
+w       weight
+.IP
-<
+W       contribution
->
+W       color coefficient
+.IP
+l       effective length of ray
+.IP
+.IP
+M       material name
+.IP
-+
+r       mirrored value contribution
-+
+.IP
-+
+x       unmirrored value contribution
-+
+.IP
-+
+R       mirrored ray length
-+
+.IP
-+
+X       unmirrored ray length
-+
+.IP
-+
+~       tilde (end of trace marker)
-+
+.IP
+If the letter 't' appears in
+.I spec,
+then the fields following will be printed for every ray traced,
+If the capital letter 'T' is given instead of 't', then all rays will
+be reported, including shadow testing rays to light sources.
+Spawned rays are indented one tab for each level.
-+
+The tilde marker ('~') is a handy way of differentiating the final ray
-+
+value from daughter values in a traced ray tree, and usually appears
-+
+right before the 't' or 'T' output flags.
-+
+E.g.,
-+
+.I \-ov~TmW
-+
+will emit a tilde followed by a tab at the end of each trace,
-+
+which can be easily distinguished even in binary output.
+.IP
+Note that there is no space between this option and its argument.
+.TP
+Add
+.I mod
+to the trace include list,
-<
+so that it will be considered during the indirect calculation.
->
+so that it will be reported by the trace option.
+The program can use either an include list or an exclude
+list, but not both.
+.TP
+.I \-dv
+option (below) may be used to override this.
+This option is especially useful in
-<
+conjunction with ximage(1) for computing illuminance at scene points.
->
+conjunction with ximage(1) for computing irradiance at scene points.
+.TP
-+
+.BR \-u
-+
+Boolean switch to control uncorrelated random sampling.
-+
+When "off", a low-discrepancy sequence is used, which reduces
-+
+variance but can result in a brushed appearance in specular highlights.
-+
+When "on", pure Monte Carlo sampling is used in all calculations.
-+
+.TP
+.BR \-I
+Boolean switch to compute irradiance rather than radiance,
+with the input origin and direction interpreted instead
+.I res.
+The output will be flushed after every
+.I res
-<
+input rays.
->
+input rays if
->
+.I \-y
->
+is set to zero.
->
+A value of one means that every ray will be flushed, whatever
->
+the setting of
->
+.I \-y.
+A value of zero means that no output flushing will take place.
+.TP
+.BI -y \ res
+and for creating valid Radiance picture files using the color output
+format.
+(See the
-<
+.I \-f
->
+.I \-f\*
+option, above.)
+.TP
-+
+.BI -n \ nproc
-+
+Execute in parallel on
-+
+.I nproc
-+
+local processes.
-+
+This option is incompatible with the
-+
+.I \-P
-+
+and
-+
+.I \-PP,
-+
+options.
-+
+Multiple processes also do not work properly with ray tree output
-+
+using any of the
-+
+.I \-o*t*
-+
+options.
-+
+There is no benefit from specifying more processes than there are
-+
+cores available on the system or the
-+
+.I \-x
-+
+setting, which forces a wait at each flush.
-+
+.TP
-+
+.BI -f \ source
-+
+Load function and variable definitions from the file
-+
+.I source
-+
+and assign at the global level.
-+
+This may be convenient for altering material appearance on a per-run basis.
-+
+The usual set of library directories is searched based on the
-+
+.I RAYPATH
-+
+environment variable.
-+
+These file definitions will override same-named variables
-+
+and functions in "rayinit.cal".
-+
+.TP
-+
+.BI -e \ expr
-+
+Set initial definitions from
-+
+.I expr,
-+
+which may include constant assignments with the ':' character.
-+
+.TP
+.BI -dj \ frac
+Set the direct jittering to
+.I frac.
+specification will be calculated.
+.TP
+.BI -dr \ N
-<
+Set the number of relays for secondary sources to
->
+Set the number of relays for virtual sources to
+.I N.
-<
+A value of 0 means that secondary sources will be ignored.
->
+A value of 0 means that virtual sources will be ignored.
+A value of 1 means that sources will be made into first generation
-<
+secondary sources; a value of 2 means that first generation
-<
+secondary sources will also be made into second generation secondary
->
+virtual sources; a value of 2 means that first generation
->
+virtual sources will also be made into second generation virtual
+sources, and so on.
+.TP
+.BI -dp \ D
-<
+Set the secondary source presampling density to D.
->
+Set the virtual source presampling density to D.
+This is the number of samples per steradian
+that will be used to determine ahead of time whether or not
+it is worth following shadow rays through all the reflections and/or
-<
+transmissions associated with a secondary source path.
-<
+A value of 0 means that the full secondary source path will always
->
+transmissions associated with a virtual source path.
->
+A value of 0 means that the full virtual source path will always
+be tested for shadows if it is tested at all.
+.TP
+.BR \-dv
+.I \-i
+option.
+.TP
-<
+.BI -sj \ frac
-<
+Set the specular sampling jitter to
-<
+.I frac.
-<
+This is the degree to which the highlights are sampled
-<
+for rough specular materials.
-<
+A value of one means that all highlights will be fully sampled
-<
+using distributed ray tracing.
->
+.BI -ss \ samp
->
+Set the specular sampling to
->
+.I samp.
->
+For values less than 1, this is the degree to which the highlights
->
+are sampled for rough specular materials.
->
+A value greater than one causes multiple ray samples to be sent
->
+to reduce noise at a commmesurate cost.
+A value of zero means that no jittering will take place, and all
+reflections will appear sharp even when they should be diffuse.
+.TP
+.TP
+.BR -bv
+Boolean switch for back face visibility.
-<
+With this switch off, back faces of opaque objects will be invisible
-<
+to all rays.
->
+With this switch off, back faces of all objects will be invisible
->
+to view rays.
+This is dangerous unless the model was constructed such that
-<
+all surface normals on opaque objects face outward.
->
+all surface normals face outward.
+Although turning off back face visibility does not save much
+computation time under most circumstances, it may be useful as a
+tool for scene debugging, or for seeing through one-sided walls from
+the outside.
-–
+This option has no effect on transparent or translucent materials.
+.TP
+.BI -av " red grn blu"
+Set the ambient value to a radiance of
+.BI -ab \ N
+Set the number of ambient bounces to
+.I N.
-<
+This is the maximum number of diffuse bounces
-<
+computed by the indirect calculation.
-<
+A value of zero implies no indirect calculation.
->
+This is the maximum number of diffuse bounces computed by the indirect
->
+calculation. A value of zero implies no indirect calculation.
->
+.IP
->
+This value defaults to 1 in photon mapping mode (see
->
+.I -ap
->
+below), implying that global photon irradiance is always computed via
->
+.I one
->
+ambient bounce; this behaviour applies to any positive number of ambient
->
+bounces, regardless of the actual value specified.  A negative value enables
->
+a preview mode that directly visualises the irradiance from the global
->
+photon map without any ambient bounces.
+.TP
+.BI -ar \ res
+Set the ambient resolution to
+Set the ambient accuracy to
+.I acc.
+This value will approximately equal the error
-<
+from indirect illuminance interpolation.
->
+from indirect irradiance interpolation.
+A value of zero implies no interpolation.
+.TP
+.BI -ad \ N
+Set the number of ambient divisions to
+.I N.
+The error in the Monte Carlo calculation of indirect
-<
+illuminance will be inversely proportional to the square
->
+irradiance will be inversely proportional to the square
+root of this number.
+A value of zero implies no indirect calculation.
+.TP
+.BI -af \ fname
+Set the ambient file to
+.I fname.
-<
+This is where indirect illuminance will be stored and retrieved.
-<
+Normally, indirect illuminance values are kept in memory and
->
+This is where indirect irradiance will be stored and retrieved.
->
+Normally, indirect irradiance values are kept in memory and
+lost when the program finishes or dies.
-<
+By using a file, different invocations can share illuminance
->
+By using a file, different invocations can share irradiance
+values, saving time in the computation.
+The ambient file is in a machine-independent binary format
+which can be examined with
+except read modifiers to be included from
+.I file.
+.TP
-+
+.BI -ap " file [bwidth1 [bwidth2]]"
-+
+Enable photon mapping mode. Loads a photon map generated with
-+
+.I mkpmap(1)
-+
+from
-+
+.I file,
-+
+and evaluates the indirect irradiance depending on the photon type
-+
+(automagically detected) using density estimates with a bandwidth of
-+
+.I bwidth1
-+
+photons, or the default bandwidth if none is specified (a warning will be
-+
+issued in this case).
-+
+.IP
-+
+Global photon irradiance is evaluated as part of the ambient calculation (see
-+
+.I \-ab
-+
+above), caustic photon irradiance is evaluated at primary rays, and
-+
+indirect inscattering in
-+
+.I mist
-+
+is accounted for by volume photons. Contribution photons are treated as
-+
+global photons by
-+
+.I rtrace.
-+
+.IP
-+
+Additionally specifying
-+
+.I bwidth2
-+
+enables bias compensation for the density estimates with a
-+
+minimum and maximum bandwidth of
-+
+.I bwidth1
-+
+and
-+
+.I bwidth2,
-+
+respectively.
-+
+.IP
-+
+Global photon irradiance may be optionally precomputed by
-+
+.I mkpmap(1),
-+
+in which case the bandwidth, if specified, is ignored, as the nearest photon
-+
+is invariably looked up.
-+
+.IP
-+
+Using direct photons replaces the direct calculation with density estimates
-+
+for debugging and validation of photon emission.
-+
+.TP
-+
+.BI -am " frac"
-+
+Maximum search radius for photon map lookups.  Without this option, an
-+
+initial maximum search radius is estimated for each photon map from the
-+
+average photon distance to the distribution's centre of gravity.  It is then
-+
+adapted to the photon density in subsequent lookups.  This option imposes a
-+
+global fixed maximum search radius for
-+
+.I all
-+
+photon maps, thus defeating the automatic adaptation.  It is useful when
-+
+multiple warnings about short photon lookups are issued.  Note that this
-+
+option does not conflict with the bandwidth specified with the
-+
+.I \-ap
-+
+option; the number of photons found will not exceed the latter, but may be
-+
+lower if the maximum search radius contains fewer photons, thus resulting in
-+
+short lookups.  Setting this radius too large, on the other hand, may
-+
+degrade performance.
-+
+.TP
-+
+.BI -ac " pagesize"
-+
+Set the photon cache page size when using out-of-core photon mapping. The
-+
+photon cache reduces disk I/O incurred by on-demand loading (paging) of
-+
+photons, and thus increases performance. This
-+
+is expressed as a (float) multiple of the density estimate bandwidth
-+
+specified with
-+
+.I \-ap
-+
+under the assumption that photon lookups are local to a cache page. Cache
-+
+performance is sensitive to this parameter: larger pagesizes will reduce the
-+
+paging frequency at the expense of higher latency when paging does occur.
-+
+Sensible values are in the range 4 (default) to 16.
-+
+.TP
-+
+.BI -aC " cachesize"
-+
+Set the total number of photons cached when using out-of-core photon
-+
+mapping, taking into account the pagesize specified by
-+
+.I \-ac.
-+
+Note that this is approximate as the number of cache pages is rounded to
-+
+the nearest prime. This allows adapting the cache to the available physical
-+
+memory. In conjunction with the
-+
+.I \-n
-+
+option, this is the cache size
-+
+.I per parallel process.
-+
+Cache performance is less sensitive to this parameter,
-+
+and reasonable performance can obtained with as few as 10k photons. The
-+
+default is 1M. This option recognises multiplier suffixes (k = 1e3, M =
-+
+e6), both in upper and lower case.
-+
+.TP
+.BI -me " rext gext bext"
+Set the global medium extinction coefficient to the indicated color,
+in units of 1/distance (distance in world coordinates).
+.TP
+.BI -lr \ N
+Limit reflections to a maximum of
-<
+.I N.
->
+.I N,
->
+if N is a positive integer.
->
+If
->
+.I N
->
+is zero or negative, then Russian roulette is used for ray
->
+termination, and the
->
+.I -lw
->
+setting (below) must be positive.
->
+If N is a negative integer, then this limits the maximum
->
+number of reflections even with Russian roulette.
->
+In scenes with dielectrics and total internal reflection,
->
+a setting of 0 (no limit) may cause a stack overflow.
+.TP
+.BI -lw \ frac
+Limit the weight of each ray to a minimum of
+.I frac.
-<
+During ray-tracing, a record is kept of the final contribution
-<
+a ray would have to the image.
-<
+If it is less then the specified minimum, the ray is not traced.
->
+During ray-tracing, a record is kept of the estimated contribution
->
+(weight) a ray would have in the image.
->
+If this weight is less than the specified minimum and the
->
+.I -lr
->
+setting (above) is positive, the ray is not traced.
->
+Otherwise, Russian roulette is used to
->
+continue rays with a probability equal to the ray weight
->
+divided by the given
->
+.I frac.
+.TP
-<
+.BR -ld
->
+.BR \-ld
+Boolean switch to limit ray distance.
+If this option is set, then rays will only be traced as far as the
+magnitude of each direction vector.
+Otherwise, vector magnitude is ignored and rays are traced to infinity.
+.TP
-+
+.BI -cs \ Ns
-+
+Use
-+
+.I Ns
-+
+bands for spectral sampling rather than the default RGB calculation space.
-+
+The maximum setting is controlled by the compiler macro MAXCSAMP, and
-+
+defaults to 24.
-+
+Larger values for Ns will be reduced to MAXCSAMP.
-+
+.TP
-+
+.BI -cw " nmA nmB"
-+
+Set extrema to the given wavelengths for spectral sampling.
-+
+The default is 380 and 780 nanometers.
-+
+The order specified does not matter.
-+
+.TP
-+
+.BR \-co
-+
+Boolean switch turns on spectral data output if selected.
-+
+The default is to reduce spectral results to RGB, but see the related
-+
+.I \-p*
-+
+options, below.
-+
+.TP
-+
+.BI -pc " xr yr xg yg xb yb xw yw"
-+
+Use the specified chromaticity pairs for output primaries and white
-+
+point rather than the standard RGB color space.
-+
+.TP
-+
+.BR \-pRGB
-+
+Output standard RGB values (the default).
-+
+.TP
-+
+.BR \-pXYZ
-+
+Output standard CIE XYZ tristimulus values rather than RGB.
-+
+.TP
-+
+.BR \-pY
-+
+Produce a single output channel corresponding to photopic luminance.
-+
+.TP
-+
+.BR \-pS
-+
+Produce a single output channel corresponding to scotopic luminance.
-+
+.TP
-+
+.BR \-pM
-+
+Produce a single output channel corresponding to melanopic luminance.
-+
+.TP
+.BI -e \ efile
+Send error messages and progress reports to
+.I efile
+on most multiprocessing platforms, since the
+.I fork(2)
+system call will share memory on a copy-on-write basis.
-+
+.SH NOTES
-+
+Photons are generally surface bound (an exception are volume photons), thus
-+
+the ambient irradiance in photon mapping mode will be biased at positions
-+
+which do not lie on a surface.
+.SH EXAMPLES
+To compute radiance values for the rays listed in samples.inp:
+.IP "" .2i
-<
+rtrace -ov scene.oct < samples.inp > radiance.out
->
+rtrace \-ov scene.oct < samples.inp > radiance.out
+.PP
-<
+To compute illuminance values at locations selected with the 't'
->
+To compute irradiance values at locations selected with the 't'
+command of
+.I ximage(1):
+.IP "" .2i
-<
+ximage scene.pic | rtrace -h -x 1 -i scene.oct | rcalc -e '$1=47.4*$1+120*$2+11.6*$3'
->
+ximage scene.hdr | rtrace \-h \-x 1 \-i scene.oct | rcalc \-e '$1=47.4*$1+120*$2+11.6*$3'
+.PP
+To record the object identifier corresponding to each pixel in an image:
+.IP "" .2i
-<
+vwrays -fd scene.pic | rtrace -fda `vwrays -d scene.pic` -os scene.oct
->
+vwrays \-fd scene.hdr | rtrace \-fda `vwrays \-d scene.hdr` \-os scene.oct
+.PP
+To compute an image with an unusual view mapping:
+.IP "" .2i
-<
+cnt 640 480 | rcalc -e 'xr:640;yr:480' -f unusual_view.cal | rtrace
-<
+-x 640 -y 480 -fac scene.oct > unusual.pic
->
+cnt 480 640 | rcalc \-e 'xr:640;yr:480' \-f unusual_view.cal | rtrace
->
+\-x 640 \-y 480 \-fac scene.oct > unusual.hdr
->
+.PP
->
+To compute ambient irradiance in photon mapping mode from a global photon
->
+map global.pm via one ambient bounce, and from a caustic photon map
->
+caustic.pm at sensor positions in samples.inp:
->
+.IP "" .2i
->
+rtrace -h -ov -ab 1 -ap global.pm 50 -ap caustic.pm 50 scene.oct <
->
+samples.inp > illum.out
+.SH ENVIRONMENT
+RAYPATH         the directories to check for auxiliary files.
+.SH FILES
+.SH AUTHOR
+Greg Ward
+.SH "SEE ALSO"
-<
+getinfo(1), lookamb(1), oconv(1), pfilt(1), pinterp(1),
-<
+pvalue(1), rpict(1), rvu(1), vwrays(1), ximage(1)
->
+dctimestep(1), getinfo(1), lookamb(1),
->
+mkpmap(1), oconv(1), pfilt(1), pinterp(1),
->
+pvalue(1), rcalc(1), rcomb(1), rcontrib(1), rcrop(1),
->
+rmtxop(1), rsplit(1),
->
+rpict(1), rtpict(1), rvu(1), vwrays(1), ximage(1)

Diff Legend

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

Comparing ray/doc/man/man1/rtrace.1 (file contents): Revision 1.7 by greg, Tue Apr 19 01:15:06 2005 UTC vs. Revision 1.43 by greg, Fri Jun 27 15:19:58 2025 UTC

Diff Legend

Comparing ray/doc/man/man1/rtrace.1 (file contents):
Revision 1.7 by greg, Tue Apr 19 01:15:06 2005 UTC vs.
Revision 1.43 by greg, Fri Jun 27 15:19:58 2025 UTC