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
#	User	Rev	Content
1	greg	1.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)