NAME¶
rtrace - trace rays in RADIANCE scene
SYNOPSIS¶
rtrace [
options ] [
$EVAR ] [
@file ]
octree
rtrace [ options ] -defaults
DESCRIPTION¶
Rtrace traces rays from the standard input through the RADIANCE scene
given by
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 `!'.) 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
-x value is unset or zero. (See the notes on this option
below.) This may be useful for programs that run
rtrace as a
separate process. In the second form, the default values for the options
(modified by those options present) are printed with a brief explanation.
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.
- -fio
- Format input according to the character i and output
according to the character o. 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 floating point (Radiance) color format for the output of
values only (-ov option, below). If the output character is
missing, the input format is used.
- Note that there is no space between this option and its
argument.
- -ospec
- Produce output fields according to spec. Characters
are interpreted as follows:
- o origin (input)
- d direction (normalized)
- v value (radiance)
- V contribution (radiance)
- w weight
- W color coefficient
- l effective length of ray
- L first intersection distance
- c local (u,v) coordinates
- p point of intersection
- n normal at intersection (perturbed)
- N normal at intersection (unperturbed)
- s surface name
- m modifier name
- M material name
- ~ tilde (end of trace marker)
- If the letter 't' appears in 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.,
-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.
- Note that there is no space between this option and its
argument.
- -te mod
- Append mod to the trace exclude list, so that it
will not be reported by the trace option (-o*t*). Any ray striking
an object having 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.
- -ti mod
- Add 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.
- -tE file
- Same as -te, except read modifiers to be excluded
from file. The RAYPATH environment variable determines which
directories are searched for this file. The modifier names are separated
by white space in the file.
- -tI file
- Same as -ti, except read modifiers to be included
from file.
- -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 -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.
- -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.
- -I
- Boolean switch to compute irradiance rather than radiance,
with the input origin and direction interpreted instead as measurement
point and orientation.
- -h
- Boolean switch for information header on output.
- -x res
- Set the x resolution to res. The output will be
flushed after every res input rays if -y is set to zero. A
value of one means that every ray will be flushed, whatever the setting of
-y. A value of zero means that no output flushing will take
place.
- -y res
- Set the y resolution to res. The program will exit
after res scanlines have been processed, where a scanline is the
number of rays given by the -x option, or 1 if -x is zero. A
value of zero means the program will not halt until the end of file is
reached.
- If both -x and -y options are given, a
resolution string is printed at the beginning of the output. This is
mostly useful for recovering image dimensions with pvalue(1), and
for creating valid Radiance picture files using the color output format.
(See the -f option, above.)
- -n nproc
- Execute in parallel on nproc local processes. This
option is incompatible with the -P and -PP, options.
Multiple processes also do not work properly with ray tree output using
any of the -o*t* options. There is no benefit from specifying more
processes than there are cores available on the system or the -x
setting, which forces a wait at each flush.
- -dj frac
- Set the direct jittering to frac. A value of zero
samples each source at specific sample points (see the -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
frac is too large.
- -ds frac
- Set the direct sampling ratio to 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.
- -dt frac
- Set the direct threshold to 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 -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.
- -dc frac
- Set the direct certainty to 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 -dt specification. A
value of zero only insures that all shadow lines resulting in a contrast
change greater than the -dt specification will be calculated.
- -dr N
- Set the number of relays for secondary sources to N.
A value of 0 means that secondary 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 sources, and so on.
- -dp D
- Set the secondary 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 be
tested for shadows if it is tested at all.
- -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 mkillum(1) to avoid inappropriate counting of light
sources, but it may also be desirable in conjunction with the -i
option.
- -ss samp
- Set the specular sampling to 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.
- -st frac
- Set the specular sampling threshold to 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.
- -bv
- Boolean switch for back face visibility. With this switch
off, back faces of opaque objects will be invisible to all rays. This is
dangerous unless the model was constructed such that all surface normals
on opaque objects 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.
- -av red grn blu
- Set the ambient value to a radiance of 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 -aw and -ab below), this value may
be modified by the computed indirect values to improve overall
accuracy.
- -aw N
- Set the relative weight of the ambient value given with the
-av option to 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.
- -ab N
- Set the number of ambient bounces to N. This is the
maximum number of diffuse bounces computed by the indirect calculation. A
value of zero implies no indirect calculation.
- -ar res
- Set the ambient resolution to 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 -aa option
below) divided by the ambient resolution. The scene size can be determined
using getinfo(1) with the -d option on the input
octree.
- -aa acc
- Set the ambient accuracy to acc. This value will
approximately equal the error from indirect illuminance interpolation. A
value of zero implies no interpolation.
- -ad N
- Set the number of ambient divisions to N. The error
in the Monte Carlo calculation of indirect illuminance will be inversely
proportional to the square root of this number. A value of zero implies no
indirect calculation.
- -as N
- Set the number of ambient super-samples to N.
Super-samples are applied only to the ambient divisions which show a
significant change.
- -af fname
- Set the ambient file to fname. This is where
indirect illuminance will be stored and retrieved. Normally, indirect
illuminance values are kept in memory and lost when the program finishes
or dies. By using a file, different invocations can share illuminance
values, saving time in the computation. The ambient file is in a
machine-independent binary format which can be examined with
lookamb(1).
- 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.
nfs(4)). The network lock manager lockd(8) is used to insure
that this information is used consistently.
- 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. Getinfo(1)
may be used to print out this information.
- -ae mod
- Append 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 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.
- -ai mod
- Add 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.
- -aE file
- Same as -ae, except read modifiers to be excluded
from file. The RAYPATH environment variable determines which
directories are searched for this file. The modifier names are separated
by white space in the file.
- -aI file
- Same as -ai, except read modifiers to be included
from file.
- -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.
- -ma ralb galb balb
- Set the global medium albedo to the given value between
0 0 0 and 1 1 1. 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.
- -mg gecc
- Set the medium Heyney-Greenstein eccentricity parameter to
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.
- -ms sampdist
- Set the medium sampling distance to 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.
- -lr N
- Limit reflections to a maximum of N, if N is a
positive integer. If N is zero or negative, then Russian roulette
is used for ray termination, and the -lw setting (below) must be
positive. If N is a negative integer, then this sets the upper limit of
reflections past which Russian roulette will be used. In scenes with
dielectrics and total internal reflection, a setting of 0 (no limit) may
cause a stack overflow.
- -lw frac
- Limit the weight of each ray to a minimum of 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 -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 frac.
- -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.
- -e efile
- Send error messages and progress reports to efile
instead of the standard error.
- -w
- Boolean switch to suppress warning messages.
- -P pfile
- Execute in a persistent mode, using pfile as the
control file. Persistent execution means that after reaching end-of-file
on its input, rtrace will fork a child process that will wait for
another rtrace command with the same -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
-P for subsequent calls.) Killing the process is achieved with the
kill(1) command. (The process ID in the first line of pfile
may be used to identify the waiting rtrace process.) This option
may be used with the -fr option of pinterp(1) to avoid the
cost of starting up rtrace many times.
- -PP pfile
- Execute in continuous-forking persistent mode, using
pfile as the control file. The difference between this option and
the -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 fork(2) system call will share memory on a copy-on-write
basis.
EXAMPLES¶
To compute radiance values for the rays listed in samples.inp:
-
- rtrace -ov scene.oct < samples.inp >
radiance.out
To compute illuminance values at locations selected with the 't' command of
ximage(1):
-
- ximage scene.hdr | rtrace -h -x 1 -i scene.oct | rcalc -e
'$1=47.4*$1+120*$2+11.6*$3'
To record the object identifier corresponding to each pixel in an image:
-
- vwrays -fd scene.hdr | rtrace -fda `vwrays -d scene.hdr`
-os scene.oct
To compute an image with an unusual view mapping:
-
- cnt 480 640 | rcalc -e 'xr:640;yr:480' -f unusual_view.cal
| rtrace -x 640 -y 480 -fac scene.oct > unusual.hdr
ENVIRONMENT¶
RAYPATH the directories to check for auxiliary files.
FILES¶
/tmp/rtXXXXXX common header information for picture sequence
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
-e option.
AUTHOR¶
Greg Ward
SEE ALSO¶
getinfo(1),
lookamb(1),
oconv(1),
pfilt(1),
pinterp(1),
pvalue(1),
rpict(1),
rtcontrib(1),
rvu(1),
vwrays(1),
ximage(1)