man/man1/rtrace.1

.\" RCSid "$Id"
.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"
.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 unset 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
for the options (modified by those options present)
are printed with a brief explanation.
.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 floating point (Radiance) color format
for the output of values only
.I (\-ov
option, below).
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
w       weight
.IP
l       effective length of ray
.IP
L       first intersection distance
.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
If the letter 't' appears in
.I spec,
then the fields following will be printed for every ray traced,
not just the final result.
Spawned rays are indented one tab for each level.
.IP
Note that there is no space between this option and its argument.
.TP
.BI -te \ mat
Append
.I mat
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 mat
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 the 't' option has been given as
part of the output specifier.
Any number of excluded materials may be given, but each
must appear in a separate option.
.TP
.BI -ti \ mat
Add
.I mat
to the trace 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 -tE \ file
Same as
.I \-te,
except read materials to be excluded from
.I file.
The RAYPATH environment variable determines which directories are
searched for this file.
The material names are separated by white space in the file.
.TP
.BI -tI \ file
Same as
.I \-ti,
except read materials 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 illuminance at scene points.
.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.
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 -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 secondary sources to
.I 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.
.TP
.BI -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.
.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 -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.
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 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.
.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.
.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 illuminance 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
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 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
.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 \ mat
Append
.I mat
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 mat
as its modifier will get the default ambient
level rather than a calculated value.
Any number of excluded materials may be given, but each
must appear in a separate option.
.TP
.BI -ai \ mat
Add
.I mat
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 materials to be excluded from
.I file.
The RAYPATH environment variable determines which directories are
searched for this file.
The material names are separated by white space in the file.
.TP
.BI -aI \ file
Same as
.I \-ai,
except read materials to be included from
.I file.
.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.
.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.
.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 -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 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 illuminance 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'
.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
.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
.SH ENVIRONMENT
RAYPATH         the directories to check for auxiliary files.
.SH FILES
/usr/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"
getinfo(1), lookamb(1), oconv(1), pfilt(1), pinterp(1),
pvalue(1), rpict(1), rview(1), vwrays(1), ximage(1)
Revision:	1.1
Committed:	Tue Mar 11 19:20:21 2003 UTC (21 years, 2 months ago) by greg
Branch:	MAIN
CVS Tags:	rad3R5
Log Message:	Added documentation to repository
#	User	Rev	Content
1	greg	1.1	.\" RCSid "$Id"
2			.TH RTRACE 1 10/17/97 RADIANCE
3			.SH NAME
4			rtrace - trace rays in RADIANCE scene
5			.SH SYNOPSIS
6			.B rtrace
7			[
8			.B options
9			]
10			[
11			.B $EVAR
12			]
13			[
14			.B @file
15			]
16			.B octree
17			.br
18			.B "rtrace [ options ] \-defaults"
19			.SH DESCRIPTION
20			.I Rtrace
21			traces rays from the standard input through the RADIANCE scene given by
22			.I octree
23			and sends the results to the standard output.
24			(The octree may be given as the output of a command enclosed in quotes
25			and preceded by a `!'.)\0
26			Input for each ray is:
27
28			xorg yorg zorg xdir ydir zdir
29
30			If the direction vector is (0,0,0), a bogus record
31			is printed and the output is flushed if the
32			.I -x
33			value is unset or zero.
34			(See the notes on this option below.)\0
35			This may be useful for programs that run
36			.I rtrace
37			as a separate process.
38			In the second form, the default values
39			for the options (modified by those options present)
40			are printed with a brief explanation.
41			.PP
42			Options may be given on the command line and/or read from the
43			environment and/or read from a file.
44			A command argument beginning with a dollar sign ('$') is immediately
45			replaced by the contents of the given environment variable.
46			A command argument beginning with an at sign ('@') is immediately
47			replaced by the contents of the given file.
48			Most options are followed by one or more arguments, which must be
49			separated from the option and each other by white space.
50			The exceptions to this rule are the boolean options.
51			Normally, the appearance of a boolean option causes a feature to
52			be "toggled", that is switched from off to on or on to off
53			depending on its previous state.
54			Boolean options may also be set
55			explicitly by following them immediately with a '+' or '-', meaning
56			on or off, respectively.
57			Synonyms for '+' are any of the characters "yYtT1", and synonyms
58			for '-' are any of the characters "nNfF0".
59			All other characters will generate an error.
60			.TP 10n
61			.BI -f io
62			Format input according to the character
63			.I i
64			and output according to the character
65			.I o.
66			.I Rtrace
67			understands the following input and output formats: 'a' for
68			ascii, 'f' for single-precision floating point,
69			and 'd' for double-precision floating point.
70			In addition to these three choices, the character 'c' may be used
71			to denote 4-byte floating point (Radiance) color format
72			for the output of values only
73			.I (\-ov
74			option, below).
75			If the output character is missing, the input format is used.
76			.IP
77			Note that there is no space between this option and its argument.
78			.TP
79			.BI -o spec
80			Produce output fields according to
81			.I spec.
82			Characters are interpreted as follows:
83			.IP
84			o origin (input)
85			.IP
86			d direction (normalized)
87			.IP
88			v value (radiance)
89			.IP
90			w weight
91			.IP
92			l effective length of ray
93			.IP
94			L first intersection distance
95			.IP
96			p point of intersection
97			.IP
98			n normal at intersection (perturbed)
99			.IP
100			N normal at intersection (unperturbed)
101			.IP
102			s surface name
103			.IP
104			m modifier name
105			.IP
106			If the letter 't' appears in
107			.I spec,
108			then the fields following will be printed for every ray traced,
109			not just the final result.
110			Spawned rays are indented one tab for each level.
111			.IP
112			Note that there is no space between this option and its argument.
113			.TP
114			.BI -te \ mat
115			Append
116			.I mat
117			to the trace exclude list,
118			so that it will not be reported by the trace option
119			.I (\-ot).
120			Any ray striking an object having
121			.I mat
122			as its modifier will not be reported to the standard output with
123			the rest of the rays being traced.
124			This option has no effect unless the 't' option has been given as
125			part of the output specifier.
126			Any number of excluded materials may be given, but each
127			must appear in a separate option.
128			.TP
129			.BI -ti \ mat
130			Add
131			.I mat
132			to the trace include list,
133			so that it will be considered during the indirect calculation.
134			The program can use either an include list or an exclude
135			list, but not both.
136			.TP
137			.BI -tE \ file
138			Same as
139			.I \-te,
140			except read materials to be excluded from
141			.I file.
142			The RAYPATH environment variable determines which directories are
143			searched for this file.
144			The material names are separated by white space in the file.
145			.TP
146			.BI -tI \ file
147			Same as
148			.I \-ti,
149			except read materials to be included from
150			.I file.
151			.TP
152			.BR \-i
153			Boolean switch to compute irradiance rather than radiance values.
154			This only affects the final result, substituting a Lambertian
155			surface and multiplying the radiance by pi.
156			Glass and other transparent surfaces are ignored during this stage.
157			Light sources still appear with their original radiance values,
158			though the
159			.I \-dv
160			option (below) may be used to override this.
161			This option is especially useful in
162			conjunction with ximage(1) for computing illuminance at scene points.
163			.TP
164			.BR \-I
165			Boolean switch to compute irradiance rather than radiance,
166			with the input origin and direction interpreted instead
167			as measurement point and orientation.
168			.TP
169			.BR \-h
170			Boolean switch for information header on output.
171			.TP
172			.BI -x \ res
173			Set the x resolution to
174			.I res.
175			The output will be flushed after every
176			.I res
177			input rays.
178			A value of zero means that no output flushing will take place.
179			.TP
180			.BI -y \ res
181			Set the y resolution to
182			.I res.
183			The program will exit after
184			.I res
185			scanlines have been processed, where a scanline is the number of rays
186			given by the
187			.I \-x
188			option, or 1 if
189			.I \-x
190			is zero.
191			A value of zero means the program will not halt until the end
192			of file is reached.
193			.IP
194			If both
195			.I \-x
196			and
197			.I \-y
198			options are given, a resolution string is printed at the beginning
199			of the output.
200			This is mostly useful for recovering image dimensions with
201			.I pvalue(1),
202			and for creating valid Radiance picture files using the color output
203			format.
204			(See the
205			.I \-f
206			option, above.)
207			.TP
208			.BI -dj \ frac
209			Set the direct jittering to
210			.I frac.
211			A value of zero samples each source at specific sample points
212			(see the
213			.I \-ds
214			option below), giving a smoother but somewhat less accurate
215			rendering.
216			A positive value causes rays to be distributed over each
217			source sample according to its size, resulting in more accurate
218			penumbras.
219			This option should never be greater than 1, and may even
220			cause problems (such as speckle) when the value is smaller.
221			A warning about aiming failure will issued if
222			.I frac
223			is too large.
224			.TP
225			.BI -ds \ frac
226			Set the direct sampling ratio to
227			.I frac.
228			A light source will be subdivided until
229			the width of each sample area divided by the distance
230			to the illuminated point is below this ratio.
231			This assures accuracy in regions close to large area sources
232			at a slight computational expense.
233			A value of zero turns source subdivision off, sending at most one
234			shadow ray to each light source.
235			.TP
236			.BI -dt \ frac
237			Set the direct threshold to
238			.I frac.
239			Shadow testing will stop when the potential contribution of at least
240			the next and at most all remaining light sources is less than
241			this fraction of the accumulated value.
242			(See the
243			.I \-dc
244			option below.)
245			The remaining light source contributions are approximated
246			statistically.
247			A value of zero means that all light sources will be tested for shadow.
248			.TP
249			.BI \-dc \ frac
250			Set the direct certainty to
251			.I frac.
252			A value of one guarantees that the absolute accuracy of the direct calculation
253			will be equal to or better than that given in the
254			.I \-dt
255			specification.
256			A value of zero only insures that all shadow lines resulting in a contrast
257			change greater than the
258			.I \-dt
259			specification will be calculated.
260			.TP
261			.BI -dr \ N
262			Set the number of relays for secondary sources to
263			.I N.
264			A value of 0 means that secondary sources will be ignored.
265			A value of 1 means that sources will be made into first generation
266			secondary sources; a value of 2 means that first generation
267			secondary sources will also be made into second generation secondary
268			sources, and so on.
269			.TP
270			.BI -dp \ D
271			Set the secondary source presampling density to D.
272			This is the number of samples per steradian
273			that will be used to determine ahead of time whether or not
274			it is worth following shadow rays through all the reflections and/or
275			transmissions associated with a secondary source path.
276			A value of 0 means that the full secondary source path will always
277			be tested for shadows if it is tested at all.
278			.TP
279			.BR \-dv
280			Boolean switch for light source visibility.
281			With this switch off, sources will be black when viewed directly
282			although they will still participate in the direct calculation.
283			This option is mostly for the program
284			.I mkillum(1)
285			to avoid inappropriate counting of light sources, but it
286			may also be desirable in conjunction with the
287			.I \-i
288			option.
289			.TP
290			.BI -sj \ frac
291			Set the specular sampling jitter to
292			.I frac.
293			This is the degree to which the highlights are sampled
294			for rough specular materials.
295			A value of one means that all highlights will be fully sampled
296			using distributed ray tracing.
297			A value of zero means that no jittering will take place, and all
298			reflections will appear sharp even when they should be diffuse.
299			.TP
300			.BI -st \ frac
301			Set the specular sampling threshold to
302			.I frac.
303			This is the minimum fraction of reflection or transmission, under which
304			no specular sampling is performed.
305			A value of zero means that highlights will always be sampled by
306			tracing reflected or transmitted rays.
307			A value of one means that specular sampling is never used.
308			Highlights from light sources will always be correct, but
309			reflections from other surfaces will be approximated using an
310			ambient value.
311			A sampling threshold between zero and one offers a compromise between image
312			accuracy and rendering time.
313			.TP
314			.BR -bv
315			Boolean switch for back face visibility.
316			With this switch off, back faces of opaque objects will be invisible
317			to all rays.
318			This is dangerous unless the model was constructed such that
319			all surface normals on opaque objects face outward.
320			Although turning off back face visibility does not save much
321			computation time under most circumstances, it may be useful as a
322			tool for scene debugging, or for seeing through one-sided walls from
323			the outside.
324			This option has no effect on transparent or translucent materials.
325			.TP
326			.BI -av " red grn blu"
327			Set the ambient value to a radiance of
328			.I "red grn blu".
329			This is the final value used in place of an
330			indirect light calculation.
331			If the number of ambient bounces is one or greater and the ambient
332			value weight is non-zero (see
333			.I -aw
334			and
335			.I -ab
336			below), this value may be modified by the computed indirect values
337			to improve overall accuracy.
338			.TP
339			.BI -aw \ N
340			Set the relative weight of the ambient value given with the
341			.I -av
342			option to
343			.I N.
344			As new indirect irradiances are computed, they will modify the
345			default ambient value in a moving average, with the specified weight
346			assigned to the initial value given on the command and all other
347			weights set to 1.
348			If a value of 0 is given with this option, then the initial ambient
349			value is never modified.
350			This is the safest value for scenes with large differences in
351			indirect contributions, such as when both indoor and outdoor
352			(daylight) areas are visible.
353			.TP
354			.BI -ab \ N
355			Set the number of ambient bounces to
356			.I N.
357			This is the maximum number of diffuse bounces
358			computed by the indirect calculation.
359			A value of zero implies no indirect calculation.
360			.TP
361			.BI -ar \ res
362			Set the ambient resolution to
363			.I res.
364			This number will determine the maximum density of ambient values
365			used in interpolation.
366			Error will start to increase on surfaces spaced closer than
367			the scene size divided by the ambient resolution.
368			The maximum ambient value density is the scene size times the
369			ambient accuracy (see the
370			.I \-aa
371			option below) divided by the ambient resolution.
372			The scene size can be determined using
373			.I getinfo(1)
374			with the
375			.I \-d
376			option on the input octree.
377			.TP
378			.BI -aa \ acc
379			Set the ambient accuracy to
380			.I acc.
381			This value will approximately equal the error
382			from indirect illuminance interpolation.
383			A value of zero implies no interpolation.
384			.TP
385			.BI -ad \ N
386			Set the number of ambient divisions to
387			.I N.
388			The error in the Monte Carlo calculation of indirect
389			illuminance will be inversely proportional to the square
390			root of this number.
391			A value of zero implies no indirect calculation.
392			.TP
393			.BI -as \ N
394			Set the number of ambient super-samples to
395			.I N.
396			Super-samples are applied only to the ambient divisions which
397			show a significant change.
398			.TP
399			.BI -af \ fname
400			Set the ambient file to
401			.I fname.
402			This is where indirect illuminance will be stored and retrieved.
403			Normally, indirect illuminance values are kept in memory and
404			lost when the program finishes or dies.
405			By using a file, different invocations can share illuminance
406			values, saving time in the computation.
407			The ambient file is in a machine-independent binary format
408			which can be examined with
409			.I lookamb(1).
410			.IP
411			The ambient file may also be used as a means of communication and
412			data sharing between simultaneously executing processes.
413			The same file may be used by multiple processes, possibly running on
414			different machines and accessing the file via the network (ie.
415			.I nfs(4)).
416			The network lock manager
417			.I lockd(8)
418			is used to insure that this information is used consistently.
419			.IP
420			If any calculation parameters are changed or the scene
421			is modified, the old ambient file should be removed so that
422			the calculation can start over from scratch.
423			For convenience, the original ambient parameters are listed in the
424			header of the ambient file.
425			.I Getinfo(1)
426			may be used to print out this information.
427			.TP
428			.BI -ae \ mat
429			Append
430			.I mat
431			to the ambient exclude list,
432			so that it will not be considered during the indirect calculation.
433			This is a hack for speeding the indirect computation by
434			ignoring certain objects.
435			Any object having
436			.I mat
437			as its modifier will get the default ambient
438			level rather than a calculated value.
439			Any number of excluded materials may be given, but each
440			must appear in a separate option.
441			.TP
442			.BI -ai \ mat
443			Add
444			.I mat
445			to the ambient include list,
446			so that it will be considered during the indirect calculation.
447			The program can use either an include list or an exclude
448			list, but not both.
449			.TP
450			.BI -aE \ file
451			Same as
452			.I \-ae,
453			except read materials to be excluded from
454			.I file.
455			The RAYPATH environment variable determines which directories are
456			searched for this file.
457			The material names are separated by white space in the file.
458			.TP
459			.BI -aI \ file
460			Same as
461			.I \-ai,
462			except read materials to be included from
463			.I file.
464			.TP
465			.BI -me " rext gext bext"
466			Set the global medium extinction coefficient to the indicated color,
467			in units of 1/distance (distance in world coordinates).
468			Light will be scattered or absorbed over distance according to
469			this value.
470			The ratio of scattering to total scattering plus absorption is set
471			by the albedo parameter, described below.
472			.TP
473			.BI -ma " ralb galb balb"
474			Set the global medium albedo to the given value between 0\00\00
475			and 1\01\01.
476			A zero value means that all light not transmitted by the medium
477			is absorbed.
478			A unitary value means that all light not transmitted by the medium
479			is scattered in some new direction.
480			The isotropy of scattering is determined by the Heyney-Greenstein
481			parameter, described below.
482			.TP
483			.BI \-mg \ gecc
484			Set the medium Heyney-Greenstein eccentricity parameter to
485			.I gecc.
486			This parameter determines how strongly scattering favors the forward
487			direction.
488			A value of 0 indicates perfectly isotropic scattering.
489			As this parameter approaches 1, scattering tends to prefer the
490			forward direction.
491			.TP
492			.BI \-ms \ sampdist
493			Set the medium sampling distance to
494			.I sampdist,
495			in world coordinate units.
496			During source scattering, this will be the average distance between
497			adjacent samples.
498			A value of 0 means that only one sample will be taken per light
499			source within a given scattering volume.
500			.TP
501			.BI -lr \ N
502			Limit reflections to a maximum of
503			.I N.
504			.TP
505			.BI -lw \ frac
506			Limit the weight of each ray to a minimum of
507			.I frac.
508			During ray-tracing, a record is kept of the final contribution
509			a ray would have to the image.
510			If it is less then the specified minimum, the ray is not traced.
511			.TP
512			.BR -ld
513			Boolean switch to limit ray distance.
514			If this option is set, then rays will only be traced as far as the
515			magnitude of each direction vector.
516			Otherwise, vector magnitude is ignored and rays are traced to infinity.
517			.TP
518			.BI -e \ efile
519			Send error messages and progress reports to
520			.I efile
521			instead of the standard error.
522			.TP
523			.BR \-w
524			Boolean switch to suppress warning messages.
525			.TP
526			.BI \-P \ pfile
527			Execute in a persistent mode, using
528			.I pfile
529			as the control file.
530			Persistent execution means that after reaching end-of-file on
531			its input,
532			.I rtrace
533			will fork a child process that will wait for another
534			.I rtrace
535			command with the same
536			.I \-P
537			option to attach to it.
538			(Note that since the rest of the command line options will be those
539			of the original invocation, it is not necessary to give any arguments
540			besides
541			.I \-P
542			for subsequent calls.)
543			Killing the process is achieved with the
544			.I kill(1)
545			command.
546			(The process ID in the first line of
547			.I pfile
548			may be used to identify the waiting
549			.I rtrace
550			process.)
551			This option may be used with the
552			.I \-fr
553			option of
554			.I pinterp(1)
555			to avoid the cost of starting up
556			.I rtrace
557			many times.
558			.TP
559			.BI \-PP \ pfile
560			Execute in continuous-forking persistent mode, using
561			.I pfile
562			as the control file.
563			The difference between this option and the
564			.I \-P
565			option described above is the creation of multiple duplicate
566			processes to handle any number of attaches.
567			This provides a simple and reliable mechanism of memory sharing
568			on most multiprocessing platforms, since the
569			.I fork(2)
570			system call will share memory on a copy-on-write basis.
571			.SH EXAMPLES
572			To compute radiance values for the rays listed in samples.inp:
573			.IP "" .2i
574			rtrace -ov scene.oct < samples.inp > radiance.out
575			.PP
576			To compute illuminance values at locations selected with the 't'
577			command of
578			.I ximage(1):
579			.IP "" .2i
580			ximage scene.pic \| rtrace -h -x 1 -i scene.oct \| rcalc -e '$1=47.4$1+120$2+11.6*$3'
581			.PP
582			To record the object identifier corresponding to each pixel in an image:
583			.IP "" .2i
584			vwrays -fd scene.pic \| rtrace -fda `vwrays -d scene.pic` -os scene.oct
585			.PP
586			To compute an image with an unusual view mapping:
587			.IP "" .2i
588			cnt 640 480 \| rcalc -e 'xr:640;yr:480' -f unusual_view.cal \| rtrace
589			-x 640 -y 480 -fac scene.oct > unusual.pic
590			.SH ENVIRONMENT
591			RAYPATH the directories to check for auxiliary files.
592			.SH FILES
593			/usr/tmp/rtXXXXXX common header information for picture sequence
594			.SH DIAGNOSTICS
595			If the program terminates from an input related error, the exit status
596			will be 1.
597			A system related error results in an exit status of 2.
598			If the program receives a signal that is caught, it will exit with a status
599			of 3.
600			In each case, an error message will be printed to the standard error, or
601			to the file designated by the
602			.I \-e
603			option.
604			.SH AUTHOR
605			Greg Ward
606			.SH "SEE ALSO"
607			getinfo(1), lookamb(1), oconv(1), pfilt(1), pinterp(1),
608			pvalue(1), rpict(1), rview(1), vwrays(1), ximage(1)