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       Convolution means replacing each pixel with a weighted average  of  the
31       nearby  pixels.   The weights and the area to average are determined by
32       the convolution matrix (sometimes called a convolution  kernel),  which
33       you supply in one of several ways.  See
34        Convolution Matrix ⟨#convolutionmatrix⟩ .
35
36       At the edges of the convolved image, where the convolution matrix would
37       extend over the edge of the image, pnmconvol just copies the input pix‐
38       els  directly to the output.  It's often better to deal with the pixels
39       near an edge by assuming some blank  or  background  color  beyond  the
40       edge.   To do that, use pnmpad to add a margin all around whose size is
41       half that of your convolution matrix size, not counting its center,  in
42       the  same  dimension.   (E.g. if your convolution matrix is 5 wide by 3
43       high,  use  pnmpad  -left=2  -right=2  -top=1  -bottom=1).   Feed  that
44       enlarged  image to pnmconvol, then use pamcut to chop the edges off the
45       convolved output, getting  back  to  your  original  image  dimensions.
46       (E.g.  pamcut -left=2 -right=-2 -top=1 -bottom=-1).
47
48       The  convolution computation can result in a value which is outside the
49       range representable in the output.  When that happens,  pnmconvol  just
50       clips the output, which means brightness is not conserved.
51
52       To  avoid clipping, you may want to scale your input values.  For exam‐
53       ple, if your convolution matrix might produce an output value  as  much
54       as  double the maximum value in the input, then make sure the maxval of
55       the input (which is also the maxval of the output) is  at  least  twice
56       the actual maximum value in the input.
57
58       Clipping negative numbers deserves special consideration.  If your con‐
59       volution matrix includes negative numbers, it is possible for pnmconvol
60       to calculate an output pixel as a negative value, which pnmconvol would
61       of course clip to zero, since Netpbm formats cannot represent  negative
62       numbers.
63
64
65
66   Convolution Matrix
67       There are three ways to specify the convolution matrix:
68
69
70
71       ·      directly with a -matrix option.
72
73
74       ·      In  a file (or set of them) named by a -matrixfile option, whose
75              contents are similar to a -matrix option value.
76
77
78       ·      With a special PNM file.
79
80
81       The PNM file option is the  hardest,  and  exists  only  because  until
82       Netpbm 10.49 (December 2009), it was the only way.
83
84       The regular convolution matrix file is slightly easier to read than the
85       -matrix option value, and makes  your  command  line  less  messy,  but
86       requires  you  to  manage a separate file.  With the file, you can have
87       separate convolution matrices  for  the  individual  color  components,
88       which you can't do with -matrix.
89
90       In  any case, the convolution matrix pnmconvol uses is a matrix of real
91       numbers.  They can be whole or fractional, positive, negative, or zero.
92
93       The convolution matrix always has an odd  width  and  height,  so  that
94       there  is  a center element.  pnmconvol figuratively places that center
95       element over a pixel of the input image and weights that pixel and  its
96       neighbors  as  indicated by the convolution matrix to produce the pixel
97       in the same location of the output image.
98
99       For a normal convolution, where you're neither adding  nor  subtracting
100       total value from the image, but merely moving it around, you'll want to
101       make sure that all the numbers in the matrix add  up  to  1.   If  they
102       don't, pnmconvol warns you.
103
104       The  elements of the matrix are actually tuples, one for each sample in
105       the input.  (I.e. if the input is an RGB image,  each  element  of  the
106       convolution  matrix  has one weight for red, one for green, and one for
107       blue.
108
109
110       Directly On the Command Line
111
112       Here are examples of a -matrix option:
113
114           -matrix=0,.2,0;.2,.2,.2;0,.2,0
115
116           -matrix=-1,3,-1
117
118       The value consists of each row of the matrix from top to bottom,  sepa‐
119       rated by semicolons.  Each row consists of the elements of the row from
120       left to right, separated by commas.  You must of course have  the  same
121       number  of  elements  in  each row.  Each element is a decimal floating
122       point number and is the weight to give to each  component  of  a  pixel
123       that corresponds to that matrix location.
124
125       Note  that  when  you  supply  this option via a shell, semicolon (";")
126       probably means something to the shell, so use quotation marks.
127
128       There is no way with this method to have different weights for  differ‐
129       ent components of a pixel.
130
131       The -normalize option is often quite handy with -matrix because it lets
132       you quickly throw together the command without working out the math  to
133       make sure the matrix isn't biased.  Note that if you use the -normalize
134       option, the weights in the matrix aren't actually the numbers you spec‐
135       ify in the -matrix option.
136
137
138       Regular Matrix File
139
140       Specify  the  name  of  the  matrix file with a -matrixfile option.  Or
141       specify a list of them, one for each plane of the image.
142
143       Examples:
144
145           -matrixfile=mymatrix
146
147           -matrixfile=myred,mygreen,myblue
148
149       Each file applies to one plane of the image (e.g. red, green, or blue),
150       in  order.   The matrix in each file must have the same dimensions.  If
151       the input image has more planes than the number of files  you  specify,
152       the first file applies to the extra planes as well.
153
154       pnmconvol  interprets  the  file  as text, with lines delimited by Unix
155       newline characters (line feeds).
156
157       Each line of the file is one row of the matrix, in order  from  top  to
158       bottom.
159
160       For  each  row,  the  file contains a floating point decimal number for
161       each element in the row, from left to right, separated by spaces.  This
162       is not just any old white space -- it is exactly one space.  Two spaces
163       in a row mean you've specified a null string for an element  (which  is
164       invalid).  If you want to line up your matrix visually, use leading and
165       trailing zeroes in the floating point numbers to do it.
166
167       There is no way to put comments in the file.  There is no signature  or
168       any other metadata in the file.
169
170       Note  that  if you use the -normalize option, the weights in the matrix
171       aren't actually what is in the file.
172
173
174       PNM File
175
176       Before Netpbm 10.49 (December 2009), this was the only way to specify a
177       convolution  matrix.   pnmconvol  used  this  method  in  an attempt to
178       exploit the generic matrix processing capabilities of  Netpbm,  but  as
179       the Netpbm formats don't directly allow matrices with the kinds of num‐
180       bers you need in a convolution matrix,  it  is  quite  cumbersome.   In
181       fact,  there simply is no way to specify some convolution matrices with
182       a legal Netpbm image, so to make it work, pnmconvol has  to  relax  the
183       Netpbm  file  requirement  that  sample  values  be no greater than the
184       image's maxval.  I.e. it isn't even a real PNM file.
185
186       The way you select this method of supplying the convolution  matrix  is
187       to  not  specify  -matrix  or  -matrixfile.  When you do that, you must
188       specify a second non-option argument -- that is the  name  of  the  PNM
189       file (or PNM equivalent PAM file).
190
191       There  are  two  ways  pnmconvol  interprets the PNM convolution matrix
192       image pixels as weights: with offsets, and without offsets.
193
194       The simpler of the two is without offsets.  That is what  happens  when
195       you  specify the -nooffset option.  In that case, pnmconvol simply nor‐
196       malizes the sample values in the PNM image by dividing by the maxval.
197
198       For example, here is a sample convolution file that  causes  an  output
199       pixel to be a simple average of its corresponding input pixel and its 8
200       neighbors, resulting in a smoothed image:
201
202           P2
203           3 3
204           18
205           2 2 2
206           2 2 2
207           2 2 2
208
209       (Note that the above text is an actual PGM file  --  you  can  cut  and
210       paste  it.   If  you're not familiar with the plain PGM format, see the
211       PGM format specification(1)).
212
213       pnmconvol divides each of the sample values (2) by the maxval  (18)  so
214       the  weight of each of the 9 input pixels gets is 1/9, which is exactly
215       what you want to keep the overall brightness of  the  image  the  same.
216       pnmconvol  creates an output pixel by multiplying the values of each of
217       9 pixels by 1/9 and adding.
218
219       Note that with maxval 18, the range of possible  values  is  0  to  18.
220       After scaling, the range is 0 to 1.
221
222       For  a  normal convolution, where you're neither adding nor subtracting
223       total value from the image, but merely moving it around, you'll want to
224       make  sure  that all the scaled values in (each plane of) your convolu‐
225       tion PNM add up to 1, which means all the actual sample values  add  up
226       to  the  maxval.   Alternatively,  you can use the -normalize option to
227       scale the scaled values further to make them all add up to 1  automati‐
228       cally.
229
230       When you don't specify -nooffset, pnmconvol applies an offset, the pur‐
231       pose of which is to allow you to indicate negative weights even  though
232       PNM  sample  values  are  never negative.  In this case, pnmconvol sub‐
233       tracts half the maxval from each sample and then normalizes by dividing
234       by  half  the  maxval.   So to get the same result as we did above with
235       -nooffset, the convolution matrix PNM image would  have  to  look  like
236       this:
237
238           P2
239           3 3
240           18
241           10 10 10
242           10 10 10
243           10 10 10
244
245       To  see  how this works, do the above-mentioned offset: 10 - 18/2 gives
246       1.  The normalization step divides by 18/2 = 9, which makes  it  1/9  -
247       exactly  what  you want.  The equivalent matrix for 5x5 smoothing would
248       have maxval 50 and be filled with 26.
249
250       Note that with maxval 18, the range of possible  values  is  0  to  18.
251       After offset, that's -9 to 9, and after normalizing, the range is -1 to
252       1.
253
254       The convolution file will usually be a PGM, so that the  same  convolu‐
255       tion gets applied to each color component.  However, if you want to use
256       a PPM and do a different convolution to different colors, you can  cer‐
257       tainly do that.
258
259
260
261   Other Forms of Convolution
262       pnmconvol  does only arithmetic, linear combination convolution.  There
263       are other forms of convolution that are especially useful in image pro‐
264       cessing.
265
266       pgmmedian  does  median filtering, which is a form of convolution where
267       the output pixel value, rather than being a linear combination  of  the
268       pixels in the window, is the median of a certain subset of them.
269
270       pgmmorphconv does dilation and erosion, which is like the median filter
271       but the output value is the minimum or maximum of  the  values  in  the
272       window.
273
274
275

