ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/radiance/ray/doc/man/man1/rmtxop.1
(Generate patch)

Comparing ray/doc/man/man1/rmtxop.1 (file contents):
Revision 1.7 by greg, Fri Jan 23 01:03:17 2015 UTC vs.
Revision 1.25 by greg, Mon Nov 27 22:04:45 2023 UTC

# Line 1 | Line 1
1   .\" RCSid "$Id$"
2 < .TH RMTXOP 1 7/8/97 RADIANCE
2 > .TH RMTXOP 1 5/31/2014 RADIANCE
3   .SH NAME
4 < rmtxop - concatenate, add, transpose, scale, and convert matrices
4 > rmtxop - concatenate, add, multiply, divide, transpose, scale, and convert matrices
5   .SH SYNOPSIS
6   .B rmtxop
7   [
# Line 11 | Line 11 | rmtxop - concatenate, add, transpose, scale, and conve
11   ][
12   .B \-t
13   ][
14 + .B "\-c ce .."
15 + ][
16   .B "\-s sf .."
17   ][
18 < .B "\-c ce .."
18 > .B "\-rf|\-rb"
19   ]
20   .B m1
21   [
22 < .B +
22 > .B ".+*/"
23   ]
24   .B ".."
25   .SH DESCRIPTION
26   .I Rmtxop
27 < loads and concatenates (multiplies) or adds together component matrix files
28 < given on the command line.
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}
34 < .sp
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
# Line 42 | Line 44 | If an appropriate header is not present, it may be add
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 BTDF data, or Radiance picture files.
53 < In the first case, a BSDF library is used to load and interpret the
54 < transmission matrix.
55 < (XML files cannot be read from the standard input.)\0
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
59 – .I \-s
60 – or
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
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
89   .I \-c
90 < option may be used to "transform" the element values, possibly changing
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
# Line 84 | Line 99 | the first new component, and the second four coefficie
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 < The
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 < and
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 < options are mutually exclusive, insofar as they cannot be applied together
92 < to the same input matrix.
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 to the result unless separated by a plus ('+') symbol,
141 < in which case the elements are added together.
142 < The number of components in the new matrix after applying any
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 new matrix, and
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 new matrix.
172 < In the case of addition, the number of rows and columns of the prior
173 < result and the new matrix must match, and will not be changed by the
174 < operation.
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 RGBE colors (-fc).
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 written as Radiance pictures must have either one
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
# Line 130 | Line 212 | 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 left.mtx + -t right.mtx > result.mtx
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), rcalc(1), rcollate(1),
260 < rcontrib(1), rfluxmtx(1), rlam(1), tabfunc(1), total(1)
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)

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines