man/man1/rtpict.1

.\" RCSid "$Id: rtpict.1,v 1.14 2023/12/12 16:31:45 greg Exp $"
.TH RTPICT 1 3/19/2018 RADIANCE
.SH NAME
rtpict - generate a RADIANCE picture, hyperspectral image, or layers using rtrace
.SH SYNOPSIS
.B rtpict
.B "-n nproc"
[
.B -co
][
.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 or hyperspectral image
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 options are silently ignored, and the
.I rtrace(1)
.I \-co
boolean switch is supported.
Options incompatible with multi-processing may generate an error.
.PP
The
.I rtrace
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),
unless the
.I \-co+
option is specified and
.I \-cs
is greater than 3.
In this case, a hyperspectral image will be generated for each
of the value types, converted by
.I rcomb(1)
and with its suffix set to ".hsr" rather than ".hdr".
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_norm(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"
or
.I "irradiance.hsr"
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
.PP
To render a hyperspectral irradiance image with 18 spectral samples:
.IP "" .2i
rtpict -vf inside.vf -i+ -cs 18 -co+ scene.oct > scene_inside.hsr
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
getinfo(1), mkpmap(1), oconv(1), pfilt(1), 
pvalue(1), rad(1), rcode_depth(1), rcode_norm(1), rcode_ident(1),
rcomb(1), rcrop(1), rmtxop(1),
rpiece(1), rpict(1), rsplit(1), rtrace(1), rvu(1), vwrays(1)
Revision:	1.15
Committed:	Tue Dec 12 17:18:27 2023 UTC (16 months, 3 weeks ago) by greg
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.14:	+2 -2 lines
Log Message:	docs: added missing option in example
#	User	Rev	Content
1	greg	1.15	.\" RCSid "$Id: rtpict.1,v 1.14 2023/12/12 16:31:45 greg Exp $"
2	greg	1.1	.TH RTPICT 1 3/19/2018 RADIANCE
3			.SH NAME
4	greg	1.13	rtpict - generate a RADIANCE picture, hyperspectral image, or layers 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.13	.B -co
10			][
11	greg	1.3	.B "-o[vrxlLRXnNsmM] out_dir"
12			][
13			.B "-d ref_depth/unit"
14			]
15			[
16	greg	1.1	.B "rpict options"
17			]
18			[
19			.B @file
20			]
21			.B octree
22			.SH DESCRIPTION
23			.I Rtpict
24	greg	1.13	is a script that generates a picture or hyperspectral image
25			from the RADIANCE scene given in
26	greg	1.1	.I octree
27			and sends it to the standard output, or to a file specified with the
28			.I \-o
29			option.
30			Most options and defaults are the same as
31			.I rpict(1),
32	greg	1.13	although a few options are silently ignored, and the
33			.I rtrace(1)
34			.I \-co
35			boolean switch is supported.
36			Options incompatible with multi-processing may generate an error.
37	greg	1.1	.PP
38			The
39	greg	1.13	.I rtrace
40	greg	1.1	tool is called with
41			.I vwrays(1)
42			to perform the actual work.
43			This enables the
44			.I \-n
45			option for multiprocessing on platforms that support it.
46			If the
47			.I \-n
48			option is not specified or is set to 1, then
49			.I rpict
50			is called directly.
51			There is no benefit in setting the number of processes to anything
52			greater than the number of virtual cores available on your machine.
53			Also, it is very important to set the
54			.I \-af
55			option if an irradiance cache is being generated;
56			otherwise, your speed-up will be far from linear.
57	greg	1.3	.PP
58			If the
59			.I \-o
60			option has additional characters corresponding to output types from
61			.I rtrace,
62			it must be followed by the name of a directory that either exists or
63			will be created to contain image layers, one per output type.
64			The supported types are listed below, and do not include types that
65			are useless or have no convenient representation.
66			The table below shows the correspondence between output type and file name
67			in the specified directory:
68			.sp
69			.nf
70			v radiance.hdr
71	greg	1.4	r r_refl.hdr
72			x r_unrefl.hdr
73			l d_effective.dpt
74			L d_firstsurf.dpt
75			R d_refl.dpt
76			X d_unrefl.dpt
77	greg	1.3	n perturbed.nrm
78			N unperturbed.nrm
79			s surface.idx
80			m modifier.idx
81			M material.idx
82			.fi
83			.sp
84			Different encodings are associated with different data types.
85			Color data (from the 'v', 'r', and 'x' types) will be converted to
86			a flat RGBE picture by
87	greg	1.13	.I pvalue(1),
88			unless the
89			.I \-co+
90			option is specified and
91			.I \-cs
92			is greater than 3.
93			In this case, a hyperspectral image will be generated for each
94			of the value types, converted by
95	greg	1.14	.I rcomb(1)
96	greg	1.13	and with its suffix set to ".hsr" rather than ".hdr".
97	greg	1.3	Distances (from the 'l', 'L', 'R', and 'X' types) will be
98			converted to a 16-bit representation by
99			.I rcode_depth(1),
100			and the
101			.I \-d
102	greg	1.5	option should be used to assign the reference (median) depth and world
103			units, which applies to the overall scene.
104	greg	1.3	Surface normals (from the 'n' and 'N' types) will be converted
105			to a 32-bit representation by
106	greg	1.12	.I rcode_norm(1).
107	greg	1.3	Finally, identifiers (from the 's', 'm', and 'M' types) will be
108			converted to a 16-bit index format by
109			.I rcode_ident(1).
110			.PP
111			If the
112			.I \-i
113			option is used to turn on irradiane output, then the picture associated
114			with the 'v' type will be renamed
115			.I "irradiance.hdr"
116	greg	1.13	or
117			.I "irradiance.hsr"
118			and some other output types become irrelevant
119			(i.e., 'r', 'x', 'R', and 'X').
120	greg	1.3	If one or more of the associated output files already exists in the
121	greg	1.8	destination directory, an error will be printed and the command will abort.
122	greg	1.3	.SH EXAMPLES
123	greg	1.1	To render a scene with four processes:
124			.IP "" .2i
125			rtpict -n 4 -vf mypers.vf -ab 1 -af scene.amb scene.oct > scene_pers.hdr
126	greg	1.3	.PP
127			To render radiance, first surface distance, and normals in a layered image:
128			.IP "" .2i
129			rtpict -n 8 -vf fish.vf @render.opt -ovLn fisholay scene.oct
130	greg	1.13	.PP
131			To render a hyperspectral irradiance image with 18 spectral samples:
132			.IP "" .2i
133	greg	1.15	rtpict -vf inside.vf -i+ -cs 18 -co+ scene.oct > scene_inside.hsr
134	greg	1.1	.SH AUTHOR
135			Greg Ward
136			.SH "SEE ALSO"
137	greg	1.3	getinfo(1), mkpmap(1), oconv(1), pfilt(1),
138	greg	1.12	pvalue(1), rad(1), rcode_depth(1), rcode_norm(1), rcode_ident(1),
139	greg	1.14	rcomb(1), rcrop(1), rmtxop(1),
140	greg	1.13	rpiece(1), rpict(1), rsplit(1), rtrace(1), rvu(1), vwrays(1)