ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/radiance/ray/doc/man/man1/rcollate.1
(Generate patch)

Comparing ray/doc/man/man1/rcollate.1 (file contents):
Revision 1.7 by greg, Sat May 31 21:33:21 2014 UTC vs.
Revision 1.14 by greg, Mon Sep 7 17:08:08 2020 UTC

# Line 1 | Line 1
1   .\" RCSid "$Id$"
2   .TH RCOLLATE 1 7/8/97 RADIANCE
3   .SH NAME
4 < rcollate - resize or transpose matrix data
4 > rcollate - resize or re-order matrix data
5   .SH SYNOPSIS
6   .B rcollate
7   [
# Line 9 | Line 9 | rcollate - resize or transpose matrix data
9   ][
10   .B \-w
11   ][
12 < .B \-f[afdb][N]
12 > .B \-c
13   ][
14 + .B \-f{a|f|d|b}[N]
15 + ][
16   .B \-t
17   ][
18   .B "\-ic in_col"
# Line 20 | Line 22 | rcollate - resize or transpose matrix data
22   .B "\-oc out_col"
23   ][
24   .B "\-or out_row"
25 + ][
26 + .B "\-o RxC[xR1xC2..]"
27   ]
28   [
29   .B input.dat
# Line 30 | Line 34 | reads in a single matrix file (table) and reshapes it
34   the number of columns specified by the
35   .I \-oc
36   option.
37 + 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 + 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 + .PP
52   By default, the file is assumed to include an information header, which
53   is copied to the standard output along with the command name.
54   The
# Line 44 | Line 63 | The
63   .I \-w
64   option turns off non-fatal warning messages, such as unexpected EOD.
65   .PP
66 + 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 + the data is the proper size.
75 + .PP
76   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
# Line 72 | Line 101 | and
101   would all be equivalent.
102   Note that the lack of row separators in binary files means that
103   .I rcollate
104 < does not actually do anything for binary files unless the transpose
105 < option is given, also.
104 > does not actually do anything for binary files unless the data is being
105 > re-ordered.
106   .PP
107   If an input header is present, it may contain the format, number of components
108   and matrix dimensions.
# Line 88 | Line 117 | information if provided.
117   The transpose option,
118   .I \-t
119   swaps rows and columns on the input.
120 < For binary files, the user must specify at least one input or output
121 < dimension to define the matrix size.
120 > For binary files with no header information, the user must
121 > specify at least one input or output dimension to define the matrix size.
122   For ASCII files,
123   .I rcollate
124   will automatically determine the number of columns based on the
125   position of the first EOL (end-of-line) character, and the number
126   of rows based on the total count of records in the file.
127   The user may override these determinations, allowing the matrix to
128 < be resized as well as transposed.
129 < If input and output dimensions are given, the number of input rows
130 < must equal the number of output columns,
128 > be resized or re-ordered as well as transposed.
129 > If input and output dimensions are given and there is no block re-ordering,
130 > the number of input rows must equal the number of output columns,
131   and the number of input columns must equal the number of output rows.
132 < For large transpose operations on Unix systems, it is most efficient
133 < to specify the input file on the command line, rather than reading
134 < from the standard input, since
135 < .I rcollate
136 < can map the file directly into virtual memory.
137 < .SH EXAMPLE
132 > If the
133 > .I \-o
134 > option is also given with multiple block levels, the transpose operation
135 > will logically precede the re-ordering operation, regardless of their
136 > position on the command line.
137 > .SH EXAMPLES
138   To change put 8760 color triplets per row in a matrix with no header:
139   .IP "" .2i
140   rcollate -h \-oc 8760 input.dat > col8760.dat
# Line 118 | Line 147 | To create an appropriate header for a binary float mat
147   .I rmtxop(1)\:
148   .IP "" .2i
149   rcollate -hi -ff3 -or 145 -oc 8760 input.smx | rmtxop dcoef.dmx - > res.txt
150 + .PP
151 + To visualize a Shirley-Chiu BTDF matrix where the interior resolution is
152 + 64x64 and the exterior resolution is 32x32:
153 + .IP "" .2i
154 + rcollate -o 64x64X32x32 s-c_bsdf.mtx | rmtxop -fc - > s-c_bsdf.hdr
155   .SH AUTHOR
156   Greg Ward
157   .SH NOTES
158 + For large transpose or re-ordering operations on Unix systems,
159 + it is most efficient to specify the input file on the command line,
160 + rather than reading from the standard input, since
161 + .I rcollate
162 + can map the file directly into virtual memory.
163 + .PP
164   The
165   .I rcollate
166   command is rather inflexible when it comes to output field and record
# Line 131 | Line 171 | between words and tabs as record separators on output.
171   Output row separtors will always be an EOL, which may differ between systems.
172   .PP
173   If no options are given on the command line, or a binary file is specified
174 < without a transpose,
174 > without a transpose or re-ordering,
175   .I rcollate
176   issues a warning and simply copies its input to its standard output.
177   .SH "SEE ALSO"
178 < cnt(1), histo(1), neaten(1), rcalc(1), rlam(1), rmtxop(1), tabfunc(1), total(1)
178 > cnt(1), histo(1), neaten(1), rcalc(1), rlam(1), rmtxop(1),
179 > rsplit(1), tabfunc(1), total(1)

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines