Debian Codegraph @

upstream/debian-unstable/man1/pamfunc.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 "Pamfunc User Manual" 1 "09 September 2020" "netpbm documentation"
7
8 .SH NAME
9 pamfunc - Apply a simple monadic arithmetic function to a Netpbm image
10
11 .UN synopsis
12 .SH SYNOPSIS
13
14 \fBpamfunc\fP
15 {
16 \fB-multiplier=\fP\fIrealnum\fP |
17 \fB-divisor=\fP\fIrealnum\fP |
18 \fB-adder=\fP\fIinteger\fP |
19 \fB-subtractor=\fP\fIinteger\fP |
20 \fB-min=\fP\fIwholenum\fP |
21 \fB-max=\fP\fIwholenum\fP
22 \fB-andmask=\fP\fIhexmask\fP
23 \fB-ormask=\fP\fIhexmask\fP
24 \fB-xormask=\fP\fIhexmask\fP
25 \fB-not\fP
26 \fB-shiftleft=\fP\fIcount\fP
27 \fB-shiftright=\fP\fIcount\fP
28 [\fB-changemaxval\fP]
29 }
30 [\fIfilespec\fP]
31 .PP
32 All options can be abbreviated to their shortest unique prefix.
33 You may use two hyphens instead of one. You may separate an option
34 name and its value with white space instead of an equals sign.
35
36 .UN description
37 .SH DESCRIPTION
38 .PP
39 This program is part of
40 .BR "Netpbm" (1)\c
41 \&.
42 .PP
43 \fBpamfunc\fP reads a Netpbm image as input and produces a Netpbm
44 image as output, with the same format, and dimensions as the
45 input. \fBpamfunc\fP applies a simple transfer function to each
46 sample in the input to generate the corresponding sample in the
47 output. The options determine what function.
48 .PP
49 The samples involved are PAM samples. If the input is PBM, PGM, or PPM,
50 the output will be that same format, but \fBpamfunc\fP applies the functions
51 to the PAM equivalent samples, yielding PAM equivalent samples. This can
52 be nonintuitive in the
53 .UR #pbmoddness
54 PBM
55 .UE
56 \& case.
57
58 .PP
59 \fBpamarith\fP is the same thing for binary functions -- it takes
60 two images as input and applies a specified simple arithmetic function
61 (e.g. addition) on pairs of samples from the two to produce the single
62 output image.
63
64
65 .UN values
66 .SS Values
67 .PP
68 The functions fall into two categories: arithmetic (such as multiply by 5)
69 and bit string (such as and with 01001000). For the arithmetic functions, the
70 function arguments and results are the fraction that a sample is of the
71 maxval, i.e. normal interpretation of PAM tuples. But for the bit string
72 functions, the value is the the bit string whose value as a binary cipher is
73 the sample value, and the maxval indicates the width of the bit string.
74
75 .B Arithmetic functions
76 .PP
77 The arithmetic functions are those selected by the options
78 \fB-multiplier\fP, \fB-divisor\fP, \fB-adder\fP, \fB-subtractor\fP,
79 \fB-min\fP, and \fB-max\fP.
80 .PP
81 As an example, consider an image with maxval 100 and a sample value of 10
82 and a function of "multiply by 5." The argument to the function is
83 10/100 (0.1) and the result is 5 * 0.1 = 0.5. In the simplest case, the
84 maxval of the output is also 100, so the output sample value is 0.5 * 100 =
85 50. As you can see, we could just talk about the sample values themselves
86 instead of these fractions and get the same result (10 * 5 = 50), but we
87 don't.
88 .PP
89 Where it makes a practical difference whether we consider the values to be
90 the fraction of the maxval or the sample value alone is where \fBpamfunc\fP
91 uses a different maxval in the output image than it finds in the input
92 image. See \fB-changemaxval\fP.
93 .PP
94 So remember in reading the descriptions below that the values are 0.1 and
95 0.5 in this example, not 10 and 50. All arguments and results are in the
96 range [0,1].
97
98 .B Bit string functions
99 .PP
100 The bit string functions are those selected by the options
101 \fB-andmask\fP, \fB-ormask\fP, \fB-xormask\fP, \fB-not\fP,
102 \fB-shiftleft\fP, and \fB-shiftright\fP.
103 .PP
104 With these functions, the maxval has a very different meaning than in
105 normal Netpbm images: it tells how wide (how many bits) the bit string is.
106 The maxval must be a full binary count (a power of two minus one, such as
107 0xff) and the number of ones in it is the width of the bit string.
108 .PP
109 As an example, consider an image with maxval 15 and a sample value of 5
110 and a function of "and with 0100". The argument to the function is
111 0101 and the result is 0100.
112 .PP
113 In this example, it doesn't make any practical difference what we consider
114 the width of the string to be, as long as it is at least 3. If the maxval
115 were 255, the result would be the same. But with a bit shift operation,
116 it matters. Consider shifting left by 2 bits. In the example, where
117 the input value is 0101, the result is 0100. But if the maxval were 255,
118 the result would be 00010100.
119 .PP
120 For a masking function, the mask value you specify must not have
121 more significant bits than the width indicated by the maxval.
122 .PP
123 For a shifting operation, the shift count you specify must not be
124 greater than the width indicated by the maxval.
125
126 .UN pbmoddness
127 .B PBM Oddness
128 .PP
129 If you're familiar with the PBM format, you may find \fBpamfunc\fP's
130 operation on PBM images to be nonintuitive. Because in PBM black is
131 represented as 1 and white as 0 (1.0 and 0.0 normlized), you might be
132 expecting adding 1 to white to yield black.
133 .PP
134 But the PBM format is irrelevant, because \fBpamfunc\fP operates on the
135 numbers found in the PAM equivalent (see above). In a PAM black and white
136 image, black is 0 and white is 1 (0.0 and 1.0 normalized). So white plus 1
137 (clipped to the maximum of 1.0) is white.
138
139
140 .UN options
141 .SH OPTIONS
142 .PP
143 In addition to the options common to all programs based on libnetpbm
144 (most notably \fB-quiet\fP, see
145 .UR index.html#commonoptions
146 Common Options
147 .UE
148 \&), \fBpamfunc\fP recognizes the following
149 command line options:
150
151
152 .TP
153 \fB-multiplier=\fIrealnum\fP\fP
154 .sp
155 This option makes the transfer function that of multiplying by
156 \fIrealnum\fP. \fIrealnum\fP must be nonnegative. If the result
157 is greater than one, it is clipped to one.
158 .sp
159 Where the input is a PGM or PPM image, this has the effect of
160 dimming or brightening it. For a different kind of brightening,
161 see
162 .BR "\fBpambrighten\fP" (1)\c
163 \& and
164 .BR "\fBppmflash\fP" (1)\c
165 \&
166 .sp
167 Also, see
168 .BR "\fBppmdim\fP" (1)\c
169 \&, which does the same
170 thing as \fBpamfunc -multiplier\fP on a PPM image with a multiplier
171 between zero and one, except it uses integer arithmetic, so it may be
172 faster.
173 .sp
174 And
175 .BR "\fBppmfade\fP" (1)\c
176 \& can generate a whole
177 sequence of images of brightness declining to black or increasing to
178 white, if that's what you want.
179
180 .TP
181 \fB-divisor=\fIrealnum\fP\fP
182 .sp
183 This option makes the transfer function that of dividing by
184 \fIrealnum\fP. \fIrealnum\fP must be nonnegative. If the result
185 is greater than one, it is clipped to one.
186 .sp
187 This is the same function as you would get with \fB-multiplier\fP,
188 specifying the multiplicative inverse of \fIrealnum\fP.
189
190 .TP
191 \fB-adder=\fIinteger\fP\fP
192 .sp
193 This option makes the transfer function that of adding
194 \fIinteger\fP/\fImaxval\fP. If the result is greater than one, it is
195 clipped to one. If it is less than zero, it is clipped to zero.
196 .sp
197 Note that in mathematics, this entity is called an "addend,"
198 and an "adder" is a snake. We use "adder" because
199 it makes more sense.
200
201 .TP
202 \fB-subtractor=\fIinteger\fP\fP
203 .sp
204 This option makes the transfer function that of subtracting
205 \fIinteger\fP/\fImaxval\fP. If the result is greater than one, it is
206 clipped to one. If it is less than zero, it is clipped to zero.
207 .sp
208 Note that in mathematics, this entity is called a
209 "subtrahend" rather than a "subtractor." We use
210 "subtractor" because it makes more sense.
211 .sp
212 This is the same function as you would get with \fB-adder\fP,
213 specifying the negative of \fIinteger\fP.
214
215 .TP
216 \fB-min=\fIwholenum\fP\fP
217 .sp
218 This option makes the transfer function that of taking the maximum of
219 the argument and \fIwholenum\fP/\fImaxval\fP. I.e the minimum value in
220 the output will be \fIwholenum\fP/\fImaxval\fP.
221
222 If \fIwholenum\fP/\fImaxval\fP is greater than one, though, every value
223 in the output will be one.
224
225 .TP
226 \fB-max=\fIwholenum\fP\fP
227 .sp
228 This option makes the transfer function that of taking the minimum of
229 the argument and \fIwholenum\fP/\fImaxval\fP. I.e the maximum value in
230 the output will be \fIwholenum\fP/\fImaxval\fP.
231
232 If \fIwholenum\fP/\fImaxval\fP is greater than one, the function is
233 idempotent -- the output is identical to the input.
234
235 .TP
236 \fB-andmask=\fIhexmask\fP\fP
237 .sp
238 This option makes the transfer function that of bitwise anding
239 with \fIhexmask\fP.
240 .sp
241 \fIhexmask\fP is in hexadecimal. Example: \f(CW0f\fP
242 .sp
243 This option was new in Netpbm 10.40 (September 2007).
244
245 .TP
246 \fB-ormask=\fIhexmask\fP\fP
247 .sp
248 This option makes the transfer function that of bitwise
249 inclusive oring with \fIhexmask\fP.
250 .sp
251 This is analogous to \fB-andmask\fP.
252 .sp
253 This option was new in Netpbm 10.40 (September 2007).
254
255 .TP
256 \fB-xormask=\fIhexmask\fP\fP
257 .sp
258 This option makes the transfer function that of bitwise
259 exclusive oring with \fIhexmask\fP.
260 .sp
261 This is analogous to \fB-andmask\fP.
262 .sp
263 This option was new in Netpbm 10.40 (September 2007).
264
265 .TP
266 \fB-not\fP
267 .sp
268 This option makes the transfer function that of bitwise logical
269 inversion (e.g. sample value 0xAA becomes 0x55).
270 .sp
271 \fBpnminvert\fP does the same thing for a bilevel visual image
272 which has maxval 1 or is of PBM type.
273 .sp
274 This option was new in Netpbm 10.40 (September 2007).
275
276 .TP
277 \fB-shiftleft=\fIcount\fP\fP
278 .sp
279 This option makes the transfer function that of bitwise shifting
280 left by \fIcount\fP bits.
281 .sp
282 This option was new in Netpbm 10.40 (September 2007).
283
284 .TP
285 \fB-shiftright=\fIcount\fP\fP
286 .sp
287 This option makes the transfer function that of bitwise shifting
288 right by \fIcount\fP bits.
289 .sp
290 This is analogous to \fB-shiftleft\fP.
291 .sp
292 This option was new in Netpbm 10.40 (September 2007).
293
294 .TP
295 \fB-changemaxval\fP
296 .sp
297 This option tells \fBpamfunc\fP to use a different maxval in the output
298 image than the maxval of the input image, if it helps. By default, the maxval
299 of the output is unchanged from the input and \fBpamfunc\fP modifies the
300 sample values as necessary to perform the operation.
301 .sp
302 But there is one case where \fBpamfunc\fP can achieve the same result just
303 by changing the maxval and leaving the sample values unchanged: dividing by a
304 number 1 or greater, or multiplying by a number 1 or less. For example, to
305 halve all of the values, \fBpamfunc\fP can just double the maxval.
306 .sp
307 With \fB-changemaxval\fP, \fBpamfunc\fP will do just that.
308 .sp
309 As the Netpbm formats have a maximum maxval of 65535, for large divisors,
310 \fBpamfunc\fP may not be able to use this method.
311 .sp
312 An advantage of dividing by changing the maxval is that you don't lose
313 precision. The higher maxval means higher precision. For example, consider
314 an image with a maxval of 100 and sample value of 10. You divide by 21 and
315 then multiply by 21 again. If \fBpamfunc\fP does this by changing the sample
316 values while retaining maxval 100, the division will result in a sample value
317 of 0 and the multiplication will also result in zero. But if \fBpamfunc\fP
318 instead keeps the sample value 10 and changes the maxval, the division will
319 result in a maxval of 2100 and the multiplication will change it back to 100,
320 and the round trip is idempotent.
321 .sp
322 This option was new in Netpbm 10.65 (December 2013).
323
324
325
326
327 .UN seealso
328 .SH SEE ALSO
329 .BR "ppmdim" (1)\c
330 \&,
331 .BR "pambrighten" (1)\c
332 \&,
333 .BR "pamdepth" (1)\c
334 \&,
335 .BR "pamarith" (1)\c
336 \&,
337 .BR "pamsummcol" (1)\c
338 \&,
339 .BR "pamsumm" (1)\c
340 \&,
341 .BR "ppmfade" (1)\c
342 \&,
343 .BR "pnminvert" (1)\c
344 \&,
345 .BR "pam" (1)\c
346 \&,
347 .BR "pnm" (1)\c
348 \&,
349
350 .UN history
351 .SH HISTORY
352 .PP
353 This program was added to Netpbm in Release 10.3 (June 2002).
354 .SH DOCUMENT SOURCE
355 This manual page was generated by the Netpbm tool 'makeman' from HTML
356 source. The master documentation is at
357 .IP
358 .B http://netpbm.sourceforge.net/doc/pamfunc.html
359 .PP