man/man1/rcollate.1

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