path: root/upstream/opensuse-leap-15-6/man1/pnmconvol.1

\
.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
.\" the corresponding HTML page on the Netpbm website, generate a patch
.\" against that, and send it to the Netpbm maintainer.
.TH "Pnmconvol User Manual" 0 "30 April 2017" "netpbm documentation"

.SH NAME

pnmconvol - general MxN convolution on a Netpbm image

.UN synopsis
.SH SYNOPSIS

\fBpnmconvol\fP
{
\fB-matrix=\fP\fIconvolution_matrix\fP
|
\fB-matrixfile=\fP\fIfilename\fP[\fB,\fP\fIfilename\fP[\fB,\fP ...]]
}
[\fB-normalize\fP]
[\fB-bias=\fIn\fP\fP]

[\fInetpbmfile\fP]
.PP
\fBpnmconvol\fP
\fIconvolution_matrix_file\fP
[\fB-normalize\fP]
[\fB-nooffset\fP]
[\fInetpbmfile\fP]
.PP
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.


.UN description
.SH DESCRIPTION
.PP
This program is part of
.BR "Netpbm" (1)\c
\&.
.PP
\fBpnmconvol\fP reads a Netpbm image as input, convolves it with
a specified convolution matrix, and writes a Netpbm image as output.
.PP
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 
.UR #convolutionmatrix
 Convolution Matrix
