man/man1/rmtxop.1

.\" RCSid "$Id: rmtxop.1,v 1.35 2025/03/27 01:26:55 greg Exp $"
.TH RMTXOP 1 5/31/2014 RADIANCE
.SH NAME
rmtxop - concatenate, add, multiply, divide, transpose, scale, and convert matrices
.SH SYNOPSIS
.B rmtxop
[
.B \-v
][
.B \-f[afdc]
][
.B "\-C {symbols|file}"
][
.B "\-c ce .."
][
.B "\-s sf .."
][
.B \-t
][
.B "\-rf|\-rb"
]
.B m1
[
.B ".+*/"
]
.B ".."
.SH DESCRIPTION
.I Rmtxop
loads and concatenates or adds/multiplies/divides
together component matrix files given on the command line.
Each 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
Two special cases are handled for component matrices that are either
XML files containing BSDF data, or Radiance picture files.
In the first case, the BSDF library loads and interprets the
transmission matrix by default.
Alternatively, the front (normal-side) reflectance is selected if the
.I \-rf
option precedes the file name, or the backside reflectance if
.I \-rb
is specified.
(XML files cannot be read from the standard input or from a command.)\0
In the second case, the RGBE or XYZE values are loaded in a 3-component
matrix where the number of columns match the X-dimension of the picture, and
the number of rows match the Y-dimension.
The picture must be in standard pixel ordering, and the first row
is at the top with the first column on the left.
Any exposure changes that were applied to the pictures before
.I rmtxop
will be undone, similar to the
.I pcomb(1)
.I \-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 \-t
and
.I \-c
and/or
.I \-s
options may be used to modify the matrix.
The
.I \-t
option transposes the matrix, swapping rows and columns.
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
If present, the second and subsequent matrices on the command
line are concatenated together, unless separated by a plus ('+'),
asterisk ('*'), or forward slash ('/') symbol,
in which case the individual matrix elements are added,
multiplied, or divided, respectively.
The concatenation operator ('.') is the default and need not be specified.
Note also that the asterisk must be quoted or escaped in most shells.
In the case of addition, the two matrices involved must have the same number
of components.
If subtraction is desired, use addition ('+') with a scaling parameter of -1
for the second matrix (the
.I \-s
option).
For element-wise multiplication and division, the second matrix is
permitted to have a single component per element, which will be
applied equally to all components of the first matrix.
If element-wise division is specified, any zero elements in the second
matrix will result in a warning and the corresponding component(s) in the
first matrix will be set to zero.
.PP
Evaluation proceeds from left to right, and all operations have
the same precedence.
If a different evaluation order is desired, pipe the result of one
.I rmtxop
command into another, as shown in one of the examples below.
.PP
The number of components in the next matrix after applying any
.I -c
transform must agree with the prior result.
For concatenation (matrix multiplication), the number of columns
in the prior result must equal the number of rows in the next matrix, and
the result will have the number of rows of the previous and the number
of columns of the next matrix.
In the case of addition, multiplication, and division,
the number of rows and columns of the prior result and the
next matrix must match, and will not be changed by the operation.
.PP
A final transpose or transform/scaling operation may be applied to
the results by appending the
.I \-t
and
.I \-c
and/or
.I \-s
options after the last matrix on the command line.
.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 \-v
option turns on verbose reporting, which announces each operation.
.SH EXAMPLES
To concatenate two matrix files with a BTDF between them and write
the result as binary float:
.IP "" .2i
rmtxop -ff view.vmx blinds.xml exterior.dmx > dcoef.dmx
.PP
To convert a BTDF matrix into a Radiance picture:
.IP "" .2i
rmtxop -fc blinds.xml > blinds.hdr
.PP
To extract the luminance values from a picture as an ASCII matrix:
.IP "" .2i
rmtxop -fa -c .265 .670 .065 image.hdr > image_lum.mtx
.PP
To render a melanopic illuminance image with
.I rtrace\:
.IP "" .2i
vwrays -ff -x 1024 -y 1024 -vf myview.vf |
rtrace -fff -cs 18 -co+ -i+ `vwrays -x 1024 -y 1024 -vf myview.vf -d` scene.oct |
rmtxop -fc -c M - > scene_meli.hdr
.PP
To scale a matrix by 4 and add it to the transpose of another matrix:
.IP "" .2i
rmtxop -s 4 first.mtx + -t second.mtx > result.mtx
.PP
To multiply elements of two matrices, then concatenate with a third,
applying a final transpose to the result:
.IP "" .2i
rmtxop first.mtx \\* second.mtx . third.mtx -t > result.mtx
.PP
To left-multiply the element-wise division of two matrices:
.IP "" .2i
rmtxop -fd numerator.mtx / denominator.mtx | rmtxop left.mtx - > result.mtx
.PP
To send the elements of a binary matrix to 
.I rcalc(1)
for further processing:
.IP "" .2i
rmtxop -fa orig.mtx | rcollate -ho -oc 1 | rcalc [operations]
.SH NOTES
Matrix concatenation is associative but not commutative, so order
matters to the result.
.I Rmtxop
takes advantage of this associative property to concatenate
from right to left when it reduces the number of basic operations.
If the rightmost matrix is a column vector for example, it is
much faster to concatenate from the right, and the result will
be the same.
Note that this only applies to concatenation;
element-wise addition, multiplication, and division are always
evaluated from left to right.
.PP
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 rmtxop
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"
cnt(1), dctimestep(1), getinfo(1), pcomb(1), pfilt(1),
pvsum(1), ra_xyze(1), rcalc(1),
rcollate(1), rcomb(1), rcontrib(1), rcrop(1), rfluxmtx(1),
rtpict(1), rtrace(1), vwrays(1), wrapBSDF(1)
Revision:	1.36
Committed:	Fri Apr 4 18:06:48 2025 UTC (4 weeks, 2 days ago) by greg
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.35:	+9 -3 lines
Log Message:	perf(rmtxop,rcomb): Switched default internal data type from double to float
#	Content
1	.\" RCSid "$Id: rmtxop.1,v 1.35 2025/03/27 01:26:55 greg Exp $"
2	.TH RMTXOP 1 5/31/2014 RADIANCE
3	.SH NAME
4	rmtxop - concatenate, add, multiply, divide, transpose, scale, and convert matrices
5	.SH SYNOPSIS
6	.B rmtxop
7	[
8	.B \-v
9	][
10	.B \-f[afdc]
11	][
12	.B "\-C {symbols\|file}"
13	][
14	.B "\-c ce .."
15	][
16	.B "\-s sf .."
17	][
18	.B \-t
19	][
20	.B "\-rf\|\-rb"
21	]
22	.B m1
23	[
24	.B ".+*/"
25	]
26	.B ".."
27	.SH DESCRIPTION
28	.I Rmtxop
29	loads and concatenates or adds/multiplies/divides
30	together component matrix files given on the command line.
31	Each file must have a header containing the following metadata:
32	.sp
33	.nf
34	NROWS={number of rows}
35	NCOLS={number of columns}
36	NCOMP={number of components}
37	FORMAT={ascii\|float\|double\|32-bit_rle_rgbe\|32-bit_rle_xyze\|Radiance_spectra}
38	.fi
39	.sp
40	The number of components indicates that each matrix element is actually
41	composed of multiple channels, most commonly an RGB triple.
42	This is essentially dividing the matrix into planes, where each component
43	participates in a separate calculation.
44	If an appropriate header is not present, it may be added with a call to
45	.I rcollate(1).
46	A matrix may be read from the standard input using a hyphen by itself ('-')
47	in the appropriate place on the command line.
48	Similarly, any of the inputs may be read from a command
49	instead of a file by
50	using quotes and a beginning exclamation point ('!').
51	.PP
52	Two special cases are handled for component matrices that are either
53	XML files containing BSDF data, or Radiance picture files.
54	In the first case, the BSDF library loads and interprets the
55	transmission matrix by default.
56	Alternatively, the front (normal-side) reflectance is selected if the
57	.I \-rf
58	option precedes the file name, or the backside reflectance if
59	.I \-rb
60	is specified.
61	(XML files cannot be read from the standard input or from a command.)\0
62	In the second case, the RGBE or XYZE values are loaded in a 3-component
63	matrix where the number of columns match the X-dimension of the picture, and
64	the number of rows match the Y-dimension.
65	The picture must be in standard pixel ordering, and the first row
66	is at the top with the first column on the left.
67	Any exposure changes that were applied to the pictures before
68	.I rmtxop
69	will be undone, similar to the
70	.I pcomb(1)
71	.I \-o
72	option.
73	Radiance spectral pictures with more than 3 components are also supported.
74	These are typically produced by
75	.I rtrace(1)
76	or
77	.I rfluxmtx(1).
78	.PP
79	Before each input, the
80	.I \-t
81	and
82	.I \-c
83	and/or
84	.I \-s
85	options may be used to modify the matrix.
86	The
87	.I \-t
88	option transposes the matrix, swapping rows and columns.
89	The
90	.I \-c
91	option can "transform" the element values, possibly changing
92	the number of components in the matrix.
93	For example, a 3-component matrix can be transformed into a single-component
94	matrix by using
95	.I \-c
96	with three coefficients.
97	A four-component matrix can be turned into a two-component matrix using 8
98	coefficients, where the first four coefficients will be used to compute
99	the first new component, and the second four coefficients
100	yield the second new component.
101	Note that the number of coefficients must be an even multiple of the number
102	of original components.
103	.PP
104	Alternatively, a set of symbolic output components may be given to the
105	.I \-c
106	option, with the following definitions:
107	.sp
108	.nf
109	R - red channel
110	G - green channel
111	B - blue channel
112	X - CIE X channel
113	Y - CIE Y channel (aka., luminance or illuminance)
114	Z - CIE Z channel
115	S - scotopic luminance or illuminance
116	M - melanopic luminance or illuminance
117	A - average component value
118	.fi
119	.sp
120	These letters may be given in any order as a single string, and if
121	.I "-c RGB"
122	or
123	.I "-c XYZ"
124	is specified for an input picture or the
125	.I "-fc"
126	option is given, the output will be written as a RGBE or XYZE picture.
127	Note that conversion from a float or RGBE color space applies a conversion
128	of 179 lumens/watt (for CIE or melanopic output) or 412 (for scotopic output),
129	and the reverse happens for conversion from XYZE input to RGB or RGBE output.
130	Lower case versions of all these components are also supported, the only
131	difference is that the aforementioned efficacy factors
132	will be left out of the conversion.
133	.PP
134	If a matrix or picture file path is given to the
135	.I \-c
136	option, then the color space of that file will be used, instead.
137	.PP
138	The
139	.I \-C
140	option takes either a symbolic color space or an input file, and will be
141	applied to all subsequent matrices that do not have their own associated
142	.I \-c
143	option.
144	.PP
145	Additionally, the
146	.I \-s
147	option applies the given scalar factor(s) to the elements of the matrix.
148	If only one factor is provided,
149	it will be used for all components.
150	If multiple factors are given, their number must match the number of matrix
151	components
152	.I after
153	application of any
154	.I \-c
155	option for this input matrix or picture, even if the
156	.I \-s
157	option appears first.
158	.PP
159	If present, the second and subsequent matrices on the command
160	line are concatenated together, unless separated by a plus ('+'),
161	asterisk ('*'), or forward slash ('/') symbol,
162	in which case the individual matrix elements are added,
163	multiplied, or divided, respectively.
164	The concatenation operator ('.') is the default and need not be specified.
165	Note also that the asterisk must be quoted or escaped in most shells.
166	In the case of addition, the two matrices involved must have the same number
167	of components.
168	If subtraction is desired, use addition ('+') with a scaling parameter of -1
169	for the second matrix (the
170	.I \-s
171	option).
172	For element-wise multiplication and division, the second matrix is
173	permitted to have a single component per element, which will be
174	applied equally to all components of the first matrix.
175	If element-wise division is specified, any zero elements in the second
176	matrix will result in a warning and the corresponding component(s) in the
177	first matrix will be set to zero.
178	.PP
179	Evaluation proceeds from left to right, and all operations have
180	the same precedence.
181	If a different evaluation order is desired, pipe the result of one
182	.I rmtxop
183	command into another, as shown in one of the examples below.
184	.PP
185	The number of components in the next matrix after applying any
186	.I -c
187	transform must agree with the prior result.
188	For concatenation (matrix multiplication), the number of columns
189	in the prior result must equal the number of rows in the next matrix, and
190	the result will have the number of rows of the previous and the number
191	of columns of the next matrix.
192	In the case of addition, multiplication, and division,
193	the number of rows and columns of the prior result and the
194	next matrix must match, and will not be changed by the operation.
195	.PP
196	A final transpose or transform/scaling operation may be applied to
197	the results by appending the
198	.I \-t
199	and
200	.I \-c
201	and/or
202	.I \-s
203	options after the last matrix on the command line.
204	.PP
205	Results are sent to the standard output.
206	By default, the values will be written in the lowest precision format
207	among the inputs, but the
208	.I \-f[adfc]
209	option may be used to explicitly output components
210	as ASCII (-fa), binary doubles (-fd), floats (-ff), or common-exponent
211	colors/spectra (-fc).
212	In the latter case, the actual matrix dimensions are written in
213	the resolution string rather than the header.
214	Also, matrix results will be written as standard
215	Radiance pictures if they have either one
216	or three components.
217	In the one-component case, the output is written as grayscale.
218	If more than 3 components are in the final matrix and
219	.I -fc
220	is specified, the output will be a Radiance spectral picture.
221	.PP
222	The
223	.I \-v
224	option turns on verbose reporting, which announces each operation.
225	.SH EXAMPLES
226	To concatenate two matrix files with a BTDF between them and write
227	the result as binary float:
228	.IP "" .2i
229	rmtxop -ff view.vmx blinds.xml exterior.dmx > dcoef.dmx
230	.PP
231	To convert a BTDF matrix into a Radiance picture:
232	.IP "" .2i
233	rmtxop -fc blinds.xml > blinds.hdr
234	.PP
235	To extract the luminance values from a picture as an ASCII matrix:
236	.IP "" .2i
237	rmtxop -fa -c .265 .670 .065 image.hdr > image_lum.mtx
238	.PP
239	To render a melanopic illuminance image with
240	.I rtrace\:
241	.IP "" .2i
242	vwrays -ff -x 1024 -y 1024 -vf myview.vf \|
243	rtrace -fff -cs 18 -co+ -i+ `vwrays -x 1024 -y 1024 -vf myview.vf -d` scene.oct \|
244	rmtxop -fc -c M - > scene_meli.hdr
245	.PP
246	To scale a matrix by 4 and add it to the transpose of another matrix:
247	.IP "" .2i
248	rmtxop -s 4 first.mtx + -t second.mtx > result.mtx
249	.PP
250	To multiply elements of two matrices, then concatenate with a third,
251	applying a final transpose to the result:
252	.IP "" .2i
253	rmtxop first.mtx \\* second.mtx . third.mtx -t > result.mtx
254	.PP
255	To left-multiply the element-wise division of two matrices:
256	.IP "" .2i
257	rmtxop -fd numerator.mtx / denominator.mtx \| rmtxop left.mtx - > result.mtx
258	.PP
259	To send the elements of a binary matrix to
260	.I rcalc(1)
261	for further processing:
262	.IP "" .2i
263	rmtxop -fa orig.mtx \| rcollate -ho -oc 1 \| rcalc [operations]
264	.SH NOTES
265	Matrix concatenation is associative but not commutative, so order
266	matters to the result.
267	.I Rmtxop
268	takes advantage of this associative property to concatenate
269	from right to left when it reduces the number of basic operations.
270	If the rightmost matrix is a column vector for example, it is
271	much faster to concatenate from the right, and the result will
272	be the same.
273	Note that this only applies to concatenation;
274	element-wise addition, multiplication, and division are always
275	evaluated from left to right.
276	.PP
277	All calculations are peformed internally using 32-bit floating-point,
278	so there is little benefit in either reading or writing 64-bit double
279	data.
280	This may be overridden at compile time using the macro
281	"-DDTrmx_native=DTdouble".
282	.SH BUGS
283	The
284	.I rmtxop
285	command currently ignores the "PRIMARIES" setting in input
286	headers, and does not produce any on output, even in
287	circumstances where it would make sense to.
288	.SH AUTHOR
289	Greg Ward
290	.SH "SEE ALSO"
291	cnt(1), dctimestep(1), getinfo(1), pcomb(1), pfilt(1),
292	pvsum(1), ra_xyze(1), rcalc(1),
293	rcollate(1), rcomb(1), rcontrib(1), rcrop(1), rfluxmtx(1),
294	rtpict(1), rtrace(1), vwrays(1), wrapBSDF(1)