.TL
Pnmconvol User Manual
.SH 1
pnmconvol
.LP
Updated: 29 June 2005
.br
Table Of Contents
.SH 2
NAME
.LP
pnmconvol - general MxN convolution on a PNM image
.SH 2
SYNOPSIS
.LP
\fBpnmconvol\fR
\fIconvolution_matrix_file\fR
[-nooffset]
[\fIpnmfile\fR]
.LP
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.
.SH 2
DESCRIPTION
.LP
.LP
This program is part of Netpbm.
.LP
\fBpnmconvol\fR reads two PNM images as input, convolves the
second using the first, and writes a PNM image as output.
.LP
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 by way of the PNM image in the file you identify with
the \fIconvolution_matrix_file\fR argument.  There are two ways
\fBpnmconvol\fR interprets the PNM convolution matrix image pixels as
weights: with offsets, and without offsets.
.LP
The simpler of the two is without offsets.  That is what happens
when you specify the \fB-nooffset\fR option.  In that case,
\fBpnmconvol\fR simply normalizes the sample values in the PNM image
by dividing by the maxval.
.LP
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:
.DS L
    P2
    3 3
    18
    2 2 2
    2 2 2
    2 2 2
.DE
.LP
(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).
.LP
\fBpnmconvol\fR 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.  \fBpnmconvol\fR creates an output pixel by multiplying the
values of each of 9 pixels by 1/9 and adding.
.LP
Note that with maxval 18, the range of possible values is 0 to 18.
After scaling, the range is 0 to 1.
.LP
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.
.LP
When you don't specify \fB-nooffset\fR, \fBpnmconvol\fR
applies an offset, the purpose of which is to allow you to indicate
negative weights even though PNM sample values are never negative.  In
this case, \fBpnmconvol\fR 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 \fB-nooffset\fR, the convolution
matrix PNM image would have to look like this:
.DS L
    P2
    3 3
    18
    10 10 10
    10 10 10
    10 10 10
.DE
.LP
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.
.LP
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.
.LP
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 offset, scaled values in (each
plane of) your convolution PNM add up to 1.  That means the actual
sample values, less half the maxval, add up to half the maxval as in
the example above.
.LP
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 different
colors, you can certainly do that.
.LP
At the edges of the convolved image, where the convolution matrix
would extend over the edge of the image, \fBpnmconvol\fR just copies
the input pixels directly to the output.
.LP
The convolution computation can result in a value which is outside the
range representable in the output.  When that happens, \fBpnmconvol\fR just
clips the output, which means brightness is not conserved.
.SH 2
HISTORY
.LP
.LP
The \fB-nooffset\fR option was new in Netpbm 10.23 (July 2004).
.SH 2
SEE ALSO
.LP
\fBpnmsmooth\fR,
\fBpgmmorphconv\fR,
\fBpnmnlfilt\fR,
\fBpgmkernel\fR,
\fBpamgauss\fR,
\fBpnm\fR
.SH 2
AUTHORS
.LP
Copyright (C) 1989, 1991 by Jef Poskanzer.
.br
Modified 26 November 1994 by Mike Burns, burns@chem.psu.edu
.br
\l'5i'
.SH 2
Table Of Contents
.LP
.IP \(bu
NAME
.IP \(bu
SYNOPSIS
.IP \(bu
DESCRIPTION
.IP \(bu
SEE ALSO
.IP \(bu
HISTORY
.IP \(bu
AUTHORS
.LP