man > pnmconvol(1)

Pnmconvol User Manual(1)               General Commands Manual              Pnmconvol User Manual(1)

NAME
       pnmconvol - general MxN convolution on a Netpbm image


SYNOPSIS
       pnmconvol  { -matrix=convolution_matrix | -matrixfile=filename[,filename[, ...]]  } [-normal‐
       ize] [-bias=n]

       [netpbmfile]

       pnmconvol convolution_matrix_file [-normalize] [-nooffset] [netpbmfile]

       Minimum unique abbreviation of option is acceptable.  You may use double hyphens  instead  of
       single hyphen to denote options.  You may use white space in place of the equals sign to sep‐
       arate an option name from its value.



DESCRIPTION
       This program is part of Netpbm(1).

       pnmconvol  reads  a  Netpbm image as input, convolves it with a specified convolution matrix,
       and writes a Netpbm image as output.

       A command use for convolution is blurring.  See examples in the pamgauss(1) manual.


       Convolution means replacing each pixel with a weighted average of  the  nearby  pixels.   The
       weights  and the area to average are determined by the convolution matrix (sometimes called a
       convolution kernel), which you supply in one of several ways.  See ]8;;#convolmatrix\ Convolution Matrix]8;;\ .

       At the edges of the convolved image, where the convolution matrix would extend over the  edge
       of the image, pnmconvol just copies the input pixels directly to the output.  It's often bet‐
       ter  to  deal  with the pixels near an edge by assuming some blank or background color beyond
       the edge.  To do that, use pnmpad to add a margin all around whose size is half that of  your
       convolution  matrix size, not counting its center, in the same dimension.  (E.g. if your con‐
       volution matrix is 5 wide by 3 high, use pnmpad -left=2  -right=2  -top=1  -bottom=1).   Feed
       that enlarged image to pnmconvol, then use pamcut to chop the edges off the convolved output,
       getting back to your original image dimensions.  (E.g.  pamcut -left=2 -right=-2 -top=1 -bot‐
       tom=-1).

       The convolution computation can result in a value which is outside the range representable in
       the  output.   When  that happens, pnmconvol just clips the output, which means brightness is
       not conserved.

       To avoid clipping, you may want to scale your input values.  For example, if your convolution
       matrix might produce an output value as much as double the maximum value in the  input,  then
       make  sure the maxval of the input (which is also the maxval of the output) is at least twice
       the actual maximum value in the input.

       Clipping negative numbers deserves special consideration.  If  your  convolution  matrix  in‐
       cludes negative numbers, it is possible for pnmconvol to calculate an output pixel as a nega‐
       tive  value, which pnmconvol would of course clip to zero, since Netpbm formats cannot repre‐
       sent negative numbers.



   Convolution Matrix
       There are three ways to specify the convolution matrix:



       •      directly with a -matrix option.


       •      In a file (or set of them) named by a -matrixfile option, whose contents  are  similar
              to a -matrix option value.


       •      With a special PNM file.


       The  PNM  file  option  is  the hardest, and exists only because until Netpbm 10.49 (December
       2009), it was the only way.

       The regular convolution matrix file is slightly easier to read than the -matrix option value,
       and makes your command line less messy, but requires you to manage a separate file.  With the
       file, you can have separate convolution matrices for the individual color  components,  which
       you can't do with -matrix.

       In  any case, the convolution matrix pnmconvol uses is a matrix of real numbers.  They can be
       whole or fractional, positive, negative, or zero.

       The convolution matrix always has an odd width and height, so that there is a center element.
       pnmconvol figuratively places that center element over a pixel of the input image and weights
       that pixel and its neighbors as indicated by the convolution matrix to produce the  pixel  in
       the same location of the output image.

       For  a  normal  convolution, where you're neither adding nor subtracting total value from the
       image, but merely moving it around, you'll want to make sure that all the numbers in the  ma‐
       trix add up to 1.  If they don't, pnmconvol warns you.

       The  elements  of the matrix are actually tuples, one for each sample in the input.  (I.e. if
       the input is an RGB image, each element of the convolution matrix has one weight for red, one
       for green, and one for blue.


       Directly On the Command Line

       Here are examples of a -matrix option:

           -matrix=0,.2,0;.2,.2,.2;0,.2,0


           -matrix=-1,3,-1


       The value consists of each row of the matrix from top to  bottom,  separated  by  semicolons.
       Each  row  consists  of the elements of the row from left to right, separated by commas.  You
       must of course have the same number of elements in each  row.   Each  element  is  a  decimal
       floating point number and is the weight to give to each component of a pixel that corresponds
       to that matrix location.

       Note  that  when you supply this option via a shell, semicolon (";") probably means something
       to the shell, so use quotation marks.

       There is no way with this method to have different weights  for  different  components  of  a
       pixel.

       The -normalize option is often quite handy with -matrix because it lets you quickly throw to‐
       gether  the  command without working out the math to make sure the matrix isn't biased.  Note
       that if you use the -normalize option, the weights in the matrix aren't actually the  numbers
       you specify in the -matrix option.


       Regular Matrix File

       Specify  the  name  of the matrix file with a -matrixfile option.  Or specify a list of them,
       one for each plane of the image.

       Examples:

           -matrixfile=mymatrix

           -matrixfile=myred,mygreen,myblue


       Each file applies to one plane of the image (e.g. red, green, or blue), in order.  The matrix
       in each file must have the same dimensions.  If the input image has more planes than the num‐
       ber of files you specify, the first file applies to the extra planes as well.

       pnmconvol interprets the file as text, with lines delimited by Unix newline characters  (line
       feeds).

       Each line of the file is one row of the matrix, in order from top to bottom.

       For  each row, the file contains a floating point decimal number for each element in the row,
       from left to right, separated by spaces.  This is not just any old white space -- it  is  ex‐
       actly  one  space.   Two  spaces  in a row mean you've specified a null string for an element
       (which is invalid).  If you want to line up your matrix visually, use  leading  and  trailing
       zeroes in the floating point numbers to do it.

       There  is no way to put comments in the file.  There is no signature or any other metadata in
       the file.

       Note that if you use the -normalize option, the weights in the matrix aren't actually what is
       in the file.


       PNM File

       Before Netpbm 10.49 (December 2009), this was the only way to specify a  convolution  matrix.
       pnmconvol  used  this method in an attempt to exploit the generic matrix processing capabili‐
       ties of Netpbm, but as the Netpbm formats don't directly allow matrices  with  the  kinds  of
       numbers  you  need in a convolution matrix, it is quite cumbersome.  In fact, there simply is
       no way to specify some convolution matrices with a legal Netpbm image, so to  make  it  work,
       pnmconvol  has to relax the Netpbm file requirement that sample values be no greater than the
       image's maxval.  I.e. it isn't even a real PNM file.

       The way you select this method of supplying the convolution matrix is to not specify  -matrix
       or  -matrixfile.  When you do that, you must specify the name of the PNM file (or PNM equiva‐
       lent PAM file) as a non-option argument (before the optional input file name).

       There are two ways pnmconvol interprets the PNM convolution matrix image pixels  as  weights:
       with offsets, and without offsets.

       The simpler of the two is without offsets.  That is what happens when you specify the -nooff‐
       set  option.  In that case, pnmconvol simply normalizes the sample values in the PNM image by
       dividing by the maxval.

       For example, here is a sample convolution file that causes an output pixel to be a simple av‐
       erage of its corresponding input pixel and its 8 neighbors, resulting in a smoothed image:

           P2
           3 3
           18
           2 2 2
           2 2 2
           2 2 2


       (Note that the above text is an actual PGM file -- you can cut and paste it.  If  you're  not
       familiar with the plain PGM format, see the PGM format specification(1)).

       pnmconvol  divides  each of the sample values (2) by the maxval (18) so the weight of each of
       the 9 input pixels gets is 1/9, which is exactly what you want to keep the overall brightness
       of the image the same.  pnmconvol creates an output pixel by multiplying the values  of  each
       of 9 pixels by 1/9 and adding.

       Note  that with maxval 18, the range of possible values is 0 to 18.  After scaling, the range
       is 0 to 1.

       For a normal convolution, where you're neither adding nor subtracting total  value  from  the
       image,  but  merely  moving it around, you'll want to make sure that all the scaled values in
       (each plane of) your convolution PNM add up to 1, which means all the  actual  sample  values
       add  up  to the maxval.  Alternatively, you can use the -normalize option to scale the scaled
       values further to make them all add up to 1 automatically.

       When you don't specify -nooffset, pnmconvol applies an offset, the purpose of which is to al‐
       low you to indicate negative weights even though PNM sample values are  never  negative.   In
       this case, pnmconvol subtracts half the maxval from each sample and then normalizes by divid‐
       ing by half the maxval.  So to get the same result as we did above with -nooffset, the convo‐
       lution matrix PNM image would have to look like this:

           P2
           3 3
           18
           10 10 10
           10 10 10
           10 10 10


       To  see  how this works, do the above-mentioned offset: 10 - 18/2 gives 1.  The normalization
       step divides by 18/2 = 9, which makes it 1/9 - exactly what you want.  The equivalent  matrix
       for 5x5 smoothing would have maxval 50 and be filled with 26.

       Note  that  with maxval 18, the range of possible values is 0 to 18.  After offset, that's -9
       to 9, and after normalizing, the range is -1 to 1.

       The convolution file will usually be a PGM, so that the same convolution gets applied to each
       color component.  However, if you want to use a PPM and do a different convolution to differ‐
       ent colors, you can certainly do that.



   Other Forms of Convolution
       pnmconvol does only arithmetic, linear combination convolution.  There  are  other  forms  of
       convolution that are especially useful in image processing.

       pgmmedian does median filtering, which is a form of convolution where the output pixel value,
       rather  than  being a linear combination of the pixels in the window, is the median of a cer‐
       tain subset of them.

       pgmmorphconv does dilation and erosion, which is like the median filter but the output  value
       is the minimum or maximum of the values in the window.



OPTIONS
       In  addition  to  the options common to all programs based on libnetpbm (most notably -quiet,
       see ]8;;index.html#commonoptions\ Common Options]8;;\ ), pnmconvol recognizes the following command line options:




       -matrix=convolution_matrix
              The value of the convolution matrix.  See ]8;;#matrixopt\Convolution Matrix]8;;\ .

              You may not specify both this and -matrixfile.

              This option was new in Netpbm 10.49 (December 2009).  Before that, use a PNM file  for
              the convolution matrix.


       -matrixfile=filename
              This  specifies that you are supplying the convolution matrix in a file and names that
              file.  See ]8;;#matrixfile\Convolution Matrix]8;;\ .

              You may not specify both this and -matrix.

              This option was new in Netpbm 10.49 (December 2009).  Before that, use a PNM file  for
              the convolution matrix.


       -normalize
              This  option  says to adjust the weights in your convolution matrix so they all add up
              to one.  You usually want them to add up to one so that the convolved result tends  to
              have  the same overall brightness as the input.  With -normalize, pnmconvol scales all
              the weights by the same factor to make the sum one.  It does this for each plane.

              This can be quite convenient because you can just throw numbers into the  matrix  that
              have  roughly  the  right  relationship to each other and let pnmconvol do the work of
              normalizing them.  And you can adjust a matrix by raising or lowering certain  weights
              without  having to modify all the other weights to maintain normalcy.  And you can use
              friendly integers.

              Example:

                  $ pnmconvol myimage.ppm -normalize -matrix=1,1,1;1,1,1;1,1,1


              This is of course a  basic  3x3  average,  but  without  you  having  to  specify  1/9
              (.1111111) for each weight.

              This  option  was  new  in  Netpbm  10.50 (March 2010).  But before Netpbm 10.79 (June
              2017), it has no effect when you specify the convolution matrix via pseudo-PNM file.


       -bias=n

              This specifies an amount to add to the convolved value for each sample.

              The purpose of this addition is normally to handle negative convolution results.   Be‐
              cause  the  convolution matrix can contain negative numbers, the convolved value for a
              pixel could be negative.  But Netpbm formats cannot contain negative sample values, so
              without any bias, such samples would get clipped to zero.  The bias allows the  output
              image  to retain the information, and a program that pocesses that output, knowing the
              bias value, could reconstruct the real convolved values.

              For example, with bias=100, a sample whose convolved value is -5 appears as 95 in  the
              output, whereas a sample whose convolved value is 5 appears as 105 in the output.

              A  typical  value  for  the bias is half the maxval, allowing the same range on either
              side of zero.

              If the sample value, after adding the bias, is still less than zero,  pnmconvol  clips
              it to zero.  If it exceeds the maxval of the output image, it clips it to the maxval.

              The default is zero.

              This option was new in Netpbm 10.68 (September 2014).


       -nooffset=
              This  is  part  of the obsolete PNM image method of specifying the convolution matrix.
              See ]8;;#matrixpnm\Convolution Matrix]8;;\ .




