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
#	Content
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)