OPTIONS

277       -matrix=convolution_matrix
278              The  value  of  the  convolution matrix.  See Convolution Matrix
279              ⟨#matrixopt⟩ .
280
281              You may not specify both this and -matrixfile.
282
283              This option was new in Netpbm  10.49  (December  2009).   Before
284              that, use a PNM file for the convolution matrix.
285
286
287       -matrixfile=filename
288              This  specifies that you are supplying the convolution matrix in
289              a  file  and  names   that   file.    See   Convolution   Matrix
290              ⟨#matrixfile⟩ .
291
292              You may not specify both this and -matrix.
293
294              This  option  was  new  in Netpbm 10.49 (December 2009).  Before
295              that, use a PNM file for the convolution matrix.
296
297
298       -normalize
299              This option says to  adjust  the  weights  in  your  convolution
300              matrix  so they all add up to one.  You usually want them to add
301              up to one so that the convolved result tends to  have  the  same
302              overall  brightness  as  the  input.  With -normalize, pnmconvol
303              scales all the weights by the same factor to make the  sum  one.
304              It does this for each plane.
305
306              This  can be quite convenient because you can just throw numbers
307              into the matrix that have roughly the right relationship to each
308              other  and  let  pnmconvol do the work of normalizing them.  And
309              you can adjust a matrix by raising or lowering  certain  weights
310              without  having to modify all the other weights to maintain nor‐
311              malcy.  And you can use friendly integers.
312
313              Example:
314
315                  $ pnmconvol myimage.ppm -normalize -matrix=1,1,1;1,1,1;1,1,1
316
317              This is of course a basic 3x3 average, but without you having to
318              specify 1/9 (.1111111) for each weight.
319
320              This  option  was  new in Netpbm 10.50 (March 2010).  But before
321              Netpbm 10.79 (June 2017), it has no effect when you specify  the
322              convolution matrix via pseudo-PNM file.
323
324
325       -bias=n
326
327              This  specifies an amount to add to the convolved value for each
328              sample.
329
330              The purpose of this addition is normally to handle negative con‐
331              volution  results.   Because  the convolution matrix can contain
332              negative numbers, the convolved value for a pixel could be nega‐
333              tive.  But Netpbm formats cannot contain negative sample values,
334              so without any bias, such samples would  get  clipped  to  zero.
335              The  bias allows the output image to retain the information, and
336              a program that pocesses that output,  knowing  the  bias  value,
337              could reconstruct the real convolved values.
338
339              For example, with bias=100, a sample whose convolved value is -5
340              appears as 95 in the output, whereas a  sample  whose  convolved
341              value is 5 appears as 105 in the output.
342
343              A  typical  value  for the bias is half the maxval, allowing the
344              same range on either side of zero.
345
346              If the sample value, after adding the bias, is still  less  than
347              zero,  pnmconvol  clips it to zero.  If it exceeds the maxval of
348              the output image, it clips it to the maxval.
349
350              The default is zero.
351
352              This option was new in Netpbm 10.68 (September 2014).
353
354
355       -nooffset=
356              This is part of the obsolete PNM image method of specifying  the
357              convolution matrix.  See Convolution Matrix ⟨#matrixpnm⟩ .
358
359
360
361

