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[, ...]]  } [netpbmfile]
12
13       pnmconvol convolution_matrix_file [-nooffset] [netpbmfile]
14
15       Minimum unique abbreviation of option is acceptable.  You may use  dou‐
16       ble  hyphens  instead  of single hyphen to denote options.  You may use
17       white space in place of the equals sign to separate an option name from
18       its value.
19
20
21

DESCRIPTION

23       This program is part of Netpbm(1).
24
25       pnmconvol reads a Netpbm images as input, convolves it with a specified
26       convolution matrix, and writes a Netpbm image as output.
27
28       Convolution means replacing each pixel with a weighted average  of  the
29       nearby  pixels.   The weights and the area to average are determined by
30       the convolution matrix (sometimes called a convolution  kernel),  which
31       you supply in one of several ways.  See
32        Convolution Matrix ⟨#convolutionmatrix⟩ .
33
34       At the edges of the convolved image, where the convolution matrix would
35       extend over the edge of the image, pnmconvol just copies the input pix‐
36       els directly to the output.
37
38       The  convolution computation can result in a value which is outside the
39       range representable in the output.  When that happens,  pnmconvol  just
40       clips the output, which means brightness is not conserved.
41
42
43
44   Convolution Matrix
45       There are three ways to specify the convolution matrix:
46
47
48
49       ·      directly with a -matrix option.
50
51
52       ·      In  a file (or set of them) named by a -matrixfile option, whose
53              contents are similar to a -matrix option value.
54
55
56       ·      With a special PNM file.
57
58
59       The PNM file option is the  hardest,  and  exists  only  because  until
60       Netpbm 10.49 (December 2009), it was the only way.
61
62       The regular convolution matrix file is slightly easier to read than the
63       -matrix option value, and makes  your  command  line  less  messy,  but
64       requires  you  to  manage a separate file.  With the file, you can have
65       separate convolution matrices  for  the  individual  color  components,
66       which you can't do with -matrix.
67
68       In  any case, the convolution matrix pnmconvol uses is a matrix of real
69       numbers.  They can be whole or fractional, positive, negative, or zero.
70
71       The convolution matrix always has an odd  width  and  height,  so  that
72       there  is  a center element.  pnmconvol figuratively places that center
73       element over a pixel of the input image and weights that pixel and  its
74       neighbors  as  indicated by the convolution matrix to produce the pixel
75       in the same location of the output image.
76
77       For a normal convolution, where you're neither adding  nor  subtracting
78       total value from the image, but merely moving it around, you'll want to
79       make sure that all the numbers in the matrix add  up  to  1.   If  they
80       don't, pnmconvol warns you.
81
82       The  elements of the matrix are actually tuples, one for each sample in
83       the input.  (I.e. if the input is an RGB image,  each  element  of  the
84       convolution  matrix  has one weight for red, one for green, and one for
85       blue.
86
87
88       Directly On the Command Line
89
90       An example of a -matrixopt option is
91
92           -matrixopt=.1,.1,.1;.1,0,.1;.1,.1,.1
93
94       The value consists of each row of the matrix from top to bottom,  sepa‐
95       rated by semicolons.  Each row consists of the elements of the row from
96       left to right, separated by commas.  You must of course have  the  same
97       number  of  elements  in  each row.  Each element is a decimal floating
98       point number and is the weight to give to each  component  of  a  pixel
99       that corresponds to that matrix location.
100
101       There  is no way with this method to have different weights for differ‐
102       ent components of a pixel.
103
104
105       Regular Matrix File
106
107       Specify the name of the matrix file  with  a  -matrixfile  option.   Or
108       specify a list of them, one for each plane of the image.
109
110       Examples:
111
112           -matrixfile=mymatrix
113
114           -matrixfile=myred,mygreen,myblue
115
116       Each file applies to one plane of the image (e.g. red, green, or blue),
117       in order.  The matrix in each file must have the same  dimensions.   If
118       the  input  image has more planes than the number of files you specify,
119       the first file applies to the extra planes as well.
120
121       pnmconvol interprets the file as text, with  lines  delimited  by  Unix
122       newline characters (line feeds).
123
124       Each  line  of  the file is one row of the matrix, in order from top to
125       bottom.
126
127       For each row, the file contains a floating  point  decimal  number  for
128       each element in the row, from left to right, separated by spaces.  This
129       is not just any old white space -- it is exactly one space.  Two spaces
130       in  a  row mean you've specified a null string for an element (which is
131       invalid).  If you want to line up your matrix visually, use leading and
132       trailing zeroes in the floating point numbers to do it.
133
134       There  is no way to put comments in the file.  There is no signature or
135       any other metadata in the file.
136
137
138       PNM File
139
140       Before Netpbm 10.49 (December 2009), this was the only way to specify a
141       convolution  matrix.   pnmconvol  used  this  method  in  an attempt to
142       exploit the generic matrix processing capabilities of  Netpbm,  but  as
143       the Netpbm formats don't directly allow matrices with the kinds of num‐
144       bers you need in a convolution matrix,  it  is  quite  cumbersome.   In
145       fact,  there simply is no way to specify some convolution matrices with
146       a legal Netpbm image, so make it  work,  pnmconvol  has  to  relax  the
147       Netpbm  file  requirement  that  sample  values  be no greater than the
148       image's maxval.  I.e. it isn't even a real PNM file.
149
150       The way you select this method of supplying the convolution  matrix  is
151       to  not  specify  -matrix  or  -matrixfile.  When you do that, you must
152       specify a second non-option argument -- that is the  name  of  the  PNM
153       file (or PNM equivalent PAM file).
154
155       There  are  two  ways  pnmconvol  interprets the PNM convolution matrix
156       image pixels as weights: with offsets, and without offsets.
157
158       The simpler of the two is without offsets.  That is what  happens  when
159       you  specify the -nooffset option.  In that case, pnmconvol simply nor‐
160       malizes the sample values in the PNM image by dividing by the maxval.
161
162       For example, here is a sample convolution file that  causes  an  output
163       pixel to be a simple average of its corresponding input pixel and its 8
164       neighbors, resulting in a smoothed image:
165
166           P2
167           3 3
168           18
169           2 2 2
170           2 2 2
171           2 2 2
172
173       (Note that the above text is an actual PGM file  --  you  can  cut  and
174       paste  it.  If you're not familiar with the plain PGM format, see theP‐
175       GMformatspecification(1)).
176
177       pnmconvol divides each of the sample values (2) by the maxval  (18)  so
178       the  weight of each of the 9 input pixels gets is 1/9, which is exactly
179       what you want to keep the overall brightness of  the  image  the  same.
180       pnmconvol  creates an output pixel by multiplying the values of each of
181       9 pixels by 1/9 and adding.
182
183       Note that with maxval 18, the range of possible  values  is  0  to  18.
184       After scaling, the range is 0 to 1.
185
186       For  a  normal convolution, where you're neither adding nor subtracting
187       total value from the image, but merely moving it around, you'll want to
188       make  sure  that all the scaled values in (each plane of) your convolu‐
189       tion PNM add up to 1, which means all the actual sample values  add  up
190       to the maxval.
191
192       When you don't specify -nooffset, pnmconvol applies an offset, the pur‐
193       pose of which is to allow you to indicate negative weights even  though
194       PNM  sample  values  are  never negative.  In this case, pnmconvol sub‐
195       tracts half the maxval from each sample and then normalizes by dividing
196       by  half  the  maxval.   So to get the same result as we did above with
197       -nooffset, the convolution matrix PNM image would  have  to  look  like
198       this:
199
200           P2
201           3 3
202           18
203           10 10 10
204           10 10 10
205           10 10 10
206
207       To  see  how this works, do the above-mentioned offset: 10 - 18/2 gives
208       1.  The normalization step divides by 18/2 = 9, which makes  it  1/9  -
209       exactly  what  you want.  The equivalent matrix for 5x5 smoothing would
210       have maxval 50 and be filled with 26.
211
212       Note that with maxval 18, the range of possible  values  is  0  to  18.
213       After offset, that's -9 to 9, and after normalizing, the range is -1 to
214       1.
215
216       The convolution file will usually be a PGM, so that the  same  convolu‐
217       tion gets applied to each color component.  However, if you want to use
218       a PPM and do a different convolution to different colors, you can  cer‐
219       tainly do that.
220
221

