Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Pnmconvol User Manual(0)			      Pnmconvol	User Manual(0)

       pnmconvol - general MxN convolution on a	Netpbm image

       pnmconvol  {  -matrix=convolution_matrix	 | -matrixfile=filename[,file-
       name[, ...]]  } [-normalize] [-bias=n]


       pnmconvol convolution_matrix_file [-normalize] [-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.

       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  pam-
       gauss(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
	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.  It's often better 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 convolution matrix is	5  wide	 by  3
       high,  use  pnmpad  -left=2  -right=2 -top=1 -bottom=1).	 Feed that en-
       larged 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 -bottom=-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	 exam-
       ple,  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 con-
       volution	matrix includes	negative numbers, it is	possible for pnmconvol
       to calculate an output pixel as a negative value, which pnmconvol would
       of  course clip to zero,	since Netpbm formats cannot represent negative

   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 re-
       quires you to manage a separate file.  With the file, you can have sep-
       arate  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

       Directly	On the Command Line

       Here are	examples of a -matrix option:



       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.

       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 differ-
       ent components of a pixel.

       The -normalize option is	often quite handy with -matrix because it lets
       you  quickly throw together 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 spec-
       ify 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.




       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

       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.

       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  ex-
       ploit  the generic matrix processing capabilities 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  le-
       gal 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 max-
       val.  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  im-
       age 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:

	   3 3
	   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(5)).

       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.  Af-
       ter 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.  Alternatively, you can use  the	-normalize  option  to
       scale  the scaled values	further	to make	them all add up	to 1 automati-

       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

	   3 3
	   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.  Af-
       ter offset, that's -9 to	9, and after normalizing, the range is	-1  to

       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.

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

       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	certain	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

	      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.

	      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.

	      This  option  says to adjust the weights in your convolution ma-
	      trix 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 over-
	      all 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  nor-
	      malcy.  And you can use friendly integers.


		  $ 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.


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

	      The purpose of this addition is normally to handle negative con-
	      volution results.	 Because the convolution  matrix  can  contain
	      negative numbers,	the convolved value for	a pixel	could be nega-
	      tive.  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).

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

       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 en-
       forcing	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.

       pnmsmooth(1),  pgmmorphconv(1),	pgmmedian(1),  pnmnlfilt(1),   pgmker-
       nel(1), pamgauss(1), pammasksharpen(1), pnmpad(1), pamcut(1), pnm(5)

       Copyright  (C)  1989, 1991 by Jef Poskanzer.  Modified 26 November 1994
       by Mike Burns,

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

netpbm documentation	       30 November 2018	      Pnmconvol	User Manual(0)


Want to link to this manual page? Use this URL:

home | help