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, 1 month 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
#	Content
1	.\" RCSid "$Id: rcode_depth.1,v 1.4 2020/02/11 23:26:43 greg Exp $"
2	.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	.B "-x xr -y yr"
17	]
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	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	.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	requires that an encoded depth file name be given on the command
130	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	rcalc(1), rcode_ident(1), rcode_norm(1), rcode2bmp(1),
152	rcrop(1), rlam(1), rsplit(1), rtpict(1)