man/man1/rmtxop.1

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