man/man1/rxpiece.1

.\" RCSid "$Id: rpiece.1,v 1.4 2018/03/20 02:40:38 greg Exp $"
.TH RXPIECE 1 6/4/2025 RADIANCE
.SH NAME
rxpiece - render tiles in a RADIANCE picture/depth buffer
.SH SYNOPSIS
.B rxpiece
[
.B "\-n nproc"
][
.B "\-x xres"
][
.B "\-y yres"
][
.B "\-X xdiv"
][
.B "\-Y ydiv"
][
.B "\-f{f|c}"
][
.B "\-d ref_depth/unit"
]
[
.B $EVAR
]
[
.B @file
]
[
rpict options
]
.B "\-o picture"
.B octree
.SH DESCRIPTION
.I Rxpiece
renders a RADIANCE picture a tile at a time.
This is useful for running multiple cooperating
processes to create a single picture.
Output is written to a memory-mapped file specified with the
.I \-o
argument.
The format will be determined by the
.I \-p
and
.I \-f
options.
The first is detailed in the
.I rpict(1)
man page, and the second may be
.I \-fc
for uncompressed common-exponent format or
.I \-ff
for float picture (matrix) output.
An output depth map may be given as well with the
.I \-z
option, which will be stored as raw float by default,
but can be written as a 16-bit/depth encoding if the
.I \-d
option is used to specify a reference depth/unit.
(See
.I rcode_depth(1).)
.PP
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
tiles.
.PP
If the output picture file already exists, new tiles will
be rendered into it.
In this way, multiple invocations of
.I rxpiece
may be used with or without the
.I \-n
multiprocessing option.
.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
Run 8
.I rxpiece
processes and create an encoded depth map with a 10-meter reference:
.IP "" .2i
rxpiece -n 8 -d 10/meter -z scene.dpt -o scene.hdr scene.oct
.SH NOTES
Unfortunately, memory-mapped files are not supported across a
network, so
.I rxpiece
only works on a single machine.
If network rendering is desired, use
.I rpiece(1),
instead.
.PP
The main advantage of
.I rxpiece
over
.I rpiece
is the
.I \-n
multiprocessing option, which requires only a single invocation
to render a tiled picture efficiently.
.I Rxpiece
also supports more output types and options, such as float and
depth map results.
Because it avoids the need for a sync file, preferring a shared
memory map, tile assignment and recovery is faster and more robust
on a single machine.
.PP
The output picture is not run-length encoded, and can be quite
large.
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 rxpiece
process after it finishes the tile it is working on.
This permits other currently running or subsequently started
.I rxpiece
process(es) to continue rendering tiles with no lost effort.
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
getinfo(1), pfilt(1), ra_rgbe(1), rcode_depth(1), rcomb(1),
rmtxop(1), rpict(1), rpiece(1), rtpict(1), ximage(1)
Revision:	1.1
Committed:	Wed Jun 4 20:32:24 2025 UTC (4 months, 3 weeks ago) by greg
Branch:	MAIN
CVS Tags:	rad6R0, HEAD
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 RXPIECE 1 6/4/2025 RADIANCE
3	.SH NAME
4	rxpiece - render tiles in a RADIANCE picture/depth buffer
5	.SH SYNOPSIS
6	.B rxpiece
7	[
8	.B "\-n nproc"
9	][
10	.B "\-x xres"
11	][
12	.B "\-y yres"
13	][
14	.B "\-X xdiv"
15	][
16	.B "\-Y ydiv"
17	][
18	.B "\-f{f\|c}"
19	][
20	.B "\-d ref_depth/unit"
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 Rxpiece
35	renders a RADIANCE picture a tile at a time.
36	This is useful for running multiple cooperating
37	processes to create a single picture.
38	Output is written to a memory-mapped file specified with the
39	.I \-o
40	argument.
41	The format will be determined by the
42	.I \-p
43	and
44	.I \-f
45	options.
46	The first is detailed in the
47	.I rpict(1)
48	man page, and the second may be
49	.I \-fc
50	for uncompressed common-exponent format or
51	.I \-ff
52	for float picture (matrix) output.
53	An output depth map may be given as well with the
54	.I \-z
55	option, which will be stored as raw float by default,
56	but can be written as a 16-bit/depth encoding if the
57	.I \-d
58	option is used to specify a reference depth/unit.
59	(See
60	.I rcode_depth(1).)
61	.PP
62	The overall picture dimensions will be
63	.I xres
64	by
65	.I yres
66	or smaller, depending on the
67	.I \-pa
68	option and other view options, and the picture will be rendered in
69	.I xdiv
70	by
71	.I ydiv
72	tiles.
73	.PP
74	If the output picture file already exists, new tiles will
75	be rendered into it.
76	In this way, multiple invocations of
77	.I rxpiece
78	may be used with or without the
79	.I \-n
80	multiprocessing option.
81	.PP
82	Options may be given on the command line and/or read from the
83	environment and/or read from a file.
84	A command argument beginning with a dollar sign ('$') is immediately
85	replaced by the contents of the given environment variable.
86	A command argument beginning with an at sign ('@') is immediately
87	replaced by the contents of the given file.
88	.SH EXAMPLE
89	Run 8
90	.I rxpiece
91	processes and create an encoded depth map with a 10-meter reference:
92	.IP "" .2i
93	rxpiece -n 8 -d 10/meter -z scene.dpt -o scene.hdr scene.oct
94	.SH NOTES
95	Unfortunately, memory-mapped files are not supported across a
96	network, so
97	.I rxpiece
98	only works on a single machine.
99	If network rendering is desired, use
100	.I rpiece(1),
101	instead.
102	.PP
103	The main advantage of
104	.I rxpiece
105	over
106	.I rpiece
107	is the
108	.I \-n
109	multiprocessing option, which requires only a single invocation
110	to render a tiled picture efficiently.
111	.I Rxpiece
112	also supports more output types and options, such as float and
113	depth map results.
114	Because it avoids the need for a sync file, preferring a shared
115	memory map, tile assignment and recovery is faster and more robust
116	on a single machine.
117	.PP
118	The output picture is not run-length encoded, and can be quite
119	large.
120	Once the picture is finished, the
121	.I ra_rgbe(1)
122	program with the \-r option may be used to convert to a run\-length
123	encoded picture for more efficient storage, although
124	.I pfilt(1)
125	or any of the other Radiance picture filters will do the same
126	thing.
127	.PP
128	The ALRM signal may be used to gracefully terminate an
129	.I rxpiece
130	process after it finishes the tile it is working on.
131	This permits other currently running or subsequently started
132	.I rxpiece
133	process(es) to continue rendering tiles with no lost effort.
134	.SH AUTHOR
135	Greg Ward
136	.SH "SEE ALSO"
137	getinfo(1), pfilt(1), ra_rgbe(1), rcode_depth(1), rcomb(1),
138	rmtxop(1), rpict(1), rpiece(1), rtpict(1), ximage(1)