man/man1/rmtxop.1

.\" RCSid "$Id: rmtxop.1,v 1.13 2019/08/12 01:20:25 greg Exp $"
.TH RMTXOP 1 7/8/97 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 "\-s sf .."
][
.B "\-c ce .."
]
.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}
.sp
.fi
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 BTDF data, or Radiance picture files.
In the first case, a BSDF library is used to load and interpret the
transmission matrix.
(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.
.PP
Before each file, the
.I \-t
and
.I \-s
or
.I \-c
options may be used to modify the matrix.
The
.I \-t
option transposes the matrix, swapping rows and columns.
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.
Alternatively, the
.I \-c
option may be used to "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.
The
.I \-s
and
.I \-c
options are mutually exclusive, insofar as they cannot be applied together
to the same input matrix.
.PP
If present, the second and subsequent matrices on the command
line are concatenated to the result unless separated by a plus ('+'),
asterisk ('*'), or forward slash ('/') symbol,
in which case the matrix elements are added, multiplied, or divided together,
respectively.
(Note that the asterisk must be quoted or escaped in most shells.)\0
In the case of addition, the two matrices involved must have the same number
of components.
For element-wise multiplication and division, the second matrix is
permitted instead 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
The number of components in the new 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 new matrix, and
the result will have the number of rows of the previous and the number
of columns of the new matrix.
In the case of addition, multiplication, and division,
the number of rows and columns of the prior result and the
new matrix must match, and will not be changed by the operation.
.PP
A final transpose or scaling/transform operation may be applied to
the results by appending the
.I \-t
and
.I \-s
or
.I \-c
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 RGBE colors (-fc).
In the latter case, the actual matrix dimensions are written in the resolution
string rather than the header.
Also, matrix results written as Radiance pictures must have either one
or three components.
In the one-component case, the output is written as grayscale.
.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 scale a matrix by 4 and add it to the transpose of another matrix:
.IP "" .2i
rmtxop -s 4 left.mtx + -t right.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 multiplication is associative but not commutative, so order
matters to the result.
.I Rmtxop
takes advantage of the associative property to evaluate the
implicit equation from right to left when this 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 should
be the same.
This only applies to matrix multiplication.
Element-wise addition, multiplication, and division are still
evaluated from left to right.
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
cnt(1), getinfo(1), histo(1), neaten(1), rcalc(1), rcollate(1),
rcontrib(1), rfluxmtx(1), rlam(1), 
rsplit(1), tabfunc(1), total(1), wrapBSDF(1)
Revision:	1.14
Committed:	Mon Aug 12 02:26:46 2019 UTC (5 years, 9 months ago) by greg
Branch:	MAIN
Changes since 1.13:	+10 -1 lines
Log Message:	Added support for trailing unary operations on final matrix result
#	User	Rev	Content
1	greg	1.14	.\" RCSid "$Id: rmtxop.1,v 1.13 2019/08/12 01:20:25 greg Exp $"
2	greg	1.1	.TH RMTXOP 1 7/8/97 RADIANCE
3			.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			.B \-t
13			][
14			.B "\-s sf .."
15			][
16			.B "\-c ce .."
17			]
18			.B m1
19			[
20	greg	1.13	.B ".+*/"
21	greg	1.1	]
22			.B ".."
23			.SH DESCRIPTION
24			.I Rmtxop
25	greg	1.10	loads and concatenates or adds/multiplies/divides
26			together component matrix files given on the command line.
27	greg	1.1	Each file must have a header containing the following variables:
28			.sp
29			.nf
30			NROWS={number of rows}
31			NCOLS={number of columns}
32			NCOMP={number of components}
33			FORMAT={ascii\|float\|double\|32-bit_rle_rgbe\|32-bit_rle_xyze}
34			.sp
35			.fi
36			The number of components indicates that each matrix element is actually
37			composed of multiple elements, most commonly an RGB triple.
38			This is essentially dividing the matrix into planes, where each component
39			participates in a separate calculation.
40			If an appropriate header is not present, it may be added with a call to
41			.I rcollate(1).
42			A matrix may be read from the standard input using a hyphen by itself ('-')
43			in the appropriate place on the command line.
44			.PP
45	greg	1.9	Any of the matrix inputs may be read from a command
46			instead of a file by
47			using quotes and a beginning exclamation point ('!').
48			.PP
49	greg	1.1	Two special cases are handled for component matrices that are either
50			XML files containing BTDF data, or Radiance picture files.
51			In the first case, a BSDF library is used to load and interpret the
52			transmission matrix.
53	greg	1.9	(XML files cannot be read from the standard input or from a command.)\0
54	greg	1.1	In the second case, the RGBE or XYZE values are loaded in a 3-component
55			matrix where the number of columns match the X-dimension of the picture, and
56			the number of rows match the Y-dimension.
57			The picture must be in standard pixel ordering, and the first row
58	greg	1.7	is at the top with the first column on the left.
59	greg	1.1	.PP
60			Before each file, the
61			.I \-t
62			and
63			.I \-s
64			or
65			.I \-c
66			options may be used to modify the matrix.
67			The
68			.I \-t
69			option transposes the matrix, swapping rows and columns.
70			The
71			.I \-s
72			option applies the given scalar factor(s) to the elements of the matrix.
73			If only one factor is provided,
74			it will be used for all components.
75			If multiple factors are given, their number must match the number of matrix
76			components.
77			Alternatively, the
78			.I \-c
79			option may be used to "transform" the element values, possibly changing
80			the number of components in the matrix.
81			For example, a 3-component matrix can be transformed into a single-component
82			matrix by using
83			.I \-c
84			with three coefficients.
85			A four-component matrix can be turned into a two-component matrix using 8
86			coefficients, where the first four coefficients will be used to compute
87			the first new component, and the second four coefficients
88			yield the second new component.
89			Note that the number of coefficients must be an even multiple of the number
90			of original components.
91			The
92			.I \-s
93			and
94			.I \-c
95			options are mutually exclusive, insofar as they cannot be applied together
96			to the same input matrix.
97			.PP
98			If present, the second and subsequent matrices on the command
99	greg	1.10	line are concatenated to the result unless separated by a plus ('+'),
100			asterisk ('*'), or forward slash ('/') symbol,
101			in which case the matrix elements are added, multiplied, or divided together,
102			respectively.
103			(Note that the asterisk must be quoted or escaped in most shells.)\0
104			In the case of addition, the two matrices involved must have the same number
105			of components.
106	greg	1.11	For element-wise multiplication and division, the second matrix is
107			permitted instead to have a single component per element, which will be
108			applied equally to all components of the first matrix.
109	greg	1.10	If element-wise division is specified, any zero elements in the second
110			matrix will result in a warning and the corresponding component(s) in the
111			first matrix will be set to zero.
112			.PP
113	greg	1.1	The number of components in the new matrix after applying any
114			.I -c
115			transform must agree with the prior result.
116			For concatenation (matrix multiplication), the number of columns
117			in the prior result must equal the number of rows in the new matrix, and
118			the result will have the number of rows of the previous and the number
119			of columns of the new matrix.
120	greg	1.10	In the case of addition, multiplication, and division,
121			the number of rows and columns of the prior result and the
122			new matrix must match, and will not be changed by the operation.
123	greg	1.1	.PP
124	greg	1.14	A final transpose or scaling/transform operation may be applied to
125			the results by appending the
126			.I \-t
127			and
128			.I \-s
129			or
130			.I \-c
131			options after the last matrix on the command line.
132			.PP
133	greg	1.1	Results are sent to the standard output.
134	greg	1.4	By default, the values will be written in the lowest resolution format
135	greg	1.6	among the inputs, but the
136	greg	1.1	.I \-f
137	greg	1.4	option may be used to explicitly output components
138			as ASCII (-fa), binary doubles (-fd), floats (-ff), or RGBE colors (-fc).
139	greg	1.1	In the latter case, the actual matrix dimensions are written in the resolution
140			string rather than the header.
141			Also, matrix results written as Radiance pictures must have either one
142			or three components.
143			In the one-component case, the output is written as grayscale.
144			.PP
145			The
146			.I \-v
147			option turns on verbose reporting, which announces each operation.
148			.SH EXAMPLES
149			To concatenate two matrix files with a BTDF between them and write
150			the result as binary double:
151			.IP "" .2i
152			rmtxop -fd view.vmx blinds.xml exterior.dmx > dcoef.dmx
153			.PP
154			To convert a BTDF matrix into a Radiance picture:
155			.IP "" .2i
156			rmtxop -fc blinds.xml > blinds.hdr
157			.PP
158			To scale a matrix by 4 and add it to the transpose of another matrix:
159			.IP "" .2i
160			rmtxop -s 4 left.mtx + -t right.mtx > result.mtx
161			.PP
162			To send the elements of a binary matrix to
163			.I rcalc(1)
164			for further processing:
165			.IP "" .2i
166	greg	1.5	rmtxop -fa orig.mtx \| rcollate -ho -oc 1 \| rcalc [operations]
167	greg	1.13	.SH NOTES
168			Matrix multiplication is associative but not commutative, so order
169			matters to the result.
170			.I Rmtxop
171			takes advantage of the associative property to evaluate the
172			implicit equation from right to left when this reduces the
173			number of basic operations.
174			If the rightmost matrix is a column vector for example, it is
175			much faster to concatenate from the right, and the result should
176			be the same.
177			This only applies to matrix multiplication.
178			Element-wise addition, multiplication, and division are still
179			evaluated from left to right.
180	greg	1.1	.SH AUTHOR
181			Greg Ward
182			.SH "SEE ALSO"
183	greg	1.5	cnt(1), getinfo(1), histo(1), neaten(1), rcalc(1), rcollate(1),
184	greg	1.12	rcontrib(1), rfluxmtx(1), rlam(1),
185			rsplit(1), tabfunc(1), total(1), wrapBSDF(1)