Debian Codegraph @

userguide/pnmconvol.html

raw
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.3//EN">
2 <html><head><title>Pnmconvol User Manual</title></head>
3 <body>
4 <h1>pnmconvol</h1>
5 Updated: 30 November 2018
6 <br>
7 <a href="#index">Table Of Contents</a>
8
9 <h2>NAME</h2>
10 pnmconvol - general MxN convolution on a Netpbm image
11
12 <h2 id="synopsis">SYNOPSIS</h2>
13
14 <b>pnmconvol</b>
15 {
16 <b>-matrix=</b><i>convolution_matrix</i>
17 |
18 <b>-matrixfile=</b><i>filename</i>[<b>,</b><i>filename</i>[<b>,</b> ...]]
19 }
20 [<b>-normalize</b>]
21 [<b>-bias=<i>n</i></b>]
22
23 [<i>netpbmfile</i>]
24
25 <p>
26
27 <b>pnmconvol</b>
28 <i>convolution_matrix_file</i>
29 [<b>-normalize</b>]
30 [<b>-nooffset</b>]
31 [<i>netpbmfile</i>]
32
33
34 <p>Minimum unique abbreviation of option is acceptable. You may use double
35 hyphens instead of single hyphen to denote options. You may use white
36 space in place of the equals sign to separate an option name from its value.
37
38
39 <h2 id="description">DESCRIPTION</h2>
40
41 <p>This program is part of <a href="index.html">Netpbm</a>.
42
43 <p><b>pnmconvol</b> reads a Netpbm image as input, convolves it with
44 a specified convolution matrix, and writes a Netpbm image as output.
45
46 <p>A command use for convolution is blurring. See examples in the
47 <a href="pamgauss.html"><b>pamgauss</b></a> manual.
48
49 <p>Convolution means replacing each pixel with a weighted average of
50 the nearby pixels. The weights and the area to average are determined
51 by the convolution matrix (sometimes called a convolution kernel),
52 which you supply in one of several ways. See <a href="#convolmatrix">
53 Convolution Matrix</a>.
54
55 <p>At the edges of the convolved image, where the convolution matrix would
56 extend over the edge of the image, <b>pnmconvol</b> just copies the input
57 pixels directly to the output. It's often better to deal with the pixels near
58 an edge by assuming some blank or background color beyond the edge. To do
59 that, use <b>pnmpad</b> to add a margin all around whose size is half that of
60 your convolution matrix size, not counting its center, in the same dimension.
61 (E.g. if your convolution matrix is 5 wide by 3 high, use
62 <kbd>pnmpad -left=2 -right=2 -top=1 -bottom=1</kbd>). Feed that enlarged
63 image to <b>pnmconvol</b>, then use <b>pamcut</b> to chop the edges off the
64 convolved output, getting back to your original image dimensions. (E.g.
65 <kbd>pamcut -left=2 -right=-2 -top=1 -bottom=-1</kbd>).
66
67 <p>The convolution computation can result in a value which is outside the
68 range representable in the output. When that happens, <b>pnmconvol</b> just
69 clips the output, which means brightness is not conserved.
70
71 <p>To avoid clipping, you may want to scale your input values. For example,
72 if your convolution matrix might produce an output value as much as double the
73 maximum value in the input, then make sure the maxval of the input (which is
74 also the maxval of the output) is at least twice the actual maximum value in
75 the input.
76
77 <p>Clipping negative numbers deserves special consideration. If your
78 convolution matrix includes negative numbers, it is possible for
79 <b>pnmconvol</b> to calculate an output pixel as a negative value,
80 which <b>pnmconvol</b> would of course clip to zero, since Netpbm formats
81 cannot represent negative numbers.
82
83
84 <h3 id="convolmatrix">Convolution Matrix</h3>
85
86 <p>There are three ways to specify the convolution matrix:
87
88 <ul>
89 <li>directly with a <b>-matrix</b> option.
90
91 <li>In a file (or set of them) named by a <b>-matrixfile</b> option, whose
92 contents are similar to a <b>-matrix</b> option value.
93
94 <li>With a special PNM file.
95 </ul>
96
97 <p>The PNM file option is the hardest, and exists only because
98 until Netpbm 10.49 (December 2009), it was the only way.
99
100 <p>The regular convolution matrix file is slightly easier to read
101 than the <b>-matrix</b> option value, and makes your command line
102 less messy, but requires you to manage a separate file. With the file,
103 you can have separate convolution matrices for the individual color
104 components, which you can't do with <b>-matrix</b>.
105
106 <p>In any case, the convolution matrix <b>pnmconvol</b> uses is a
107 matrix of real numbers. They can be whole or fractional, positive,
108 negative, or zero.
109
110 <p>The convolution matrix always has an odd width and height, so that
111 there is a center element. <b>pnmconvol</b> figuratively places that
112 center element over a pixel of the input image and weights that pixel
113 and its neighbors as indicated by the convolution matrix to produce the
114 pixel in the same location of the output image.
115
116 <p>For a normal convolution, where you're neither adding nor subtracting total
117 value from the image, but merely moving it around, you'll want to make sure
118 that all the numbers in the matrix add up to 1. If they don't,
119 <b>pnmconvol</b> warns you.
120
121 <p>The elements of the matrix are actually tuples, one for each sample in the
122 input. (I.e. if the input is an RGB image, each element of the convolution
123 matrix has one weight for red, one for green, and one for blue.
124
125
126 <h4 id="matrixopt">Directly On the Command Line</h4>
127
128 <p>Here are examples of a <b>-matrix</b> option:
129
130 <pre>
131 <kbd>
132 -matrix=0,.2,0;.2,.2,.2;0,.2,0
133 </kbd>
134 </pre>
135
136 <pre>
137 <kbd>
138 -matrix=-1,3,-1
139 </kbd>
140 </pre>
141
142
143 <p>The value consists of each row of the matrix from top to bottom, separated
144 by semicolons. Each row consists of the elements of the row from left to
145 right, separated by commas. You must of course have the same number of
146 elements in each row. Each element is a decimal floating point number
147 and is the weight to give to each component of a pixel that corresponds to
148 that matrix location.
149
150 <p>Note that when you supply this option via a shell, semicolon
151 (";") probably means something to the shell, so use quotation
152 marks.
153
154 <p>There is no way with this method to have different weights for different
155 components of a pixel.
156
157 <p>The <b>-normalize</b> option is often quite handy with <b>-matrix</b>
158 because it lets you quickly throw together the command without working out the
159 math to make sure the matrix isn't biased. Note that if you use the
160 <b>-normalize</b> option, the weights in the matrix aren't actually the
161 numbers you specify in the <b>-matrix</b> option.
162
163
164 <h4 id="matrixfile">Regular Matrix File</h4>
165
166 <p>Specify the name of the matrix file with a <b>-matrixfile</b>
167 option. Or specify a list of them, one for each plane of the image.
168
169 <p>Examples:
170
171 <pre>
172 <kbd>
173 -matrixfile=mymatrix
174 </kbd>
175
176 <kbd>
177 -matrixfile=myred,mygreen,myblue
178 </kbd>
179 </pre>
180
181 <p>Each file applies to one plane of the image (e.g. red, green, or blue), in
182 order. The matrix in each file must have the same dimensions. If the
183 input image has more planes than the number of files you specify, the first
184 file applies to the extra planes as well.
185
186 <p><b>pnmconvol</b> interprets the file as text, with lines delimited by Unix
187 newline characters (line feeds).
188
189 <p>Each line of the file is one row of the matrix, in order from top to
190 bottom.
191
192 <p>For each row, the file contains a floating point decimal number for each
193 element in the row, from left to right, separated by spaces. This is not just
194 any old white space -- it is exactly one space. Two spaces in a row mean
195 you've specified a null string for an element (which is invalid). If you
196 want to line up your matrix visually, use leading and trailing zeroes
197 in the floating point numbers to do it.
198
199 <p>There is no way to put comments in the file. There is no signature
200 or any other metadata in the file.
201
202 <p>Note that if you use the <b>-normalize</b> option, the weights in the
203 matrix aren't actually what is in the file.
204
205
206 <h4 id="matrixpnm">PNM File</h4>
207
208 <p>Before Netpbm 10.49 (December 2009), this was the only way to
209 specify a convolution matrix. <b>pnmconvol</b> used this method in
210 an attempt to exploit the generic matrix processing capabilities of
211 Netpbm, but as the Netpbm formats don't directly allow matrices with
212 the kinds of numbers you need in a convolution matrix, it is quite
213 cumbersome. In fact, there simply is no way to specify some convolution
214 matrices with a legal Netpbm image, so to make it work, <b>pnmconvol</b> has
215 to relax the Netpbm file requirement that sample values be no greater
216 than the image's maxval. I.e. it isn't even a real PNM file.
217
218 <p>The way you select this method of supplying the convolution matrix is to
219 <em>not</em> specify <b>-matrix</b> or <b>-matrixfile</b>. When you do that,
220 you must specify the name of the PNM file (or PNM equivalent PAM file) as a
221 non-option argument (before the optional input file name).
222
223 <p>There are two ways <b>pnmconvol</b> interprets the PNM convolution matrix
224 image pixels as weights: with offsets, and without offsets.
225
226 <p>The simpler of the two is without offsets. That is what happens
227 when you specify the <b>-nooffset</b> option. In that case,
228 <b>pnmconvol</b> simply normalizes the sample values in the PNM image
229 by dividing by the maxval.
230
231 <p>For example, here is a sample convolution file that causes an output pixel
232 to be a simple average of its corresponding input pixel and its 8 neighbors,
233 resulting in a smoothed image:
234
235 <pre>
236 P2
237 3 3
238 18
239 2 2 2
240 2 2 2
241 2 2 2
242 </pre>
243
244 <p>(Note that the above text is an actual PGM file -- you can cut and paste
245 it. If you're not familiar with the plain PGM format, see
246 <a href="pgm.html">the PGM format specification</a>).
247
248 <p><b>pnmconvol</b> divides each of the sample values (2) by the maxval
249 (18) so the weight of each of the 9 input pixels gets is 1/9, which is
250 exactly what you want to keep the overall brightness of the image the
251 same. <b>pnmconvol</b> creates an output pixel by multiplying the
252 values of each of 9 pixels by 1/9 and adding.
253
254 <p>Note that with maxval 18, the range of possible values is 0 to 18.
255 After scaling, the range is 0 to 1.
256
257 <p>For a normal convolution, where you're neither adding nor
258 subtracting total value from the image, but merely moving it around,
259 you'll want to make sure that all the scaled values in (each plane of)
260 your convolution PNM add up to 1, which means all the actual sample
261 values add up to the maxval. Alternatively, you can use the
262 <b>-normalize</b> option to scale the scaled values further to make them all
263 add up to 1 automatically.
264
265 <p>When you <em>don't</em> specify <b>-nooffset</b>, <b>pnmconvol</b>
266 applies an offset, the purpose of which is to allow you to indicate
267 negative weights even though PNM sample values are never negative. In
268 this case, <b>pnmconvol</b> subtracts half the maxval from each sample
269 and then normalizes by dividing by half the maxval. So to get the
270 same result as we did above with <b>-nooffset</b>, the convolution
271 matrix PNM image would have to look like this:
272
273 <pre>
274 P2
275 3 3
276 18
277 10 10 10
278 10 10 10
279 10 10 10
280 </pre>
281
282 <p>To see how this works, do the above-mentioned offset: 10 - 18/2
283 gives 1. The normalization step divides by 18/2 = 9, which makes it
284 1/9 - exactly what you want. The equivalent matrix for 5x5 smoothing
285 would have maxval 50 and be filled with 26.
286
287 <p>Note that with maxval 18, the range of possible values is 0 to 18.
288 After offset, that's -9 to 9, and after normalizing, the range is -1 to 1.
289
290 <p>The convolution file will usually be a PGM, so that the same
291 convolution gets applied to each color component. However, if you
292 want to use a PPM and do a different convolution to different
293 colors, you can certainly do that.
294
295
296 <h3 id="otherconvol">Other Forms of Convolution</h3>
297
298 <p><b>pnmconvol</b> does only arithmetic, linear combination convolution.
299 There are other forms of convolution that are especially useful in image
300 processing.
301
302 <p><b>pgmmedian</b> does median filtering, which is a form of convolution
303 where the output pixel value, rather than being a linear combination of the
304 pixels in the window, is the median of a certain subset of them.
305
306 <p><b>pgmmorphconv</b> does dilation and erosion, which is like the median
307 filter but the output value is the minimum or maximum of the values in the
308 window.
309
310
311 <h2 id="options">OPTIONS</h2>
312
313 <p>In addition to the options common to all programs based on libnetpbm
314 (most notably <b>-quiet</b>, see <a href="index.html#commonoptions">
315 Common Options</a>), <b>pnmconvol</b> recognizes the following
316 command line options:
317
318 <dl compact>
319
320 <dt><b>-matrix=</b><i>convolution_matrix</i>
321 <dd>The value of the convolution matrix. See
322 <a href="#matrixopt">Convolution Matrix</a>.
323
324 <p>You may not specify both this and <b>-matrixfile</b>.
325
326 <p>This option was new in Netpbm 10.49 (December 2009). Before
327 that, use a PNM file for the convolution matrix.
328
329 <dt><b>-matrixfile=</b><i>filename</i>
330 <dd>This specifies that you are supplying the convolution matrix in
331 a file and names that file. See
332 <a href="#matrixfile">Convolution Matrix</a>.
333
334 <p>You may not specify both this and <b>-matrix</b>.
335
336 <p>This option was new in Netpbm 10.49 (December 2009). Before
337 that, use a PNM file for the convolution matrix.
338
339 <dt><b>-normalize</b>
340
341 <dd>This option says to adjust the weights in your convolution matrix so they
342 all add up to one. You usually want them to add up to one so that the
343 convolved result tends to have the same overall brightness as the input. With
344 <b>-normalize</b>, <b>pnmconvol</b> scales all the weights by the same factor
345 to make the sum one. It does this for each plane.
346
347 <p>This can be quite convenient because you can just throw numbers into
348 the matrix that have roughly the right relationship to each other and let
349 <b>pnmconvol</b> do the work of normalizing them. And you can adjust a matrix
350 by raising or lowering certain weights without having to modify all the other
351 weights to maintain normalcy. And you can use friendly integers.
352
353 <p>Example:
354
355 <pre>
356 <kbd>
357 $ pnmconvol myimage.ppm -normalize -matrix=1,1,1;1,1,1;1,1,1
358 </kbd>
359 </pre>
360
361 <p>This is of course a basic 3x3 average, but without you having to
362 specify 1/9 (.1111111) for each weight.
363
364 <p>This option was new in Netpbm 10.50 (March 2010). But before Netpbm 10.79
365 (June 2017), it has no effect when you specify the convolution matrix via
366 pseudo-PNM file.
367
368 <dt><b>-bias=</b><i>n</i>
369 <dd>
370
371 <p>This specifies an amount to add to the convolved value for each sample.
372
373 <p>The purpose of this addition is normally to handle negative convolution
374 results. Because the convolution matrix can contain negative numbers, the
375 convolved value for a pixel could be negative. But Netpbm formats cannot
376 contain negative sample values, so without any bias, such samples would get
377 clipped to zero. The bias allows the output image to retain the information,
378 and a program that pocesses that output, knowing the bias value, could
379 reconstruct the real convolved values.
380
381 <p>For example, with <b>bias=100</b>, a sample whose convolved value is -5
382 appears as 95 in the output, whereas a sample whose convolved value is 5
383 appears as 105 in the output.
384
385 <p>A typical value for the bias is half the maxval, allowing the same range on
386 either side of zero.
387
388 <p>If the sample value, after adding the bias, is still less than
389 zero, <b>pnmconvol</b> clips it to zero. If it exceeds the maxval of the
390 output image, it clips it to the maxval.
391
392 <p>The default is zero.
393
394 <p>This option was new in Netpbm 10.68 (September 2014).
395
396 <dt><b>-nooffset=</b>
397 <dd>This is part of the obsolete PNM image method of specifying the
398 convolution matrix. See
399 <a href="#matrixpnm">Convolution Matrix</a>.
400
401 </dl>
402
403 <h2 id="history">HISTORY</h2>
404
405 <p>The <b>-nooffset</b> option was new in Netpbm 10.23 (July 2004),
406 making it substantially easier to specify a convolution matrix, but
407 still hard. In Netpbm 10.49 (December 2009), the PNM convolution
408 matrix tyranny was finally ended with the <b>-matrix</b> and
409 <b>-matrixfile</b> options. In between, <b>pnmconvol</b> was broken
410 for a while because the Netpbm library started enforcing the
411 requirement that a sample value not exceed the maxval of the
412 image. <b>pnmconvol</b> used the Netpbm library to read the PNM
413 convolution matrix file, but in the pseudo-PNM format
414 that <b>pnmconvol</b> uses, a sample value sometimes has to exceed the
415 maxval.
416
417 <h2 id="seealso">SEE ALSO</h2>
418
419 <b><a href="pnmsmooth.html">pnmsmooth</a></b>,
420 <b><a href="pgmmorphconv.html">pgmmorphconv</a></b>,
421 <b><a href="pgmmedian.html">pgmmedian</a></b>,
422 <b><a href="pnmnlfilt.html">pnmnlfilt</a></b>,
423 <b><a href="pgmkernel.html">pgmkernel</a></b>,
424 <b><a href="pamgauss.html">pamgauss</a></b>,
425 <b><a href="pammasksharpen.html">pammasksharpen</a></b>,
426 <b><a href="pnmpad.html">pnmpad</a></b>,
427 <b><a href="pamcut.html">pamcut</a></b>,
428 <b><a href="pnm.html">pnm</a></b>
429
430 <h2 id="authors">AUTHORS</h2>
431
432 Copyright (C) 1989, 1991 by Jef Poskanzer.
433 <br>
434
435 Modified 26 November 1994 by Mike Burns, <a
436 href="mailto:[email protected]">[email protected]</a>
437
438
439 <hr>
440 <h2 id="index">Table Of Contents</h2>
441 <ul>
442 <li><a href="#synopsis">SYNOPSIS</a>
443 <li><a href="#description">DESCRIPTION</a>
444 <ul>
445 <li><a href="#convolmatrix">Convolution Matrix</a>
446 <ul>
447 <li><a href="#matrixopt">Directly On the Command Line</a>
448 <li><a href="#matrixfile">Regular Matrix File</a>
449 <li><a href="#matrixpnm">PNM File</a>
450 </ul>
451 <li><a href="#otherconvol">Other Forms of Convolution</a>
452 </ul>
453 <li><a href="#options">OPTIONS</a>
454 <li><a href="#history">HISTORY</a>
455 <li><a href="#seealso">SEE ALSO</a>
456 <li><a href="#authors">AUTHORS</a>
457 </ul>
458 </body>
459 </html>