\
.\" 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 "Pgmkernel User Manual" 1 "19 December 2013" "netpbm documentation"

.SH NAME
pgmkernel - generate a convolution kernel

.UN synopsis
.SH SYNOPSIS
.PP
\fBpgmkernel\fP
[\fB-weight=\fP\fInumber\fP]
[\fB-maxval=\fP] {\fIsize\fP | \fIwidth\fP \fIheight\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
\fBpgmkernel\fP generates a convolution kernel that you can use
with \fBpnmconvol\fP.  The kernel is one where the weight of each location
is inversely proportional to its distance from the center of the kernel.
.PP
\fBpgmkernel\fP generates a PGM image of width and height \fIsize\fP
if you specify one argument, or width \fIwidth\fP and height \fIheight\fP
if you specify two arguments.
.PP
\fBpgmkernel\fP computes the convolution function K as follows.

.RS
K(i,j) = 1 / ( 1 + w * sqrt(i^2 + j^2)) 
.RE

where \fIw\fP is a coefficient specified via the \fB-weight\fP
option.  \fIi\fP and \fIj\fP are measured in pixels.  K is zero
everywhere beyond the specified kernel width and height.
.PP
The sample values in the PGM output have this value scaled and biased using
the protocol \fBpnmconvol\fP specifies for representing the real numbers K
in PGM.


.UN options
.SH OPTIONS
.PP
In addition to the options common to all programs based on libnetpbm
(most notably \fB-quiet\fP, see 
.UR index.html#commonoptions
 Common Options
.UE
\&), \fBpgmkernel\fP recognizes the following
command line options:


.TP
\fB-weight=\fP\fInumber\fP
The distance from the center is weighted by this; a higher number means
the value falls off more quickly as you go away from the center.
.sp
This must be a positive real number.
.sp
The default is 6.0.

.TP
\fB-maxval=\fP\fImaxval\fP
The maxval for the PGM kernel.
.sp
Default is 255.
.sp
This option was new in Netpbm 10.65 (December 2013).  Before that, the
maxval is always 255.
    



.UN limitations
.SH LIMITATIONS
.PP
The computation time is proportional to \fIwidth\fP*\fIheight\fP.
This increases rapidly with the increase of the kernel size.  A better
approach could be using a FFT in these cases.

.UN history
.SH HISTORY
.PP
Before Netpbm 10.65 (December 2013), the output was always in
Plain (text) PGM format.  (Now, like standard Netpbm programs, the default
is raw PGM and you can get Plain PGM with a \fB-plain\fP option).
.PP
Before Netpbm 10.65 (December 2013), this manual said negative values
for \fB-weight\fP were valid (as long as they were greater than -1.0).  But
the program never worked with negative numbers and it isn't clear that the
result would be useful, so \fB-weight\fP is now required to be nonnegative
and the program fails gracefully if you specify a negative value.

.UN seealso
.SH SEE ALSO
.BR "pnmconvol" (1)\c
\&,
.BR "pnmsmooth" (1)\c
\&
.BR "pamgauss" (1)\c
\&
.BR "pgm" (1)\c
\&


.UN author
.SH AUTHOR

Alberto Accomazzi (\fIalberto@cfa.harvard.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/pgmkernel.html
.PP