--- ray/doc/man/man1/rcollate.1	2014/05/30 16:50:43	1.6
+++ ray/doc/man/man1/rcollate.1	2019/11/11 18:38:41	1.12
@@ -1,4 +1,4 @@
-.\" RCSid "$Id: rcollate.1,v 1.6 2014/05/30 16:50:43 greg Exp $"
+.\" 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 transpose matrix data
@@ -9,7 +9,7 @@ rcollate - resize or transpose matrix data
 ][
 .B \-w
 ][
-.B \-f[afdb][N]]
+.B \-f[afdb][N]
 ][
 .B \-t
 ][
@@ -20,6 +20,8 @@ rcollate - resize or transpose matrix data
 .B "\-oc out_col"
 ][
 .B "\-or out_row"
+][
+.B "\-o RxC[xR1xC2..]"
 ]
 [
 .B input.dat
@@ -30,6 +32,21 @@ reads in a single matrix file (table) and reshapes it 
 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
@@ -105,7 +122,12 @@ to specify the input file on the command line, rather 
 from the standard input, since
 .I rcollate
 can map the file directly into virtual memory.
-.SH EXAMPLE
+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
@@ -113,6 +135,16 @@ rcollate -h \-oc 8760 input.dat > col8760.dat
 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
@@ -130,4 +162,5 @@ 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)
+cnt(1), histo(1), neaten(1), rcalc(1), rlam(1), rmtxop(1), 
+rsplit(1), tabfunc(1), total(1)