man/man1/rcomb.1

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