Debian Codegraph @

upstream/debian-unstable/man1/pamarith.1

raw
1 \
2 .\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
3 .\" Do not hand-hack it! If you have bug fixes or improvements, please find
4 .\" the corresponding HTML page on the Netpbm website, generate a patch
5 .\" against that, and send it to the Netpbm maintainer.
6 .TH "Pamarith User Manual" 1 "24 October 2020" "netpbm documentation"
7
8 .SH NAME
9 pamarith - perform arithmetic on two Netpbm images
10
11 .UN synopsis
12 .SH SYNOPSIS
13
14 \fBpamarith\fP
15 \fB-add\fP | \fB-subtract\fP | \fB-multiply\fP | \fB-divide\fP |
16 \fB-difference\fP |
17 \fB-minimum\fP | \fB-maximum\fP | \fB-mean\fP |
18 \fB-equal\fP | \fB-compare\fP |
19 \fB-and\fP | \fB-or\fP | \fB-nand\fP | \fB-nor\fP | \fB-xor\fP |
20 \fB-shiftleft\fP | \fB-shiftright\fP
21 [\fB-closeness=\fP\fIN\fP]
22 \fIpamfile1\fP \fIpamfile2\fP ...
23 .PP
24 All options can be abbreviated to their shortest unique prefix.
25 You may use two hyphens instead of one. You may separate an option
26 name and its value with white space instead of an equals sign.
27
28 .UN description
29 .SH DESCRIPTION
30 .PP
31 This program is part of
32 .BR "Netpbm" (1)\c
33 \&.
34 .PP
35 \fBpamarith\fP reads two or more PBM, PGM, PPM, or PAM images as input.
36 It performs the specified binary arithmetic operation on their sample
37 values and produces an output of a format which is the more general of
38 the two input formats. The two input images must be of the same width
39 and height. The arithmetic is performed on each pair of identically
40 located tuples to generate the identically located tuple of the
41 output.
42 .PP
43 For functions that are commutative and associative, \fBpamarith\fP applies
44 the binary function repetitively on as many input images as you supply. For
45 example, for \fB-add\fP , the output is the sum of all the inputs. For
46 other functions (e.g. \fB-subtract\fP), the program fails if you supply
47 more than two input images. (Before Netpbm 10.93 (December 2020), the
48 program always failed with more than two input images).
49 .PP
50 For some other functions, \fBpamarith\fP could theoretically compute a
51 meaningful result for multiple arguments, but it fails nonetheless if you
52 give more than two input images. \fB-mean\fP and \fB-equal\fP are in that
53 category.
54
55 .PP
56 Most of what \fBpamarith\fP does is not meaningful for visual images. It
57 works toward Netpbm's secondary purpose of just manipulating arbitrary
58 matrices of numbers.
59
60 .PP
61 For the purpose of the calculation, it assumes any PBM, PGM, or PPM
62 input image is the equivalent PAM image of tuple type
63 \fBBLACKANDWHITE\fP, \fBGRAYSCALE\fP, or \fBRGB\fP, respectively,
64 and if it produces a PBM, PGM, or PPM output, produces the equivalent
65 of the PAM image which is the result of the calculation.
66 .PP
67 The first \fIpamfile\fP argument identifies the "left"
68 argument image; the second \fIpamfile\fP argument identifies the
69 "right" one.
70 .PP
71 If the output is PAM, the tuple type is the same as the tuple type of
72 the left input image.
73 .PP
74 \fBpamarith\fP performs the arithmetic on each pair of identically
75 located tuples in the two input images.
76 .PP
77 The arithmetic operation is in all cases fundamentally a function from two
78 integers to an integer (but see below - the functions are defined in ways that
79 you can effectively e.g. add real numbers). The operation is performed on two
80 tuples as follows. The two input images must have the same depth, or one of
81 them must have depth one. \fBpamarith\fP fails if one of these is not the
82 case.
83 .PP
84 If they have the same depth, \fBpamarith\fP simply carries out the
85 arithmetic one sample at a time. I.e. if at a particular position the
86 left input image contains the tuple (s1,s2,...,sN) and the right
87 input image contains the tuple (t1,t2,...tN), and the function is f,
88 then the output image contains the tuple
89 (f(s1,t1),f(s2,t2),...,f(sN,tN)).
90 .PP
91 If one of the images has depth 1, the arithmetic is performed
92 between the one sample in that image and each of the samples in the
93 other. I.e. if at a particular position the left input image
94 contains the tuple (s) and the right input image contains the tuple
95 (t1,t2,...tN), and the function is f, then the output image contains
96 the tuple (f(s,t1),f(s,t2),...,f(s,tN)).
97
98
99 .UN pbmoddness
100 .SS PBM Oddness
101 .PP
102 If you're familiar with the PBM format, you may find \fBpamarith\fP's
103 operation on PBM images to be nonintuitive. Because in PBM black is
104 represented as 1 and white as 0, you might be expecting black minus black
105 to be white.
106 .PP
107 But the PBM format is irrelevant, because \fBpamarith\fP operates on the
108 numbers found in the PAM equivalent (see above). In a PAM black and white
109 image, black is 0 and white is 1. So black minus black is black.
110
111
112 .UN maxval
113 .SS Maxval
114 .PP
115 The meanings of the samples with respect to the maxval varies
116 according to the function you select.
117 .PP
118 In PAM images in general, the most usual meaning of a sample (the
119 one that applies when a PAM image represents a visual image), is that
120 it represents a fraction of some maximum. The maxval of the image
121 corresponds to some maximum value (in the case of a visual image, it
122 corresponds to "full intensity."), and a sample value
123 divided by the maxval gives the fraction.
124 .PP
125 For \fBpamarith\fP, this interpretation applies to the regular
126 arithmetic functions: \fB-add\fP, \fB-subtract\fP, \fB-multiply\fP,
127 \fB-divide\fP,
128 \fB-difference\fP, \fB-minimum\fP, \fB-maximum\fP, \fB-mean\fP,
129 \fB-equal\fP,
130 and \fB-compare\fP. For those, you should think of the arguments and
131 result as numbers in the range [0,1). For example, if the maxval of
132 the left argument image is 100 and the maxval of the right argument
133 image is 200 and the maxval of the output image is 200, and the left
134 sample value in an \fB-add\fP calculation is 50 and the right sample
135 is 60, the actual calculation is 50/100 + 60/200 = 160/200, and
136 the output sample value is 160.
137 .PP
138 For these functions, \fBpamarith\fP makes the output image's
139 maxval the maximum of the two input maxvals, except with
140 \fB-equal \fP and \fB-compare\fP. For \fB-equal\fP, the output maxval is
141 always 1. For \fB-compare\fP, it is always 2. (Before Netpbm 10.14
142 (February 2003), there was no exception for \fB-compare\fP; in 10.14, the
143 exception was just that the maxval was \fIat least\fP 2, and sometime
144 between 10.18 and 10.26 (January 2005), it changed to being exactly 2).
145 .PP
146 If the result of a calculation falls outside the range [0, 1),
147 \fBpamarith\fP clips it -- i.e. considers it to be zero or 1-.
148 .PP
149 In many cases, where both your input maxvals are the same, you can
150 just think of the operation as taking place between the sample values
151 directly, with no consideration of the maxval except for the clipping.
152 E.g. an \fB-add\fP of sample value 5 to sample value 8 yields sample
153 value 13.
154 .PP
155 But with \fB-multiply\fP, this doesn't work. Say your two input
156 images have maxval 255, which means the output image also has maxval
157 255. Consider a location in the image where the input sample values
158 are 5 and 10. You might think the multiplicative product of those
159 would yield 50 in the output. But \fBpamarith\fP carries out the
160 arithmetic on the fractions 5/255 and 10/255. It multiplies those
161 together and then rescales to the output maxval, giving a sample value
162 in the output PAM of 50/255 rounded to the nearest integer: 0.
163 .PP
164 With the bit string operations, the maxval has a whole different
165 meaning. The operations in question are: \fB-and\fP, \fB-or\fP,
166 \fB-nand\fP, \fB-nor\fP, \fB-xor\fP, and \fB-shiftleft\fP,
167 \fB-shiftright\fP.
168 .PP
169 With these, each sample value in one or both input images, and in
170 the output image, represents a bit string, not a number. The maxval
171 tells how wide the bit string is. The maxval must be a full binary
172 count (a power of two minus one, such as 0xff) and the number of ones
173 in it is the width of the bit string. For the dyadic bit string
174 operations (that's everything but the shift functions), the maxvals of
175 the input images must be the same and \fBpamarith\fP makes the maxval
176 of the output image the same.
177 .PP
178 For the bit shift operations, the output maxval is the same as the
179 left input maxval. The right input image (which contains the shift
180 counts) can have any maxval and the maxval is irrelevant to the
181 interpretation of the samples. The sample value is the actual shift
182 count. But it's still required that no sample value exceed the
183 maxval.
184
185
186 .UN note
187 .SH NOTE: UNARY FUNCTIONS
188 .PP
189 \fBpamarith\fP applies only binary functions. If you want to apply a
190 unary function, e.g. "halve", to a single image, use \fBpamfunc\fP.
191
192
193 .UN options
194 .SH OPTIONS
195 .PP
196 In addition to the options common to all programs based on libnetpbm
197 (most notably \fB-quiet\fP, see
198 .UR index.html#commonoptions
199 Common Options
200 .UE
201 \&), \fBpamarith\fP recognizes the following
202 command line options:
203
204 .UN function
205 .SS The Function
206 .PP
207 These options select the function that \fBpamarith\fP applies.
208 .PP
209 You must specify one of these, and cannot specify more than one.
210
211
212
213 .TP
214 \fB-add\fP
215 Adds the two values. If the result is larger than maxval, it is
216 clipped.
217
218 .TP
219 \fB-subtract\fP
220 Subtracts a value in the right input image from a value in the left input
221 image.
222
223 .TP
224 \fB-minimum\fP
225 Chooses the smaller value of the two.
226
227 .TP
228 \fB-maximum\fP
229 Chooses the larger value of the two.
230
231 .TP
232 \fB-difference\fP
233 Calculates the absolute value of the difference.
234
235 .TP
236 \fB-multiply\fP
237 Does an ordinary arithmetic multiplication, but tends to produce
238 nonobvious results because of the way \fBpamarith\fP interprets
239 sample values. See
240 .UR #maxval
241 Maxval
242 .UE
243 \&.
244
245 .TP
246 \fB-divide\fP
247 Divides a value in the left input image by the value in the right
248 input image. But like \fB-multiply\fP, it tends to produce nonobvious
249 results. Note that \fBpamarith\fP clipping behavior makes this of
250 little use when the left argument (dividend) is greater than the right
251 argument (divisor) -- the result in that case is always the maxval.
252 If the divisor is 0, the result is the maxval.
253 .sp
254 \fB-divide\fP was new in Netpbm 10.30 (October 2005).
255
256 .TP
257 \fB-equal\fP
258 Produces maxval when the values in the two images are equal and
259 zero when they are not. Note that the output maxval is always 1 for
260 \fB-equal\fP.
261 .sp
262 If the maxvals of the input images are not identical, \fBpamarith\fP may
263 claim two values are not equal when in fact they are, because of the precision
264 with which it does the arithmetic.
265 .sp
266 You can make the equality test approximate with the \fB-closeness\fP
267 option. This gives the percentage of maxval by which the samples can
268 differ and still be considered equal.
269 .sp
270 \fB-equal\fP was new in Netpbm 10.93 (December 2020).
271
272 .TP
273 \fB-compare\fP
274 Produces the value \fB0\fP when the value in the
275 left input image is less than the value in the right input image,
276 \fB1\fP when the values are equal, and \fB2\fP when the left is
277 greater than the right.
278 .sp
279 If the maxvals of the input images are not identical, \fBpamarith\fP
280 may claim two values are not equal when in fact they are, because of
281 the precision with which it does the arithmetic. However, it will never
282 say A is greater than B if A is less than B.
283 .sp
284 \fB-compare\fP was new in Netpbm 10.13 (December 2002).
285
286 .TP
287 \fB-and\fP, \fB-nand\fP, \fB-or\fP, \fB-nor\fP, \fB-xor\fP
288 These consider the input and output images to contain bit strings;
289 they compute bitwise logic operations. Note that if the maxval is 1,
290 you can also look at these as logic operations on boolean input values.
291 See section
292 .UR #maxval
293 Maxval
294 .UE
295 \& for the special meaning of
296 maxval with respect to bit string operations such as these.
297
298 .TP
299 \fB-shiftleft\fP, \fB-shiftright\fP
300 These consider the left input image and output image to contain
301 bit strings. They compute a bit shift operation, with bits falling
302 off the left or right end and zeroes shifting in, as opposed to bits
303 off one end to the other. The right input image sample value is the
304 number of bit positions to shift.
305 .sp
306 Note that the maxval (see
307 .UR #maxval
308 Maxval
309 .UE
310 \&) determines
311 the width of the frame within which you are shifting.
312
313
314
315 .UN otheroptions
316 .SS Other
317
318
319
320 .TP
321 \fB-closeness\fP
322 This changes the meaning of \fB-equal\fP. It is not valid with any
323 other function. See the description of \fB-equal\fP.
324
325
326
327 .UN seealso
328 .SH SEE ALSO
329 .BR "\fBpamfunc\fP" (1)\c
330 \&,
331 .BR "\fBpamsummcol\fP" (1)\c
332 \&,
333 .BR "\fBpamsumm\fP" (1)\c
334 \&,
335 .BR "\fBpnminvert\fP" (1)\c
336 \&,
337 .BR "\fBpambrighten\fP" (1)\c
338 \&,
339 .BR "\fBppmdim\fP" (1)\c
340 \&,
341 .BR "\fBpnmconvol\fP" (1)\c
342 \&,
343 .BR "\fBpamdepth\fP" (1)\c
344 \&,
345 .BR "\fBpnmpsnr\fP" (1)\c
346 \&,
347 .BR "\fBpnm\fP" (1)\c
348 \&,
349 .BR "\fBpam\fP" (1)\c
350 \&
351
352
353 .UN history
354 .SH HISTORY
355 .PP
356 \fBpamarith\fP replaced \fBpnmarith\fP in Netpbm 10.3 (June 2002).
357 .PP
358 In Netpbm 10.3 through 10.8, though, \fBpamarith\fP was not
359 backward compatible because it required the input images to be of the
360 same depth, so you could not multiply a PBM by a PPM as is often done
361 for masking. (It was not intended at the time that \fBpnmarith\fP
362 would be removed from Netpbm -- the plan was just to rewrite it to use
363 \fBpamarith\fP; it was removed by mistake).
364 .PP
365 But starting with Netpbm 10.9 (September 2002), \fBpamarith\fP allows
366 the images to have different depths as long as one of them has depth 1, and
367 that made it backward compatible with \fBpnmarith\fP.
368 .PP
369 The original \fBpnmarith\fP did not have the \fB-mean\fP option.
370 .PP
371 The \fB-compare\fP option was added in Netpbm 10.13 (December 2002).
372 .PP
373 The bit string operations were added in Netpbm 10.27 (March 2005).
374 .PP
375 The \fB-divide\fP option was added in Netpbm 10.30 (October 2005).
376 .PP
377 The ability to have more than one input (operand) was added in Netpbm
378 10.93 (December 2020).
379 .PP
380 The \fB-equal\fP option was added in Netpbm 10.93 (December 2020).
381 .SH DOCUMENT SOURCE
382 This manual page was generated by the Netpbm tool 'makeman' from HTML
383 source. The master documentation is at
384 .IP
385 .B http://netpbm.sourceforge.net/doc/pamarith.html
386 .PP