--- ray/doc/man/man1/rcomb.1	2024/02/10 19:32:32	1.6
+++ ray/doc/man/man1/rcomb.1	2025/04/04 18:06:48	1.13
@@ -1,4 +1,4 @@
-.\" RCSid "$Id: rcomb.1,v 1.6 2024/02/10 19:32:32 greg Exp $"
+.\" RCSid "$Id: rcomb.1,v 1.13 2025/04/04 18:06:48 greg Exp $"
 .TH RCOMB 12/5/2023 RADIANCE
 .SH NAME
 rcomb - combine and convert matrices a row at a time
@@ -11,6 +11,8 @@ rcomb - combine and convert matrices a row at a time
 ][
 .B \-f[afdc]
 ][
+.B "\-n nproc"
+][
 .B "\-f file"
 ][
 .B "\-e expr"
@@ -53,7 +55,7 @@ or
 .I \-s
 options follow the last input matrix, output results will be transformed
 and/or scaled accordingly.
-These operations are discussed in greater detail further on.
+These operations are discussed in greater detail below.
 A single concatenation matrix may be applied after element operations
 using the
 .I \-m
@@ -71,7 +73,7 @@ FORMAT={ascii|float|double|32-bit_rle_rgbe|32-bit_rle_
 .fi
 .sp
 The number of components indicates that each matrix element is actually
-composed of multiple elements, most commonly an RGB triple.
+composed of multiple channels, most commonly an RGB triple.
 This is essentially dividing the matrix into planes, where each component
 participates in a separate calculation.
 If an appropriate header is not present, it may be added with a call to
@@ -141,12 +143,11 @@ or
 is specified for an input picture or the
 .I "-fc"
 option is given, the output will be written as a RGBE or XYZE picture.
-Note that conversion from a float or RGBE color space applies a conversion
+Note that conversion from a float or RGBE color space applies an efficacy factor
 of 179 lumens/watt (for CIE or melanopic output) or 412 (for scotopic output),
-and the reverse happens for conversion from XYZE input to RGB or RGBE output.
+and the inverse happens for conversion from XYZE input to RGB or RGBE output.
 Lower case versions of all these components are also supported, the only
-difference is that the aforementioned efficacy factors
-will be left out of the conversion.
+difference being that the efficacy factors are ignored.
 .PP
 If a matrix or picture file path is given to the
 .I \-c
@@ -188,8 +189,8 @@ If the
 or
 .I \-f
 options are used to define a "co" variable or "co(p)" function,
-this will be evaluated at each output
-component for the current element.
+which will be evaluated for each output
+component from the current element.
 The "co" variable defines identical operations for all components,
 whereas "co(p)" may specify different operations for each component.
 The element position is defined
@@ -250,11 +251,18 @@ The
 .I \-w
 option turns off warnings about divide-by-zero and other non-fatal
 calculation errors.
+.PP
+The
+.I \-n
+option specifies how many execution processes to employ,
+which may improve performance on multi-core architectures,
+especially for matrix multiplication
+and complex operations on long input rows.
 .SH EXAMPLES
-To convert two hyperspectral inputs to RGB color space,
+To convert two hyperspectral pictures to RGB color space,
 average them together, and write them out as a RADIANCE picture:
 .IP "" .2i
-rcomb -C RGB -s .5 img1.spc -s .5 img2.spc > avg.hdr
+rcomb -C RGB -s .5 img1.hsr -s .5 -fc img2.hsr > avg.hdr
 .PP
 Divide one set of matrix elements by the Euclidean sum of two others:
 .IP "" .2i
@@ -264,9 +272,9 @@ inp2.mtx inp3.mtx > out.mtx
 Compute the absolute and relative differences between melanopic and photopic values
 in a spectral image:
 .IP "" .2i
-rcomb -fa -C MY -e "abs(x):if(x,x,-x)"
+rcomb -C MY -e "abs(x):if(x,x,-x)"
 -e "co(p)=select(p,abs(ci(1,1)-ci(1,2)),(ci(1,1)-ci(1,2))/ci(1,2))"
-input_spec.hsr > compare.mtx
+input_spec.hsr -fa > compare.mtx
 .PP
 Concatenate a spectral flux coefficient matrix with a spectral sky
 matrix to compute a set of melanopic lux values:
@@ -281,7 +289,7 @@ and
 .I pcomb,
 whose capabilities somewhat overlap.
 The former loads each matrix into memory before operations,
-and element components take 8 bytes apiece, adding up quickly.
+and element components are stored as double-precision.
 Very large matrices therefore present a problem with that tool.
 Furthermore, 
 .I rmtxop
@@ -314,23 +322,31 @@ Generally speaking,
 .I rcomb
 should be preferred over
 .I rmtxop
-for any operations in can handle, which is everything except
+for any operations it can handle, which is everything except
 multiple matrix concatenations and transpose
-operations, which are handled more efficiently by
-.I rcollate(1)
-in any case.
+operations.
+The latter may be handled more efficiently by
+.I rcollate(1).
 That said, there is no significant difference for
-simple operations on smallish matrices, and note that only
+simple operations on small matrices, and only
 .I rmtxop
 and
 .I dctimestep(1)
-currently accept XML files as inputs.
-Also, the resizing function of
+accept XML files as inputs.
+Also note that the resizing function of
 .I pcomb
 is not supported in
 .I rcomb,
 and should instead be handled by
 .I pfilt(1).
+.PP
+Similar to
+.I rmtxop,
+all calculations are peformed internally using 32-bit floating-point,
+so there is little benefit in either reading or writing 64-bit double
+data.
+This may be overridden at compile time using the macro
+"-DDTrmx_native=DTdouble".
 .SH BUGS
 The
 .I rcomb
@@ -341,6 +357,6 @@ circumstances where it would make sense to.
 Greg Ward
 .SH "SEE ALSO"
 dctimestep(1), icalc(1), getinfo(1), pcomb(1), pfilt(1),
-ra_xyze(1), rcalc(1),
+pvsum(1), ra_rgbe(1), ra_xyze(1), rcalc(1),
 rcollate(1), rcontrib(1), rcrop(1), rfluxmtx(1), 
 rmtxop(1), rtpict(1), rtrace(1), vwrays(1)