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

NAME

6       pamfunc - Apply a simple monadic arithmetic function to a Netpbm image
7
8

SYNOPSIS

10       pamfunc  {  -multiplier=realnum  |  -divisor=realnum | -adder=integer |
11       -subtractor=integer | -min=wholenum  |  -max=wholenum  -andmask=hexmask
12       -ormask=hexmask       -xormask=hexmask       -not      -shiftleft=count
13       -shiftright=count [-changemaxval] } [filespec]
14
15       All options can be abbreviated to their shortest  unique  prefix.   You
16       may  use  two  hyphens instead of one.  You may separate an option name
17       and its value with white space instead of an equals sign.
18
19

DESCRIPTION

21       This program is part of Netpbm(1).
22
23       pamfunc reads a Netpbm image as input and produces a  Netpbm  image  as
24       output,  with  the  same  format, and dimensions as the input.  pamfunc
25       applies a simple transfer function to each sample in the input to  gen‐
26       erate  the  corresponding  sample in the output.  The options determine
27       what function.
28
29       pamarith is the same thing for binary functions -- it takes two  images
30       as input and applies a specified simple arithmetic function (e.g. addi‐
31       tion) on pairs of samples from the two to  produce  the  single  output
32       image.
33
34
35
36   Values
37       The functions fall into two categories: arithmetic (such as multiply by
38       5) and bit string (such as and  with  01001000).   For  the  arithmetic
39       functions,  the  function arguments and results are the fraction that a
40       sample is of the maxval, i.e. normal interpretation of PAM tuples.  But
41       for  the  bit string functions, the value is the bit string whose value
42       as a binary cipher is the sample value, and the  maxval  indicates  the
43       width of the bit string.
44
45       Arithmetic functions
46
47       The arithmetic functions are those selected by the options -multiplier,
48       -divisor, -adder, -subtractor, -min, and -max.
49
50       As an example, consider an image with maxval 100 and a sample value  of
51       10  and  a function of "multiply by 5." The argument to the function is
52       10/100 (0.1) and the result is 5 * 0.1 = 0.5.  In  the  simplest  case,
53       the maxval of the output is also 100, so the output sample value is 0.5
54       * 100 = 50.  As you can see, we could just talk about the sample values
55       themselves instead of these fractions and get the same result (10 * 5 =
56       50), but we don't.
57
58       Where it makes a practical difference whether we consider the values to
59       be  the  fraction of the maxval or the sample value alone is where pam‐
60       func uses a different maxval in the output image than it finds  in  the
61       input image.  See -changemaxval.
62
63       So  remember  in reading the descriptions below that the values are 0.1
64       and 0.5 in this example, not 10 and 50.  All arguments and results  are
65       in the range [0,1].
66
67       Bit string functions
68
69       The  bit  string  functions are those selected by the options -andmask,
70       -ormask, -xormask, -not, -shiftleft, and -shiftright.
71
72       With these functions, the maxval has a very different meaning  than  in
73       normal  Netpbm images: it tells how wide (how many bits) the bit string
74       is.  The maxval must be a full binary count (a power of two minus  one,
75       such  as  0xff)  and  the  number of ones in it is the width of the bit
76       string.
77
78       As an example, consider an image with maxval 15 and a sample value of 5
79       and  a  function  of  "and with 0100".  The argument to the function is
80       0101 and the result is 0100.
81
82       In this example, it doesn't make any practical difference what we  con‐
83       sider  the  width of the string to be, as long as it is at least 3.  If
84       the maxval were 255, the result would be the  same.   But  with  a  bit
85       shift operation, it matters.  Consider shifting left by 2 bits.  In the
86       example, where the input value is 0101, the result is 0100.  But if the
87       maxval were 255, the result would be 00010100.
88
89       For  a  masking function, the mask value you specify must not have more
90       significant bits than the width indicated by the maxval.
91
92       For a shifting operation, the shift  count  you  specify  must  not  be
93       greater than the width indicated by the maxval.
94
95
96

OPTIONS

98       -multiplier=realnum
99
100              This option makes the transfer function that of multiplying by
101                   realnum.  realnum must be nonnegative.  If the result
102                   is greater than one, it is clipped to one.
103
104              Where the input is a PGM or PPM image, this has the effect of
105                   dimming or brightening it.  For a different kind of bright‐
106              ening,
107                   see pambrighten(1) and ppmflash(1)
108
109              Also, see ppmdim(1), which does the same
110                   thing as pamfunc -multiplier on a PPM image with  a  multi‐
111              plier
112                   between zero and one, except it uses integer arithmetic, so
113              it may be
114                   faster.
115
116              And ppmfade(1) can generate a whole
117                   sequence of images of  brightness  declining  to  black  or
118              increasing to
119                   white, if that's what you want.
120
121
122       -divisor=realnum
123
124              This option makes the transfer function that of dividing by
125                   realnum.  realnum must be nonnegative.  If the result
126                   is greater than one, it is clipped to one.
127
128              This is the same function as you would get with -multiplier,
129                   specifying the multiplicative inverse of realnum.
130
131
132       -adder=integer
133
134              This option makes the transfer function that of adding
135                   integer/maxval.  If the result is greater than one, it is
136                   clipped  to one.  If it is less than zero, it is clipped to
137              zero.
138
139              Note that in mathematics, this entity is called an "addend,"
140                   and an "adder" is a snake.  We use "adder" because
141                   it makes more sense.
142
143
144       -subtractor=integer
145
146              This option makes the transfer function that of subtracting
147                   integer/maxval.  If the result is greater than one, it is
148                   clipped to one.  If it is less than zero, it is clipped  to
149              zero.
150
151              Note that in mathematics, this entity is called a
152                   "subtrahend" rather than a "subtractor." We use
153                   "subtractor" because it makes more sense.
154
155              This is the same function as you would get with -adder,
156                   specifying the negative of integer.
157
158
159       -min=wholenum
160
161              This option makes the transfer function that of taking the maxi‐
162              mum of
163                   the argument and wholenum/maxval.  I.e the minimum value in
164                   the output will be wholenum/maxval.
165
166                   If wholenum/maxval is greater than one, though, every value
167                   in the output will be one.
168
169
170       -max=wholenum
171
172              This option makes the transfer function that of taking the mini‐
173              mum of
174                   the argument and wholenum/maxval.  I.e the maximum value in
175                   the output will be wholenum/maxval.
176
177                   If wholenum/maxval is greater than one, the function is
178                   idempotent -- the output is identical to the input.
179
180
181       -andmask=hexmask
182
183              This option makes the transfer function that of bitwise anding
184                   with hexmask.
185
186              hexmask is in hexadecimal.  Example: 0f
187
188              This option was new in Netpbm 10.40 (September 2007).
189
190
191       -ormask=hexmask
192
193              This option makes the transfer function that of bitwise
194                   inclusive oring with hexmask.
195
196              This is analogous to -andmask.
197
198              This option was new in Netpbm 10.40 (September 2007).
199
200
201       -xormask=hexmask
202
203              This option makes the transfer function that of bitwise
204                   exclusive oring with hexmask.
205
206              This is analogous to -andmask.
207
208              This option was new in Netpbm 10.40 (September 2007).
209
210
211       -not
212
213              This option makes the transfer function that of bitwise logical
214                   inversion (e.g. sample value 0xAA becomes 0x55).
215
216              pnminvert does the same thing for a bilevel visual image
217                   which has maxval 1 or is of PBM type.
218
219              This option was new in Netpbm 10.40 (September 2007).
220
221
222       -shiftleft=count
223
224              This option makes the transfer function that of bitwise shifting
225                   left by count bits.
226
227              This option was new in Netpbm 10.40 (September 2007).
228
229
230       -shiftright=count
231
232              This option makes the transfer function that of bitwise shifting
233                   right by count bits.
234
235              This is analogous to -shiftleft.
236
237              This option was new in Netpbm 10.40 (September 2007).
238
239
240       -changemaxval
241
242              This  option tells pamfunc to use a different maxval in the out‐
243              put image than the maxval of the input image, if it  helps.   By
244              default,  the  maxval  of the output is unchanged from the input
245              and pamfunc modifies the sample values as necessary  to  perform
246              the operation.
247
248              But  there is one case where pamfunc can achieve the same result
249              just by changing  the  maxval  and  leaving  the  sample  values
250              unchanged:  dividing by a number 1 or greater, or multiplying by
251              a number 1 or less.  For example, to halve all  of  the  values,
252              pamfunc can just double the maxval.
253
254              With -changemaxval, pamfunc will do just that.
255
256              As  the Netpbm formats have a maximum maxval of 65535, for large
257              divisors, pamfunc may not be able to use this method.
258
259              An advantage of dividing by changing  the  maxval  is  that  you
260              don't lose precision.  The higher maxval means higher precision.
261              For example, consider an image with a maxval of 100  and  sample
262              value  of  10.   You divide by 21 and then multiply by 21 again.
263              If pamfunc does this by changing the sample values while retain‐
264              ing  maxval 100, the division will result in a sample value of 0
265              and the multiplication will also result in zero.  But if pamfunc
266              instead  keeps  the  sample value 10 and changes the maxval, the
267              division will result in a maxval of 2100 and the  multiplication
268              will change it back to 100, and the round trip is idempotent.
269
270              This option was new in Netpbm 10.65 (December 2013).
271
272
273
274
275

SEE ALSO

277       ppmdim(1),  pambrighten(1),  pamdepth(1),  pamarith(1),  pamsummcol(1),
278       pamsumm(1), ppmfade(1), pnminvert(1), pam(1), pnm(1),
279
280

HISTORY

282       This program was added to Netpbm in Release 10.3 (June 2002).
283

DOCUMENT SOURCE

285       This manual page was generated by the Netpbm tool 'makeman'  from  HTML
286       source.  The master documentation is at
287
288              http://netpbm.sourceforge.net/doc/pamfunc.html
289
290netpbm documentation             December 2013          Pamfunc User Manual(0)
Impressum