--- ray/doc/man/man1/rcomb.1 2023/12/25 16:29:56 1.4 +++ ray/doc/man/man1/rcomb.1 2025/06/19 22:36:53 1.14 @@ -1,4 +1,4 @@ -.\" RCSid "$Id: rcomb.1,v 1.4 2023/12/25 16:29:56 greg Exp $" +.\" RCSid "$Id: rcomb.1,v 1.14 2025/06/19 22:36:53 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" @@ -23,7 +25,7 @@ rcomb - combine and convert matrices a row at a time ] .B "m1 .." [ -.B "\-m mcat" +.B "\-m[t] mcat" ] .SH DESCRIPTION .I Rcomb @@ -53,11 +55,14 @@ 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 option. +If the option is given as +.I \-mt +then the concatenation matrix will be transposed before it is applied. Matrix concatenation will happen before or after any trailing operations, depending on relative command line placement. .PP @@ -71,7 +76,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 @@ -94,7 +99,7 @@ will be undone, similar to the option. Radiance spectral pictures with more than 3 components are also supported. These are typically produced by -.I rtrace(1) +.I rtpict(1) or .I rfluxmtx(1). .PP @@ -141,12 +146,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 +192,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 @@ -207,7 +211,7 @@ and the number of components is defined by the "ncomp" If given as "ci(i)", the function returns the current component being evaluated by .I rcomb. -A different component may be referenced using th second argument. +A different component may be referenced using the second argument. For example, "ci(1,2)" accesses the second component from the first input. If the input is a picture, the the constants "R", "G", and "B" @@ -222,7 +226,8 @@ For convenience and compatibility with the functions "ri(i)", "gi(i)", and "bi(i)" are predefined as "ci(i,R)", "ci(i,G)", and "ci(i,B)", respectively. Accordingly, the "ro", "go", and "bo" -variables may be used in place of "co(R)", "co(G)", and "co(B)". +variables may be used in place of "co(R)", "co(G)", and "co(B)", +but all three must be defined for this substitution to take place. Finally, the total number of input files is set in the constant "nfiles". .PP Results are sent to the standard output. @@ -249,11 +254,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 @@ -263,9 +275,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: @@ -280,7 +292,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 @@ -313,23 +325,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 @@ -340,6 +360,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)