1Pamfunc User Manual(0) Pamfunc User Manual(0)
2
6 pamfunc - Apply a simple monadic arithmetic function to a Netpbm image
7
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 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
21 This program is part of Netpbm(1).
22 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 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 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 Arithmetic functions
46 The arithmetic functions are those selected by the options -multiplier,
48 -divisor, -adder, -subtractor, -min, and -max.
49 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 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 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 Bit string functions
68 The bit string functions are those selected by the options -andmask,
70 -ormask, -xormask, -not, -shiftleft, and -shiftright.
71 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 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 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 For a masking function, the mask value you specify must not have more
90 significant bits than the width indicated by the maxval.
91 For a shifting operation, the shift count you specify must not be
93 greater than the width indicated by the maxval.
94
98 -multiplier=realnum
99 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 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 ppmbrighten(1) and ppmflash(1)
108 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 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 -divisor=realnum
123 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 This is the same function as you would get with -multiplier,
129 specifying the multiplicative inverse of realnum.
130 -adder=integer
133 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 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 -subtractor=integer
145 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 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 This is the same function as you would get with -adder,
156 specifying the negative of integer.
157 -min=wholenum
160 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 If wholenum/maxval is greater than one, though, every value
167 in the output will be one.
168 -max=wholenum
171 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 If wholenum/maxval is greater than one, the function is
178 idempotent -- the output is identical to the input.
179 -andmask=hexmask
182 This option makes the transfer function that of bitwise anding
184 with hexmask.
185 hexmask is in hexadecimal. Example: 0f
187 This option was new in Netpbm 10.40 (September 2007).
189 -ormask=hexmask
192 This option makes the transfer function that of bitwise
194 inclusive oring with hexmask.
195 This is analogous to -andmask.
197 This option was new in Netpbm 10.40 (September 2007).
199 -xormask=hexmask
202 This option makes the transfer function that of bitwise
204 exclusive oring with hexmask.
205 This is analogous to -andmask.
207 This option was new in Netpbm 10.40 (September 2007).
209 -not
212 This option makes the transfer function that of bitwise logical
214 inversion (e.g. sample value 0xAA becomes 0x55).
215 pnminvert does the same thing for a bilevel visual image
217 which has maxval 1 or is of PBM type.
218 This option was new in Netpbm 10.40 (September 2007).
220 -shiftleft=count
223 This option makes the transfer function that of bitwise shifting
225 left by count bits.
226 This option was new in Netpbm 10.40 (September 2007).
228 -shiftright=count
231 This option makes the transfer function that of bitwise shifting
233 right by count bits.
234 This is analogous to -shiftleft.
236 This option was new in Netpbm 10.40 (September 2007).
238 -changemaxval
241 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 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 With -changemaxval, pamfunc will do just that.
255 As the Netpbm formats have a maximum maxval of 65535, for large
257 divisors, pamfunc may not be able to use this method.
258 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 This option was new in Netpbm 10.65 (December 2013).
271
277 ppmdim(1), ppmbrighten(1), pamdepth(1), pamarith(1), pamsummcol(1),
278 pamsumm(1), ppmfade(1), pnminvert(1), pam(1), pnm(1),
279
282 This program was added to Netpbm in Release 10.3 (June 2002).
283
285 This manual page was generated by the Netpbm tool 'makeman' from HTML
286 source. The master documentation is at
287 http://netpbm.sourceforge.net/doc/pamfunc.html
289netpbm documentation December 2013 Pamfunc User Manual(0)