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

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines