Tune Netpbm Image Smoothing and Edge Enhancement with pnmnlfilt

You will apply a repeatable non-linear filter to a PNM image, choose the mode from the alpha value, and check the output without overwriting the source. The examples use Netpbm 11.5.2, installed here as Debian package version 2:11.05.02-1.1build1. Allow about fifteen minutes for a first pass and a visual check.

You need a shell, the netpbm package, and a readable PGM, PPM or another PNM image. This guide reads and writes image files as an ordinary user. It does not need sudo. Keep the original image until you have inspected the result.

1. Check the installed command

Confirm that the command in your PATH is the one you expect, then record the package version:

$ command -v pnmnlfilt
/usr/bin/pnmnlfilt
$ pnmnlfilt -version
pnmnlfilt: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
...
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1

The version command also prints build details, so the final lines can differ. The installed manual describes the interface as pnmnlfilt alpha radius [pnmfile]. There are no pnmnlfilt-specific long options for selecting a mode. The input file is optional: if you omit it, the program reads a PNM stream from standard input, and it writes the filtered PNM image to standard output.

$ pnmfile original.pgm
original.pgm: PGM raw, 1920 by 1080  maxval 255

Use the actual filename and expect the dimensions and format to vary. If pnmfile cannot identify the input, convert it to PGM or PPM with an appropriate Netpbm tool first. Do not feed an arbitrary JPEG or PNG directly to pnmnlfilt.

2. Start with a subtle smoothing pass

For an alpha-trimmed mean filter, use an alpha between 0.0 and 0.5. A value of 0.0 averages the surrounding samples. A value of 0.5 keeps the middle value of the sorted samples, which behaves like a median filter and is useful for isolated pixel noise.

The radius must be between 1/3 and 1.0. It controls the size of the seven hexagonal sampling areas. A radius near 1.0 covers roughly the immediate 3 by 3 neighbourhood; a radius of 1/3 has little or no filtering effect. Start small so that detail is easier to preserve:

$ pnmnlfilt 0.0 0.55 original.pgm > smoothed.pgm
$ pnmfile smoothed.pgm
smoothed.pgm: PGM raw, 1920 by 1080  maxval 255

That redirection creates a new file and leaves original.pgm alone. The command normally prints no progress message because the image is its standard output. A zero exit status means the filter completed; it does not tell you whether the image looks good.

$ pnmnlfilt 0.0 0.55 original.pgm > smoothed.pgm.new
$ pnmfile smoothed.pgm.new
$ mv -- smoothed.pgm.new smoothed.pgm

If the filter fails, the original smoothed.pgm is still present and the incomplete smoothed.pgm.new can be discarded. If you replaced a file and need to undo it, restore it from your backup or regenerate it from the unchanged source with the previous parameters.

3. Use the median mode for isolated noise

Speckles and single-pixel defects can spread when you average them. Try alpha 0.5 instead, with a moderate radius:

$ pnmnlfilt 0.5 0.6 original.pgm > median.pgm
$ pnmfile median.pgm
median.pgm: PGM raw, 1920 by 1080  maxval 255

On the installed command, this completed successfully for a small PGM test image and produced a valid raw PGM stream. The exact pixel values depend on the source, dimensions, maxval and image edges. Inspect median.pgm in an image viewer or pass it to the next tool in your workflow. If fine lines disappear, reduce the radius or return to a lower alpha-trimmed mean value.

4. Let local variance control smoothing

For dither or quantisation noise in bitmap and colour images, choose optimal estimation smoothing with an alpha between 1.0 and 2.0. It estimates local variance and applies less smoothing where the image has stronger features. The manual recommends keeping the radius around 0.8 to 1.0 for this calculation:

$ pnmnlfilt 1.2 1.0 original.ppm > estimated.ppm
$ pnmfile estimated.ppm
estimated.ppm: PPM raw, 1920 by 1080  maxval 255

Lower alpha values make the effect more subtle; higher values smooth more of the image. Several passes with decreasing alpha values can be more useful than one aggressive pass, but every pass can remove detail. Keep each intermediate output if you may need to compare or recover it.

5. Add edge enhancement only after testing the filter

Negative alpha selects edge enhancement. The useful range is -0.1 to -0.9, with values closer to -0.1 producing a subtler effect. Use a radius around 0.5 to 0.9:

$ pnmnlfilt -0.2 0.8 estimated.ppm > sharpened.ppm
$ pnmfile sharpened.ppm
sharpened.ppm: PPM raw, 1920 by 1080  maxval 255

Edge enhancement is the opposite of smoothing and is usually more useful after an alpha-trimmed or optimal-estimation pass. It can make halos and noise more visible. Compare the output with the unsharpened image before using it in a batch job or publishing it. If the effect is too strong, regenerate from estimated.ppm with alpha nearer to -0.1, rather than sharpening the already sharpened file.

6. Diagnose rejected parameters

A parameter outside the mode's range is rejected before a useful output is produced. For example, 0.6 is not a valid alpha for the alpha-trimmed mean mode:

$ pnmnlfilt 0.6 0.6 original.pgm > failed.pgm
pnmnlfilt: Alpha must be in range 0.0 <= alpha <= 0.5 for alpha trimmed mean. You specified 0.600000
$ printf 'exit status: %s\n' "$?"
exit status: 1

The error text identifies the selected range. A radius below 1/3 is also rejected. Check the decimal values, the order of the two arguments, and whether a leading minus sign selected edge enhancement accidentally. If the output path already existed, check it: shell redirection may have emptied it even though the filter failed. This is another reason to use a new .new path during experiments.