man/man1/rcode_ident.1

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