man/man1/rtcontrib.1

.\" RCSid "$Id$"
.TH RPIECE 1 5/25/05 RADIANCE
.SH NAME
rtcontrib - compute contributions in a RADIANCE scene
.SH SYNOPSIS
.B rtcontrib
[
.B "\-n nprocs"
][
.B "\-e expr"
][
.B "\-f source"
][
.B "\-o fspec"
][
.B "\-b binv"
]
[
.B $EVAR
]
[
.B @file
]
[
rtrace options
]
.B "\-m mod .."
.B octree
.SH DESCRIPTION
.I Rtcontrib
computes ray contributions (i.e., color coefficients)
for objects whose modifiers are named in one or more
.I \-m
settings.
These modifiers are usually materials associated with specific
light sources, though they could correspond to intermediate objects as well.
The resulting contributions may then be used in linear combination to
reproduce any desired variation, e.g., simulating lighting controls or
changing sky conditions via daylight coefficients.
More generally,
.I rtcontrib
can compute general input-output relationships in optical
systems, such as light pipes and shading devices.
.PP
.I Rtrace(1)
is called to calculate the contributions for each input ray,
and the output tallies are sent to one or more files according to the
.I \-o
specification.
If the output file specification contains a "%s" format, this will be
replaced by the modifier name.
The
.I \-b
option may be used to further define
a "bin number" within each object if finer resolution is desired, and
will be applied to a "%d" format in the output file
specification if present.
(The actual bin number is computed at run time based on ray direction
and surface intersection, as described below.)\0
The most recent
.I \-b
and
.I \-o
options (to the left) of each
.I \-m
setting affect only that modifier, and the ordering
of other options is unimportant.
.PP
Input and output format defaults to plain text, where each ray's
origin and direction (6 real values) must appear together per
line of input, and one line of output is produced per output file
file per ray.
Alternative input and output formats may be specified using the
.I \-f[io]
option, which is explained in the
.I rtrace
man page along with the associated
.I \-x
and
.I \-y
resolution settings.
In particular, the 'c' output setting
together with positive dimensions for
.I \-x
and
.I \-y
will produce an uncompressed RADIANCE picture,
suitable for manipulation with
.I pcomb(1)
and related tools.
.PP
If no
.I \-o
specification is given, results are written on the standard output in order
of modifier (as given on the command line) then bin number.
The same format is used for a simple file name specification
without any embedded "%s" or "%d" formats.
If a "%s" format appears but no "%d" in the
.I \-o
specification, then each modifier will have its own output file, with
multiple values per record in the case of a non-zero
.I \-b
definition.
If a "%d" format appears but no "%s", then each bin will get its own
output file, with modifiers output in order in each record.
For text output, each RGB coefficient triple is separated by a tab,
with a newline at the end of each ray record.
For binary output formats, there is no such delimiter to mark
the end of each record.
.PP
If a
.I \-b
expression is defined for a particular modifier,
the bin number will be evaluated at run time for each
ray contribution from
.I rtrace.
Specifically, each ray's world intersection point will be assigned to
the variables Px, Py, and Pz, and the normalized ray direction
will be assigned to Dx, Dy, and Dz.
These ray parameters may be combined with any definitions given in
.I \-e
options, or any files read in from
.I \-f
options, to compute the bin, which will be
rounded to the closest whole number.
This mechanism allows the user to define precise regions (or directions)
they wish to accumulate, such as the Tregenza sky grid, which would be
otherwise impossible to specify as a set of RADIANCE primitives.
.PP
If the
.I \-n
option is specified with a value greater than 1, multiple
.I rtrace(1)
processes will be used to accelerate computation on a shared
memory machine.
Note that there is no benefit to using more processes
than there are local CPUs available to do the work.
.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.
.SH EXAMPLE
First
.I rpiece
process is started on the machine "goober":
.IP "" .2i
goober% echo 1 8 > syncfile
.br
goober% echo -F syncfile -x 1024 -y 1024 -vf view -o picture octree > args
.br
goober% rpiece @args &
.PP
Second
.I rpiece
processes is started on the machine "sucker":
.IP "" .2i
sucker% rpiece @args &
.SH NOTES
Due to NFS file buffering, the network lock manager is employed to
guarantee consistency in the output file even though non-overlapping
writes are used.
This would tend to slow the process down if
.I rpiece
were to wait for this I/O to complete before starting on the next
piece, so
.I rpiece
forks separate processes to hang around waiting for I/O completion.
The number of processes thus designated is set by the MAXFORK macro
in the program (compiled in the src/util directory).
If the fork call is slow on a system, it may actually be better to
set MAXFORK to zero.
In other cases, the network lock manager may be so slow that this
value should be increased to get the best utilization.
.PP
The output picture is not run-length encoded, and can be quite
large.
The approximate size (in kilobytes) can be computed by the simple
formula:
.IP "" .2i
filesize = xres*yres/256
.PP
Make sure that there is enough space on the filesystem to hold the
entire picture before beginning.
Once the picture is finished, the
.I ra_rgbe(1)
program with the -r option may be used to convert to a run-length
encoded picture for more efficient storage, although
.I pfilt(1)
or any of the other Radiance picture filters will do the same
thing.
.PP
The ALRM signal may be used to gracefully terminate an
.I rpiece
process after it finishes the current piece.
This permits other currently running or subsequently started
.I rpiece
process(es) to continue rendering the picture without loss.
The
.I \-T
option will send the ALRM signal to
.I rpiece
after the specified number of (decimal) hours.
This is the best way to force a time limit on the computation,
since information will not be lost, though the process may continue
for some time afterwards to finish its current piece.
.SH BUGS
This program may not work on some systems whose NFS lock manager is
unreliable.
In particular, some System V derivative UNIX systems often have
problems with the network lock manager.
If the output is scrambled or rpict aborts with some ambient file
related problem, you should just remove the ambient file and go
back to normal rendering.
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
cnt(1), getinfo(1), pcomb(1), pfilt(1), ra_rgbe(1),
rcalc(1), rpict(1), rtrace(1), vwrays(1), ximage(1)
Revision:	1.1
Committed:	Thu May 26 06:55:22 2005 UTC (19 years ago) by greg
Branch:	MAIN
Log Message:	Got rtcontrib working and wrote basic man page
#	User	Rev	Content
1	greg	1.1	.\" RCSid "$Id$"
2			.TH RPIECE 1 5/25/05 RADIANCE
3			.SH NAME
4			rtcontrib - compute contributions in a RADIANCE scene
5			.SH SYNOPSIS
6			.B rtcontrib
7			[
8			.B "\-n nprocs"
9			][
10			.B "\-e expr"
11			][
12			.B "\-f source"
13			][
14			.B "\-o fspec"
15			][
16			.B "\-b binv"
17			]
18			[
19			.B $EVAR
20			]
21			[
22			.B @file
23			]
24			[
25			rtrace options
26			]
27			.B "\-m mod .."
28			.B octree
29			.SH DESCRIPTION
30			.I Rtcontrib
31			computes ray contributions (i.e., color coefficients)
32			for objects whose modifiers are named in one or more
33			.I \-m
34			settings.
35			These modifiers are usually materials associated with specific
36			light sources, though they could correspond to intermediate objects as well.
37			The resulting contributions may then be used in linear combination to
38			reproduce any desired variation, e.g., simulating lighting controls or
39			changing sky conditions via daylight coefficients.
40			More generally,
41			.I rtcontrib
42			can compute general input-output relationships in optical
43			systems, such as light pipes and shading devices.
44			.PP
45			.I Rtrace(1)
46			is called to calculate the contributions for each input ray,
47			and the output tallies are sent to one or more files according to the
48			.I \-o
49			specification.
50			If the output file specification contains a "%s" format, this will be
51			replaced by the modifier name.
52			The
53			.I \-b
54			option may be used to further define
55			a "bin number" within each object if finer resolution is desired, and
56			will be applied to a "%d" format in the output file
57			specification if present.
58			(The actual bin number is computed at run time based on ray direction
59			and surface intersection, as described below.)\0
60			The most recent
61			.I \-b
62			and
63			.I \-o
64			options (to the left) of each
65			.I \-m
66			setting affect only that modifier, and the ordering
67			of other options is unimportant.
68			.PP
69			Input and output format defaults to plain text, where each ray's
70			origin and direction (6 real values) must appear together per
71			line of input, and one line of output is produced per output file
72			file per ray.
73			Alternative input and output formats may be specified using the
74			.I \-f[io]
75			option, which is explained in the
76			.I rtrace
77			man page along with the associated
78			.I \-x
79			and
80			.I \-y
81			resolution settings.
82			In particular, the 'c' output setting
83			together with positive dimensions for
84			.I \-x
85			and
86			.I \-y
87			will produce an uncompressed RADIANCE picture,
88			suitable for manipulation with
89			.I pcomb(1)
90			and related tools.
91			.PP
92			If no
93			.I \-o
94			specification is given, results are written on the standard output in order
95			of modifier (as given on the command line) then bin number.
96			The same format is used for a simple file name specification
97			without any embedded "%s" or "%d" formats.
98			If a "%s" format appears but no "%d" in the
99			.I \-o
100			specification, then each modifier will have its own output file, with
101			multiple values per record in the case of a non-zero
102			.I \-b
103			definition.
104			If a "%d" format appears but no "%s", then each bin will get its own
105			output file, with modifiers output in order in each record.
106			For text output, each RGB coefficient triple is separated by a tab,
107			with a newline at the end of each ray record.
108			For binary output formats, there is no such delimiter to mark
109			the end of each record.
110			.PP
111			If a
112			.I \-b
113			expression is defined for a particular modifier,
114			the bin number will be evaluated at run time for each
115			ray contribution from
116			.I rtrace.
117			Specifically, each ray's world intersection point will be assigned to
118			the variables Px, Py, and Pz, and the normalized ray direction
119			will be assigned to Dx, Dy, and Dz.
120			These ray parameters may be combined with any definitions given in
121			.I \-e
122			options, or any files read in from
123			.I \-f
124			options, to compute the bin, which will be
125			rounded to the closest whole number.
126			This mechanism allows the user to define precise regions (or directions)
127			they wish to accumulate, such as the Tregenza sky grid, which would be
128			otherwise impossible to specify as a set of RADIANCE primitives.
129			.PP
130			If the
131			.I \-n
132			option is specified with a value greater than 1, multiple
133			.I rtrace(1)
134			processes will be used to accelerate computation on a shared
135			memory machine.
136			Note that there is no benefit to using more processes
137			than there are local CPUs available to do the work.
138			.PP
139			Options may be given on the command line and/or read from the
140			environment and/or read from a file.
141			A command argument beginning with a dollar sign ('$') is immediately
142			replaced by the contents of the given environment variable.
143			A command argument beginning with an at sign ('@') is immediately
144			replaced by the contents of the given file.
145			.SH EXAMPLE
146			First
147			.I rpiece
148			process is started on the machine "goober":
149			.IP "" .2i
150			goober% echo 1 8 > syncfile
151			.br
152			goober% echo -F syncfile -x 1024 -y 1024 -vf view -o picture octree > args
153			.br
154			goober% rpiece @args &
155			.PP
156			Second
157			.I rpiece
158			processes is started on the machine "sucker":
159			.IP "" .2i
160			sucker% rpiece @args &
161			.SH NOTES
162			Due to NFS file buffering, the network lock manager is employed to
163			guarantee consistency in the output file even though non-overlapping
164			writes are used.
165			This would tend to slow the process down if
166			.I rpiece
167			were to wait for this I/O to complete before starting on the next
168			piece, so
169			.I rpiece
170			forks separate processes to hang around waiting for I/O completion.
171			The number of processes thus designated is set by the MAXFORK macro
172			in the program (compiled in the src/util directory).
173			If the fork call is slow on a system, it may actually be better to
174			set MAXFORK to zero.
175			In other cases, the network lock manager may be so slow that this
176			value should be increased to get the best utilization.
177			.PP
178			The output picture is not run-length encoded, and can be quite
179			large.
180			The approximate size (in kilobytes) can be computed by the simple
181			formula:
182			.IP "" .2i
183			filesize = xres*yres/256
184			.PP
185			Make sure that there is enough space on the filesystem to hold the
186			entire picture before beginning.
187			Once the picture is finished, the
188			.I ra_rgbe(1)
189			program with the -r option may be used to convert to a run-length
190			encoded picture for more efficient storage, although
191			.I pfilt(1)
192			or any of the other Radiance picture filters will do the same
193			thing.
194			.PP
195			The ALRM signal may be used to gracefully terminate an
196			.I rpiece
197			process after it finishes the current piece.
198			This permits other currently running or subsequently started
199			.I rpiece
200			process(es) to continue rendering the picture without loss.
201			The
202			.I \-T
203			option will send the ALRM signal to
204			.I rpiece
205			after the specified number of (decimal) hours.
206			This is the best way to force a time limit on the computation,
207			since information will not be lost, though the process may continue
208			for some time afterwards to finish its current piece.
209			.SH BUGS
210			This program may not work on some systems whose NFS lock manager is
211			unreliable.
212			In particular, some System V derivative UNIX systems often have
213			problems with the network lock manager.
214			If the output is scrambled or rpict aborts with some ambient file
215			related problem, you should just remove the ambient file and go
216			back to normal rendering.
217			.SH AUTHOR
218			Greg Ward
219			.SH "SEE ALSO"
220			cnt(1), getinfo(1), pcomb(1), pfilt(1), ra_rgbe(1),
221			rcalc(1), rpict(1), rtrace(1), vwrays(1), ximage(1)