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 (4 hours, 19 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
#	Content
1	.\" RCSid "$Id: rcomb.1,v 1.13 2025/04/04 18:06:48 greg Exp $"
2	.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	.B "\-n nproc"
15	][
16	.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	.B "\-m[t] mcat"
29	]
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	These operations are discussed in greater detail below.
59	A single concatenation matrix may be applied after element operations
60	using the
61	.I \-m
62	option.
63	If the option is given as
64	.I \-mt
65	then the concatenation matrix will be transposed before it is applied.
66	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	composed of multiple channels, most commonly an RGB triple.
80	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	.I rtpict(1)
103	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	Note that conversion from a float or RGBE color space applies an efficacy factor
150	of 179 lumens/watt (for CIE or melanopic output) or 412 (for scotopic output),
151	and the inverse happens for conversion from XYZE input to RGB or RGBE output.
152	Lower case versions of all these components are also supported, the only
153	difference being that the efficacy factors are ignored.
154	.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	which will be evaluated for each output
196	component from the current element.
197	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	(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	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	A different component may be referenced using the second argument.
215	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	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	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	.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	.SH EXAMPLES
265	To convert two hyperspectral pictures to RGB color space,
266	average them together, and write them out as a RADIANCE picture:
267	.IP "" .2i
268	rcomb -C RGB -s .5 img1.hsr -s .5 -fc img2.hsr > avg.hdr
269	.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	rcomb -C MY -e "abs(x):if(x,x,-x)"
279	-e "co(p)=select(p,abs(ci(1,1)-ci(1,2)),(ci(1,1)-ci(1,2))/ci(1,2))"
280	input_spec.hsr -fa > compare.mtx
281	.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	and element components are stored as double-precision.
296	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	for any operations it can handle, which is everything except
329	multiple matrix concatenations and transpose
330	operations.
331	The latter may be handled more efficiently by
332	.I rcollate(1).
333	That said, there is no significant difference for
334	simple operations on small matrices, and only
335	.I rmtxop
336	and
337	.I dctimestep(1)
338	accept XML files as inputs.
339	Also note that the resizing function of
340	.I pcomb
341	is not supported in
342	.I rcomb,
343	and should instead be handled by
344	.I pfilt(1).
345	.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	.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	.SH AUTHOR
360	Greg Ward
361	.SH "SEE ALSO"
362	dctimestep(1), icalc(1), getinfo(1), pcomb(1), pfilt(1),
363	pvsum(1), ra_rgbe(1), ra_xyze(1), rcalc(1),
364	rcollate(1), rcontrib(1), rcrop(1), rfluxmtx(1),
365	rmtxop(1), rtpict(1), rtrace(1), vwrays(1)