man/man1/rpiece.1

.\" RCSid "$Id: rpiece.1,v 1.4 2018/03/20 02:40:38 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
argument.
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), rtpict(1), rxpiece(1), ximage(1)
Revision:	1.5
Committed:	Wed Jun 4 20:32:24 2025 UTC (4 months, 3 weeks ago) by greg
Branch:	MAIN
CVS Tags:	rad6R0, HEAD
Changes since 1.4:	+3 -3 lines
Error occurred while calculating annotation data.
Log Message:	feat(rxpiece): Added rxpiece to standard distribution
#	Content
1	.\" RCSid "$Id: rpiece.1,v 1.4 2018/03/20 02:40:38 greg Exp $"
2	.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	argument.
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	goober% echo \-F syncfile \-x 1024 \-y 1024 \-vf view \-o picture octree > args
160	.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	program with the \-r option may be used to convert to a run\-length
197	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), rtpict(1), rxpiece(1), ximage(1)