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 ⟨#convolutionmatrix⟩ .
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
48       enlarged 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
90       requires you to manage a separate file.  With the file,  you  can  have
91       separate  convolution  matrices  for  the  individual color components,
92       which 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           -matrix=-1,3,-1
121
122       The  value consists of each row of the matrix from top to bottom, sepa‐
123       rated by semicolons.  Each row consists of the elements of the row from
124       left  to  right, separated by commas.  You must of course have the same
125       number of elements in each row.  Each element  is  a  decimal  floating
126       point  number  and  is  the weight to give to each component of a pixel
127       that corresponds to that matrix location.
128
129       Note that when you supply this option  via  a  shell,  semicolon  (";")
130       probably means something to the shell, so use quotation marks.
131
132       There  is no way with this method to have different weights for differ‐
133       ent components of a pixel.
134
135       The -normalize option is often quite handy with -matrix because it lets
136       you  quickly throw together the command without working out the math to
137       make sure the matrix isn't biased.  Note that if you use the -normalize
138       option, the weights in the matrix aren't actually the numbers you spec‐
139       ify in the -matrix option.
140
141
142       Regular Matrix File
143
144       Specify the name of the matrix file  with  a  -matrixfile  option.   Or
145       specify a list of them, one for each plane of the image.
146
147       Examples:
148
149           -matrixfile=mymatrix
150
151           -matrixfile=myred,mygreen,myblue
152
153       Each file applies to one plane of the image (e.g. red, green, or blue),
154       in order.  The matrix in each file must have the same  dimensions.   If
155       the  input  image has more planes than the number of files you specify,
156       the first file applies to the extra planes as well.
157
158       pnmconvol interprets the file as text, with  lines  delimited  by  Unix
159       newline characters (line feeds).
160
161       Each  line  of  the file is one row of the matrix, in order from top to
162       bottom.
163
164       For each row, the file contains a floating  point  decimal  number  for
165       each element in the row, from left to right, separated by spaces.  This
166       is not just any old white space -- it is exactly one space.  Two spaces
167       in  a  row mean you've specified a null string for an element (which is
168       invalid).  If you want to line up your matrix visually, use leading and
169       trailing zeroes in the floating point numbers to do it.
170
171       There  is no way to put comments in the file.  There is no signature or
172       any other metadata in the file.
173
174       Note that if you use the -normalize option, the weights in  the  matrix
175       aren't actually what is in the file.
176
177
178       PNM File
179
180       Before Netpbm 10.49 (December 2009), this was the only way to specify a
181       convolution matrix.  pnmconvol  used  this  method  in  an  attempt  to
182       exploit  the  generic  matrix processing capabilities of Netpbm, but as
183       the Netpbm formats don't directly allow matrices with the kinds of num‐
184       bers  you  need  in  a  convolution matrix, it is quite cumbersome.  In
185       fact, there simply is no way to specify some convolution matrices  with
186       a  legal  Netpbm  image, so to make it work, pnmconvol has to relax the
187       Netpbm file requirement that sample  values  be  no  greater  than  the
188       image's maxval.  I.e. it isn't even a real PNM file.
189
190       The  way  you select this method of supplying the convolution matrix is
191       to not specify -matrix or -matrixfile.  When  you  do  that,  you  must
192       specify  a  second  non-option  argument -- that is the name of the PNM
193       file (or PNM equivalent PAM file).
194
195       There are two ways pnmconvol  interprets  the  PNM  convolution  matrix
196       image pixels as weights: with offsets, and without offsets.
197
198       The  simpler  of the two is without offsets.  That is what happens when
199       you specify the -nooffset option.  In that case, pnmconvol simply  nor‐
200       malizes the sample values in the PNM image by dividing by the maxval.
201
202       For  example,  here  is a sample convolution file that causes an output
203       pixel to be a simple average of its corresponding input pixel and its 8
204       neighbors, resulting in a smoothed image:
205
206           P2
207           3 3
208           18
209           2 2 2
210           2 2 2
211           2 2 2
212
213       (Note  that  the  above  text  is an actual PGM file -- you can cut and
214       paste it.  If you're not familiar with the plain PGM  format,  see  the
215       PGM format specification(1)).
216
217       pnmconvol  divides  each of the sample values (2) by the maxval (18) so
218       the weight of each of the 9 input pixels gets is 1/9, which is  exactly
219       what  you  want  to  keep the overall brightness of the image the same.
220       pnmconvol creates an output pixel by multiplying the values of each  of
221       9 pixels by 1/9 and adding.
222
223       Note  that  with  maxval  18,  the range of possible values is 0 to 18.
224       After scaling, the range is 0 to 1.
225
226       For a normal convolution, where you're neither adding  nor  subtracting
227       total value from the image, but merely moving it around, you'll want to
228       make sure that all the scaled values in (each plane of)  your  convolu‐
229       tion  PNM  add up to 1, which means all the actual sample values add up
230       to the maxval.  Alternatively, you can use  the  -normalize  option  to
231       scale  the scaled values further to make them all add up to 1 automati‐
232       cally.
233
234       When you don't specify -nooffset, pnmconvol applies an offset, the pur‐
235       pose  of which is to allow you to indicate negative weights even though
236       PNM sample values are never negative.  In  this  case,  pnmconvol  sub‐
237       tracts half the maxval from each sample and then normalizes by dividing
238       by half the maxval.  So to get the same result as  we  did  above  with
239       -nooffset,  the  convolution  matrix  PNM image would have to look like
240       this:
241
242           P2
243           3 3
244           18
245           10 10 10
246           10 10 10
247           10 10 10
248
249       To see how this works, do the above-mentioned offset: 10 -  18/2  gives
250       1.   The  normalization  step divides by 18/2 = 9, which makes it 1/9 -
251       exactly what you want.  The equivalent matrix for 5x5  smoothing  would
252       have maxval 50 and be filled with 26.
253
254       Note  that  with  maxval  18,  the range of possible values is 0 to 18.
255       After offset, that's -9 to 9, and after normalizing, the range is -1 to
256       1.
257
258       The  convolution  file will usually be a PGM, so that the same convolu‐
259       tion gets applied to each color component.  However, if you want to use
260       a  PPM and do a different convolution to different colors, you can cer‐
261       tainly do that.
262
263
264
265   Other Forms of Convolution
266       pnmconvol does only arithmetic, linear combination convolution.   There
267       are other forms of convolution that are especially useful in image pro‐
268       cessing.
269
270       pgmmedian does median filtering, which is a form of  convolution  where
271       the  output  pixel value, rather than being a linear combination of the
272       pixels in the window, is the median of a certain subset of them.
273
274       pgmmorphconv does dilation and erosion, which is like the median filter
275       but  the  output  value  is the minimum or maximum of the values in the
276       window.
277
278
279

OPTIONS

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

HISTORY

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

SEE ALSO

381       pnmsmooth(1),  pgmmorphconv(1),  pgmmedian(1),  pnmnlfilt(1),   pgmker‐
382       nel(1), pamgauss(1), pammasksharpen(1), pnmpad(1), pamcut(1), pnm(1)
383
384

AUTHORS

386       Copyright  (C)  1989, 1991 by Jef Poskanzer.  Modified 26 November 1994
387       by Mike Burns, burns@chem.psu.edu
388

DOCUMENT SOURCE

390       This manual page was generated by the Netpbm tool 'makeman'  from  HTML
391       source.  The master documentation is at
392
393              http://netpbm.sourceforge.net/doc/pnmconvol.html
394
395netpbm documentation           30 November 2018       Pnmconvol User Manual(0)
Impressum