man/man1/rmtxop.1

.\" RCSid "$Id: rmtxop.1,v 1.17 2019/09/10 17:58:20 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.
Any exposure changes applied to the pictures beforehand
.I rmtxop
will be undone, similar to the
.I pcomb\(1)
.I \-o
option.
.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 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 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 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 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), rcalc(1),
rcollate(1), rcontrib(1), rfluxmtx(1), rlam(1), 
rsplit(1), tabfunc(1), total(1), wrapBSDF(1)
Revision:	1.18
Committed:	Wed Mar 25 01:51:09 2020 UTC (5 years, 1 month ago) by greg
Branch:	MAIN
CVS Tags:	rad5R3
Changes since 1.17:	+9 -3 lines
Log Message:	Changed rmtxop and dctimestep to undo any exposure on Radiance input pictures
#	User	Rev	Content
1	greg	1.18	.\" RCSid "$Id: rmtxop.1,v 1.17 2019/09/10 17:58:20 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.18	Any exposure changes applied to the pictures beforehand
60			.I rmtxop
61			will be undone, similar to the
62			.I pcomb\(1)
63			.I \-o
64			option.
65	greg	1.1	.PP
66			Before each file, the
67			.I \-t
68			and
69			.I \-s
70			or
71			.I \-c
72			options may be used to modify the matrix.
73			The
74			.I \-t
75			option transposes the matrix, swapping rows and columns.
76			The
77			.I \-s
78			option applies the given scalar factor(s) to the elements of the matrix.
79			If only one factor is provided,
80			it will be used for all components.
81			If multiple factors are given, their number must match the number of matrix
82			components.
83			Alternatively, the
84			.I \-c
85			option may be used to "transform" the element values, possibly changing
86			the number of components in the matrix.
87			For example, a 3-component matrix can be transformed into a single-component
88			matrix by using
89			.I \-c
90			with three coefficients.
91			A four-component matrix can be turned into a two-component matrix using 8
92			coefficients, where the first four coefficients will be used to compute
93			the first new component, and the second four coefficients
94			yield the second new component.
95			Note that the number of coefficients must be an even multiple of the number
96			of original components.
97			The
98			.I \-s
99			and
100			.I \-c
101			options are mutually exclusive, insofar as they cannot be applied together
102			to the same input matrix.
103			.PP
104			If present, the second and subsequent matrices on the command
105	greg	1.16	line are concatenated together, unless separated by a plus ('+'),
106	greg	1.10	asterisk ('*'), or forward slash ('/') symbol,
107	greg	1.15	in which case the individual matrix elements are added,
108	greg	1.16	multiplied, or divided, respectively.
109			The concatenation operator ('.') is the default and need not be specified.
110			Note also that the asterisk must be quoted or escaped in most shells.
111	greg	1.10	In the case of addition, the two matrices involved must have the same number
112			of components.
113	greg	1.15	If subtraction is desired, use addition ('+') with a scaling parameter of -1
114			for the second matrix (the
115			.I \-s
116			option).
117	greg	1.11	For element-wise multiplication and division, the second matrix is
118	greg	1.15	permitted to have a single component per element, which will be
119	greg	1.11	applied equally to all components of the first matrix.
120	greg	1.10	If element-wise division is specified, any zero elements in the second
121			matrix will result in a warning and the corresponding component(s) in the
122			first matrix will be set to zero.
123			.PP
124	greg	1.16	Evaluation proceeds from left to right, and all operations have
125			the same precedence.
126			If a different evaluation order is desired, pipe the result of one
127			.I rmtxop
128			command into another, as shown in one of the examples below.
129			.PP
130	greg	1.17	The number of components in the next matrix after applying any
131	greg	1.1	.I -c
132			transform must agree with the prior result.
133			For concatenation (matrix multiplication), the number of columns
134	greg	1.17	in the prior result must equal the number of rows in the next matrix, and
135	greg	1.1	the result will have the number of rows of the previous and the number
136	greg	1.17	of columns of the next matrix.
137	greg	1.10	In the case of addition, multiplication, and division,
138			the number of rows and columns of the prior result and the
139	greg	1.17	next matrix must match, and will not be changed by the operation.
140	greg	1.1	.PP
141	greg	1.14	A final transpose or scaling/transform operation may be applied to
142			the results by appending the
143			.I \-t
144			and
145			.I \-s
146			or
147			.I \-c
148			options after the last matrix on the command line.
149			.PP
150	greg	1.1	Results are sent to the standard output.
151	greg	1.4	By default, the values will be written in the lowest resolution format
152	greg	1.6	among the inputs, but the
153	greg	1.1	.I \-f
154	greg	1.4	option may be used to explicitly output components
155			as ASCII (-fa), binary doubles (-fd), floats (-ff), or RGBE colors (-fc).
156	greg	1.1	In the latter case, the actual matrix dimensions are written in the resolution
157			string rather than the header.
158			Also, matrix results written as Radiance pictures must have either one
159			or three components.
160			In the one-component case, the output is written as grayscale.
161			.PP
162			The
163			.I \-v
164			option turns on verbose reporting, which announces each operation.
165			.SH EXAMPLES
166			To concatenate two matrix files with a BTDF between them and write
167			the result as binary double:
168			.IP "" .2i
169			rmtxop -fd view.vmx blinds.xml exterior.dmx > dcoef.dmx
170			.PP
171			To convert a BTDF matrix into a Radiance picture:
172			.IP "" .2i
173			rmtxop -fc blinds.xml > blinds.hdr
174			.PP
175	greg	1.16	To extract the luminance values from a picture as an ASCII matrix:
176			.IP "" .2i
177			rmtxop -fa -c .265 .670 .065 image.hdr > image_lum.mtx
178			.PP
179	greg	1.1	To scale a matrix by 4 and add it to the transpose of another matrix:
180			.IP "" .2i
181	greg	1.16	rmtxop -s 4 first.mtx + -t second.mtx > result.mtx
182			.PP
183			To multiply elements of two matrices, then concatenate with a third,
184			applying a final transpose to the result:
185			.IP "" .2i
186			rmtxop first.mtx \\* second.mtx . third.mtx -t > result.mtx
187	greg	1.1	.PP
188	greg	1.15	To left-multiply the element-wise division of two matrices:
189			.IP "" .2i
190			rmtxop -fd numerator.mtx / denominator.mtx \| rmtxop left.mtx - > result.mtx
191			.PP
192	greg	1.1	To send the elements of a binary matrix to
193			.I rcalc(1)
194			for further processing:
195			.IP "" .2i
196	greg	1.5	rmtxop -fa orig.mtx \| rcollate -ho -oc 1 \| rcalc [operations]
197	greg	1.13	.SH NOTES
198	greg	1.16	Matrix concatenation is associative but not commutative, so order
199	greg	1.13	matters to the result.
200			.I Rmtxop
201	greg	1.16	takes advantage of this associative property to concatenate
202			from right to left when it reduces the number of basic operations.
203	greg	1.13	If the rightmost matrix is a column vector for example, it is
204	greg	1.16	much faster to concatenate from the right, and the result will
205	greg	1.13	be the same.
206	greg	1.16	Note that this only applies to concatenation;
207			element-wise addition, multiplication, and division are always
208	greg	1.13	evaluated from left to right.
209	greg	1.1	.SH AUTHOR
210			Greg Ward
211			.SH "SEE ALSO"
212	greg	1.18	cnt(1), getinfo(1), histo(1), neaten(1), pcomb(1), rcalc(1),
213			rcollate(1), rcontrib(1), rfluxmtx(1), rlam(1),
214	greg	1.12	rsplit(1), tabfunc(1), total(1), wrapBSDF(1)