1Pnmconvol User Manual(0) Pnmconvol User Manual(0)
2
6 pnmconvol - general MxN convolution on a Netpbm image
7
10 pnmconvol { -matrix=convolution_matrix | -matrixfile=filename[,file‐
11 name[, ...]] } [-normalize] [-bias=n]
12 [netpbmfile]
14 pnmconvol convolution_matrix_file [-normalize] [-nooffset] [netpbmfile]
16 Minimum unique abbreviation of option is acceptable. You may use dou‐
18 ble hyphens instead of single hyphen to denote options. You may use
19 white space in place of the equals sign to separate an option name from
20 its value.
21
25 This program is part of Netpbm(1).
26 pnmconvol reads a Netpbm image as input, convolves it with a specified
28 convolution matrix, and writes a Netpbm image as output.
29 A command use for convolution is blurring. See examples in the pam‐
31 gauss(1) manual.
32 Convolution means replacing each pixel with a weighted average of the
35 nearby pixels. The weights and the area to average are determined by
36 the convolution matrix (sometimes called a convolution kernel), which
37 you supply in one of several ways. See
38 Convolution Matrix ⟨#convolmatrix⟩ .
39 At the edges of the convolved image, where the convolution matrix would
41 extend over the edge of the image, pnmconvol just copies the input pix‐
42 els directly to the output. It's often better to deal with the pixels
43 near an edge by assuming some blank or background color beyond the
44 edge. To do that, use pnmpad to add a margin all around whose size is
45 half that of your convolution matrix size, not counting its center, in
46 the same dimension. (E.g. if your convolution matrix is 5 wide by 3
47 high, use pnmpad -left=2 -right=2 -top=1 -bottom=1). Feed that en‐
48 larged image to pnmconvol, then use pamcut to chop the edges off the
49 convolved output, getting back to your original image dimensions.
50 (E.g. pamcut -left=2 -right=-2 -top=1 -bottom=-1).
51 The convolution computation can result in a value which is outside the
53 range representable in the output. When that happens, pnmconvol just
54 clips the output, which means brightness is not conserved.
55 To avoid clipping, you may want to scale your input values. For exam‐
57 ple, if your convolution matrix might produce an output value as much
58 as double the maximum value in the input, then make sure the maxval of
59 the input (which is also the maxval of the output) is at least twice
60 the actual maximum value in the input.
61 Clipping negative numbers deserves special consideration. If your con‐
63 volution matrix includes negative numbers, it is possible for pnmconvol
64 to calculate an output pixel as a negative value, which pnmconvol would
65 of course clip to zero, since Netpbm formats cannot represent negative
66 numbers.
67 Convolution Matrix
71 There are three ways to specify the convolution matrix:
72 • directly with a -matrix option.
76 • In a file (or set of them) named by a -matrixfile option, whose
79 contents are similar to a -matrix option value.
80 • With a special PNM file.
83 The PNM file option is the hardest, and exists only because until
86 Netpbm 10.49 (December 2009), it was the only way.
87 The regular convolution matrix file is slightly easier to read than the
89 -matrix option value, and makes your command line less messy, but re‐
90 quires you to manage a separate file. With the file, you can have sep‐
91 arate convolution matrices for the individual color components, which
92 you can't do with -matrix.
93 In any case, the convolution matrix pnmconvol uses is a matrix of real
95 numbers. They can be whole or fractional, positive, negative, or zero.
96 The convolution matrix always has an odd width and height, so that
98 there is a center element. pnmconvol figuratively places that center
99 element over a pixel of the input image and weights that pixel and its
100 neighbors as indicated by the convolution matrix to produce the pixel
101 in the same location of the output image.
102 For a normal convolution, where you're neither adding nor subtracting
104 total value from the image, but merely moving it around, you'll want to
105 make sure that all the numbers in the matrix add up to 1. If they
106 don't, pnmconvol warns you.
107 The elements of the matrix are actually tuples, one for each sample in
109 the input. (I.e. if the input is an RGB image, each element of the
110 convolution matrix has one weight for red, one for green, and one for
111 blue.
112 Directly On the Command Line
115 Here are examples of a -matrix option:
117 -matrix=0,.2,0;.2,.2,.2;0,.2,0
119 -matrix=-1,3,-1
122 The value consists of each row of the matrix from top to bottom, sepa‐
125 rated by semicolons. Each row consists of the elements of the row from
126 left to right, separated by commas. You must of course have the same
127 number of elements in each row. Each element is a decimal floating
128 point number and is the weight to give to each component of a pixel
129 that corresponds to that matrix location.
130 Note that when you supply this option via a shell, semicolon (";")
132 probably means something to the shell, so use quotation marks.
133 There is no way with this method to have different weights for differ‐
135 ent components of a pixel.
136 The -normalize option is often quite handy with -matrix because it lets
138 you quickly throw together the command without working out the math to
139 make sure the matrix isn't biased. Note that if you use the -normalize
140 option, the weights in the matrix aren't actually the numbers you spec‐
141 ify in the -matrix option.
142 Regular Matrix File
145 Specify the name of the matrix file with a -matrixfile option. Or
147 specify a list of them, one for each plane of the image.
148 Examples:
150 -matrixfile=mymatrix
152 -matrixfile=myred,mygreen,myblue
154 Each file applies to one plane of the image (e.g. red, green, or blue),
157 in order. The matrix in each file must have the same dimensions. If
158 the input image has more planes than the number of files you specify,
159 the first file applies to the extra planes as well.
160 pnmconvol interprets the file as text, with lines delimited by Unix
162 newline characters (line feeds).
163 Each line of the file is one row of the matrix, in order from top to
165 bottom.
166 For each row, the file contains a floating point decimal number for
168 each element in the row, from left to right, separated by spaces. This
169 is not just any old white space -- it is exactly one space. Two spaces
170 in a row mean you've specified a null string for an element (which is
171 invalid). If you want to line up your matrix visually, use leading and
172 trailing zeroes in the floating point numbers to do it.
173 There is no way to put comments in the file. There is no signature or
175 any other metadata in the file.
176 Note that if you use the -normalize option, the weights in the matrix
178 aren't actually what is in the file.
179 PNM File
182 Before Netpbm 10.49 (December 2009), this was the only way to specify a
184 convolution matrix. pnmconvol used this method in an attempt to ex‐
185 ploit the generic matrix processing capabilities of Netpbm, but as the
186 Netpbm formats don't directly allow matrices with the kinds of numbers
187 you need in a convolution matrix, it is quite cumbersome. In fact,
188 there simply is no way to specify some convolution matrices with a le‐
189 gal Netpbm image, so to make it work, pnmconvol has to relax the Netpbm
190 file requirement that sample values be no greater than the image's max‐
191 val. I.e. it isn't even a real PNM file.
192 The way you select this method of supplying the convolution matrix is
194 to not specify -matrix or -matrixfile. When you do that, you must
195 specify a second non-option argument -- that is the name of the PNM
196 file (or PNM equivalent PAM file).
197 There are two ways pnmconvol interprets the PNM convolution matrix im‐
199 age pixels as weights: with offsets, and without offsets.
200 The simpler of the two is without offsets. That is what happens when
202 you specify the -nooffset option. In that case, pnmconvol simply nor‐
203 malizes the sample values in the PNM image by dividing by the maxval.
204 For example, here is a sample convolution file that causes an output
206 pixel to be a simple average of its corresponding input pixel and its 8
207 neighbors, resulting in a smoothed image:
208 P2
210 3 3
211 18
212 2 2 2
213 2 2 2
214 2 2 2
215 (Note that the above text is an actual PGM file -- you can cut and
218 paste it. If you're not familiar with the plain PGM format, see the
219 PGM format specification(1)).
220 pnmconvol divides each of the sample values (2) by the maxval (18) so
222 the weight of each of the 9 input pixels gets is 1/9, which is exactly
223 what you want to keep the overall brightness of the image the same.
224 pnmconvol creates an output pixel by multiplying the values of each of
225 9 pixels by 1/9 and adding.
226 Note that with maxval 18, the range of possible values is 0 to 18. Af‐
228 ter scaling, the range is 0 to 1.
229 For a normal convolution, where you're neither adding nor subtracting
231 total value from the image, but merely moving it around, you'll want to
232 make sure that all the scaled values in (each plane of) your convolu‐
233 tion PNM add up to 1, which means all the actual sample values add up
234 to the maxval. Alternatively, you can use the -normalize option to
235 scale the scaled values further to make them all add up to 1 automati‐
236 cally.
237 When you don't specify -nooffset, pnmconvol applies an offset, the pur‐
239 pose of which is to allow you to indicate negative weights even though
240 PNM sample values are never negative. In this case, pnmconvol sub‐
241 tracts half the maxval from each sample and then normalizes by dividing
242 by half the maxval. So to get the same result as we did above with
243 -nooffset, the convolution matrix PNM image would have to look like
244 this:
245 P2
247 3 3
248 18
249 10 10 10
250 10 10 10
251 10 10 10
252 To see how this works, do the above-mentioned offset: 10 - 18/2 gives
255 1. The normalization step divides by 18/2 = 9, which makes it 1/9 -
256 exactly what you want. The equivalent matrix for 5x5 smoothing would
257 have maxval 50 and be filled with 26.
258 Note that with maxval 18, the range of possible values is 0 to 18. Af‐
260 ter offset, that's -9 to 9, and after normalizing, the range is -1 to
261 1.
262 The convolution file will usually be a PGM, so that the same convolu‐
264 tion gets applied to each color component. However, if you want to use
265 a PPM and do a different convolution to different colors, you can cer‐
266 tainly do that.
267 Other Forms of Convolution
271 pnmconvol does only arithmetic, linear combination convolution. There
272 are other forms of convolution that are especially useful in image pro‐
273 cessing.
274 pgmmedian does median filtering, which is a form of convolution where
276 the output pixel value, rather than being a linear combination of the
277 pixels in the window, is the median of a certain subset of them.
278 pgmmorphconv does dilation and erosion, which is like the median filter
280 but the output value is the minimum or maximum of the values in the
281 window.
282
286 In addition to the options common to all programs based on libnetpbm
287 (most notably -quiet, see
288 Common Options ⟨index.html#commonoptions⟩ ), pnmconvol recognizes the
289 following command line options:
290 -matrix=convolution_matrix
295 The value of the convolution matrix. See Convolution Matrix
296 ⟨#matrixopt⟩ .
297 You may not specify both this and -matrixfile.
299 This option was new in Netpbm 10.49 (December 2009). Before
301 that, use a PNM file for the convolution matrix.
302 -matrixfile=filename
305 This specifies that you are supplying the convolution matrix in
306 a file and names that file. See Convolution Matrix
307 ⟨#matrixfile⟩ .
308 You may not specify both this and -matrix.
310 This option was new in Netpbm 10.49 (December 2009). Before
312 that, use a PNM file for the convolution matrix.
313 -normalize
316 This option says to adjust the weights in your convolution ma‐
317 trix so they all add up to one. You usually want them to add up
318 to one so that the convolved result tends to have the same over‐
319 all brightness as the input. With -normalize, pnmconvol scales
320 all the weights by the same factor to make the sum one. It does
321 this for each plane.
322 This can be quite convenient because you can just throw numbers
324 into the matrix that have roughly the right relationship to each
325 other and let pnmconvol do the work of normalizing them. And
326 you can adjust a matrix by raising or lowering certain weights
327 without having to modify all the other weights to maintain nor‐
328 malcy. And you can use friendly integers.
329 Example:
331 $ pnmconvol myimage.ppm -normalize -matrix=1,1,1;1,1,1;1,1,1
333 This is of course a basic 3x3 average, but without you having to
336 specify 1/9 (.1111111) for each weight.
337 This option was new in Netpbm 10.50 (March 2010). But before
339 Netpbm 10.79 (June 2017), it has no effect when you specify the
340 convolution matrix via pseudo-PNM file.
341 -bias=n
344 This specifies an amount to add to the convolved value for each
346 sample.
347 The purpose of this addition is normally to handle negative con‐
349 volution results. Because the convolution matrix can contain
350 negative numbers, the convolved value for a pixel could be nega‐
351 tive. But Netpbm formats cannot contain negative sample values,
352 so without any bias, such samples would get clipped to zero.
353 The bias allows the output image to retain the information, and
354 a program that pocesses that output, knowing the bias value,
355 could reconstruct the real convolved values.
356 For example, with bias=100, a sample whose convolved value is -5
358 appears as 95 in the output, whereas a sample whose convolved
359 value is 5 appears as 105 in the output.
360 A typical value for the bias is half the maxval, allowing the
362 same range on either side of zero.
363 If the sample value, after adding the bias, is still less than
365 zero, pnmconvol clips it to zero. If it exceeds the maxval of
366 the output image, it clips it to the maxval.
367 The default is zero.
369 This option was new in Netpbm 10.68 (September 2014).
371 -nooffset=
374 This is part of the obsolete PNM image method of specifying the
375 convolution matrix. See Convolution Matrix ⟨#matrixpnm⟩ .
376
381 The -nooffset option was new in Netpbm 10.23 (July 2004), making it
382 substantially easier to specify a convolution matrix, but still hard.
383 In Netpbm 10.49 (December 2009), the PNM convolution matrix tyranny was
384 finally ended with the -matrix and -matrixfile options. In between,
385 pnmconvol was broken for a while because the Netpbm library started en‐
386 forcing the requirement that a sample value not exceed the maxval of
387 the image. pnmconvol used the Netpbm library to read the PNM convolu‐
388 tion matrix file, but in the pseudo-PNM format that pnmconvol uses, a
389 sample value sometimes has to exceed the maxval.
390
393 pnmsmooth(1), pgmmorphconv(1), pgmmedian(1), pnmnlfilt(1), pgmker‐
394 nel(1), pamgauss(1), pammasksharpen(1), pnmpad(1), pamcut(1), pnm(1)
395
398 Copyright (C) 1989, 1991 by Jef Poskanzer. Modified 26 November 1994
399 by Mike Burns, burns@chem.psu.edu
400
402 This manual page was generated by the Netpbm tool 'makeman' from HTML
403 source. The master documentation is at
404 http://netpbm.sourceforge.net/doc/pnmconvol.html
406netpbm documentation 30 November 2018 Pnmconvol User Manual(0)