HISTORY

363       The  -nooffset  option  was  new in Netpbm 10.23 (July 2004), making it
364       substantially easier to specify a convolution matrix, but  still  hard.
365       In Netpbm 10.49 (December 2009), the PNM convolution matrix tyranny was
366       finally ended with the -matrix and -matrixfile  options.   In  between,
367       pnmconvol  was  broken  for  a while because the Netpbm library started
368       enforcing the requirement that a sample value not exceed the maxval  of
369       the  image.  pnmconvol used the Netpbm library to read the PNM convolu‐
370       tion matrix file, but in the pseudo-PNM format that pnmconvol  uses,  a
371       sample value sometimes has to exceed the maxval.
372
373
374

SEE ALSO

376       pnmsmooth(1),   pgmmorphconv(1),  pgmmedian(1),  pnmnlfilt(1),  pgmker‐
377       nel(1), pamgauss(1), pammasksharpen(1), pnmpad(1), pamcut(1), pnm(1)
378
379

AUTHORS

381       Copyright (C) 1989, 1991 by Jef Poskanzer.  Modified 26  November  1994
382       by Mike Burns, burns@chem.psu.edu
383

DOCUMENT SOURCE

385       This  manual  page was generated by the Netpbm tool 'makeman' from HTML
386       source.  The master documentation is at
387
388              http://netpbm.sourceforge.net/doc/pnmconvol.html
389
390netpbm documentation             30 April 2017        Pnmconvol User Manual(0)
Impressum