man/man1/rcode_depth.1

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