man/man1/rcode_ident.1

.\" RCSid "$Id: rcode_ident.1,v 1.6 2022/02/02 22:25:24 greg Exp $"
.TH RCODE_IDENT 1 7/19/2019 RADIANCE
.SH NAME
rcode_ident - store identifiers in an indexed map and retrieve from same
.SH SYNOPSIS
.B rcode_ident
[
.I "-8 | -16 | -24"
][
.B \-h
][
.B \-tS
][
.B "-x xr -y yr"
]
[
input.txt
[output.idx]
]
.br
.B "rcode_ident -r"
[
.B \-i
][
.B \-u
][
.B \-h
][
.B \-H
][
.B \-l
][
.B \-n
][
.B \-tS
]
input.idx
[output.txt]
.SH DESCRIPTION
.I Rcode_ident
takes a list of ASCII identifiers on the input and encodes them
as a 16-bit index to a table appended to the output.
This default index size can hold up to 65 thousand unique IDs,
which is suitable for most applications.
The
.I \-8
option may be used to specify an 8-bit index, which saves space
if 256 or fewer unique identifiers appear on the input.
The
.I \-24
option creates a 24-bit index that can record over 16 million
unique identifiers.
.PP
Identifiers are separated by newlines by default, but any single-character
separator may be given with the
.I \-tS
option.
Note there is no space between this option and its argument.
Leading and trailing white space is eliminated from each identifier,
and the maximum ID length is 255 characters.
.PP
Input is taken from the first named file, or standard input if no
files are given.
(Input file is required for
.I \-r
option.)
Output is sent to the second named file, or standard output if none.
.PP
The
.I \-h
option tells
.I rcode_ident
not to expect an information header on its input.
The
.I \-x
and
.I \-y
options give the horizontal and vertical map dimensions, respectively.
If these are not specified, then a resolution string must be
included on the header, as produced by
.I rtrace(1)
when both resolutions are specified.
.PP
The second form applies the
.I \-r
option to read an indexed id file and produce the original
identifiers for each pixel position on the output.
With this option, the ID file must be given on the
command line and cannot be read from the standard input.
The 
.I \-h
and
.I \-H
options may be used to leave off the header and resolution
string, respectively.
The
.I \-tS
option specifies an alternate ID separator instead of the default newline.
The
.I \-l
option tells
.I rcode_ident
to list identifiers following the header information (if present).
The
.I \-n
option prints identifier table indexes rather than the strings themselves.
Indexing starts from 0 for the first table entry.
.PP
When decoding, the
.I \-i
option tells
.I rcode_ident
to produce an identifier 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.
If the
.I \-u
option is also given, output will be flushed after each identifier
.SH EXAMPLES
To store modifier IDs out of rtrace:
.IP "" .2i
rtrace -ffa < rays.flt -x 512 -y 400 -om octree | rcode_ident > mods.idx
.PP
To query specific modifiers using ximage with the 't' command:
.IP "" .2i
ximage -op render.hdr | rcode_ident -i -r mods.idx
.PP
To only print out the list of unique identifiers:
.IP "" .2i
rcode_ident -r -h -H -i -l mods.idx < /dev/null
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
rcalc(1), rcode_depth(1), rcode_norm(1), rcode2bmp(1),
rlam(1), rsplit(1), rtpict(1)
Revision:	1.7
Committed:	Wed Aug 24 19:34:07 2022 UTC (3 years, 2 months ago) by greg
Branch:	MAIN
CVS Tags:	rad6R0, rad5R4, HEAD
Changes since 1.6:	+3 -5 lines
Log Message:	docs(rcode_ident): Clarified wording regarding -r option
#	User	Rev	Content
1	greg	1.7	.\" RCSid "$Id: rcode_ident.1,v 1.6 2022/02/02 22:25:24 greg Exp $"
2	greg	1.1	.TH RCODE_IDENT 1 7/19/2019 RADIANCE
3			.SH NAME
4			rcode_ident - store identifiers in an indexed map and retrieve from same
5			.SH SYNOPSIS
6			.B rcode_ident
7			[
8			.I "-8 \| -16 \| -24"
9			][
10			.B \-h
11			][
12			.B \-tS
13			][
14			.B "-x xr -y yr"
15			]
16			[
17			input.txt
18			[output.idx]
19			]
20			.br
21			.B "rcode_ident -r"
22			[
23			.B \-i
24			][
25			.B \-u
26			][
27			.B \-h
28			][
29			.B \-H
30			][
31	greg	1.2	.B \-l
32			][
33			.B \-n
34			][
35	greg	1.1	.B \-tS
36			]
37			input.idx
38			[output.txt]
39			.SH DESCRIPTION
40			.I Rcode_ident
41	greg	1.5	takes a list of ASCII identifiers on the input and encodes them
42	greg	1.1	as a 16-bit index to a table appended to the output.
43			This default index size can hold up to 65 thousand unique IDs,
44			which is suitable for most applications.
45			The
46			.I \-8
47			option may be used to specify an 8-bit index, which saves space
48			if 256 or fewer unique identifiers appear on the input.
49			The
50			.I \-24
51	greg	1.4	option creates a 24-bit index that can record over 16 million
52	greg	1.1	unique identifiers.
53			.PP
54			Identifiers are separated by newlines by default, but any single-character
55			separator may be given with the
56			.I \-tS
57			option.
58			Note there is no space between this option and its argument.
59			Leading and trailing white space is eliminated from each identifier,
60			and the maximum ID length is 255 characters.
61			.PP
62			Input is taken from the first named file, or standard input if no
63			files are given.
64	greg	1.6	(Input file is required for
65			.I \-r
66			option.)
67	greg	1.1	Output is sent to the second named file, or standard output if none.
68			.PP
69			The
70			.I \-h
71			option tells
72			.I rcode_ident
73			not to expect an information header on its input.
74			The
75			.I \-x
76			and
77			.I \-y
78			options give the horizontal and vertical map dimensions, respectively.
79			If these are not specified, then a resolution string must be
80			included on the header, as produced by
81			.I rtrace(1)
82			when both resolutions are specified.
83			.PP
84			The second form applies the
85			.I \-r
86			option to read an indexed id file and produce the original
87			identifiers for each pixel position on the output.
88	greg	1.7	With this option, the ID file must be given on the
89			command line and cannot be read from the standard input.
90	greg	1.1	The
91			.I \-h
92			and
93			.I \-H
94			options may be used to leave off the header and resolution
95			string, respectively.
96			The
97			.I \-tS
98			option specifies an alternate ID separator instead of the default newline.
99	greg	1.2	The
100			.I \-l
101			option tells
102			.I rcode_ident
103			to list identifiers following the header information (if present).
104			The
105			.I \-n
106			option prints identifier table indexes rather than the strings themselves.
107			Indexing starts from 0 for the first table entry.
108	greg	1.1	.PP
109			When decoding, the
110			.I \-i
111			option tells
112			.I rcode_ident
113			to produce an identifier for each integer input pair specifying
114			the horizontal and vertical coordinates of a particular pixel,
115			where x is measured from 0 on the left and y from 0 at the bottom
116			in the standard orientation.
117			If the
118			.I \-u
119			option is also given, output will be flushed after each identifier
120			.SH EXAMPLES
121			To store modifier IDs out of rtrace:
122			.IP "" .2i
123			rtrace -ffa < rays.flt -x 512 -y 400 -om octree \| rcode_ident > mods.idx
124			.PP
125			To query specific modifiers using ximage with the 't' command:
126			.IP "" .2i
127			ximage -op render.hdr \| rcode_ident -i -r mods.idx
128	greg	1.2	.PP
129			To only print out the list of unique identifiers:
130			.IP "" .2i
131			rcode_ident -r -h -H -i -l mods.idx < /dev/null
132	greg	1.1	.SH AUTHOR
133			Greg Ward
134			.SH "SEE ALSO"
135	greg	1.3	rcalc(1), rcode_depth(1), rcode_norm(1), rcode2bmp(1),
136			rlam(1), rsplit(1), rtpict(1)