Smooth a Netpbm Image Safely with pnmsmooth

You will finish with a smoothed PNM image and a repeatable way to check that the result is valid. pnmsmooth replaces each pixel with the average of its neighbours, using a rectangular convolution matrix. Allow about ten minutes for a single image, including verification.

The examples use Netpbm 11.5.2, from package version 2:11.05.02-1.1build1 on this machine. You need a readable PNM input such as a PPM file, a shell, and a directory where you can write the output. Image conversion is normally an unprivileged operation. Do not use sudo unless the input or destination permissions genuinely require it.

1. Check the installed command

Confirm which binary will run and record its Netpbm version. These are read-only checks:

$ command -v pnmsmooth
/usr/bin/pnmsmooth
$ pnmsmooth --version 2>&1 | sed -n '1,2p'
pnmsmooth: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
pnmsmooth: Built from source dated 2024-03-31 09:09:47

The command accepts a PNM file argument and writes the smoothed image to standard output. If you omit the file argument, it can read the image from standard input, which is useful in a pipeline but makes it easier to lose track of the source and destination.

2. Preserve the source before writing output

Pick a new output name. Shell redirection with > truncates an existing destination before pnmsmooth starts, so do not point it at the original image or at the only copy of a useful result.

$ INPUT='/path/to/source.ppm'
$ OUTPUT='/path/to/source-smoothed.ppm'
$ test -r "$INPUT" && echo 'input is readable'
input is readable
$ test ! -e "$OUTPUT" && echo 'output name is unused'
output name is unused

If the destination already exists and you need to keep it, choose another name or make an explicit backup first:

$ cp --preserve=all "$OUTPUT" "$OUTPUT.bak"
$ pnmsmooth "$INPUT" > "$OUTPUT.new"
$ mv "$OUTPUT.new" "$OUTPUT"

The mv only replaces the old destination after the new file has been produced. If smoothing fails, leave the original destination in place and inspect the diagnostic. Removing a backup is irreversible, so do that separately after checking the image.

3. Smooth with the default 3 by 3 window

Run pnmsmooth with no size options. The default convolution matrix is three columns by three rows:

$ pnmsmooth "$INPUT" > "$OUTPUT"
pnmsmooth: Running Pnmconvol -normalize -matrix=1,1,1;1,1,1;1,1,1

The diagnostic is normally written to standard error while the image is written to standard output. Its wording identifies the normalised matrix, not a progress percentage. A successful command should leave a non-empty PNM file:

$ test -s "$OUTPUT" && echo 'output is non-empty'
output is non-empty
$ pamfile "$OUTPUT"
/path/to/source-smoothed.ppm:  PPM raw, 1600 by 1200  maxval 255

Your dimensions and whether the PPM is plain or raw will vary. The useful checks are that the file is recognised as a PNM image and that its dimensions are the ones you expect.

4. Choose a larger or non-square window

Use -width and -height when a 3 by 3 average is not the right amount of smoothing:

$ pnmsmooth -width=5 -height=3 "$INPUT" > "$OUTPUT"
pnmsmooth: Running Pnmconvol -normalize -matrix=1,1,1,1,1;1,1,1,1,1;1,1,1,1,1

These values describe the convolution window. They do not resize the image, and they do not mean five output columns by three output rows. A larger window averages more neighbours and generally produces a softer result. Keep the dimensions explicit in scripts so a reader does not have to remember the defaults.

The image must be large enough for the selected kernel. A five-column kernel cannot convolve an image that is only five columns wide, and the same boundary applies to rows. If the command reports that the image is too narrow or too short, use a smaller window or a larger source image. Check the source before changing options:

$ pamfile "$INPUT"
/path/to/source.ppm:  PPM raw, 1600 by 1200  maxval 255

5. Avoid obsolete examples

Older instructions may show pnmsmooth -size 5 5 image.ppm. The installed command retains -size for backward compatibility, with the width and height as the next two arguments, but new scripts should use -width and -height. The modern form makes the option values visible and lets you choose a rectangular window.

Do not build a workflow around -dump. On this installation it is rejected with a message saying that the option no longer exists. Older Netpbm documentation described several different dump behaviours before that option disappeared. If you need to construct a convolution explicitly, use the current pnmconvol interface rather than copying an old dump example.

6. Check the result and recover from a failure

Inspect the output with pamfile or your normal image viewer. For a second, format-level check, convert a copy to PNG if pnmtopng is installed:

$ pnmtopng "$OUTPUT" > /tmp/source-smoothed.png
$ file /tmp/source-smoothed.png
/tmp/source-smoothed.png: PNG image data, 1600 x 1200, 8-bit/color RGB, non-interlaced

The temporary PNG is a separate conversion; it is not produced by pnmsmooth. If the output is empty or pamfile cannot read it, keep the source, remove only the failed new file, and rerun with a new destination after reading the diagnostic:

$ rm -- "$OUTPUT.new"
$ pnmsmooth -width=3 -height=3 "$INPUT" > "$OUTPUT.new"
$ pamfile "$OUTPUT.new"
$ mv "$OUTPUT.new" "$OUTPUT"

Do not remove the source as a cleanup step. Smoothing is a lossy image transformation: the original pixels cannot be reconstructed from the averaged output.