man/man1/rcode_depth.1

.\" RCSid "$Id: rcode_depth.1,v 1.1 2019/07/20 02:07:23 greg Exp $"
.TH RCODE_DEPTH 1 7/19/2019 RADIANCE
.SH NAME
rcode_depth - encode/decode 16-bit depth map
.SH SYNOPSIS
.B rcode_depth
[
.B "-d ref_depth/unit"
][
.B \-h[io]
][
.B \-H[io]
][
.B \-f[afd]
]
[
input
[output.dpt]
]
.br
.B rcode_depth
{
.B \-r
|
.B \-p
}
[
.B \-i
][
.B \-u
][
.B \-h[io]
][
.B \-H[io]
][
.B \-f[afd]
]
[
input.dpt
[output]
]
.SH DESCRIPTION
.I Rcode_depth
reads a map of depth values from 0 to infinity
and encodes them in an efficient 16-bit/pixel format for storage.
Input is taken from the first named file, or standard input if no
files are given.
Output is sent to the second named file, or standard output if none.
.PP
The
.I \-d
option specifies a reference distance with an optional unit
after a slash separator ('/').
(E.g., "1/meter" for diopters.)\0
This distance should roughly correspond to the average
depths on the input, as it sets the threshold between a linear
near-field and a reciprocal far-field range.
The default value is 1.0, with no specified units.
.PP
The
.I \-hi
option tells
.I rcode_depth
not to expect an information header on its input.
The
.I \-ho
option tells
.I rcode_depth
not to produce an information header on its output.
Specifying
.I \-h
turns both input and output headers off.
Similarly, the
.I \-Hi
option says not to expect an image resolution string on input, the
.I \-Ho
option says not to produce one on output, and
.I \-H
applies both.
.PP
The default input format is ASCII (user-readable) real values,
corresponding to the
.I \-fa
option.
The
.I \-ff
option tells
.I rcode_depth
to expect binary, 32-bit floating-point values per
depth on its input, instead.
The
.I \-fd
option tells it to expect 64-bit/pixel binary input.
.PP
The second form applies either the
.I \-r
option to decode from 16-bit depths to the desired format, or the
.I \-p
option to compute world intersection points from
view parameters in the encoded depth file header.
The output format is specified with the
.I \-f
option as described above.
The 
.I \-h
and
.I \-H
options have the same behavior as before.
.PP
When decoding, the
.I \-i
option further tells
.I rcode_depth
to produce one depth or world point
for each integer input pair specifying
the horizontal and vertical coordinates of a particular pixel,
where x is measured from 0 on the left and y from 0 at the bottom
in the standard orientation.
Note that
.I \-i
implies that an encoded normal file is explicitly given on the command
line, since the pixel coordinates are read from the standard input.
Also, the
.I \-H
option is not supported with
.I \-i,
since the map dimensions are required on the
input and not copied to the output.
If the
.I \-u
option is also given, output will be flushed after each coordinate pair.
.SH EXAMPLES
To store first surface intersection distances out of rtrace:
.IP "" .2i
rtrace -ff < rays.flt -x 512 -y 400 -oL octree | rcode_depth -ff > first.dpt
.PP
To query world intersection points using ximage with the 't' command:
.IP "" .2i
ximage -op render.hdr | rcode_depth -i -p first.dpt
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
rcalc(1), rcode_ident(1), rcode_norm(1), rcode2bmp(1),
rlam(1), rsplit(1), rtpict(1)
Revision:	1.2
Committed:	Fri Jul 26 01:32:32 2019 UTC (5 years, 9 months ago) by greg
Branch:	MAIN
Changes since 1.1:	+3 -2 lines
Log Message:	Added man page for rcode2bmp
#	User	Rev	Content
1	greg	1.2	.\" RCSid "$Id: rcode_depth.1,v 1.1 2019/07/20 02:07:23 greg Exp $"
2	greg	1.1	.TH RCODE_DEPTH 1 7/19/2019 RADIANCE
3			.SH NAME
4			rcode_depth - encode/decode 16-bit depth map
5			.SH SYNOPSIS
6			.B rcode_depth
7			[
8			.B "-d ref_depth/unit"
9			][
10			.B \-h[io]
11			][
12			.B \-H[io]
13			][
14			.B \-f[afd]
15			]
16			[
17			input
18			[output.dpt]
19			]
20			.br
21			.B rcode_depth
22			{
23			.B \-r
24			\|
25			.B \-p
26			}
27			[
28			.B \-i
29			][
30			.B \-u
31			][
32			.B \-h[io]
33			][
34			.B \-H[io]
35			][
36			.B \-f[afd]
37			]
38			[
39			input.dpt
40			[output]
41			]
42			.SH DESCRIPTION
43			.I Rcode_depth
44			reads a map of depth values from 0 to infinity
45			and encodes them in an efficient 16-bit/pixel format for storage.
46			Input is taken from the first named file, or standard input if no
47			files are given.
48			Output is sent to the second named file, or standard output if none.
49			.PP
50			The
51			.I \-d
52			option specifies a reference distance with an optional unit
53			after a slash separator ('/').
54			(E.g., "1/meter" for diopters.)\0
55			This distance should roughly correspond to the average
56			depths on the input, as it sets the threshold between a linear
57			near-field and a reciprocal far-field range.
58			The default value is 1.0, with no specified units.
59			.PP
60			The
61			.I \-hi
62			option tells
63			.I rcode_depth
64			not to expect an information header on its input.
65			The
66			.I \-ho
67			option tells
68			.I rcode_depth
69			not to produce an information header on its output.
70			Specifying
71			.I \-h
72			turns both input and output headers off.
73			Similarly, the
74			.I \-Hi
75			option says not to expect an image resolution string on input, the
76			.I \-Ho
77			option says not to produce one on output, and
78			.I \-H
79			applies both.
80			.PP
81			The default input format is ASCII (user-readable) real values,
82			corresponding to the
83			.I \-fa
84			option.
85			The
86			.I \-ff
87			option tells
88			.I rcode_depth
89			to expect binary, 32-bit floating-point values per
90			depth on its input, instead.
91			The
92			.I \-fd
93			option tells it to expect 64-bit/pixel binary input.
94			.PP
95			The second form applies either the
96			.I \-r
97			option to decode from 16-bit depths to the desired format, or the
98			.I \-p
99			option to compute world intersection points from
100			view parameters in the encoded depth file header.
101			The output format is specified with the
102			.I \-f
103			option as described above.
104			The
105			.I \-h
106			and
107			.I \-H
108			options have the same behavior as before.
109			.PP
110			When decoding, the
111			.I \-i
112			option further tells
113			.I rcode_depth
114			to produce one depth or world point
115			for each integer input pair specifying
116			the horizontal and vertical coordinates of a particular pixel,
117			where x is measured from 0 on the left and y from 0 at the bottom
118			in the standard orientation.
119			Note that
120			.I \-i
121			implies that an encoded normal file is explicitly given on the command
122			line, since the pixel coordinates are read from the standard input.
123			Also, the
124			.I \-H
125			option is not supported with
126			.I \-i,
127			since the map dimensions are required on the
128			input and not copied to the output.
129			If the
130			.I \-u
131			option is also given, output will be flushed after each coordinate pair.
132			.SH EXAMPLES
133			To store first surface intersection distances out of rtrace:
134			.IP "" .2i
135			rtrace -ff < rays.flt -x 512 -y 400 -oL octree \| rcode_depth -ff > first.dpt
136			.PP
137			To query world intersection points using ximage with the 't' command:
138			.IP "" .2i
139			ximage -op render.hdr \| rcode_depth -i -p first.dpt
140			.SH AUTHOR
141			Greg Ward
142			.SH "SEE ALSO"
143	greg	1.2	rcalc(1), rcode_ident(1), rcode_norm(1), rcode2bmp(1),
144			rlam(1), rsplit(1), rtpict(1)