man/man1/rcollate.1

.\" RCSid "$Id: rcollate.1,v 1.18 2024/01/25 19:25:50 greg Exp $"
.TH RCOLLATE 1 9/5/2013 RADIANCE
.SH NAME
rcollate - resize or re-order matrix data
.SH SYNOPSIS
.B rcollate
[
.B \-h[io]
][
.B \-w
][
.B \-c
][
.B \-f{a|f|d|b}[N]
][
.B \-t
][
.B "\-ic in_col"
][
.B "\-ir in_row"
][
.B "\-oc out_col"
][
.B "\-or out_row"
][
.B "\-o RxC[xR1xC2..]"
]
[
.B input.dat
]
.SH DESCRIPTION
.I Rcollate
reads in a single matrix file (table) and reshapes it to have
the number of columns specified by the
.I \-oc
option.
The number of rows may be specified with a
.I \-or
option, or may be determined automatically from the size of the input if
it is an even multiple of the number of columns (as it should be).
Alternatively, both may be specified using a
.I \-o
option with the number of rows and columns separated by an 'x', as in "30x14"
for 30 rows by 14 columns.
.I Rcollate
can also reorder the input into nested blocks by continuing the output size
string.
For example, "3x10X7x2" would order output data with a 3x10 super-array of
7x2 subblocks.
This type of block hierarchy is convenient for visualizing tensor data.
.PP
By default, the file is assumed to include an information header, which
is copied to the standard output along with the command name.
The
.I \-hi
option may be used to turn off the expectation of a header on input.
The
.I \-ho
option turns off header output, and
.I \-h
by itself turns off both input and output headers.
The
.I \-w
option turns off non-fatal warning messages, such as unexpected EOD.
.PP
Normally,
.I rcollate
detects whether any transformation is actually taking place, and will
reproduce the data verbatim if the input size and shape should be unaltered.
The
.I \-c
opiton forces the operation to proceed, even if it appears to be a no-op,
which can be useful to correct a misshapen input matrix or check that
the data is the proper size and formatted correctly (in the case of ASCII input).
.PP
The input format is assumed to be ASCII, with three white-space separated words
(typically numbers) in each record.
A different input format may be specified with the
.I \-f
option.
The suboptions are
.I \-fa,
.I \-ff,
.I \-fd,
and
.I \-fb
for ASCII, float, double, and binary, respectively.
An optional count may be attached to specify the number of data elements per
record, which defaults to 1.
Thus, the default setting is
.I \-fa3.
Since
.I rcollate
does not interpret the fields, all binary options of the same
length have the same result.
On most architectures,
.I \-ff6,
.I \-fd3,
and
.I \-fb24
would all be equivalent.
Note that the lack of row separators in binary files means that
.I rcollate
does not actually do anything for binary files unless the data is being
re-ordered.
.PP
If an input header is present, it may contain the format, number of components
and matrix dimensions.
In such cases, the
.I \-ic,
.I \-ir
and
.I \-f
options are not required, but will be checked against the header
information if provided.
An exception is made for
.I \-fbN
where N>1 and the
.I \-c
option is not present.
In this case, the header may indicate a different format or number of
components
and the specified byte length is taken instead to be the exact size
of each data record.
.PP
The transpose option,
.I \-t
swaps rows and columns on the input.
For binary files with no header information, the user must
specify at least one input or output dimension to define the matrix size.
For ASCII files,
.I rcollate
will automatically determine the number of columns based on the
position of the first EOL (end-of-line) character, and the number
of rows based on the total count of records in the file.
The user may override these determinations, allowing the matrix to
be resized or re-ordered as well as transposed.
If input and output dimensions are given and there is no block re-ordering,
the number of input rows must equal the number of output columns,
and the number of input columns must equal the number of output rows.
If the
.I \-o
option is also given with multiple block levels, the transpose operation
will logically precede the re-ordering operation, regardless of their
position on the command line.
.SH EXAMPLES
To change put 8760 color triplets per row in a matrix with no header:
.IP "" .2i
rcollate -h \-oc 8760 input.dat > col8760.dat
.PP
To transpose a binary file with 145 float triplets per input row:
.IP "" .2i
rcollate -ff3 -ic 145 -t orig.flt > transpose.flt
.PP
To create an appropriate header for a binary float matrix as required by
.I rmtxop(1)\:
.IP "" .2i
rcollate -hi -ff3 -or 145 -oc 8760 input.smx | rmtxop dcoef.dmx - > res.txt
.PP
To visualize a Shirley-Chiu BTDF matrix where the interior resolution is
64x64 and the exterior resolution is 32x32:
.IP "" .2i
rcollate -o 64x64X32x32 s-c_bsdf.mtx | rmtxop -fc - > s-c_bsdf.hdr
.SH AUTHOR
Greg Ward
.SH NOTES
For large transpose or re-ordering operations on Unix systems,
it is most efficient to specify the input file on the command line,
rather than reading from the standard input, since
.I rcollate
can map the file directly into virtual memory.
.PP
The
.I rcollate
command is rather inflexible when it comes to output field and record
separators for ASCII data.
It accepts any amount of white space between fields
on input, but only produces spaces as field separators
between words and tabs as record separators on output.
Output row separtors will always be an EOL, which may differ between systems.
.PP
If no options are given on the command line, or a binary file is specified
without a transpose or re-ordering,
.I rcollate
issues a warning and simply copies its input to its standard output.
.SH "SEE ALSO"
cnt(1), histo(1), neaten(1), rcalc(1), rcomb(1), rcrop(1), rlam(1),
rsensor(1), rmtxop(1), rsplit(1), tabfunc(1), total(1)
Revision:	1.19
Committed:	Fri Jan 26 00:47:17 2024 UTC (20 months, 4 weeks ago) by greg
Branch:	MAIN
CVS Tags:	rad6R0, HEAD
Changes since 1.18:	+8 -4 lines
Log Message:	feat(rcollate): Made -c option override new -fbN behavior
#	User	Rev	Content
1	greg	1.19	.\" RCSid "$Id: rcollate.1,v 1.18 2024/01/25 19:25:50 greg Exp $"
2	greg	1.15	.TH RCOLLATE 1 9/5/2013 RADIANCE
3	greg	1.1	.SH NAME
4	greg	1.13	rcollate - resize or re-order matrix data
5	greg	1.1	.SH SYNOPSIS
6			.B rcollate
7			[
8	greg	1.6	.B \-h[io]
9	greg	1.1	][
10	greg	1.3	.B \-w
11			][
12	greg	1.14	.B \-c
13			][
14			.B \-f{a\|f\|d\|b}[N]
15	greg	1.1	][
16			.B \-t
17			][
18			.B "\-ic in_col"
19			][
20			.B "\-ir in_row"
21			][
22			.B "\-oc out_col"
23			][
24			.B "\-or out_row"
25	greg	1.9	][
26			.B "\-o RxC[xR1xC2..]"
27	greg	1.1	]
28			[
29			.B input.dat
30			]
31			.SH DESCRIPTION
32			.I Rcollate
33			reads in a single matrix file (table) and reshapes it to have
34			the number of columns specified by the
35			.I \-oc
36			option.
37	greg	1.9	The number of rows may be specified with a
38			.I \-or
39			option, or may be determined automatically from the size of the input if
40			it is an even multiple of the number of columns (as it should be).
41			Alternatively, both may be specified using a
42			.I \-o
43			option with the number of rows and columns separated by an 'x', as in "30x14"
44			for 30 rows by 14 columns.
45			.I Rcollate
46			can also reorder the input into nested blocks by continuing the output size
47	greg	1.12	string.
48			For example, "3x10X7x2" would order output data with a 3x10 super-array of
49			7x2 subblocks.
50			This type of block hierarchy is convenient for visualizing tensor data.
51	greg	1.9	.PP
52	greg	1.1	By default, the file is assumed to include an information header, which
53	greg	1.6	is copied to the standard output along with the command name.
54			The
55			.I \-hi
56			option may be used to turn off the expectation of a header on input.
57			The
58			.I \-ho
59			option turns off header output, and
60	greg	1.1	.I \-h
61	greg	1.6	by itself turns off both input and output headers.
62	greg	1.3	The
63			.I \-w
64			option turns off non-fatal warning messages, such as unexpected EOD.
65	greg	1.1	.PP
66	greg	1.14	Normally,
67			.I rcollate
68			detects whether any transformation is actually taking place, and will
69			reproduce the data verbatim if the input size and shape should be unaltered.
70			The
71			.I \-c
72			opiton forces the operation to proceed, even if it appears to be a no-op,
73			which can be useful to correct a misshapen input matrix or check that
74	greg	1.16	the data is the proper size and formatted correctly (in the case of ASCII input).
75	greg	1.14	.PP
76	greg	1.1	The input format is assumed to be ASCII, with three white-space separated words
77			(typically numbers) in each record.
78			A different input format may be specified with the
79			.I \-f
80			option.
81			The suboptions are
82			.I \-fa,
83			.I \-ff,
84			.I \-fd,
85			and
86			.I \-fb
87			for ASCII, float, double, and binary, respectively.
88			An optional count may be attached to specify the number of data elements per
89			record, which defaults to 1.
90			Thus, the default setting is
91			.I \-fa3.
92			Since
93			.I rcollate
94			does not interpret the fields, all binary options of the same
95			length have the same result.
96			On most architectures,
97			.I \-ff6,
98			.I \-fd3,
99			and
100			.I \-fb24
101			would all be equivalent.
102	greg	1.2	Note that the lack of row separators in binary files means that
103	greg	1.1	.I rcollate
104	greg	1.13	does not actually do anything for binary files unless the data is being
105			re-ordered.
106	greg	1.1	.PP
107	greg	1.5	If an input header is present, it may contain the format, number of components
108			and matrix dimensions.
109			In such cases, the
110			.I \-ic,
111			.I \-ir
112			and
113			.I \-f
114			options are not required, but will be checked against the header
115			information if provided.
116	greg	1.18	An exception is made for
117			.I \-fbN
118	greg	1.19	where N>1 and the
119			.I \-c
120			option is not present.
121			In this case, the header may indicate a different format or number of
122			components
123			and the specified byte length is taken instead to be the exact size
124			of each data record.
125	greg	1.5	.PP
126	greg	1.1	The transpose option,
127			.I \-t
128			swaps rows and columns on the input.
129	greg	1.13	For binary files with no header information, the user must
130			specify at least one input or output dimension to define the matrix size.
131	greg	1.1	For ASCII files,
132			.I rcollate
133			will automatically determine the number of columns based on the
134			position of the first EOL (end-of-line) character, and the number
135	greg	1.2	of rows based on the total count of records in the file.
136	greg	1.1	The user may override these determinations, allowing the matrix to
137	greg	1.13	be resized or re-ordered as well as transposed.
138			If input and output dimensions are given and there is no block re-ordering,
139			the number of input rows must equal the number of output columns,
140	greg	1.2	and the number of input columns must equal the number of output rows.
141	greg	1.10	If the
142			.I \-o
143			option is also given with multiple block levels, the transpose operation
144	greg	1.13	will logically precede the re-ordering operation, regardless of their
145			position on the command line.
146	greg	1.8	.SH EXAMPLES
147	greg	1.1	To change put 8760 color triplets per row in a matrix with no header:
148			.IP "" .2i
149			rcollate -h \-oc 8760 input.dat > col8760.dat
150			.PP
151			To transpose a binary file with 145 float triplets per input row:
152			.IP "" .2i
153			rcollate -ff3 -ic 145 -t orig.flt > transpose.flt
154	greg	1.7	.PP
155			To create an appropriate header for a binary float matrix as required by
156			.I rmtxop(1)\:
157			.IP "" .2i
158			rcollate -hi -ff3 -or 145 -oc 8760 input.smx \| rmtxop dcoef.dmx - > res.txt
159	greg	1.9	.PP
160			To visualize a Shirley-Chiu BTDF matrix where the interior resolution is
161			64x64 and the exterior resolution is 32x32:
162			.IP "" .2i
163			rcollate -o 64x64X32x32 s-c_bsdf.mtx \| rmtxop -fc - > s-c_bsdf.hdr
164	greg	1.1	.SH AUTHOR
165			Greg Ward
166			.SH NOTES
167	greg	1.13	For large transpose or re-ordering operations on Unix systems,
168			it is most efficient to specify the input file on the command line,
169			rather than reading from the standard input, since
170			.I rcollate
171			can map the file directly into virtual memory.
172			.PP
173	greg	1.1	The
174			.I rcollate
175			command is rather inflexible when it comes to output field and record
176			separators for ASCII data.
177	greg	1.2	It accepts any amount of white space between fields
178	greg	1.1	on input, but only produces spaces as field separators
179	greg	1.2	between words and tabs as record separators on output.
180	greg	1.1	Output row separtors will always be an EOL, which may differ between systems.
181			.PP
182			If no options are given on the command line, or a binary file is specified
183	greg	1.13	without a transpose or re-ordering,
184	greg	1.1	.I rcollate
185	greg	1.2	issues a warning and simply copies its input to its standard output.
186	greg	1.1	.SH "SEE ALSO"
187	greg	1.18	cnt(1), histo(1), neaten(1), rcalc(1), rcomb(1), rcrop(1), rlam(1),
188			rsensor(1), rmtxop(1), rsplit(1), tabfunc(1), total(1)