--- ray/doc/man/man1/rcollate.1	2013/09/06 21:34:38	1.3
+++ ray/doc/man/man1/rcollate.1	2019/11/08 22:19:23	1.11
@@ -1,15 +1,15 @@
-.\" RCSid "$Id: rcollate.1,v 1.3 2013/09/06 21:34:38 greg Exp $"
+.\" RCSid "$Id: rcollate.1,v 1.11 2019/11/08 22:19:23 greg Exp $"
 .TH RCOLLATE 1 7/8/97 RADIANCE
 .SH NAME
 rcollate - resize or transpose matrix data
 .SH SYNOPSIS
 .B rcollate
 [
-.B \-h
+.B \-h[io]
 ][
 .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,10 +32,30 @@ 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, "3x10X7x2" would order output data with a 3x10 super-array of 7x2
+subblocks.
+This is a convenient way to visualize 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, but the
+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
-option may be used to turn this behavior off.
+by itself turns off both input and output headers.
 The
 .I \-w
 option turns off non-fatal warning messages, such as unexpected EOD.
@@ -69,6 +91,16 @@ Note that the lack of row separators in binary files m
 does not actually do anything for binary files unless the transpose
 option is given, also.
 .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.
@@ -88,8 +120,13 @@ For large transpose operations on Unix systems, it is 
 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 memory.
-.SH EXAMPLE
+can map the file directly into virtual memory.
+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
@@ -97,6 +134,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
@@ -114,4 +161,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)