HISTORY
       The -nooffset option was new in Netpbm 10.23 (July 2004), making it substantially  easier  to
       specify  a convolution matrix, but still hard.  In Netpbm 10.49 (December 2009), the PNM con‐
       volution matrix tyranny was finally ended with the -matrix and -matrixfile options.   In  be‐
       tween,  pnmconvol was broken for a while because the Netpbm library started enforcing the re‐
       quirement that a sample value not exceed the maxval of the image.  pnmconvol used the  Netpbm
       library  to read the PNM convolution matrix file, but in the pseudo-PNM format that pnmconvol
       uses, a sample value sometimes has to exceed the maxval.


SEE ALSO
       pnmsmooth(1), pgmmorphconv(1), pgmmedian(1), pnmnlfilt(1),  pgmkernel(1),  pamgauss(1),  pam‐
       masksharpen(1), pnmpad(1), pamcut(1), pnm(1)


AUTHORS
       Copyright  (C)  1989,  1991  by  Jef  Poskanzer.   Modified  26  November 1994 by Mike Burns,
       burns AT chem.edu

DOCUMENT SOURCE
       This manual page was generated by the Netpbm tool 'makeman' from  HTML  source.   The  master
       documentation is at

              http://netpbm.sourceforge.net/doc/pnmconvol.html

netpbm documentation                      30 November 2018                  Pnmconvol User Manual(1)