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[, ...]] } [netpbmfile]
12 pnmconvol convolution_matrix_file [-normalize] [-nooffset] [netpbmfile]
14 Minimum unique abbreviation of option is acceptable. You may use dou‐
16 ble hyphens instead of single hyphen to denote options. You may use
17 white space in place of the equals sign to separate an option name from
18 its value.
19
23 This program is part of Netpbm(1).
24 pnmconvol reads a Netpbm image as input, convolves it with a specified
26 convolution matrix, and writes a Netpbm image as output.
27 Convolution means replacing each pixel with a weighted average of the
29 nearby pixels. The weights and the area to average are determined by
30 the convolution matrix (sometimes called a convolution kernel), which
31 you supply in one of several ways. See
32 Convolution Matrix ⟨#convolutionmatrix⟩ .
33 At the edges of the convolved image, where the convolution matrix would
35 extend over the edge of the image, pnmconvol just copies the input pix‐
36 els directly to the output.
37 The convolution computation can result in a value which is outside the
39 range representable in the output. When that happens, pnmconvol just
40 clips the output, which means brightness is not conserved.
41 Convolution Matrix
45 There are three ways to specify the convolution matrix:
46 · directly with a -matrix option.
50 · In a file (or set of them) named by a -matrixfile option, whose
53 contents are similar to a -matrix option value.
54 · With a special PNM file.
57 The PNM file option is the hardest, and exists only because until
60 Netpbm 10.49 (December 2009), it was the only way.
61 The regular convolution matrix file is slightly easier to read than the
63 -matrix option value, and makes your command line less messy, but
64 requires you to manage a separate file. With the file, you can have
65 separate convolution matrices for the individual color components,
66 which you can't do with -matrix.
67 In any case, the convolution matrix pnmconvol uses is a matrix of real
69 numbers. They can be whole or fractional, positive, negative, or zero.
70 The convolution matrix always has an odd width and height, so that
72 there is a center element. pnmconvol figuratively places that center
73 element over a pixel of the input image and weights that pixel and its
74 neighbors as indicated by the convolution matrix to produce the pixel
75 in the same location of the output image.
76 For a normal convolution, where you're neither adding nor subtracting
78 total value from the image, but merely moving it around, you'll want to
79 make sure that all the numbers in the matrix add up to 1. If they
80 don't, pnmconvol warns you.
81 The elements of the matrix are actually tuples, one for each sample in
83 the input. (I.e. if the input is an RGB image, each element of the
84 convolution matrix has one weight for red, one for green, and one for
85 blue.
86 Directly On the Command Line
89 An example of a -matrix option is
91 -matrix=0,.2,0;.2,.2,.2;0,.2,0
93 The value consists of each row of the matrix from top to bottom, sepa‐
95 rated by semicolons. Each row consists of the elements of the row from
96 left to right, separated by commas. You must of course have the same
97 number of elements in each row. Each element is a decimal floating
98 point number and is the weight to give to each component of a pixel
99 that corresponds to that matrix location.
100 Note that when you supply this option via a shell, semicolon (';')
102 probably means something to the shell, so use quotation marks.
103 There is no way with this method to have different weights for differ‐
105 ent components of a pixel.
106 The -normalize option is often quite handy with -matrix because it lets
108 you quickly throw together the command without working out the math to
109 make sure the matrix isn't biased. Note that if you use the -normalize
110 option, the weights in the matrix aren't actually the numbers you spec‐
111 ify in the -matrix option.
112 Regular Matrix File
115 Specify the name of the matrix file with a -matrixfile option. Or
117 specify a list of them, one for each plane of the image.
118 Examples:
120 -matrixfile=mymatrix
122 -matrixfile=myred,mygreen,myblue
124 Each file applies to one plane of the image (e.g. red, green, or blue),
126 in order. The matrix in each file must have the same dimensions. If
127 the input image has more planes than the number of files you specify,
128 the first file applies to the extra planes as well.
129 pnmconvol interprets the file as text, with lines delimited by Unix
131 newline characters (line feeds).
132 Each line of the file is one row of the matrix, in order from top to
134 bottom.
135 For each row, the file contains a floating point decimal number for
137 each element in the row, from left to right, separated by spaces. This
138 is not just any old white space -- it is exactly one space. Two spaces
139 in a row mean you've specified a null string for an element (which is
140 invalid). If you want to line up your matrix visually, use leading and
141 trailing zeroes in the floating point numbers to do it.
142 There is no way to put comments in the file. There is no signature or
144 any other metadata in the file.
145 Note that if you use the -normalize option, the weights in the matrix
147 aren't actually what is in the file.
148 PNM File
151 Before Netpbm 10.49 (December 2009), this was the only way to specify a
153 convolution matrix. pnmconvol used this method in an attempt to
154 exploit the generic matrix processing capabilities of Netpbm, but as
155 the Netpbm formats don't directly allow matrices with the kinds of num‐
156 bers you need in a convolution matrix, it is quite cumbersome. In
157 fact, there simply is no way to specify some convolution matrices with
158 a legal Netpbm image, so make it work, pnmconvol has to relax the
159 Netpbm file requirement that sample values be no greater than the
160 image's maxval. I.e. it isn't even a real PNM file.
161 The way you select this method of supplying the convolution matrix is
163 to not specify -matrix or -matrixfile. When you do that, you must
164 specify a second non-option argument -- that is the name of the PNM
165 file (or PNM equivalent PAM file).
166 There are two ways pnmconvol interprets the PNM convolution matrix
168 image pixels as weights: with offsets, and without offsets.
169 The simpler of the two is without offsets. That is what happens when
171 you specify the -nooffset option. In that case, pnmconvol simply nor‐
172 malizes the sample values in the PNM image by dividing by the maxval.
173 For example, here is a sample convolution file that causes an output
175 pixel to be a simple average of its corresponding input pixel and its 8
176 neighbors, resulting in a smoothed image:
177 P2
179 3 3
180 18
181 2 2 2
182 2 2 2
183 2 2 2
184 (Note that the above text is an actual PGM file -- you can cut and
186 paste it. If you're not familiar with the plain PGM format, see theP‐
187 GMformatspecification[1m(1)).
188 pnmconvol divides each of the sample values (2) by the maxval (18) so
190 the weight of each of the 9 input pixels gets is 1/9, which is exactly
191 what you want to keep the overall brightness of the image the same.
192 pnmconvol creates an output pixel by multiplying the values of each of
193 9 pixels by 1/9 and adding.
194 Note that with maxval 18, the range of possible values is 0 to 18.
196 After scaling, the range is 0 to 1.
197 For a normal convolution, where you're neither adding nor subtracting
199 total value from the image, but merely moving it around, you'll want to
200 make sure that all the scaled values in (each plane of) your convolu‐
201 tion PNM add up to 1, which means all the actual sample values add up
202 to the maxval.
203 When you don't specify -nooffset, pnmconvol applies an offset, the pur‐
205 pose of which is to allow you to indicate negative weights even though
206 PNM sample values are never negative. In this case, pnmconvol sub‐
207 tracts half the maxval from each sample and then normalizes by dividing
208 by half the maxval. So to get the same result as we did above with
209 -nooffset, the convolution matrix PNM image would have to look like
210 this:
211 P2
213 3 3
214 18
215 10 10 10
216 10 10 10
217 10 10 10
218 To see how this works, do the above-mentioned offset: 10 - 18/2 gives
220 1. The normalization step divides by 18/2 = 9, which makes it 1/9 -
221 exactly what you want. The equivalent matrix for 5x5 smoothing would
222 have maxval 50 and be filled with 26.
223 Note that with maxval 18, the range of possible values is 0 to 18.
225 After offset, that's -9 to 9, and after normalizing, the range is -1 to
226 1.
227 The convolution file will usually be a PGM, so that the same convolu‐
229 tion gets applied to each color component. However, if you want to use
230 a PPM and do a different convolution to different colors, you can cer‐
231 tainly do that.
232
235 -matrix=convolution_matrix
236 The value of the convolution matrix. See Convolution Matrix
237 ⟨#matrixopt⟩ .
238 You may not specify both this and -matrixfile.
240 This option was new in Netpbm 10.49 (December 2009). Before
242 that, use a PNM file for the convolution matrix.
243 -matrixfile=filename
246 This specifies that you are supplying the convolution matrix in
247 a file and names that file. See Convolution Matrix
248 ⟨#matrixfile⟩ .
249 You may not specify both this and -matrix.
251 This option was new in Netpbm 10.49 (December 2009). Before
253 that, use a PNM file for the convolution matrix.
254 -normalize
257 This option says to adjust the weights in your convolution
258 matrix so they all add up to one. You usually want them to add
259 up to one so that the convolved result tends to have the same
260 overall brightness as the input. With -normalize, pnmconvol
261 scales all the weights by the same factor to make the sum one.
262 It does this for each plane.
263 This can be quite convenient because you can just throw numbers
265 into the matrix that have roughly the right relationship to each
266 other and let pnmconvol do the work of normalizing them. And
267 you can adjust a matrix by raising or lowering certain weights
268 without having to modify all the other weights to maintain nor‐
269 malcy. And you can use friendly integers.
270 Example:
272 $ pnmconvol myimage.ppm -normalize -matrix=1,1,1;1,1,1;1,1,1
274 This is of course a basic 3x3 average, but without you having to
276 specify 1/9 (.1111111) for each weight.
277 This option has no effect when you specify the convolution
279 matrix via pseudo-PNM file.
280 This option was new in Netpbm 10.50 (March 2010).
282 -nooffset=
285 This is part of the obsolete PNM image method of specifying the
286 convolution matrix. See Convolution Matrix ⟨#matrixpnm⟩ .
287
292 The -nooffset option was new in Netpbm 10.23 (July 2004), making it
293 substantially easier to specify a convolution matrix, but still hard.
294 In Netpbm 10.49 (December 2009), the PNM convolution matrix tyranny was
295 finally ended with the -matrix and -matrixfile options. In between,
296 pnmconvol was broken for a while because the Netpbm library started
297 enforcing the requirement that a sample value not exceed the maxval of
298 the image. pnmconvol used the Netpbm library to read the PNM convolu‐
299 tion matrix file, but in the pseudo-PNM format that pnmconvol uses, a
300 sample value sometimes has to exceed the maxval.
301
305 pnmsmooth(1), pgmmorphconv(1), pnmnlfilt(1), pgmkernel(1), pamgauss(1),
306 pammasksharpen(1), pnm(1)
307
310 Copyright (C) 1989, 1991 by Jef Poskanzer. Modified 26 November 1994
311 by Mike Burns, burns@chem.psu.edu
312netpbm documentation 03 January 2010 Pnmconvol User Manual(0)