man/man1/rtrace.1

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