OPTIONS

223       -matrix=convolution_matrix
224              The  value  of  the  convolution matrix.  See Convolution Matrix
225              ⟨#matrixopt⟩ .
226
227              You may not specify both this and -matrixfile.
228
229              This option was new in Netpbm  10.49  (December  2009).   Before
230              that, use a PNM file for the convolution matrix.
231
232
233       -matrixfile=filename
234              This  specifies that you are supplying the convolution matrix in
235              a  file  and  names   that   file.    See   Convolution   Matrix
236              ⟨#matrixfile⟩ .
237
238              You may not specify both this and -matrix.
239
240              This  option  was  new  in Netpbm 10.49 (December 2009).  Before
241              that, use a PNM file for the convolution matrix.
242
243
244
245       -nooffset=
246              This is part of the obsolete PNM image method of specifying  the
247              convolution matrix.  See Convolution Matrix ⟨#matrixpnm⟩ .
248
249
250
251

HISTORY

253       The  -nooffset  option  was  new in Netpbm 10.23 (July 2004), making it
254       substantially easier to specify a convolution matrix, but  still  hard.
255       In Netpbm 10.49 (December 2009), the PNM convolution matrix tyranny was
256       finally ended with the -matrix and -matrixfile  options.   In  between,
257       pnmconvol  was  broken  for  a while because the Netpbm library started
258       enforcing the requirement that a sample value not exceed the maxval  of
259       the  image.  pnmconvol used the Netpbm library to read the PNM convolu‐
260       tion matrix file, but in the pseudo-PNM format that pnmconvol  uses,  a
261       sample value sometimes has to exceed the maxval.
262
263
264

SEE ALSO

266       pnmsmooth(1), pgmmorphconv(1), pnmnlfilt(1), pgmkernel(1), pamgauss(1),
267       pammasksharpen(1), pnm(1)
268
269

AUTHORS

271       Copyright (C) 1989, 1991 by Jef Poskanzer.  Modified 26  November  1994
272       by Mike Burns, burns@chem.psu.edu
273
274
275
276netpbm documentation           07 December 2009       Pnmconvol User Manual(0)
Impressum