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 The samples involved are PAM samples. If the input is PBM, PGM, or
30 PPM, the output will be that same format, but pamfunc applies the func‐
31 tions to the PAM equivalent samples, yielding PAM equivalent samples.
32 This can be nonintuitive in the PBM ⟨#pbmoddness⟩ case.
33 pamarith is the same thing for binary functions -- it takes two images
36 as input and applies a specified simple arithmetic function (e.g. addi‐
37 tion) on pairs of samples from the two to produce the single output
38 image.
39 Values
43 The functions fall into two categories: arithmetic (such as multiply by
44 5) and bit string (such as and with 01001000). For the arithmetic
45 functions, the function arguments and results are the fraction that a
46 sample is of the maxval, i.e. normal interpretation of PAM tuples. But
47 for the bit string functions, the value is the bit string whose value
48 as a binary cipher is the sample value, and the maxval indicates the
49 width of the bit string.
50 Arithmetic functions
52 The arithmetic functions are those selected by the options -multiplier,
54 -divisor, -adder, -subtractor, -min, and -max.
55 As an example, consider an image with maxval 100 and a sample value of
57 10 and a function of "multiply by 5." The argument to the function is
58 10/100 (0.1) and the result is 5 * 0.1 = 0.5. In the simplest case,
59 the maxval of the output is also 100, so the output sample value is 0.5
60 * 100 = 50. As you can see, we could just talk about the sample values
61 themselves instead of these fractions and get the same result (10 * 5 =
62 50), but we don't.
63 Where it makes a practical difference whether we consider the values to
65 be the fraction of the maxval or the sample value alone is where pam‐
66 func uses a different maxval in the output image than it finds in the
67 input image. See -changemaxval.
68 So remember in reading the descriptions below that the values are 0.1
70 and 0.5 in this example, not 10 and 50. All arguments and results are
71 in the range [0,1].
72 Bit string functions
74 The bit string functions are those selected by the options -andmask,
76 -ormask, -xormask, -not, -shiftleft, and -shiftright.
77 With these functions, the maxval has a very different meaning than in
79 normal Netpbm images: it tells how wide (how many bits) the bit string
80 is. The maxval must be a full binary count (a power of two minus one,
81 such as 0xff) and the number of ones in it is the width of the bit
82 string.
83 As an example, consider an image with maxval 15 and a sample value of 5
85 and a function of "and with 0100". The argument to the function is
86 0101 and the result is 0100.
87 In this example, it doesn't make any practical difference what we con‐
89 sider the width of the string to be, as long as it is at least 3. If
90 the maxval were 255, the result would be the same. But with a bit
91 shift operation, it matters. Consider shifting left by 2 bits. In the
92 example, where the input value is 0101, the result is 0100. But if the
93 maxval were 255, the result would be 00010100.
94 For a masking function, the mask value you specify must not have more
96 significant bits than the width indicated by the maxval.
97 For a shifting operation, the shift count you specify must not be
99 greater than the width indicated by the maxval.
100 PBM Oddness
102 If you're familiar with the PBM format, you may find pamfunc's opera‐
104 tion on PBM images to be nonintuitive. Because in PBM black is repre‐
105 sented as 1 and white as 0 (1.0 and 0.0 normlized), you might be
106 expecting adding 1 to white to yield black.
107 But the PBM format is irrelevant, because pamfunc operates on the num‐
109 bers found in the PAM equivalent (see above). In a PAM black and white
110 image, black is 0 and white is 1 (0.0 and 1.0 normalized). So white
111 plus 1 (clipped to the maximum of 1.0) is white.
112
116 In addition to the options common to all programs based on libnetpbm
117 (most notably -quiet, see
118 Common Options ⟨index.html#commonoptions⟩ ), pamfunc recognizes the
119 following command line options:
120 -multiplier=realnum
124 This option makes the transfer function that of multiplying by
126 realnum. realnum must be nonnegative. If the result
127 is greater than one, it is clipped to one.
128 Where the input is a PGM or PPM image, this has the effect of
130 dimming or brightening it. For a different kind of bright‐
131 ening,
132 see pambrighten(1) and ppmflash(1)
133 Also, see ppmdim(1), which does the same
135 thing as pamfunc -multiplier on a PPM image with a multi‐
136 plier
137 between zero and one, except it uses integer arithmetic, so
138 it may be
139 faster.
140 And ppmfade(1) can generate a whole
142 sequence of images of brightness declining to black or
143 increasing to
144 white, if that's what you want.
145 -divisor=realnum
148 This option makes the transfer function that of dividing by
150 realnum. realnum must be nonnegative. If the result
151 is greater than one, it is clipped to one.
152 This is the same function as you would get with -multiplier,
154 specifying the multiplicative inverse of realnum.
155 -adder=integer
158 This option makes the transfer function that of adding
160 integer/maxval. If the result is greater than one, it is
161 clipped to one. If it is less than zero, it is clipped to
162 zero.
163 Note that in mathematics, this entity is called an "addend,"
165 and an "adder" is a snake. We use "adder" because
166 it makes more sense.
167 -subtractor=integer
170 This option makes the transfer function that of subtracting
172 integer/maxval. If the result is greater than one, it is
173 clipped to one. If it is less than zero, it is clipped to
174 zero.
175 Note that in mathematics, this entity is called a
177 "subtrahend" rather than a "subtractor." We use
178 "subtractor" because it makes more sense.
179 This is the same function as you would get with -adder,
181 specifying the negative of integer.
182 -min=wholenum
185 This option makes the transfer function that of taking the maxi‐
187 mum of
188 the argument and wholenum/maxval. I.e the minimum value in
189 the output will be wholenum/maxval.
190 If wholenum/maxval is greater than one, though, every value
192 in the output will be one.
193 -max=wholenum
196 This option makes the transfer function that of taking the mini‐
198 mum of
199 the argument and wholenum/maxval. I.e the maximum value in
200 the output will be wholenum/maxval.
201 If wholenum/maxval is greater than one, the function is
203 idempotent -- the output is identical to the input.
204 -andmask=hexmask
207 This option makes the transfer function that of bitwise anding
209 with hexmask.
210 hexmask is in hexadecimal. Example: 0f
212 This option was new in Netpbm 10.40 (September 2007).
214 -ormask=hexmask
217 This option makes the transfer function that of bitwise
219 inclusive oring with hexmask.
220 This is analogous to -andmask.
222 This option was new in Netpbm 10.40 (September 2007).
224 -xormask=hexmask
227 This option makes the transfer function that of bitwise
229 exclusive oring with hexmask.
230 This is analogous to -andmask.
232 This option was new in Netpbm 10.40 (September 2007).
234 -not
237 This option makes the transfer function that of bitwise logical
239 inversion (e.g. sample value 0xAA becomes 0x55).
240 pnminvert does the same thing for a bilevel visual image
242 which has maxval 1 or is of PBM type.
243 This option was new in Netpbm 10.40 (September 2007).
245 -shiftleft=count
248 This option makes the transfer function that of bitwise shifting
250 left by count bits.
251 This option was new in Netpbm 10.40 (September 2007).
253 -shiftright=count
256 This option makes the transfer function that of bitwise shifting
258 right by count bits.
259 This is analogous to -shiftleft.
261 This option was new in Netpbm 10.40 (September 2007).
263 -changemaxval
266 This option tells pamfunc to use a different maxval in the out‐
268 put image than the maxval of the input image, if it helps. By
269 default, the maxval of the output is unchanged from the input
270 and pamfunc modifies the sample values as necessary to perform
271 the operation.
272 But there is one case where pamfunc can achieve the same result
274 just by changing the maxval and leaving the sample values
275 unchanged: dividing by a number 1 or greater, or multiplying by
276 a number 1 or less. For example, to halve all of the values,
277 pamfunc can just double the maxval.
278 With -changemaxval, pamfunc will do just that.
280 As the Netpbm formats have a maximum maxval of 65535, for large
282 divisors, pamfunc may not be able to use this method.
283 An advantage of dividing by changing the maxval is that you
285 don't lose precision. The higher maxval means higher precision.
286 For example, consider an image with a maxval of 100 and sample
287 value of 10. You divide by 21 and then multiply by 21 again.
288 If pamfunc does this by changing the sample values while retain‐
289 ing maxval 100, the division will result in a sample value of 0
290 and the multiplication will also result in zero. But if pamfunc
291 instead keeps the sample value 10 and changes the maxval, the
292 division will result in a maxval of 2100 and the multiplication
293 will change it back to 100, and the round trip is idempotent.
294 This option was new in Netpbm 10.65 (December 2013).
296
302 ppmdim(1), pambrighten(1), pamdepth(1), pamarith(1), pamsummcol(1),
303 pamsumm(1), ppmfade(1), pnminvert(1), pam(1), pnm(1),
304
307 This program was added to Netpbm in Release 10.3 (June 2002).
308
310 This manual page was generated by the Netpbm tool 'makeman' from HTML
311 source. The master documentation is at
312 http://netpbm.sourceforge.net/doc/pamfunc.html
314netpbm documentation 09 September 2020 Pamfunc User Manual(0)