Pnmconvol User Manual(0)			      Pnmconvol User Manual(0)



NAME
       pnmconvol - general MxN convolution on a Netpbm image


SYNOPSIS
       pnmconvol  {  -matrix=convolution_matrix	 | -matrixfile=filename[,file-
       name[, ...]]  } [netpbmfile]

       pnmconvol convolution_matrix_file [-nooffset] [netpbmfile]

       Minimum unique abbreviation of option is acceptable.  You may use  dou-
       ble  hyphens  instead  of single hyphen to denote options.  You may use
       white space in place of the equals sign to separate an option name from
       its value.



DESCRIPTION
       This program is part of Netpbm(1).

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

       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
	Convolution Matrix <#convolutionmatrix> .

       At the edges of the convolved image, where the convolution matrix would
       extend over the edge of the image, pnmconvol just copies the input pix-
       els directly to the output.

       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.



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



       o      directly with a -matrix option.


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


       o      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 matrix 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

       An example of a -matrixopt option is

	   -matrixopt=.1,.1,.1;.1,0,.1;.1,.1,.1

       The value consists of each row of the matrix from top to bottom,	 sepa-
       rated 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.

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


       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 number 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 exactly 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.


       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 capabilities of  Netpbm,  but  as
       the Netpbm formats don't directly allow matrices with the kinds of num-
       bers 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 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 a second non-option argument -- that is the  name  of  the  PNM
       file (or PNM equivalent PAM file).

       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 -nooffset option.  In that case, pnmconvol simply nor-
       malizes 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 average 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 theP-
       GMformatspecification(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 convolu-
       tion PNM add up to 1, which means all the actual sample values  add  up
       to the maxval.

       When you don't specify -nooffset, pnmconvol applies an offset, the pur-
       pose of which is to allow you to indicate negative weights even	though
       PNM  sample  values  are	 never negative.  In this case, pnmconvol sub-
       tracts half the maxval from each sample and then normalizes by dividing
       by  half	 the  maxval.	So to get the same result as we did above with
       -nooffset, the convolution 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  convolu-
       tion gets applied to each color component.  However, if you want to use
       a PPM and do a different convolution to different colors, you can  cer-
       tainly do that.


OPTIONS
       -matrix=convolution_matrix
	      The  value  of  the  convolution matrix.	See Convolution Matrix
	      <#matrixopt> .

	      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	  Convolution	Matrix
	      <#matrixfile> .

	      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.



       -nooffset=
	      This is part of the obsolete PNM image method of specifying  the
	      convolution matrix.  See Convolution Matrix <#matrixpnm> .




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 convolution matrix tyranny was
       finally ended with the -matrix and -matrixfile  options.	  In  between,
       pnmconvol  was  broken  for  a while because the Netpbm library started
       enforcing the requirement that a sample value not exceed the maxval  of
       the  image.  pnmconvol used the Netpbm library to read the PNM convolu-
       tion 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), pnmnlfilt(1), pgmkernel(1), pamgauss(1),
       pammasksharpen(1), pnm(1)


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



netpbm documentation	       07 December 2009	      Pnmconvol User Manual(0)