man/man1/rcomb.1

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