man/man1/rcomb.1

.\" 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
.SH SYNOPSIS
.B rcomb
[
.B \-h
][
.B \-w
][
.B \-f[afdc]
][
.B "\-n nproc"
][
.B "\-f file"
][
.B "\-e expr"
][
.B "\-C {symbols|file}"
][
.B "\-c ce .."
][
.B "\-s sf .."
]
.B "m1 .."
[
.B "\-m[t] mcat"
]
.SH DESCRIPTION
.I Rcomb
combines inputs given on the command line,
one matrix row or picture scanline at a time.
By default, the result is a linear combination of
the matrix elements or pixels transformed by
.I \-c
specifications and scaled by
.I \-s
coefficients, but an arbitrary mapping can be assigned with the
.I \-e
and
.I \-f
options, similar to the
.I pcomb(1)
and
.I rcalc(1)
commands.
(The definitions in each
.I \-f source
file are read and compiled from the RADIANCE library where it is found.)\0
.PP
If any
.I \-c
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 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
Each input file must have a header containing the following metadata:
.sp
.nf
NROWS={number of rows}
NCOLS={number of columns}
NCOMP={number of components}
FORMAT={ascii|float|double|32-bit_rle_rgbe|32-bit_rle_xyze|Radiance_spectra}
.fi
.sp
The number of components indicates that each matrix element is actually
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
.I rcollate(1).
A matrix may be read from the standard input using a hyphen by itself ('-')
in the appropriate place on the command line.
Similarly, any of the inputs may be read from a command
instead of a file by
using quotes and a beginning exclamation point ('!').
.PP
In the case of Radiance picture files,
the number of columns is the X-dimension of the picture, and
the number of rows is the Y-dimension.
The picture must be in standard pixel ordering, and the zeroeth row
is at the top with the zeroeth column on the left.
Any exposure changes that were applied to the pictures before
.I rcomb
will be undone, similar to the
.I "pcomb \-o"
option.
Radiance spectral pictures with more than 3 components are also supported.
These are typically produced by
.I rtpict(1)
or
.I rfluxmtx(1).
.PP
Before each input, the
.I \-c
and/or
.I \-s
options may be used to modify the matrix elements.
The
.I \-c
option can "transform" the element values, possibly changing
the number of components in the matrix.
For example, a 3-component matrix can be transformed into a single-component
matrix by using
.I \-c
with three coefficients.
A four-component matrix can be turned into a two-component matrix using 8
coefficients, where the first four coefficients will be used to compute
the first new component, and the second four coefficients
yield the second new component.
Note that the number of coefficients must be an even multiple of the number
of original components.
.PP
Alternatively, a set of symbolic output components may be given to the
.I \-c
option, with the following definitions:
.sp
.nf
R       - red channel
G       - green channel
B       - blue channel
X       - CIE X channel
Y       - CIE Y channel (aka., luminance or illuminance)
Z       - CIE Z channel
S       - scotopic luminance or illuminance
M       - melanopic luminance or illuminance
A       - average component value
.fi
.sp
These letters may be given in any order as a single string, and if
.I "-c RGB"
or
.I "-c XYZ"
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 an efficacy factor
of 179 lumens/watt (for CIE or melanopic output) or 412 (for scotopic 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 being that the efficacy factors are ignored.
.PP
If a matrix or picture file path is given to the
.I \-c
option, then the color space of that file will be used, instead.
.PP
The
.I \-C
option takes either a symbolic color space or an input file, and will be
applied to all subsequent matrices that do not have their own associated
.I \-c
option.
.PP
Additionally, the
.I \-s
option applies the given scalar factor(s) to the elements of the matrix.
If only one factor is provided,
it will be used for all components.
If multiple factors are given, their number must match the number of matrix
components
.I after
application of any
.I \-c
option for this input matrix or picture, even if the
.I \-s
option appears first.
.PP
The number of components in all input
matrices after applying any
.I -c
transform must agree.
Similarly, the number of rows and columns of all results must match
exactly.
(The
.I rcrop(1)
utility may be used to trim inputs if necessary.)\0
.PP
If the
.I \-e
or
.I \-f
options are used to define a "co" variable or "co(p)" function,
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
by the "r" and "c" variables, where
.I r
goes from 0 to "nrows" minus one, and
.I c
goes from 0 to "ncols" minus one.
(Note that "nrows" may be zero if unspecified in inputs, and this
is a unique capability of
.I rcomb
to handle these.)\0
Component p from input i is accessed with the "ci(i,p)" function,
and the number of components is defined by the "ncomp" constant.
If given as "ci(i)", the function returns the current component
being evaluated by
.I rcomb.
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"
are conveniently defined as the channel numbers 1, 2, and 3,
respectively.
For color or spectral inputs, the function "wl(p)" gives the
central wavelength for channel
.I p
in nanometers.
For convenience and compatibility with
.I pcomb,
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)",
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.
By default, the values will be written in the lowest precision format
among the inputs, but the
.I \-f[adfc]
option may be used to explicitly output components
as ASCII (-fa), binary doubles (-fd), floats (-ff), or common-exponent
colors/spectra (-fc).
In the latter case, the actual matrix dimensions are written in the resolution string rather than the header.
Also, matrix results will be written as standard
Radiance pictures if they have either one
or three components.
In the one-component case, the output is written as grayscale.
If more than 3 components are in the final matrix and
.I -fc
is specified, the output will be a Radiance spectral picture.
.PP
The
.I \-h
option may be used to reduce the information header size, which
can grow disproportionately, otherwise.
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 pictures to RGB color space,
average them together, and write them out as a RADIANCE picture:
.IP "" .2i
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
rcomb -e "co=ci(1)/sqrt(ci(2)^2+ci(3)^2)" inp1.mtx 
inp2.mtx inp3.mtx > out.mtx
.PP
Compute the absolute and relative differences between melanopic and photopic values
in a spectral image:
.IP "" .2i
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 -fa > compare.mtx
.PP
Concatenate a spectral flux coefficient matrix with a spectral sky
matrix to compute a set of melanopic lux values:
.IP "" .2i
rcomb view_spec.mtx -m sky_spec.mtx -c M > melux.mtx
.SH NOTES
The
.I rcomb
tool was created to overcome some limitations of
.I rmtxop
and
.I pcomb,
whose capabilities somewhat overlap.
The former loads each matrix into memory before operations,
and element components are stored as double-precision.
Very large matrices therefore present a problem with that tool.
Furthermore, 
.I rmtxop
does not allow arbitrary expressions, limiting
what can be accomplished easily on the command-line.
In contrast,
.I pcomb
is fully programmable and operates on its input using a
scanline window, so it can handle much larger input dimensions.
It also handles single- and three-component float matrices on
input and output, but unlike
.I rmtxop,
.I pcomb
has not been extended to handle RADIANCE hyperspectral images
or more general matrix data.
.PP
The
.I rcomb
tool is a compromise that exceeds the capabilities of either of
its predecessors in certain circumstances.
In particular, very large matrices may be combined using
arbitrary, user-defined operations, and the convenient
color conversions of
.I rmtxop
are supported for both input and output.
Finally, a single matrix may be concatenated after operations,
permitting a flux transfer matrix with millions of rows to
pass through.
Generally speaking,
.I rcomb
should be preferred over
.I rmtxop
for any operations it can handle, which is everything except
multiple matrix concatenations and transpose
operations.
The latter may be handled more efficiently by
.I rcollate(1).
That said, there is no significant difference for
simple operations on small matrices, and only
.I rmtxop
and
.I dctimestep(1)
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
command currently ignores the "PRIMARIES" setting in input
headers, and does not produce any on output, even in
circumstances where it would make sense to.
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
dctimestep(1), icalc(1), getinfo(1), pcomb(1), pfilt(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)
Revision:	1.14
Committed:	Thu Jun 19 22:36:53 2025 UTC (18 hours, 4 minutes ago) by greg
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.13:	+5 -2 lines
Log Message:	feat(rcomb): Added -mt option to transpose concatenation matrix after load
#	User	Rev	Content
1	greg	1.14	.\" RCSid "$Id: rcomb.1,v 1.13 2025/04/04 18:06:48 greg Exp $"
2	greg	1.1	.TH RCOMB 12/5/2023 RADIANCE
3			.SH NAME
4			rcomb - combine and convert matrices a row at a time
5			.SH SYNOPSIS
6			.B rcomb
7			[
8			.B \-h
9			][
10			.B \-w
11			][
12			.B \-f[afdc]
13			][
14	greg	1.8	.B "\-n nproc"
15			][
16	greg	1.1	.B "\-f file"
17			][
18			.B "\-e expr"
19			][
20			.B "\-C {symbols\|file}"
21			][
22			.B "\-c ce .."
23			][
24			.B "\-s sf .."
25			]
26			.B "m1 .."
27			[
28	greg	1.14	.B "\-m[t] mcat"
29	greg	1.1	]
30			.SH DESCRIPTION
31			.I Rcomb
32			combines inputs given on the command line,
33			one matrix row or picture scanline at a time.
34			By default, the result is a linear combination of
35			the matrix elements or pixels transformed by
36			.I \-c
37			specifications and scaled by
38			.I \-s
39			coefficients, but an arbitrary mapping can be assigned with the
40			.I \-e
41			and
42			.I \-f
43			options, similar to the
44			.I pcomb(1)
45			and
46			.I rcalc(1)
47			commands.
48			(The definitions in each
49			.I \-f source
50			file are read and compiled from the RADIANCE library where it is found.)\0
51			.PP
52			If any
53			.I \-c
54			or
55			.I \-s
56			options follow the last input matrix, output results will be transformed
57			and/or scaled accordingly.
58	greg	1.7	These operations are discussed in greater detail below.
59	greg	1.1	A single concatenation matrix may be applied after element operations
60			using the
61			.I \-m
62			option.
63	greg	1.14	If the option is given as
64			.I \-mt
65			then the concatenation matrix will be transposed before it is applied.
66	greg	1.1	Matrix concatenation will happen before or after any trailing
67			operations, depending on relative command line placement.
68			.PP
69			Each input file must have a header containing the following metadata:
70			.sp
71			.nf
72			NROWS={number of rows}
73			NCOLS={number of columns}
74			NCOMP={number of components}
75			FORMAT={ascii\|float\|double\|32-bit_rle_rgbe\|32-bit_rle_xyze\|Radiance_spectra}
76			.fi
77			.sp
78			The number of components indicates that each matrix element is actually
79	greg	1.7	composed of multiple channels, most commonly an RGB triple.
80	greg	1.1	This is essentially dividing the matrix into planes, where each component
81			participates in a separate calculation.
82			If an appropriate header is not present, it may be added with a call to
83			.I rcollate(1).
84			A matrix may be read from the standard input using a hyphen by itself ('-')
85			in the appropriate place on the command line.
86			Similarly, any of the inputs may be read from a command
87			instead of a file by
88			using quotes and a beginning exclamation point ('!').
89			.PP
90			In the case of Radiance picture files,
91			the number of columns is the X-dimension of the picture, and
92			the number of rows is the Y-dimension.
93			The picture must be in standard pixel ordering, and the zeroeth row
94			is at the top with the zeroeth column on the left.
95			Any exposure changes that were applied to the pictures before
96			.I rcomb
97			will be undone, similar to the
98			.I "pcomb \-o"
99			option.
100			Radiance spectral pictures with more than 3 components are also supported.
101			These are typically produced by
102	greg	1.5	.I rtpict(1)
103	greg	1.1	or
104			.I rfluxmtx(1).
105			.PP
106			Before each input, the
107			.I \-c
108			and/or
109			.I \-s
110			options may be used to modify the matrix elements.
111			The
112			.I \-c
113			option can "transform" the element values, possibly changing
114			the number of components in the matrix.
115			For example, a 3-component matrix can be transformed into a single-component
116			matrix by using
117			.I \-c
118			with three coefficients.
119			A four-component matrix can be turned into a two-component matrix using 8
120			coefficients, where the first four coefficients will be used to compute
121			the first new component, and the second four coefficients
122			yield the second new component.
123			Note that the number of coefficients must be an even multiple of the number
124			of original components.
125			.PP
126			Alternatively, a set of symbolic output components may be given to the
127			.I \-c
128			option, with the following definitions:
129			.sp
130			.nf
131			R - red channel
132			G - green channel
133			B - blue channel
134			X - CIE X channel
135			Y - CIE Y channel (aka., luminance or illuminance)
136			Z - CIE Z channel
137			S - scotopic luminance or illuminance
138			M - melanopic luminance or illuminance
139			A - average component value
140			.fi
141			.sp
142			These letters may be given in any order as a single string, and if
143			.I "-c RGB"
144			or
145			.I "-c XYZ"
146			is specified for an input picture or the
147			.I "-fc"
148			option is given, the output will be written as a RGBE or XYZE picture.
149	greg	1.9	Note that conversion from a float or RGBE color space applies an efficacy factor
150	greg	1.1	of 179 lumens/watt (for CIE or melanopic output) or 412 (for scotopic output),
151	greg	1.9	and the inverse happens for conversion from XYZE input to RGB or RGBE output.
152	greg	1.3	Lower case versions of all these components are also supported, the only
153	greg	1.9	difference being that the efficacy factors are ignored.
154	greg	1.1	.PP
155			If a matrix or picture file path is given to the
156			.I \-c
157			option, then the color space of that file will be used, instead.
158			.PP
159			The
160			.I \-C
161			option takes either a symbolic color space or an input file, and will be
162			applied to all subsequent matrices that do not have their own associated
163			.I \-c
164			option.
165			.PP
166			Additionally, the
167			.I \-s
168			option applies the given scalar factor(s) to the elements of the matrix.
169			If only one factor is provided,
170			it will be used for all components.
171			If multiple factors are given, their number must match the number of matrix
172			components
173			.I after
174			application of any
175			.I \-c
176			option for this input matrix or picture, even if the
177			.I \-s
178			option appears first.
179			.PP
180			The number of components in all input
181			matrices after applying any
182			.I -c
183			transform must agree.
184			Similarly, the number of rows and columns of all results must match
185			exactly.
186			(The
187			.I rcrop(1)
188			utility may be used to trim inputs if necessary.)\0
189			.PP
190			If the
191			.I \-e
192			or
193			.I \-f
194			options are used to define a "co" variable or "co(p)" function,
195	greg	1.7	which will be evaluated for each output
196			component from the current element.
197	greg	1.1	The "co" variable defines identical operations for all components,
198			whereas "co(p)" may specify different operations for each component.
199			The element position is defined
200			by the "r" and "c" variables, where
201			.I r
202			goes from 0 to "nrows" minus one, and
203			.I c
204			goes from 0 to "ncols" minus one.
205	greg	1.2	(Note that "nrows" may be zero if unspecified in inputs, and this
206			is a unique capability of
207			.I rcomb
208			to handle these.)\0
209	greg	1.1	Component p from input i is accessed with the "ci(i,p)" function,
210			and the number of components is defined by the "ncomp" constant.
211			If given as "ci(i)", the function returns the current component
212			being evaluated by
213			.I rcomb.
214	greg	1.6	A different component may be referenced using the second argument.
215	greg	1.1	For example, "ci(1,2)" accesses
216			the second component from the first input.
217			If the input is a picture, the the constants "R", "G", and "B"
218			are conveniently defined as the channel numbers 1, 2, and 3,
219			respectively.
220			For color or spectral inputs, the function "wl(p)" gives the
221			central wavelength for channel
222			.I p
223			in nanometers.
224			For convenience and compatibility with
225			.I pcomb,
226			the functions "ri(i)", "gi(i)", and "bi(i)" are predefined as
227			"ci(i,R)", "ci(i,G)", and "ci(i,B)", respectively.
228			Accordingly, the "ro", "go", and "bo"
229	greg	1.6	variables may be used in place of "co(R)", "co(G)", and "co(B)",
230			but all three must be defined for this substitution to take place.
231	greg	1.1	Finally, the total number of input files is set in the constant "nfiles".
232			.PP
233			Results are sent to the standard output.
234			By default, the values will be written in the lowest precision format
235			among the inputs, but the
236			.I \-f[adfc]
237			option may be used to explicitly output components
238			as ASCII (-fa), binary doubles (-fd), floats (-ff), or common-exponent
239			colors/spectra (-fc).
240			In the latter case, the actual matrix dimensions are written in the resolution string rather than the header.
241			Also, matrix results will be written as standard
242			Radiance pictures if they have either one
243			or three components.
244			In the one-component case, the output is written as grayscale.
245			If more than 3 components are in the final matrix and
246			.I -fc
247			is specified, the output will be a Radiance spectral picture.
248			.PP
249			The
250			.I \-h
251			option may be used to reduce the information header size, which
252			can grow disproportionately, otherwise.
253			The
254			.I \-w
255			option turns off warnings about divide-by-zero and other non-fatal
256			calculation errors.
257	greg	1.8	.PP
258			The
259			.I \-n
260			option specifies how many execution processes to employ,
261			which may improve performance on multi-core architectures,
262			especially for matrix multiplication
263			and complex operations on long input rows.
264	greg	1.1	.SH EXAMPLES
265	greg	1.10	To convert two hyperspectral pictures to RGB color space,
266	greg	1.1	average them together, and write them out as a RADIANCE picture:
267			.IP "" .2i
268	greg	1.10	rcomb -C RGB -s .5 img1.hsr -s .5 -fc img2.hsr > avg.hdr
269	greg	1.1	.PP
270			Divide one set of matrix elements by the Euclidean sum of two others:
271			.IP "" .2i
272			rcomb -e "co=ci(1)/sqrt(ci(2)^2+ci(3)^2)" inp1.mtx
273			inp2.mtx inp3.mtx > out.mtx
274			.PP
275			Compute the absolute and relative differences between melanopic and photopic values
276			in a spectral image:
277			.IP "" .2i
278	greg	1.10	rcomb -C MY -e "abs(x):if(x,x,-x)"
279	greg	1.1	-e "co(p)=select(p,abs(ci(1,1)-ci(1,2)),(ci(1,1)-ci(1,2))/ci(1,2))"
280	greg	1.10	input_spec.hsr -fa > compare.mtx
281	greg	1.1	.PP
282			Concatenate a spectral flux coefficient matrix with a spectral sky
283			matrix to compute a set of melanopic lux values:
284			.IP "" .2i
285			rcomb view_spec.mtx -m sky_spec.mtx -c M > melux.mtx
286			.SH NOTES
287			The
288			.I rcomb
289			tool was created to overcome some limitations of
290			.I rmtxop
291			and
292			.I pcomb,
293			whose capabilities somewhat overlap.
294			The former loads each matrix into memory before operations,
295	greg	1.7	and element components are stored as double-precision.
296	greg	1.1	Very large matrices therefore present a problem with that tool.
297			Furthermore,
298			.I rmtxop
299			does not allow arbitrary expressions, limiting
300			what can be accomplished easily on the command-line.
301			In contrast,
302			.I pcomb
303			is fully programmable and operates on its input using a
304			scanline window, so it can handle much larger input dimensions.
305			It also handles single- and three-component float matrices on
306			input and output, but unlike
307			.I rmtxop,
308			.I pcomb
309			has not been extended to handle RADIANCE hyperspectral images
310			or more general matrix data.
311			.PP
312			The
313			.I rcomb
314			tool is a compromise that exceeds the capabilities of either of
315			its predecessors in certain circumstances.
316			In particular, very large matrices may be combined using
317			arbitrary, user-defined operations, and the convenient
318			color conversions of
319			.I rmtxop
320			are supported for both input and output.
321			Finally, a single matrix may be concatenated after operations,
322			permitting a flux transfer matrix with millions of rows to
323			pass through.
324			Generally speaking,
325			.I rcomb
326			should be preferred over
327			.I rmtxop
328	greg	1.7	for any operations it can handle, which is everything except
329	greg	1.1	multiple matrix concatenations and transpose
330	greg	1.7	operations.
331			The latter may be handled more efficiently by
332			.I rcollate(1).
333	greg	1.1	That said, there is no significant difference for
334	greg	1.7	simple operations on small matrices, and only
335	greg	1.1	.I rmtxop
336			and
337			.I dctimestep(1)
338	greg	1.7	accept XML files as inputs.
339			Also note that the resizing function of
340	greg	1.1	.I pcomb
341			is not supported in
342			.I rcomb,
343			and should instead be handled by
344			.I pfilt(1).
345	greg	1.13	.PP
346			Similar to
347			.I rmtxop,
348			all calculations are peformed internally using 32-bit floating-point,
349			so there is little benefit in either reading or writing 64-bit double
350			data.
351			This may be overridden at compile time using the macro
352			"-DDTrmx_native=DTdouble".
353	greg	1.4	.SH BUGS
354			The
355			.I rcomb
356			command currently ignores the "PRIMARIES" setting in input
357			headers, and does not produce any on output, even in
358			circumstances where it would make sense to.
359	greg	1.1	.SH AUTHOR
360			Greg Ward
361			.SH "SEE ALSO"
362			dctimestep(1), icalc(1), getinfo(1), pcomb(1), pfilt(1),
363	greg	1.12	pvsum(1), ra_rgbe(1), ra_xyze(1), rcalc(1),
364	greg	1.1	rcollate(1), rcontrib(1), rcrop(1), rfluxmtx(1),
365			rmtxop(1), rtpict(1), rtrace(1), vwrays(1)