Debian Codegraph @

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