man/man1/rcollate.1

.\" RCSid "$Id: rcollate.1,v 1.3 2013/09/06 21:34:38 greg Exp $"
.TH RCOLLATE 1 7/8/97 RADIANCE
.SH NAME
rcollate - resize or transpose matrix data
.SH SYNOPSIS
.B rcollate
[
.B \-h
][
.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 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.
By default, the file is assumed to include an information header, which
is copied to the standard output along with the command name, but the
.I \-h
option may be used to turn this behavior off.
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
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.
.SH EXAMPLE
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
.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), tabfunc(1), total(1)
Revision:	1.4
Committed:	Wed Sep 18 21:24:36 2013 UTC (11 years, 7 months ago) by greg
Branch:	MAIN
Changes since 1.3:	+2 -2 lines
Log Message:	Added missing word
#	Content
1	.\" RCSid "$Id: rcollate.1,v 1.3 2013/09/06 21:34:38 greg Exp $"
2	.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	.B \-h
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	[
25	.B input.dat
26	]
27	.SH DESCRIPTION
28	.I Rcollate
29	reads in a single matrix file (table) and reshapes it to have
30	the number of columns specified by the
31	.I \-oc
32	option.
33	By default, the file is assumed to include an information header, which
34	is copied to the standard output along with the command name, but the
35	.I \-h
36	option may be used to turn this behavior off.
37	The
38	.I \-w
39	option turns off non-fatal warning messages, such as unexpected EOD.
40	.PP
41	The input format is assumed to be ASCII, with three white-space separated words
42	(typically numbers) in each record.
43	A different input format may be specified with the
44	.I \-f
45	option.
46	The suboptions are
47	.I \-fa,
48	.I \-ff,
49	.I \-fd,
50	and
51	.I \-fb
52	for ASCII, float, double, and binary, respectively.
53	An optional count may be attached to specify the number of data elements per
54	record, which defaults to 1.
55	Thus, the default setting is
56	.I \-fa3.
57	Since
58	.I rcollate
59	does not interpret the fields, all binary options of the same
60	length have the same result.
61	On most architectures,
62	.I \-ff6,
63	.I \-fd3,
64	and
65	.I \-fb24
66	would all be equivalent.
67	Note that the lack of row separators in binary files means that
68	.I rcollate
69	does not actually do anything for binary files unless the transpose
70	option is given, also.
71	.PP
72	The transpose option,
73	.I \-t
74	swaps rows and columns on the input.
75	For binary files, the user must specify at least one input or output
76	dimension to define the matrix size.
77	For ASCII files,
78	.I rcollate
79	will automatically determine the number of columns based on the
80	position of the first EOL (end-of-line) character, and the number
81	of rows based on the total count of records in the file.
82	The user may override these determinations, allowing the matrix to
83	be resized as well as transposed.
84	If input and output dimensions are given, the number of input rows
85	must equal the number of output columns,
86	and the number of input columns must equal the number of output rows.
87	For large transpose operations on Unix systems, it is most efficient
88	to specify the input file on the command line, rather than reading
89	from the standard input, since
90	.I rcollate
91	can map the file directly into virtual memory.
92	.SH EXAMPLE
93	To change put 8760 color triplets per row in a matrix with no header:
94	.IP "" .2i
95	rcollate -h \-oc 8760 input.dat > col8760.dat
96	.PP
97	To transpose a binary file with 145 float triplets per input row:
98	.IP "" .2i
99	rcollate -ff3 -ic 145 -t orig.flt > transpose.flt
100	.SH AUTHOR
101	Greg Ward
102	.SH NOTES
103	The
104	.I rcollate
105	command is rather inflexible when it comes to output field and record
106	separators for ASCII data.
107	It accepts any amount of white space between fields
108	on input, but only produces spaces as field separators
109	between words and tabs as record separators on output.
110	Output row separtors will always be an EOL, which may differ between systems.
111	.PP
112	If no options are given on the command line, or a binary file is specified
113	without a transpose,
114	.I rcollate
115	issues a warning and simply copies its input to its standard output.
116	.SH "SEE ALSO"
117	cnt(1), histo(1), neaten(1), rcalc(1), rlam(1), tabfunc(1), total(1)