man/man1/rcollate.1

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