.UE
\&.
.PP
At the edges of the convolved image, where the convolution matrix would
extend over the edge of the image, \fBpnmconvol\fP just copies the input
pixels 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 \fBpnmpad\fP 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
\f(CWpnmpad -left=2 -right=2 -top=1 -bottom=1\fP).  Feed that enlarged
image to \fBpnmconvol\fP, then use \fBpamcut\fP to chop the edges off the
convolved output, getting back to your original image dimensions.  (E.g.
\f(CWpamcut -left=2 -right=-2 -top=1 -bottom=-1\fP).
.PP
The convolution computation can result in a value which is outside the
range representable in the output.  When that happens, \fBpnmconvol\fP just
clips the output, which means brightness is not conserved.
.PP
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.
.PP
Clipping negative numbers deserves special consideration.  If your
convolution matrix includes negative numbers, it is possible for
\fBpnmconvol\fP to calculate an output pixel as a negative value,
which \fBpnmconvol\fP would of course clip to zero, since Netpbm formats
cannot represent negative numbers.


.UN convolutionmatrix
.SS Convolution Matrix
.PP
There are three ways to specify the convolution matrix:


.IP \(bu
directly with a \fB-matrix\fP option.

.IP \(bu
In a file (or set of them) named by a \fB-matrixfile\fP option, whose
contents are similar to a \fB-matrix\fP option value.

.IP \(bu
With a special PNM file.

.PP
The PNM file option is the hardest, and exists only because
until Netpbm 10.49 (December 2009), it was the only way.
.PP
The regular convolution matrix file is slightly easier to read
than the \fB-matrix\fP 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 \fB-matrix\fP.
.PP
In any case, the convolution matrix \fBpnmconvol\fP uses is a
matrix of real numbers.  They can be whole or fractional, positive,
negative, or zero.
.PP
The convolution matrix always has an odd width and height, so that
there is a center element.  \fBpnmconvol\fP 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.
.PP
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,
\fBpnmconvol\fP warns you.
.PP
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.


.UN matrixopt
.B Directly On the Command Line
.PP
Here are examples of a \fB-matrix\fP option:

.nf
\f(CW
    -matrix=0,.2,0;.2,.2,.2;0,.2,0
\fP
.fi

.nf
\f(CW
    -matrix=-1,3,-1
\fP
.fi
.PP
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.
.PP
Note that when you supply this option via a shell, semicolon
(";") probably means something to the shell, so use quotation
marks.
.PP
There is no way with this method to have different weights for different
components of a pixel.
.PP
The \fB-normalize\fP option is often quite handy with \fB-matrix\fP
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
\fB-normalize\fP option, the weights in the matrix aren't actually the
numbers you specify in the \fB-matrix\fP option.


.UN matrixfile
.B Regular Matrix File
.PP
Specify the name of the matrix file with a \fB-matrixfile\fP
option.  Or specify a list of them, one for each plane of the image.
.PP
Examples:

.nf
\f(CW
    -matrixfile=mymatrix
\fP

\f(CW
    -matrixfile=myred,mygreen,myblue
\fP
.fi
.PP
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.
.PP
\fBpnmconvol\fP interprets the file as text, with lines delimited by Unix
newline characters (line feeds).
.PP
Each line of the file is one row of the matrix, in order from top to
bottom.
.PP
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.
.PP
There is no way to put comments in the file.  There is no signature
or any other metadata in the file.
.PP
Note that if you use the \fB-normalize\fP option, the weights in the
matrix aren't actually what is in the file.


.UN matrixpnm
.B PNM File
.PP
Before Netpbm 10.49 (December 2009), this was the only way to 
specify a convolution matrix.  \fBpnmconvol\fP 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, \fBpnmconvol\fP 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.
.PP
The way you select this method of supplying the convolution matrix is to
\fInot\fP specify \fB-matrix\fP or \fB-matrixfile\fP.  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).
.PP
There are two ways \fBpnmconvol\fP interprets the PNM convolution matrix
image pixels as weights: with offsets, and without offsets.
.PP
The simpler of the two is without offsets.  That is what happens
when you specify the \fB-nooffset\fP option.  In that case,
\fBpnmconvol\fP simply normalizes the sample values in the PNM image
by dividing by the maxval.
.PP
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:

.nf
    P2
    3 3
    18
    2 2 2
    2 2 2
    2 2 2
.fi
.PP
(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
.BR "the PGM format specification" (5)\c
\&).
.PP
\fBpnmconvol\fP 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\fP creates an output pixel by multiplying the
values of each of 9 pixels by 1/9 and adding.
.PP
Note that with maxval 18, the range of possible values is 0 to 18.
After scaling, the range is 0 to 1.
.PP
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
\fB-normalize\fP option to scale the scaled values further to make them all
add up to 1 automatically.
.PP
When you \fIdon't\fP specify \fB-nooffset\fP, \fBpnmconvol\fP
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\fP 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\fP, the convolution
matrix PNM image would have to look like this:

.nf
    P2
    3 3
    18
    10 10 10
    10 10 10
    10 10 10
.fi
.PP
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.
.PP
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.
.PP
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.


.UN otherconvol
.SS Other Forms of Convolution
.PP
\fBpnmconvol\fP does only arithmetic, linear combination convolution.
There are other forms of convolution that are especially useful in image
processing.
.PP
\fBpgmmedian\fP 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.
.PP
\fBpgmmorphconv\fP 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.


.UN options
.SH OPTIONS



.TP
\fB-matrix=\fP\fIconvolution_matrix\fP
The value of the convolution matrix.  See
.UR #matrixopt
Convolution Matrix
.UE
\&.
.sp
You may not specify both this and \fB-matrixfile\fP.
.sp
This option was new in Netpbm 10.49 (December 2009).  Before
that, use a PNM file for the convolution matrix.

.TP
\fB-matrixfile=\fP\fIfilename\fP
This specifies that you are supplying the convolution matrix in
a file and names that file.  See
.UR #matrixfile
Convolution Matrix
.UE
\&.
.sp
You may not specify both this and \fB-matrix\fP.
.sp
This option was new in Netpbm 10.49 (December 2009).  Before
that, use a PNM file for the convolution matrix.

.TP
\fB-normalize\fP
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
\fB-normalize\fP, \fBpnmconvol\fP scales all the weights by the same factor
to make the sum one.  It does this for each plane.
.sp
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
\fBpnmconvol\fP 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.
.sp
Example:

.nf
\f(CW
    $ pnmconvol myimage.ppm -normalize -matrix=1,1,1;1,1,1;1,1,1
\fP
.fi
.sp
This is of course a basic 3x3 average, but without you having to
specify 1/9 (.1111111) for each weight.
.sp
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.

.TP
\fB-bias=\fP\fIn\fP
.sp
This specifies an amount to add to the convolved value for each sample.
.sp
The purpose of this addition is normally to handle negative convolution
results.  Because 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.
.sp
For example, with \fBbias=100\fP, 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.
.sp
A typical value for the bias is half the maxval, allowing the same range on
either side of zero.
.sp
If the sample value, after adding the bias, is still less than
zero, \fBpnmconvol\fP clips it to zero.  If it exceeds the maxval of the
output image, it clips it to the maxval.
.sp
The default is zero.
.sp
This option was new in Netpbm 10.68 (September 2014).

.TP
\fB-nooffset=\fP
This is part of the obsolete PNM image method of specifying the
convolution matrix.  See
.UR #matrixpnm
Convolution Matrix
.UE
\&.



.UN history
.SH HISTORY 
.PP
The \fB-nooffset\fP 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 \fB-matrix\fP and
\fB-matrixfile\fP options.  In between, \fBpnmconvol\fP was broken for a
while because the Netpbm library started enforcing the requirement that a
sample value not exceed the maxval of the image.  \fBpnmconvol\fP used the
Netpbm library to read the PNM convolution matrix file, but in the pseudo-PNM
format that \fBpnmconvol\fP uses, a sample value sometimes has to exceed
the maxval.


.UN seealso
.SH SEE ALSO
.BR "pnmsmooth" (1)\c
\&,
.BR "pgmmorphconv" (1)\c
\&,
.BR "pgmmedian" (1)\c
\&,
.BR "pnmnlfilt" (1)\c
\&,
.BR "pgmkernel" (1)\c
\&,
.BR "pamgauss" (1)\c
\&,
.BR "pammasksharpen" (1)\c
\&,
.BR "pnmpad" (1)\c
\&,
.BR "pamcut" (1)\c
\&,
.BR "pnm" (5)\c
\&

.UN authors
.SH AUTHORS

Copyright (C) 1989, 1991 by Jef Poskanzer.
Modified 26 November 1994 by Mike Burns, \fIburns@chem.psu.edu\fP
.SH DOCUMENT SOURCE
This manual page was generated by the Netpbm tool 'makeman' from HTML
source.  The master documentation is at
.IP
.B http://netpbm.sourceforge.net/doc/pnmconvol.html
.PP