1Pamarith User Manual(0)                                Pamarith User Manual(0)
2
3
4

NAME

6       pamarith - perform arithmetic on two Netpbm images
7
8

SYNOPSIS

10       pamarith  -add | -subtract | -multiply | -divide | -difference | -mini‐
11       mum | -maximum | -mean | -equal | -compare | -and | -or | -nand |  -nor
12       | -xor | -shiftleft | -shiftright [-closeness=N] pamfile1 pamfile2 ...
13
14       All  options  can  be abbreviated to their shortest unique prefix.  You
15       may use two hyphens instead of one.  You may separate  an  option  name
16       and its value with white space instead of an equals sign.
17
18

DESCRIPTION

20       This program is part of Netpbm(1).
21
22       pamarith  reads  two or more PBM, PGM, PPM, or PAM images as input.  It
23       performs the specified binary arithmetic operation on their sample val‐
24       ues and produces an output of a format which is the more general of the
25       two input formats.  The two input images must be of the same width  and
26       height.   The  arithmetic  is  performed  on  each  pair of identically
27       located tuples to generate the identically located tuple of the output.
28
29       For functions that are commutative and associative, pamarith applies
30         the binary function repetitively on as many input images as you  sup‐
31       ply.  For
32         example, for -add , the output is the sum of all the inputs.  For
33         other functions (e.g. -subtract), the program fails if you supply
34         more  than  two  input images.  (Before Netpbm 10.93 (December 2020),
35       the
36         program always failed with more than two input images).
37
38       For some other functions, pamarith could theoretically compute a
39         meaningful result for multiple arguments, but it fails nonetheless if
40       you
41         give more than two input images.  -mean and -equal are in that
42         category.
43
44
45       Most of what pamarith does is not meaningful for visual images.  It
46         works  toward  Netpbm's  secondary purpose of just manipulating arbi‐
47       trary
48         matrices of numbers.
49
50
51       For the purpose of the calculation, it assumes any  PBM,  PGM,  or  PPM
52       input  image  is  the equivalent PAM image of tuple type BLACKANDWHITE,
53       GRAYSCALE, or RGB, respectively, and if it produces a PBM, PGM, or  PPM
54       output, produces the equivalent of the PAM image which is the result of
55       the calculation.
56
57       The first pamfile argument identifies the "left"  argument  image;  the
58       second pamfile argument identifies the "right" one.
59
60       If  the  output is PAM, the tuple type is the same as the tuple type of
61       the left input image.
62
63       pamarith performs the arithmetic on each pair  of  identically  located
64       tuples in the two input images.
65
66       The  arithmetic operation is in all cases fundamentally a function from
67       two integers to an integer (but see below - the functions  are  defined
68       in ways that you can effectively e.g. add real numbers).  The operation
69       is performed on two tuples as follows.  The two input images must  have
70       the  same depth, or one of them must have depth one.  pamarith fails if
71       one of these is not the case.
72
73       If they have the same depth, pamarith simply carries out the arithmetic
74       one  sample at a time.  I.e. if at a particular position the left input
75       image contains the tuple (s1,s2,...,sN) and the right input image  con‐
76       tains  the  tuple (t1,t2,...tN), and the function is f, then the output
77       image contains the tuple (f(s1,t1),f(s2,t2),...,f(sN,tN)).
78
79       If one of the images has depth 1, the arithmetic is  performed  between
80       the  one  sample  in  that  image and each of the samples in the other.
81       I.e. if at a particular position the  left  input  image  contains  the
82       tuple  (s)  and the right input image contains the tuple (t1,t2,...tN),
83       and the function is  f,  then  the  output  image  contains  the  tuple
84       (f(s,t1),f(s,t2),...,f(s,tN)).
85
86
87
88   PBM Oddness
89       If  you're familiar with the PBM format, you may find pamarith's opera‐
90       tion on PBM images to be nonintuitive.  Because in PBM black is  repre‐
91       sented as 1 and white as 0, you might be expecting black minus black to
92       be white.
93
94       But the PBM format is irrelevant, because pamarith operates on the num‐
95       bers found in the PAM equivalent (see above).  In a PAM black and white
96       image, black is 0 and white is 1.  So black minus black is black.
97
98
99
100   Maxval
101       The meanings of the samples with respect to the maxval varies according
102       to the function you select.
103
104       In  PAM  images in general, the most usual meaning of a sample (the one
105       that applies when a PAM image represents a visual image),  is  that  it
106       represents  a fraction of some maximum.  The maxval of the image corre‐
107       sponds to some maximum value (in the case of a visual image, it  corre‐
108       sponds  to "full intensity."), and a sample value divided by the maxval
109       gives the fraction.
110
111       For pamarith, this interpretation applies  to  the  regular  arithmetic
112       functions:  -add, -subtract, -multiply, -divide, -difference, -minimum,
113       -maximum, -mean, -equal, and -compare.  For those, you should think  of
114       the  arguments  and result as numbers in the range [0,1).  For example,
115       if the maxval of the left argument image is 100 and the maxval  of  the
116       right  argument image is 200 and the maxval of the output image is 200,
117       and the left sample value in an -add calculation is 50  and  the  right
118       sample  is 60, the actual calculation is 50/100 + 60/200 = 160/200, and
119       the output sample value is 160.
120
121       For these functions, pamarith makes the output image's maxval the maxi‐
122       mum  of  the  two input maxvals, except with -equal  and -compare.  For
123       -equal, the output maxval is always 1.  For -compare, it is  always  2.
124       (Before  Netpbm 10.14 (February 2003), there was no exception for -com‐
125       pare; in 10.14, the exception was just that the maxval was at least  2,
126       and  sometime  between  10.18  and  10.26 (January 2005), it changed to
127       being exactly 2).
128
129       If the result of a calculation falls outside the range [0, 1), pamarith
130       clips it -- i.e.  considers it to be zero or 1-.
131
132       In many cases, where both your input maxvals are the same, you can just
133       think of the operation  as  taking  place  between  the  sample  values
134       directly,  with no consideration of the maxval except for the clipping.
135       E.g. an -add of sample value 5 to sample value 8  yields  sample  value
136       13.
137
138       But  with -multiply, this doesn't work.  Say your two input images have
139       maxval 255, which means the output image also has maxval 255.  Consider
140       a  location  in  the  image where the input sample values are 5 and 10.
141       You might think the multiplicative product of those would yield  50  in
142       the  output.   But pamarith carries out the arithmetic on the fractions
143       5/255 and 10/255.  It multiplies those together and  then  rescales  to
144       the  output  maxval,  giving a sample value in the output PAM of 50/255
145       rounded to the nearest integer: 0.
146
147       With the bit string operations, the maxval has a whole different  mean‐
148       ing.  The operations in question are: -and, -or, -nand, -nor, -xor, and
149       -shiftleft, -shiftright.
150
151       With these, each sample value in one or both input images, and  in  the
152       output  image, represents a bit string, not a number.  The maxval tells
153       how wide the bit string is.  The maxval must be a full binary count  (a
154       power  of  two minus one, such as 0xff) and the number of ones in it is
155       the width of the bit string.  For  the  dyadic  bit  string  operations
156       (that's  everything  but the shift functions), the maxvals of the input
157       images must be the same and pamarith makes the  maxval  of  the  output
158       image the same.
159
160       For the bit shift operations, the output maxval is the same as the left
161       input maxval.  The right input image (which contains the shift  counts)
162       can  have any maxval and the maxval is irrelevant to the interpretation
163       of the samples.  The sample value is the actual shift count.  But  it's
164       still required that no sample value exceed the maxval.
165
166
167

NOTE: UNARY FUNCTIONS

169       pamarith  applies  only binary functions.  If you want to apply a unary
170       function, e.g. "halve", to a single image, use pamfunc.
171
172
173

OPTIONS

175       In addition to the options common to all programs  based  on  libnetpbm
176       (most notably -quiet, see
177        Common  Options  ⟨index.html#commonoptions⟩ ), pamarith recognizes the
178       following command line options:
179
180
181   The Function
182       These options select the function that pamarith applies.
183
184       You must specify one of these, and cannot specify more than one.
185
186
187
188
189       -add   Adds the two values.  If the result is larger than maxval, it is
190              clipped.
191
192
193       -subtract
194              Subtracts  a  value in the right input image from a value in the
195              left input image.
196
197
198       -minimum
199              Chooses the smaller value of the two.
200
201
202       -maximum
203              Chooses the larger value of the two.
204
205
206       -difference
207              Calculates the absolute value of the difference.
208
209
210       -multiply
211              Does an ordinary arithmetic multiplication, but tends to produce
212              nonobvious results because of the way pamarith interprets sample
213              values.  See Maxval ⟨#maxval⟩ .
214
215
216       -divide
217              Divides a value in the left input image  by  the  value  in  the
218              right  input  image.   But  like  -multiply, it tends to produce
219              nonobvious results.  Note that pamarith clipping behavior  makes
220              this  of little use when the left argument (dividend) is greater
221              than the right argument (divisor) -- the result in that case  is
222              always  the maxval.  If the divisor is 0, the result is the max‐
223              val.
224
225              -divide was new in Netpbm 10.30 (October 2005).
226
227
228       -equal Produces maxval when the values in the two images are equal  and
229              zero when they are not.  Note that the output maxval is always 1
230              for -equal.
231
232              If the maxvals of the input images are not  identical,  pamarith
233              may  claim  two  values  are  not  equal  when in fact they are,
234              because of the precision with  which  it  does  the  arithmetic.
235              However, it will never say A is greater than B if A is less than
236              B.
237
238              You can make the equality test approximate with  the  -closeness
239              option.   This  gives the percentage of maxval by which the sam‐
240              ples can differ and still be considered equal.
241
242              -equal was new in Netpbm 10.93 (December 2020).
243
244
245       -compare
246              Produces the value 0 when the value in the left input  image  is
247              less  than the value in the right input image, 1 when the values
248              are equal, and 2 when the left is greater than the right.
249
250              If the maxvals of the input images are not  identical,  pamarith
251              may  claim  two  values  are  not  equal  when in fact they are,
252              because of the precision with  which  it  does  the  arithmetic.
253              However, it will never say A is greater than B if A is less than
254              B.
255
256              -compare was new in Netpbm 10.13 (December 2002).
257
258
259       -and, -nand, -or, -nor, -xor
260              These consider the  input  and  output  images  to  contain  bit
261              strings;  they  compute  bitwise logic operations.  Note that if
262              the maxval is 1, you can also look at these as logic  operations
263              on  boolean input values.  See section Maxval ⟨#maxval⟩  for the
264              special meaning of maxval with respect to bit string  operations
265              such as these.
266
267
268       -shiftleft, -shiftright
269              These  consider the left input image and output image to contain
270              bit strings.  They compute a  bit  shift  operation,  with  bits
271              falling  off  the  left  or right end and zeroes shifting in, as
272              opposed to bits off one end to the other.  The right input image
273              sample value is the number of bit positions to shift.
274
275              Note  that  the  maxval  (see  Maxval ⟨#maxval⟩ ) determines the
276              width of the frame within which you are shifting.
277
278
279
280
281   Other
282       -closeness
283              This changes the meaning of -equal.  It is not  valid  with  any
284              other function.  See the description of -equal.
285
286
287
288

SEE ALSO

290       pamfunc(1),  pamsummcol(1),  pamsumm(1),  pnminvert(1), pambrighten(1),
291       ppmdim(1), pnmconvol(1), pamdepth(1), pnmpsnr(1), pnm(1), pam(1)
292
293
294

HISTORY

296       pamarith replaced pnmarith in Netpbm 10.3 (June 2002).
297
298       In Netpbm 10.3 through 10.8, though, pamarith was not backward compati‐
299       ble  because  it  required the input images to be of the same depth, so
300       you could not multiply a PBM by a PPM as is  often  done  for  masking.
301       (It  was  not  intended at the time that pnmarith would be removed from
302       Netpbm -- the plan was just to rewrite  it  to  use  pamarith;  it  was
303       removed by mistake).
304
305       But  starting  with  Netpbm  10.9 (September 2002), pamarith allows the
306       images to have different depths as long as one of them has depth 1, and
307       that made it backward compatible with pnmarith.
308
309       The original pnmarith did not have the -mean option.
310
311       The -compare option was added in Netpbm 10.13 (December 2002).
312
313       The bit string operations were added in Netpbm 10.27 (March 2005).
314
315       The -divide option was added in Netpbm 10.30 (October 2005).
316
317       The  ability  to have more than one input (operand) was added in Netpbm
318       10.93 (December 2020).
319
320       The -equal option was added in Netpbm 10.93 (December 2020).
321

DOCUMENT SOURCE

323       This manual page was generated by the Netpbm tool 'makeman'  from  HTML
324       source.  The master documentation is at
325
326              http://netpbm.sourceforge.net/doc/pamarith.html
327
328netpbm documentation            24 October 2020        Pamarith User Manual(0)
Impressum