man/man1/rmtxop.1

.\" RCSid "$Id: rmtxop.1,v 1.1 2014/05/31 21:33:21 greg Exp $"
.TH RMTXOP 1 7/8/97 RADIANCE
.SH NAME
rmtxop - concatenate, add, transpose, scale, and convert matrices
.SH SYNOPSIS
.B rmtxop
[
.B \-v
][
.B \-f[afd]
][
.B \-t
][
.B "\-s sf .."
][
.B "\-c ce .."
]
.B m1
[
.B +
]
.B ".."
.SH DESCRIPTION
.I Rmtxop
loads and concatenates (multiplies) or adds 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
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.)\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
as 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 ('+') symbol,
in which case the elements are added together.
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, 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
Results are sent to the standard output.
By default, the values will be written in ASCII format, but the
.I \-f
option may be used to output components
as 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 [opertions]
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
cnt(1), histo(1), neaten(1), rcalc(1), rcollate(1),
rcontrib(1), rfluxmtx(1), rlam(1), tabfunc(1), total(1)
Revision:	1.2
Committed:	Tue Jul 22 21:55:31 2014 UTC (10 years, 9 months ago) by greg
Branch:	MAIN
CVS Tags:	rad4R2
Changes since 1.1:	+2 -2 lines
Log Message:	Created man page for rfluxmtx and added some error checks
#	User	Rev	Content
1	greg	1.2	.\" RCSid "$Id: rmtxop.1,v 1.1 2014/05/31 21:33:21 greg Exp $"
2	greg	1.1	.TH RMTXOP 1 7/8/97 RADIANCE
3			.SH NAME
4			rmtxop - concatenate, add, transpose, scale, and convert matrices
5			.SH SYNOPSIS
6			.B rmtxop
7			[
8			.B \-v
9			][
10			.B \-f[afd]
11			][
12			.B \-t
13			][
14			.B "\-s sf .."
15			][
16			.B "\-c ce .."
17			]
18			.B m1
19			[
20			.B +
21			]
22			.B ".."
23			.SH DESCRIPTION
24			.I Rmtxop
25			loads and concatenates (multiplies) or adds together component matrix files
26			given on the command line.
27			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			Two special cases are handled for component matrices that are either
46			XML files containing BTDF data, or Radiance picture files.
47			In the first case, a BSDF library is used to load and interpret the
48			transmission matrix.
49			(XML files cannot be read from the standard input.)\0
50			In the second case, the RGBE or XYZE values are loaded in a 3-component
51			matrix where the number of columns match the X-dimension of the picture, and
52			the number of rows match the Y-dimension.
53			The picture must be in standard pixel ordering, and the first row
54			as at the top with the first column on the left.
55			.PP
56			Before each file, the
57			.I \-t
58			and
59			.I \-s
60			or
61			.I \-c
62			options may be used to modify the matrix.
63			The
64			.I \-t
65			option transposes the matrix, swapping rows and columns.
66			The
67			.I \-s
68			option applies the given scalar factor(s) to the elements of the matrix.
69			If only one factor is provided,
70			it will be used for all components.
71			If multiple factors are given, their number must match the number of matrix
72			components.
73			Alternatively, the
74			.I \-c
75			option may be used to "transform" the element values, possibly changing
76			the number of components in the matrix.
77			For example, a 3-component matrix can be transformed into a single-component
78			matrix by using
79			.I \-c
80			with three coefficients.
81			A four-component matrix can be turned into a two-component matrix using 8
82			coefficients, where the first four coefficients will be used to compute
83			the first new component, and the second four coefficients
84			yield the second new component.
85			Note that the number of coefficients must be an even multiple of the number
86			of original components.
87			The
88			.I \-s
89			and
90			.I \-c
91			options are mutually exclusive, insofar as they cannot be applied together
92			to the same input matrix.
93			.PP
94			If present, the second and subsequent matrices on the command
95			line are concatenated to the result unless separated by a plus ('+') symbol,
96			in which case the elements are added together.
97			The number of components in the new matrix after applying any
98			.I -c
99			transform must agree with the prior result.
100			For concatenation (matrix multiplication), the number of columns
101			in the prior result must equal the number of rows in the new matrix, and
102			the result will have the number of rows of the previous and the number
103			of columns of the new matrix.
104			In the case of addition, the number of rows and columns of the prior
105			result and the new matrix must match, and will not be changed by the
106			operation.
107			.PP
108			Results are sent to the standard output.
109			By default, the values will be written in ASCII format, but the
110			.I \-f
111			option may be used to output components
112			as binary doubles (-fd), floats (-ff), or RGBE colors (-fc).
113			In the latter case, the actual matrix dimensions are written in the resolution
114			string rather than the header.
115			Also, matrix results written as Radiance pictures must have either one
116			or three components.
117			In the one-component case, the output is written as grayscale.
118			.PP
119			The
120			.I \-v
121			option turns on verbose reporting, which announces each operation.
122			.SH EXAMPLES
123			To concatenate two matrix files with a BTDF between them and write
124			the result as binary double:
125			.IP "" .2i
126			rmtxop -fd view.vmx blinds.xml exterior.dmx > dcoef.dmx
127			.PP
128			To convert a BTDF matrix into a Radiance picture:
129			.IP "" .2i
130			rmtxop -fc blinds.xml > blinds.hdr
131			.PP
132			To scale a matrix by 4 and add it to the transpose of another matrix:
133			.IP "" .2i
134			rmtxop -s 4 left.mtx + -t right.mtx > result.mtx
135			.PP
136			To send the elements of a binary matrix to
137			.I rcalc(1)
138			for further processing:
139			.IP "" .2i
140			rmtxop -fa orig.mtx \| rcollate -ho -oc 1 \| rcalc [opertions]
141			.SH AUTHOR
142			Greg Ward
143			.SH "SEE ALSO"
144			cnt(1), histo(1), neaten(1), rcalc(1), rcollate(1),
145	greg	1.2	rcontrib(1), rfluxmtx(1), rlam(1), tabfunc(1), total(1)