\
.\" 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 "Pnmnlfilt User Manual" 0 "24 October 2006" "netpbm documentation"

.SH NAME

pnmnlfilt - non-linear filters: smooth, alpha trim mean, optimal
estimation smoothing, edge enhancement.

.UN synopsis
.SH SYNOPSIS

\fBpnmnlfilt\fP
\fIalpha\fP
\fIradius\fP
[\fIpnmfile\fP]

.UN description
.SH DESCRIPTION
.PP
This program is part of
.BR "Netpbm" (1)\c
\&.
.PP
\fBpnmnlfilt\fP produces an output image where the pixels are a
summary of multiple pixels near the corresponding location in an input
image.
.PP
This program works on multi-image streams.
.PP
This is something of a swiss army knife filter.  It has 3 distinct
operating modes.  In all of the modes \fBpnmnlfilt\fP examines each
pixel in the image and processes it according to the values of it and
its surrounding pixels.  Rather than using a square block of
surrounding pixels (e.g. the subject pixel and its 8 immediate
neighbors, in a 3x3 square), \fBpnmnlfilt\fP uses 7 hexagonal areas.
You choose the size of the hexagons with the radius parameter.  A
radius value of 1/3 means that the 7 hexagons essentially fit into the
subject pixel (ie.  there will be no filtering effect).  A radius
value of 1.0 means that the 7 hexagons essentially cover the 3x3
immediate neighbor square.
.PP
Your choice of "alpha" parameter selects among the three
modes.

.UN alphatrimmedmean
.SS 
Alpha trimmed mean filter (0.0 <= alpha <= 0.5)
.PP
The value of the center pixel will be replaced by the mean of
the 7 hexagon values, but the 7 values are sorted by size and the top
and bottom alpha portion of the 7 are excluded from the mean.  This
implies that an alpha value of 0.0 gives the same sort of output as a
normal convolution (ie. averaging or smoothing filter), where radius
will determine the "strength" of the filter. A good value to
start from for subtle filtering is alpha = 0.0, radius = 0.55 For a
more blatant effect, try alpha 0.0 and radius 1.0
.PP
An alpha value of 0.5 will cause the median value of the 7 hexagons
to be used to replace the center pixel value. This sort of filter is
good for eliminating "pop" or single pixel noise from an
image without spreading the noise out or smudging features on the
image. Judicious use of the radius parameter will fine tune the
filtering. Intermediate values of alpha give effects somewhere between
smoothing and "pop" noise reduction. For subtle filtering
try starting with values of alpha = 0.4, radius = 0.6 For a more
blatant effect try alpha = 0.5, radius = 1.0

.UN optimalestsmooth
.SS 
Optimal estimation smoothing. (1.0 <= alpha <= 2.0)
.PP
This type of filter applies a smoothing filter adaptively over the
image.  For each pixel the variance of the surrounding hexagon values
is calculated, and the amount of smoothing is made inversely
proportional to it. The idea is that if the variance is small then it
is due to noise in the image, while if the variance is large, it is
because of "wanted" image features. As usual the radius
parameter controls the effective radius, but it probably advisable to
leave the radius between 0.8 and 1.0 for the variance calculation to
be meaningful.  The alpha parameter sets the noise threshold, over
which less smoothing will be done.  This means that small values of
alpha will give the most subtle filtering effect, while large values
will tend to smooth all parts of the image. You could start with
values like alpha = 1.2, radius = 1.0 and try increasing or decreasing
the alpha parameter to get the desired effect. This type of filter is
best for filtering out dithering noise in both bitmap and color
images.

.UN edgeenhance
.SS Edge enhancement. (-0.1 >= alpha >= -0.9)
.PP
This is the opposite type of filter to the smoothing filter. It
enhances edges. The alpha parameter controls the amount of edge
enhancement, from subtle (-0.1) to blatant (-0.9). The radius
parameter controls the effective radius as usual, but useful values
are between 0.5 and 0.9. Try starting with values of alpha = 0.3,
radius = 0.8

.UN combination
.SS Combination use.
.PP
The various modes of \fBpnmnlfilt\fP can be used one after the
other to get the desired result. For instance to turn a monochrome
dithered image into a grayscale image you could try one or two passes
of the smoothing filter, followed by a pass of the optimal estimation
filter, then some subtle edge enhancement. Note that using edge
enhancement is only likely to be useful after one of the non-linear
filters (alpha trimmed mean or optimal estimation filter), as edge
enhancement is the direct opposite of smoothing.
.PP
For reducing color quantization noise in images (ie. turning .gif
files back into 24 bit files) you could try a pass of the optimal
estimation filter (alpha 1.2, radius 1.0), a pass of the median filter
(alpha 0.5, radius 0.55), and possibly a pass of the edge enhancement
filter.  Several passes of the optimal estimation filter with
declining alpha values are more effective than a single pass with a
large alpha value.  As usual, there is a tradeoff between filtering
effectiveness and losing detail. Experimentation is encouraged.

.UN options
.SH OPTIONS
.PP
There are no command line options defined specifically
for \fBpnmnlfilt\fP, but it recognizes the options common to all
programs based on libnetpbm (See 
.UR index.html#commonoptions
 Common Options
.UE
\&.)

.UN references
.SH REFERENCES
.PP
The alpha-trimmed mean filter is based on the description in IEEE
CG&A May 1990 Page 23 by Mark E. Lee and Richard A. Redner, and
has been enhanced to allow continuous alpha adjustment.
.PP
The optimal estimation filter is taken from an article
"Converting Dithered Images Back to Gray Scale" by Allen
Stenger, Dr Dobb's Journal, November 1992, and this article references
"Digital Image Enhancement and Noise Filtering by Use of Local
Statistics", Jong-Sen Lee, IEEE Transactions on Pattern Analysis
and Machine Intelligence, March 1980.
.PP
The edge enhancement details are from
.BR "pgmenhance" (1)\c
\&, which is taken from Philip
R. Thompson's "xim" program, which in turn took it from
section 6 of "Digital Halftones by Dot Diffusion",
D. E. Knuth, ACM Transaction on Graphics Vol. 6, No. 4, October 1987,
which in turn got it from two 1976 papers by J. F. Jarvis et. al.

.UN parameters
.SH PARAMETERS
.PP
The parameters are:


.TP
\fIalpha\fP
The alpha value (described above), in decimal.  May be fractional.

.TP
\fIradius\fP
The radius (described above), in decimal.  May be fractional.


.UN seealso
.SH SEE ALSO
.BR "pgmenhance" (1)\c
\&,
.BR "pnmconvol" (1)\c
\&,
.BR "pnm" (1)\c
\&

.UN author
.SH AUTHOR

Graeme W. Gill \fIgraeme@labtam.oz.au\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/pnmnlfilt.html
.PP