man/man1/rtrace.1

.\" RCSid "$Id: rtrace.1,v 1.42 2025/04/23 15:09:03 greg Exp $"
.TH RTRACE 1 10/17/97 RADIANCE
.SH NAME
rtrace - trace rays in RADIANCE scene
.SH SYNOPSIS
.B rtrace
[
.B options
]
[
.B $EVAR
]
[
.B @file
]
.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
.I octree
and sends the results to the standard output.
(The octree may be given as the output of a command enclosed in quotes
and preceded by a `!'.)\0
Input for each ray is:

        xorg yorg zorg xdir ydir zdir

If the direction vector is (0,0,0), a bogus record
is printed and the output is flushed if the
.I -x
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.
.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
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.
Most options are followed by one or more arguments, which must be
separated from the option and each other by white space.
The exceptions to this rule are the boolean options.
Normally, the appearance of a boolean option causes a feature to
be "toggled", that is switched from off to on or on to off
depending on its previous state.
Boolean options may also be set
explicitly by following them immediately with a '+' or '-', meaning
on or off, respectively.
Synonyms for '+' are any of the characters "yYtT1", and synonyms
for '-' are any of the characters "nNfF0".
All other characters will generate an error.
.TP 10n
.BI -f io
Format input according to the character
.I i
and output according to the character
.I o.
.I Rtrace
understands the following input and output formats:  'a' for
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 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.
.TP
.BI -o spec
Produce output fields according to
.I spec.
Characters are interpreted as follows:
.IP
o       origin (input)
.IP
d       direction (normalized)
.IP
v       value (radiance)
.IP
V       contribution (radiance)
.IP
w       weight
.IP
W       color coefficient
.IP
l       effective length of ray
.IP
L       first intersection distance
.IP
c       local (u,v) coordinates
.IP
p       point of intersection
.IP
n       normal at intersection (perturbed)
.IP
N       normal at intersection (unperturbed)
.IP
s       surface name
.IP
m       modifier name
.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,
not just the final result.
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
.BI -te \ mod
Append
.I mod
to the trace exclude list,
so that it will not be reported by the trace option
.I (\-o*t*).
Any ray striking an object having
.I mod
as its modifier will not be reported to the standard output with
the rest of the rays being traced.
This option has no effect unless either the 't' or 'T'
option has been given as part of the output specifier.
Any number of excluded modifiers may be given, but each
must appear in a separate option.
.TP
.BI -ti \ mod
Add
.I mod
to the trace include list,
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
.BI -tE \ file
Same as
.I \-te,
except read modifiers to be excluded from
.I file.
The RAYPATH environment variable determines which directories are
searched for this file.
The modifier names are separated by white space in the file.
.TP
.BI -tI \ file
Same as
.I \-ti,
except read modifiers to be included from
.I file.
.TP
.BR \-i
Boolean switch to compute irradiance rather than radiance values.
This only affects the final result, substituting a Lambertian
surface and multiplying the radiance by pi.
Glass and other transparent surfaces are ignored during this stage.
Light sources still appear with their original radiance values,
though the
.I \-dv
option (below) may be used to override this.
This option is especially useful in
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
as measurement point and orientation.
.TP
.BR \-h
Boolean switch for information header on output.
.TP
.BI -x \ res
Set the x resolution to
.I res.
The output will be flushed after every
.I res
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
Set the y resolution to
.I res.
The program will exit after
.I res
scanlines have been processed, where a scanline is the number of rays
given by the
.I \-x
option, or 1 if
.I \-x
is zero.
A value of zero means the program will not halt until the end
of file is reached.
.IP
If both
.I \-x
and
.I \-y
options are given, a resolution string is printed at the beginning
of the output.
This is mostly useful for recovering image dimensions with
.I pvalue(1),
and for creating valid Radiance picture files using the color output
format.
(See the
.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.
A value of zero samples each source at specific sample points
(see the
.I \-ds
option below), giving a smoother but somewhat less accurate
rendering.
A positive value causes rays to be distributed over each
source sample according to its size, resulting in more accurate
penumbras.
This option should never be greater than 1, and may even
cause problems (such as speckle) when the value is smaller.
A warning about aiming failure will issued if
.I frac
is too large.
.TP
.BI -ds \ frac
Set the direct sampling ratio to
.I frac.
A light source will be subdivided until
the width of each sample area divided by the distance
to the illuminated point is below this ratio.
This assures accuracy in regions close to large area sources
at a slight computational expense.
A value of zero turns source subdivision off, sending at most one
shadow ray to each light source.
.TP
.BI -dt \ frac
Set the direct threshold to
.I frac.
Shadow testing will stop when the potential contribution of at least
the next and at most all remaining light sources is less than
this fraction of the accumulated value.
(See the
.I \-dc
option below.)
The remaining light source contributions are approximated
statistically.
A value of zero means that all light sources will be tested for shadow.
.TP
.BI \-dc \ frac
Set the direct certainty to
.I frac.
A value of one guarantees that the absolute accuracy of the direct calculation
will be equal to or better than that given in the
.I \-dt
specification.
A value of zero only insures that all shadow lines resulting in a contrast
change greater than the
.I \-dt
specification will be calculated.
.TP
.BI -dr \ N
Set the number of relays for virtual sources to
.I N.
A value of 0 means that virtual sources will be ignored.
A value of 1 means that sources will be made into first generation
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 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 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
Boolean switch for light source visibility.
With this switch off, sources will be black when viewed directly
although they will still participate in the direct calculation.
This option is mostly for the program
.I mkillum(1)
to avoid inappropriate counting of light sources, but it
may also be desirable in conjunction with the
.I \-i
option.
.TP
.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
.BI -st \ frac
Set the specular sampling threshold to
.I frac.
This is the minimum fraction of reflection or transmission, under which 
no specular sampling is performed.
A value of zero means that highlights will always be sampled by
tracing reflected or transmitted rays.
A value of one means that specular sampling is never used.
Highlights from light sources will always be correct, but
reflections from other surfaces will be approximated using an
ambient value.
A sampling threshold between zero and one offers a compromise between image
accuracy and rendering time.
.TP
.BR -bv
Boolean switch for back face visibility.
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 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.
.TP
.BI -av " red grn blu"
Set the ambient value to a radiance of
.I "red grn blu".
This is the final value used in place of an
indirect light calculation.
If the number of ambient bounces is one or greater and the ambient
value weight is non-zero (see
.I -aw
and
.I -ab
below), this value may be modified by the computed indirect values
to improve overall accuracy.
.TP
.BI -aw \ N
Set the relative weight of the ambient value given with the
.I -av
option to
.I N.
As new indirect irradiances are computed, they will modify the
default ambient value in a moving average, with the specified weight
assigned to the initial value given on the command and all other
weights set to 1.
If a value of 0 is given with this option, then the initial ambient
value is never modified.
This is the safest value for scenes with large differences in
indirect contributions, such as when both indoor and outdoor
(daylight) areas are visible.
.TP
.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. 
.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
.I res.
This number will determine the maximum density of ambient values
used in interpolation.
Error will start to increase on surfaces spaced closer than
the scene size divided by the ambient resolution.
The maximum ambient value density is the scene size times the
ambient accuracy (see the
.I \-aa
option below) divided by the ambient resolution.
The scene size can be determined using
.I getinfo(1)
with the
.I \-d
option on the input octree.
.TP
.BI -aa \ acc
Set the ambient accuracy to
.I acc.
This value will approximately equal the error
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
irradiance will be inversely proportional to the square
root of this number.
A value of zero implies no indirect calculation.
.TP
.BI -as \ N
Set the number of ambient super-samples to
.I N.
Super-samples are applied only to the ambient divisions which
show a significant change.
.TP
.BI -af \ fname
Set the ambient file to
.I fname.
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 irradiance
values, saving time in the computation.
The ambient file is in a machine-independent binary format
which can be examined with
.I lookamb(1).
.IP
The ambient file may also be used as a means of communication and
data sharing between simultaneously executing processes.
The same file may be used by multiple processes, possibly running on
different machines and accessing the file via the network (ie.
.I nfs(4)).
The network lock manager
.I lockd(8)
is used to insure that this information is used consistently.
.IP
If any calculation parameters are changed or the scene
is modified, the old ambient file should be removed so that
the calculation can start over from scratch.
For convenience, the original ambient parameters are listed in the
header of the ambient file.
.I Getinfo(1)
may be used to print out this information.
.TP
.BI -ae \ mod
Append
.I mod
to the ambient exclude list,
so that it will not be considered during the indirect calculation.
This is a hack for speeding the indirect computation by
ignoring certain objects.
Any object having
.I mod
as its modifier will get the default ambient
level rather than a calculated value.
Any number of excluded modifiers may be given, but each
must appear in a separate option.
.TP
.BI -ai \ mod
Add
.I mod
to the ambient include list,
so that it will be considered during the indirect calculation.
The program can use either an include list or an exclude
list, but not both.
.TP
.BI -aE \ file
Same as
.I \-ae,
except read modifiers to be excluded from
.I file.
The RAYPATH environment variable determines which directories are
searched for this file.
The modifier names are separated by white space in the file.
.TP
.BI -aI \ file
Same as
.I \-ai,
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 =
1e6), 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).
Light will be scattered or absorbed over distance according to
this value.
The ratio of scattering to total scattering plus absorption is set
by the albedo parameter, described below.
.TP
.BI -ma " ralb galb balb"
Set the global medium albedo to the given value between 0\00\00
and 1\01\01.
A zero value means that all light not transmitted by the medium
is absorbed.
A unitary value means that all light not transmitted by the medium
is scattered in some new direction.
The isotropy of scattering is determined by the Heyney-Greenstein
parameter, described below.
.TP
.BI \-mg \ gecc
Set the medium Heyney-Greenstein eccentricity parameter to
.I gecc.
This parameter determines how strongly scattering favors the forward
direction.
A value of 0 indicates perfectly isotropic scattering.
As this parameter approaches 1, scattering tends to prefer the
forward direction.
.TP
.BI \-ms \ sampdist
Set the medium sampling distance to
.I sampdist,
in world coordinate units.
During source scattering, this will be the average distance between
adjacent samples.
A value of 0 means that only one sample will be taken per light
source within a given scattering volume.
.TP
.BI -lr \ N
Limit reflections to a maximum of
.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 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
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
instead of the standard error.
.TP
.BR \-w
Boolean switch to suppress warning messages.
.TP
.BI \-P \ pfile
Execute in a persistent mode, using
.I pfile
as the control file.
Persistent execution means that after reaching end-of-file on
its input,
.I rtrace
will fork a child process that will wait for another
.I rtrace
command with the same
.I \-P
option to attach to it.
(Note that since the rest of the command line options will be those
of the original invocation, it is not necessary to give any arguments
besides
.I \-P
for subsequent calls.)
Killing the process is achieved with the
.I kill(1)
command.
(The process ID in the first line of
.I pfile
may be used to identify the waiting
.I rtrace
process.)
This option may be used with the
.I \-fr
option of
.I pinterp(1)
to avoid the cost of starting up
.I rtrace
many times.
.TP
.BI \-PP \ pfile
Execute in continuous-forking persistent mode, using
.I pfile
as the control file.
The difference between this option and the
.I \-P
option described above is the creation of multiple duplicate
processes to handle any number of attaches.
This provides a simple and reliable mechanism of memory sharing
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
.PP
To compute irradiance values at locations selected with the 't'
command of
.I ximage(1):
.IP "" .2i
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.hdr | rtrace \-fda `vwrays \-d scene.hdr` \-os scene.oct
.PP
To compute an image with an unusual view mapping:
.IP "" .2i
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
/tmp/rtXXXXXX           common header information for picture sequence
.SH DIAGNOSTICS
If the program terminates from an input related error, the exit status
will be 1.
A system related error results in an exit status of 2.
If the program receives a signal that is caught, it will exit with a status
of 3.
In each case, an error message will be printed to the standard error, or
to the file designated by the
.I \-e
option.
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
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)
Revision:	1.43
Committed:	Fri Jun 27 15:19:58 2025 UTC (3 days, 4 hours ago) by greg
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.42:	+8 -4 lines
Log Message:	docs(rpict,rtrace): Clarified -f and -e options