man/man1/rtpict.1

.\" RCSid "$Id: rtpict.1,v 1.9 2022/03/16 00:06:08 greg Exp $"
.TH RTPICT 1 3/19/2018 RADIANCE
.SH NAME
rtpict - generate a RADIANCE picture or layered image using rtrace
.SH SYNOPSIS
.B rtpict
.B "-n nproc"
[
.B "-o[vrxlLRXnNsmM] out_dir"
][
.B "-d ref_depth/unit"
]
[
.B "rpict options"
]
[
.B @file
]
.B octree
.SH DESCRIPTION
.I Rtpict
is a script that generates a picture from the RADIANCE scene given in
.I octree
and sends it to the standard output, or to a file specified with the
.I \-o
option.
Most options and defaults are the same as
.I rpict(1),
although a few switches are silently ignored.
Options incompatible with multi-processing can generate an error.
.PP
The
.I rtrace(1)
tool is called with
.I vwrays(1)
to perform the actual work.
This enables the
.I \-n
option for multiprocessing on platforms that support it.
If the
.I \-n
option is not specified or is set to 1, then
.I rpict
is called directly.
There is no benefit in setting the number of processes to anything
greater than the number of virtual cores available on your machine.
Also, it is very important to set the
.I \-af
option if an irradiance cache is being generated;
otherwise, your speed-up will be far from linear.
.PP
If the
.I \-o
option has additional characters corresponding to output types from
.I rtrace,
it must be followed by the name of a directory that either exists or
will be created to contain image layers, one per output type.
The supported types are listed below, and do not include types that
are useless or have no convenient representation.
The table below shows the correspondence between output type and file name
in the specified directory:
.sp
.nf
v       radiance.hdr
r       r_refl.hdr
x       r_unrefl.hdr
l       d_effective.dpt
L       d_firstsurf.dpt
R       d_refl.dpt
X       d_unrefl.dpt
n       perturbed.nrm
N       unperturbed.nrm
s       surface.idx
m       modifier.idx
M       material.idx
.fi
.sp
Different encodings are associated with different data types.
Color data (from the 'v', 'r', and 'x' types) will be converted to
a flat RGBE picture by
.I pvalue(1).
Distances (from the 'l', 'L', 'R', and 'X' types) will be
converted to a 16-bit representation by
.I rcode_depth(1),
and the
.I \-d
option should be used to assign the reference (median) depth and world
units, which applies to the overall scene.
Surface normals (from the 'n' and 'N' types) will be converted
to a 32-bit representation by
.I rcode_normal(1).
Finally, identifiers (from the 's', 'm', and 'M' types) will be
converted to a 16-bit index format by
.I rcode_ident(1).
.PP
If the
.I \-i
option is used to turn on irradiane output, then the picture associated
with the 'v' type will be renamed
.I "irradiance.hdr"
and some other output types become irrelevant (i.e., 'r', 'x', 'R', and 'X').
If one or more of the associated output files already exists in the
destination directory, an error will be printed and the command will abort.
.SH EXAMPLES
To render a scene with four processes:
.IP "" .2i
rtpict -n 4 -vf mypers.vf -ab 1 -af scene.amb scene.oct > scene_pers.hdr
.PP
To render radiance, first surface distance, and normals in a layered image:
.IP "" .2i
rtpict -n 8 -vf fish.vf @render.opt -ovLn fisholay scene.oct
.SH NOTES
Users should seriously consider using
.I rpiece(1)
for multiprocessing
when irradiance caching is employed with a shared ambient file.
If
.I rtpict
is used with
.I \-n
greater than 1, it tries to compute neighboring parts
of the same scanline in different processes, which can
result in many redundant calculations and cache entries.
.I Rtpict
will automatically run a randomly-ordered overture calculation
to mitigate this problem, but it is not a perfect solution.
.I Rpiece
avoids redundant cache calculations by working on separate tiles in each
process, which brings other benefits as well, such as enabling the
.I \-ps
option for image plane sampling.
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
getinfo(1), mkpmap(1), oconv(1), pfilt(1), 
pvalue(1), rad(1), rcode_depth(1), rcode_normal(1), rcode_ident(1),
rcrop(1), rpiece(1), rpict(1), rsplit(1), rtrace(1), rvu(1), vwrays(1)
Revision:	1.10
Committed:	Sun Apr 10 03:46:27 2022 UTC (3 years ago) by greg
Branch:	MAIN
Changes since 1.9:	+15 -14 lines
Log Message:	perf(rtpict): Added overture calculation with ambient cache and -n > 1
#	User	Rev	Content
1	greg	1.10	.\" RCSid "$Id: rtpict.1,v 1.9 2022/03/16 00:06:08 greg Exp $"
2	greg	1.1	.TH RTPICT 1 3/19/2018 RADIANCE
3			.SH NAME
4	greg	1.7	rtpict - generate a RADIANCE picture or layered image using rtrace
5	greg	1.1	.SH SYNOPSIS
6			.B rtpict
7	greg	1.2	.B "-n nproc"
8	greg	1.1	[
9	greg	1.3	.B "-o[vrxlLRXnNsmM] out_dir"
10			][
11			.B "-d ref_depth/unit"
12			]
13			[
14	greg	1.1	.B "rpict options"
15			]
16			[
17			.B @file
18			]
19			.B octree
20			.SH DESCRIPTION
21			.I Rtpict
22			is a script that generates a picture from the RADIANCE scene given in
23			.I octree
24			and sends it to the standard output, or to a file specified with the
25			.I \-o
26			option.
27			Most options and defaults are the same as
28			.I rpict(1),
29			although a few switches are silently ignored.
30			Options incompatible with multi-processing can generate an error.
31			.PP
32			The
33			.I rtrace(1)
34			tool is called with
35			.I vwrays(1)
36			to perform the actual work.
37			This enables the
38			.I \-n
39			option for multiprocessing on platforms that support it.
40			If the
41			.I \-n
42			option is not specified or is set to 1, then
43			.I rpict
44			is called directly.
45			There is no benefit in setting the number of processes to anything
46			greater than the number of virtual cores available on your machine.
47			Also, it is very important to set the
48			.I \-af
49			option if an irradiance cache is being generated;
50			otherwise, your speed-up will be far from linear.
51	greg	1.3	.PP
52			If the
53			.I \-o
54			option has additional characters corresponding to output types from
55			.I rtrace,
56			it must be followed by the name of a directory that either exists or
57			will be created to contain image layers, one per output type.
58			The supported types are listed below, and do not include types that
59			are useless or have no convenient representation.
60			The table below shows the correspondence between output type and file name
61			in the specified directory:
62			.sp
63			.nf
64			v radiance.hdr
65	greg	1.4	r r_refl.hdr
66			x r_unrefl.hdr
67			l d_effective.dpt
68			L d_firstsurf.dpt
69			R d_refl.dpt
70			X d_unrefl.dpt
71	greg	1.3	n perturbed.nrm
72			N unperturbed.nrm
73			s surface.idx
74			m modifier.idx
75			M material.idx
76			.fi
77			.sp
78			Different encodings are associated with different data types.
79			Color data (from the 'v', 'r', and 'x' types) will be converted to
80			a flat RGBE picture by
81			.I pvalue(1).
82			Distances (from the 'l', 'L', 'R', and 'X' types) will be
83			converted to a 16-bit representation by
84			.I rcode_depth(1),
85			and the
86			.I \-d
87	greg	1.5	option should be used to assign the reference (median) depth and world
88			units, which applies to the overall scene.
89	greg	1.3	Surface normals (from the 'n' and 'N' types) will be converted
90			to a 32-bit representation by
91			.I rcode_normal(1).
92			Finally, identifiers (from the 's', 'm', and 'M' types) will be
93			converted to a 16-bit index format by
94			.I rcode_ident(1).
95			.PP
96			If the
97			.I \-i
98			option is used to turn on irradiane output, then the picture associated
99			with the 'v' type will be renamed
100			.I "irradiance.hdr"
101			and some other output types become irrelevant (i.e., 'r', 'x', 'R', and 'X').
102			If one or more of the associated output files already exists in the
103	greg	1.8	destination directory, an error will be printed and the command will abort.
104	greg	1.3	.SH EXAMPLES
105	greg	1.1	To render a scene with four processes:
106			.IP "" .2i
107			rtpict -n 4 -vf mypers.vf -ab 1 -af scene.amb scene.oct > scene_pers.hdr
108	greg	1.3	.PP
109			To render radiance, first surface distance, and normals in a layered image:
110			.IP "" .2i
111			rtpict -n 8 -vf fish.vf @render.opt -ovLn fisholay scene.oct
112	greg	1.6	.SH NOTES
113			Users should seriously consider using
114			.I rpiece(1)
115	greg	1.10	for multiprocessing
116	greg	1.6	when irradiance caching is employed with a shared ambient file.
117			If
118			.I rtpict
119	greg	1.10	is used with
120			.I \-n
121			greater than 1, it tries to compute neighboring parts
122			of the same scanline in different processes, which can
123			result in many redundant calculations and cache entries.
124			.I Rtpict
125			will automatically run a randomly-ordered overture calculation
126			to mitigate this problem, but it is not a perfect solution.
127			.I Rpiece
128			avoids redundant cache calculations by working on separate tiles in each
129			process, which brings other benefits as well, such as enabling the
130			.I \-ps
131			option for image plane sampling.
132	greg	1.1	.SH AUTHOR
133			Greg Ward
134			.SH "SEE ALSO"
135	greg	1.3	getinfo(1), mkpmap(1), oconv(1), pfilt(1),
136			pvalue(1), rad(1), rcode_depth(1), rcode_normal(1), rcode_ident(1),
137	greg	1.9	rcrop(1), rpiece(1), rpict(1), rsplit(1), rtrace(1), rvu(1), vwrays(1)