man/man1/rmtxop.1

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