Manual: pnmconvol
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[, ...]] } [-normalize] [-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 separate 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 avâ
erage are determined by the convolution matrix (sometimes called a convolution kernel), which you supply in one of
several ways. See Convolution Matrix .
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 better to deal with the pixels near an edge by asâ
suming 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 convoluâ
tion matrix is 5 wide by 3 high, use pnmpad -left=2 -right=2 -top=1 -bottom=1). Feed that enlarged image to pnmconâ
vol, 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 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 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 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 matriâ
ces 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 imâ
age, 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 quoâ
tation 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 together the command withâ
out 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 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, sepâ
arated 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 exploit 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 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 equivalent 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 -nooffset 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 average of its correspondâ
ing 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 allow you to indicate negaâ
tive weights even though PNM sample values are never negative. In this case, pnmconvol subtracts 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 normalizâ
ing, 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. Howâ
ever, if you want to use a PPM and do a different convolution to different 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 espeâ
cially 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 certain subset of them.
pgmmorphconv does dilation and erosion, which is like the median filter but the output value is the minimum or maxiâ
mum of the values in the window.
OPTIONS
In addition to the options common to all programs based on libnetpbm (most notably -quiet, see Common Options ), pnâ
mconvol recognizes the following command line options:
-matrix=convolution_matrix
The value of the convolution matrix. See Convolution Matrix .
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 .
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. Because the convolution maâ
trix can contain negative numbers, the convolved value for a pixel could be negative. But Netpbm formats canâ
not contain negative sample values, so without any bias, such samples would get clipped to zero. The bias alâ
lows 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 exâ
ceeds 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 Convolution Matrix .
HISTORY
The -nooffset option was new in Netpbm 10.23 (July 2004), making it substantially easier to specify a convolution maâ
trix, 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 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), pammasksharpen(1), pnmpad(1),
pamcut(1), pnm(1)
AUTHORS
Copyright (C) 1989, 1991 by Jef Poskanzer. Modified 26 November 1994 by Mike Burns, burns@chem.psu.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)