man/man1/rmtxcomb.1

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