man/man1/rmtxcomb.1

.\" RCSid "$Id: rmtxcomb.1,v 1.5 2023/12/11 19:21:43 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 \-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 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)
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 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 \-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
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
Compute the absolute and relative differences between melanopic and photopic values
in a spectral image:
.IP "" .2i
rmtxcomb -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
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
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 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.
Also, the resizing function of
.I pcomb
is not supported in
.I rmtxcomb,
and should instead be handled by
.I pfilt(1).
.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:	Tue Dec 12 16:31:45 2023 UTC (16 months, 3 weeks ago) by greg
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.5:	+1 -1 lines
State:	*FILE REMOVED*
Log Message:	chore(rcomb): Renamed rmtxcomb to simpler "rcomb"
#	Content
1	.\" RCSid "$Id: rmtxcomb.1,v 1.5 2023/12/11 19:21:43 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 \-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 Rmtxcomb
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 rmtxcomb
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	.I rtrace(1)
98	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	.PP
148	If a matrix or picture file path is given to the
149	.I \-c
150	option, then the color space of that file will be used, instead.
151	.PP
152	The
153	.I \-C
154	option takes either a symbolic color space or an input file, and will be
155	applied to all subsequent matrices that do not have their own associated
156	.I \-c
157	option.
158	.PP
159	Additionally, the
160	.I \-s
161	option applies the given scalar factor(s) to the elements of the matrix.
162	If only one factor is provided,
163	it will be used for all components.
164	If multiple factors are given, their number must match the number of matrix
165	components
166	.I after
167	application of any
168	.I \-c
169	option for this input matrix or picture, even if the
170	.I \-s
171	option appears first.
172	.PP
173	The number of components in all input
174	matrices after applying any
175	.I -c
176	transform must agree.
177	Similarly, the number of rows and columns of all results must match
178	exactly.
179	(The
180	.I rcrop(1)
181	utility may be used to trim inputs if necessary.)\0
182	.PP
183	If the
184	.I \-e
185	or
186	.I \-f
187	options are used to define a "co" variable or "co(p)" function,
188	this will be evaluated at each output
189	component for the current element.
190	The "co" variable defines identical operations for all components,
191	whereas "co(p)" may specify different operations for each component.
192	The element position is defined
193	by the "r" and "c" variables, where
194	.I r
195	goes from 0 to "nrows" minus one, and
196	.I c
197	goes from 0 to "ncols" minus one.
198	Component p from input i is accessed with the "ci(i,p)" function,
199	and the number of components is defined by the "ncomp" constant.
200	If given as "ci(i)", the function returns the current component
201	being evaluated by
202	.I rmtxcomb.
203	A different component may be referenced using th second argument.
204	For example, "ci(1,2)" accesses
205	the second component from the first input.
206	If the input is a picture, the the constants "R", "G", and "B"
207	are conveniently defined as the channel numbers 1, 2, and 3,
208	respectively.
209	For color or spectral inputs, the function "wl(p)" gives the
210	central wavelength for channel
211	.I p
212	in nanometers.
213	For convenience and compatibility with
214	.I pcomb,
215	the functions "ri(i)", "gi(i)", and "bi(i)" are predefined as
216	"ci(i,R)", "ci(i,G)", and "ci(i,B)", respectively.
217	Accordingly, the "ro", "go", and "bo"
218	variables may be used in place of "co(R)", "co(G)", and "co(B)".
219	Finally, the total number of input files is set in the constant "nfiles".
220	.PP
221	Results are sent to the standard output.
222	By default, the values will be written in the lowest precision format
223	among the inputs, but the
224	.I \-f[adfc]
225	option may be used to explicitly output components
226	as ASCII (-fa), binary doubles (-fd), floats (-ff), or common-exponent
227	colors/spectra (-fc).
228	In the latter case, the actual matrix dimensions are written in the resolution string rather than the header.
229	Also, matrix results will be written as standard
230	Radiance pictures if they have either one
231	or three components.
232	In the one-component case, the output is written as grayscale.
233	If more than 3 components are in the final matrix and
234	.I -fc
235	is specified, the output will be a Radiance spectral picture.
236	.PP
237	The
238	.I \-h
239	option may be used to reduce the information header size, which
240	can grow disproportionately, otherwise.
241	The
242	.I \-w
243	option turns off warnings about divide-by-zero and other non-fatal
244	calculation errors.
245	.SH EXAMPLES
246	To convert two hyperspectral inputs to RGB color space,
247	average them together, and write them out as a RADIANCE picture:
248	.IP "" .2i
249	rmtxcomb -C RGB -s .5 img1.spc -s .5 img2.spc > avg.hdr
250	.PP
251	Divide one set of matrix elements by the Euclidean sum of two others:
252	.IP "" .2i
253	rmtxcomb -e "co=ci(1)/sqrt(ci(2)^2+ci(3)^2)" inp1.mtx
254	inp2.mtx inp3.mtx > out.mtx
255	.PP
256	Compute the absolute and relative differences between melanopic and photopic values
257	in a spectral image:
258	.IP "" .2i
259	rmtxcomb -fa -C MY -e "abs(x):if(x,x,-x)"
260	-e "co(p)=select(p,abs(ci(1,1)-ci(1,2)),(ci(1,1)-ci(1,2))/ci(1,2))"
261	input_spec.hsr > compare.mtx
262	.PP
263	Concatenate a spectral flux coefficient matrix with a spectral sky
264	matrix to compute a set of melanopic lux values:
265	.IP "" .2i
266	rmtxcomb view_spec.mtx -m sky_spec.mtx -c M > melux.mtx
267	.SH NOTES
268	The
269	.I rmtxcomb
270	tool was created to overcome some limitations of
271	.I rmtxop
272	and
273	.I pcomb,
274	whose capabilities somewhat overlap.
275	The former loads each matrix into memory before operations,
276	and element components take 8 bytes apiece, adding up quickly.
277	Very large matrices therefore present a problem with that tool.
278	Furthermore,
279	.I rmtxop
280	does not allow arbitrary expressions, limiting
281	what can be accomplished easily on the command-line.
282	In contrast,
283	.I pcomb
284	is fully programmable and operates on its input using a
285	scanline window, so it can handle much larger input dimensions.
286	It also handles single- and three-component float matrices on
287	input and output, but unlike
288	.I rmtxop,
289	.I pcomb
290	has not been extended to handle RADIANCE hyperspectral images
291	or more general matrix data.
292	.PP
293	The
294	.I rmtxcomb
295	tool is a compromise that exceeds the capabilities of either of
296	its predecessors in certain circumstances.
297	In particular, very large matrices may be combined using
298	arbitrary, user-defined operations, and the convenient
299	color conversions of
300	.I rmtxop
301	are supported for both input and output.
302	Finally, a single matrix may be concatenated after operations,
303	permitting a flux transfer matrix with millions of rows to
304	pass through.
305	Generally speaking,
306	.I rmtxcomb
307	should be preferred over
308	.I rmtxop
309	for any operations in can handle, which is everything except
310	multiple matrix concatenations and transpose
311	operations, which are handled more efficiently by
312	.I rcollate(1)
313	in any case.
314	That said, there is no significant difference for
315	simple operations on smallish matrices, and note that only
316	.I rmtxop
317	and
318	.I dctimestep(1)
319	currently accept XML files as inputs.
320	Also, the resizing function of
321	.I pcomb
322	is not supported in
323	.I rmtxcomb,
324	and should instead be handled by
325	.I pfilt(1).
326	.SH AUTHOR
327	Greg Ward
328	.SH "SEE ALSO"
329	dctimestep(1), icalc(1), getinfo(1), pcomb(1), pfilt(1),
330	ra_xyze(1), rcalc(1),
331	rcollate(1), rcontrib(1), rcrop(1), rfluxmtx(1),
332	rmtxop(1), rtpict(1), rtrace(1), vwrays(1)