man/man1/rpiece.1

.\" RCSid "$Id: rpiece.1,v 1.2 2003/12/09 15:59:07 greg Exp $"
.TH RPIECE 1 10/1/98 RADIANCE
.SH NAME
rpiece - render pieces of a RADIANCE picture
.SH SYNOPSIS
.B rpiece
[
.B \-v
][
.B "\-x xres"
][
.B "\-y yres"
][
.B "\-X xdiv"
][
.B "\-Y ydiv"
][
.B "\-F|R syncfile"
][
.B "\-T timelim"
]
[
.B $EVAR
]
[
.B @file
]
[
rpict options
]
.B "\-o picture"
.B octree
.SH DESCRIPTION
.I Rpiece
renders a RADIANCE picture a piece at a time, calling
.I rpict(1)
to do the actual work.
This is useful for running multiple
.I rpict
processes on cooperating machines to render a single picture,
which is a shared file specified with the
.I \-o
option.
The overall picture dimensions will be
.I xres
by
.I yres
(or smaller, depending on the
.I \-pa
option and other view options), and the picture will be rendered in
.I xdiv
by
.I ydiv
pieces.
.PP
There are two basic methods for telling
.I rpiece
which piece(s) of a picture to render.
The explicit method is to write on the standard input the
.I X
and
.I Y
position of the desired piece(s), where
.I X
runs from zero to
.I xdiv\-\1
and
.I Y
runs from zero to
.I ydiv\-\1.
(The lower left piece of a picture corresponds to (0,0) in this
system.)\0
Alternatively, the implicit specification method uses a
synchronization file to
determine which piece is to be rendered next.
Specified with the
.I \-F
option,
.I syncfile
initially contains the values for
.I xdiv
and
.I ydiv,
so the
.I \-X
and
.I \-Y
options are unnecessary.
(However, they are used if
.I syncfile
does not exist.)\0
The first
.I rpiece
process puts a lock on
.I syncfile
and modifies its contents before
starting work on the first piece of the image.
It writes the
.I X
and
.I Y
position of the piece it will work on, so the next
.I rpiece
process to modify
.I syncfile
will start on the next piece.
(When it finishes with its piece, it appends the index to the end of
.I syncfile.)
This procedure continues until all the pieces are done, at which point all
of the
.I rpiece
processes will terminate.
.PP
The
.I \-R
option may be used instead of
.I \-F
if some of the pieces were not properly finished by previous (killed)
runs of
.I rpiece.
This option should be used by at most one
.I rpiece
process, which must be started first and with
.I "no other rpiece processes running"
or else it will rerender the same pieces other processes have begun.
Once the recover process is started, you may start other
.I rpiece
processes using the
.I \-F
option to run simultaneously.
If some processes die during execution, leaving one or more half-finished
pieces in the picture even though the other processes think the
work is done, you may run a single
.I rpiece
with the
.I \-R
option by itself to repair the holes.
.PP
The
.I \-v
flag switches on verbose mode, where
.I rpiece
reports to the standard output after each piece begins and
after each piece is finished.
.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"
getinfo(1), pfilt(1), ra_rgbe(1), rpict(1), ximage(1)
Revision:	1.3
Committed:	Tue Sep 4 17:36:41 2007 UTC (18 years, 1 month ago) by greg
Branch:	MAIN
CVS Tags:	rad5R0, rad5R1, rad4R2, rad4R1, rad4R0, rad3R9, rad4R2P1, rad4R2P2
Changes since 1.2:	+3 -3 lines
Log Message:	Added backslashes in front of hyphens (thanks to Bernd Zeimetz for his effort)
#	User	Rev	Content
1	greg	1.3	.\" RCSid "$Id: rpiece.1,v 1.2 2003/12/09 15:59:07 greg Exp $"
2	greg	1.1	.TH RPIECE 1 10/1/98 RADIANCE
3			.SH NAME
4			rpiece - render pieces of a RADIANCE picture
5			.SH SYNOPSIS
6			.B rpiece
7			[
8			.B \-v
9			][
10			.B "\-x xres"
11			][
12			.B "\-y yres"
13			][
14			.B "\-X xdiv"
15			][
16			.B "\-Y ydiv"
17			][
18			.B "\-F\|R syncfile"
19			][
20			.B "\-T timelim"
21			]
22			[
23			.B $EVAR
24			]
25			[
26			.B @file
27			]
28			[
29			rpict options
30			]
31			.B "\-o picture"
32			.B octree
33			.SH DESCRIPTION
34			.I Rpiece
35			renders a RADIANCE picture a piece at a time, calling
36			.I rpict(1)
37			to do the actual work.
38			This is useful for running multiple
39			.I rpict
40			processes on cooperating machines to render a single picture,
41			which is a shared file specified with the
42			.I \-o
43			option.
44			The overall picture dimensions will be
45			.I xres
46			by
47			.I yres
48			(or smaller, depending on the
49			.I \-pa
50			option and other view options), and the picture will be rendered in
51			.I xdiv
52			by
53			.I ydiv
54			pieces.
55			.PP
56			There are two basic methods for telling
57			.I rpiece
58			which piece(s) of a picture to render.
59			The explicit method is to write on the standard input the
60			.I X
61			and
62			.I Y
63			position of the desired piece(s), where
64			.I X
65			runs from zero to
66			.I xdiv\-\1
67			and
68			.I Y
69			runs from zero to
70			.I ydiv\-\1.
71			(The lower left piece of a picture corresponds to (0,0) in this
72			system.)\0
73			Alternatively, the implicit specification method uses a
74			synchronization file to
75			determine which piece is to be rendered next.
76			Specified with the
77			.I \-F
78			option,
79			.I syncfile
80			initially contains the values for
81			.I xdiv
82			and
83			.I ydiv,
84			so the
85			.I \-X
86			and
87			.I \-Y
88			options are unnecessary.
89			(However, they are used if
90			.I syncfile
91			does not exist.)\0
92			The first
93			.I rpiece
94			process puts a lock on
95			.I syncfile
96			and modifies its contents before
97			starting work on the first piece of the image.
98			It writes the
99			.I X
100			and
101			.I Y
102			position of the piece it will work on, so the next
103			.I rpiece
104			process to modify
105			.I syncfile
106			will start on the next piece.
107			(When it finishes with its piece, it appends the index to the end of
108			.I syncfile.)
109			This procedure continues until all the pieces are done, at which point all
110			of the
111			.I rpiece
112			processes will terminate.
113			.PP
114			The
115			.I \-R
116			option may be used instead of
117			.I \-F
118			if some of the pieces were not properly finished by previous (killed)
119			runs of
120			.I rpiece.
121			This option should be used by at most one
122			.I rpiece
123			process, which must be started first and with
124			.I "no other rpiece processes running"
125			or else it will rerender the same pieces other processes have begun.
126			Once the recover process is started, you may start other
127			.I rpiece
128			processes using the
129			.I \-F
130			option to run simultaneously.
131			If some processes die during execution, leaving one or more half-finished
132			pieces in the picture even though the other processes think the
133			work is done, you may run a single
134			.I rpiece
135			with the
136			.I \-R
137			option by itself to repair the holes.
138			.PP
139			The
140			.I \-v
141			flag switches on verbose mode, where
142			.I rpiece
143			reports to the standard output after each piece begins and
144			after each piece is finished.
145			.PP
146			Options may be given on the command line and/or read from the
147			environment and/or read from a file.
148			A command argument beginning with a dollar sign ('$') is immediately
149			replaced by the contents of the given environment variable.
150			A command argument beginning with an at sign ('@') is immediately
151			replaced by the contents of the given file.
152			.SH EXAMPLE
153			First
154			.I rpiece
155			process is started on the machine "goober":
156			.IP "" .2i
157			goober% echo 1 8 > syncfile
158			.br
159	greg	1.3	goober% echo \-F syncfile \-x 1024 \-y 1024 \-vf view \-o picture octree > args
160	greg	1.1	.br
161			goober% rpiece @args &
162			.PP
163			Second
164			.I rpiece
165			processes is started on the machine "sucker":
166			.IP "" .2i
167			sucker% rpiece @args &
168			.SH NOTES
169			Due to NFS file buffering, the network lock manager is employed to
170			guarantee consistency in the output file even though non-overlapping
171			writes are used.
172			This would tend to slow the process down if
173			.I rpiece
174			were to wait for this I/O to complete before starting on the next
175			piece, so
176			.I rpiece
177			forks separate processes to hang around waiting for I/O completion.
178			The number of processes thus designated is set by the MAXFORK macro
179			in the program (compiled in the src/util directory).
180			If the fork call is slow on a system, it may actually be better to
181			set MAXFORK to zero.
182			In other cases, the network lock manager may be so slow that this
183			value should be increased to get the best utilization.
184			.PP
185			The output picture is not run-length encoded, and can be quite
186			large.
187			The approximate size (in kilobytes) can be computed by the simple
188			formula:
189			.IP "" .2i
190			filesize = xres*yres/256
191			.PP
192			Make sure that there is enough space on the filesystem to hold the
193			entire picture before beginning.
194			Once the picture is finished, the
195			.I ra_rgbe(1)
196	greg	1.3	program with the \-r option may be used to convert to a run\-length
197	greg	1.1	encoded picture for more efficient storage, although
198			.I pfilt(1)
199			or any of the other Radiance picture filters will do the same
200			thing.
201			.PP
202			The ALRM signal may be used to gracefully terminate an
203			.I rpiece
204			process after it finishes the current piece.
205			This permits other currently running or subsequently started
206			.I rpiece
207			process(es) to continue rendering the picture without loss.
208			The
209			.I \-T
210			option will send the ALRM signal to
211			.I rpiece
212			after the specified number of (decimal) hours.
213			This is the best way to force a time limit on the computation,
214			since information will not be lost, though the process may continue
215			for some time afterwards to finish its current piece.
216			.SH BUGS
217			This program may not work on some systems whose NFS lock manager is
218			unreliable.
219			In particular, some System V derivative UNIX systems often have
220			problems with the network lock manager.
221			If the output is scrambled or rpict aborts with some ambient file
222			related problem, you should just remove the ambient file and go
223			back to normal rendering.
224			.SH AUTHOR
225			Greg Ward
226			.SH "SEE ALSO"
227			getinfo(1), pfilt(1), ra_rgbe(1), rpict(1), ximage(1)