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.10 by greg, Fri Nov 8 05:39:05 2019 UTC vs.
Revision 1.19 by greg, Fri Jan 26 00:47:17 2024 UTC

# Line 1 | Line 1
1   .\" RCSid "$Id$"
2 < .TH RCOLLATE 1 7/8/97 RADIANCE
2 > .TH RCOLLATE 1 9/5/2013 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 42 | Line 44 | option with the number of rows and columns separated b
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, "3x10X7x2" would order output data with a 3x10 super-array of 7x2
48 < subblocks.
49 < This is a convenient way to visualize tensor data.
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.
# Line 60 | 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 and formatted correctly (in the case of ASCII input).
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 88 | 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 100 | Line 113 | and
113   .I \-f
114   options are not required, but will be checked against the header
115   information if provided.
116 + An exception is made for
117 + .I \-fbN
118 + 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   .PP
126   The transpose option,
127   .I \-t
128   swaps rows and columns on the input.
129 < For binary files, the user must specify at least one input or output
130 < dimension to define the matrix size.
129 > 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   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   of rows based on the total count of records in the file.
136   The user may override these determinations, allowing the matrix to
137 < be resized as well as transposed.
138 < If input and output dimensions are given, the number of input rows
139 < must equal the number of output columns,
137 > 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   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 – to specify the input file on the command line, rather than reading
121 – from the standard input, since
122 – .I rcollate
123 – can map the file directly into virtual memory.
141   If the
142   .I \-o
143   option is also given with multiple block levels, the transpose operation
144 < will logically precede the reblocking operation.
144 > will logically precede the re-ordering operation, regardless of their
145 > position on the command line.
146   .SH EXAMPLES
147   To change put 8760 color triplets per row in a matrix with no header:
148   .IP "" .2i
# Line 146 | Line 164 | rcollate -o 64x64X32x32 s-c_bsdf.mtx | rmtxop -fc - >
164   .SH AUTHOR
165   Greg Ward
166   .SH NOTES
167 + 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   The
174   .I rcollate
175   command is rather inflexible when it comes to output field and record
# Line 156 | Line 180 | between words and tabs as record separators on output.
180   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 < without a transpose,
183 > without a transpose or re-ordering,
184   .I rcollate
185   issues a warning and simply copies its input to its standard output.
186   .SH "SEE ALSO"
187 < cnt(1), histo(1), neaten(1), rcalc(1), rlam(1), rmtxop(1),
188 < rsplit(1), tabfunc(1), total(1)
187 > 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)

Diff Legend

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