1Pnmconvol User Manual(0)                              Pnmconvol User Manual(0)
2
3
4

NAME

6       pnmconvol - general MxN convolution on a Netpbm image
7
8

SYNOPSIS

10       pnmconvol  {  -matrix=convolution_matrix  | -matrixfile=filename[,file‐
11       name[, ...]]  } [-normalize] [-bias=n]
12
13       [netpbmfile]
14
15       pnmconvol convolution_matrix_file [-normalize] [-nooffset] [netpbmfile]
16
17       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
22
23

DESCRIPTION

25       This program is part of Netpbm(1).
26
27       pnmconvol  reads a Netpbm image as input, convolves it with a specified
28       convolution matrix, and writes a Netpbm image as output.
29
30       A command use for convolution is blurring.  See examples  in  the  pam‐
31       gauss(1) manual.
32
33
34       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
40       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
52       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
56       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
62       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
68
69
70   Convolution Matrix
71       There are three ways to specify the convolution matrix:
72
73
74
75       •      directly with a -matrix option.
76
77
78       •      In a file (or set of them) named by a -matrixfile option,  whose
79              contents are similar to a -matrix option value.
80
81
82       •      With a special PNM file.
83
84
85       The  PNM  file  option  is  the  hardest, and exists only because until
86       Netpbm 10.49 (December 2009), it was the only way.
87
88       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
94       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
97       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
103       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
108       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
113
114       Directly On the Command Line
115
116       Here are examples of a -matrix option:
117
118           -matrix=0,.2,0;.2,.2,.2;0,.2,0
119
120
121           -matrix=-1,3,-1
122
123
124       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
131       Note that when you supply this option  via  a  shell,  semicolon  (";")
132       probably means something to the shell, so use quotation marks.
133
134       There  is no way with this method to have different weights for differ‐
135       ent components of a pixel.
136
137       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
143
144       Regular Matrix File
145
146       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
149       Examples:
150
151           -matrixfile=mymatrix
152
153           -matrixfile=myred,mygreen,myblue
154
155
156       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
161       pnmconvol interprets the file as text, with  lines  delimited  by  Unix
162       newline characters (line feeds).
163
164       Each  line  of  the file is one row of the matrix, in order from top to
165       bottom.
166
167       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
174       There  is no way to put comments in the file.  There is no signature or
175       any other metadata in the file.
176
177       Note that if you use the -normalize option, the weights in  the  matrix
178       aren't actually what is in the file.
179
180
181       PNM File
182
183       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
193       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
198       There are two ways pnmconvol interprets the PNM convolution matrix  im‐
199       age pixels as weights: with offsets, and without offsets.
200
201       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
205       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
209           P2
210           3 3
211           18
212           2 2 2
213           2 2 2
214           2 2 2
215
216
217       (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
221       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
227       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
230       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
238       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
246           P2
247           3 3
248           18
249           10 10 10
250           10 10 10
251           10 10 10
252
253
254       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
259       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
263       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
268
269
270   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
275       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
279       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
283
284

OPTIONS

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
291
292
293
294       -matrix=convolution_matrix
295              The value of the convolution  matrix.   See  Convolution  Matrix
296              ⟨#matrixopt⟩ .
297
298              You may not specify both this and -matrixfile.
299
300              This  option  was  new  in Netpbm 10.49 (December 2009).  Before
301              that, use a PNM file for the convolution matrix.
302
303
304       -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
309              You may not specify both this and -matrix.
310
311              This option was new in Netpbm  10.49  (December  2009).   Before
312              that, use a PNM file for the convolution matrix.
313
314
315       -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
323              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
330              Example:
331
332                  $ pnmconvol myimage.ppm -normalize -matrix=1,1,1;1,1,1;1,1,1
333
334
335              This is of course a basic 3x3 average, but without you having to
336              specify 1/9 (.1111111) for each weight.
337
338              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
342
343       -bias=n
344
345              This specifies an amount to add to the convolved value for  each
346              sample.
347
348              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
357              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
361              A typical value for the bias is half the  maxval,  allowing  the
362              same range on either side of zero.
363
364              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
368              The default is zero.
369
370              This option was new in Netpbm 10.68 (September 2014).
371
372
373       -nooffset=
374              This  is part of the obsolete PNM image method of specifying the
375              convolution matrix.  See Convolution Matrix ⟨#matrixpnm⟩ .
376
377
378
379

HISTORY

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
391

SEE ALSO

393       pnmsmooth(1),  pgmmorphconv(1),  pgmmedian(1),  pnmnlfilt(1),   pgmker‐
394       nel(1), pamgauss(1), pammasksharpen(1), pnmpad(1), pamcut(1), pnm(1)
395
396

AUTHORS

398       Copyright  (C)  1989, 1991 by Jef Poskanzer.  Modified 26 November 1994
399       by Mike Burns, burns@chem.psu.edu
400

DOCUMENT SOURCE

402       This manual page was generated by the Netpbm tool 'makeman'  from  HTML
403       source.  The master documentation is at
404
405              http://netpbm.sourceforge.net/doc/pnmconvol.html
406
407netpbm documentation           30 November 2018       Pnmconvol User Manual(0)
Impressum