Remove PBM Specks Safely with pbmclean

You will produce a cleaned PBM image without changing the original file, then choose between single-pixel cleaning and whole-blob removal when the default is not suitable. Allow about ten minutes. You need a shell, the netpbm package, and a readable PBM image. The examples use Netpbm 11.5.2, installed here as Debian package version 2:11.05.02-1.1build1.

Safety first: pbmclean writes the result to standard output. Keep that output in a new file while you inspect it. Shell redirection with > truncates an existing destination before the program has succeeded.

1. Check the installed command

Confirm which executable your shell will run and record the Netpbm version:

$ command -v pbmclean
/usr/bin/pbmclean
$ pbmclean --version
pbmclean: Using libnetpbm from Netpbm Version: Netpbm 11.5.2

The version command also prints build details. The manual page installed with this release is dated 19 November 2011. Its documented options are the behaviour to rely on here; do not infer extra resizing, thresholding or file-repair features from the command name.

Checkpoint: if command -v finds nothing, install Netpbm through your normal package manager before continuing. No sudo is needed for the cleaning commands when the input and output are in a directory you can access.

2. Clean isolated pixels in basic mode

Basic mode is the default. It examines pixels individually and flips an isolated pixel when it does not have enough neighbours of the same colour. With the default -minneighbors value of 1, only a completely isolated pixel is flipped. By default, pixels of both colours are considered.

Use a new output name first:

$ pbmclean /path/to/input.pbm > /path/to/input-clean.pbm

The input path is optional, so the same operation can read standard input:

$ pbmclean < /path/to/input.pbm > /path/to/input-clean.pbm

PBM output may be written in raw binary form. On this installed version, a small plain-text P1 input produces a P4 output. That is still PBM, but it is not suitable for checking with cat because the image data can contain non-printing bytes.

$ file /path/to/input-clean.pbm
/path/to/input-clean.pbm: Netpbm image data, size 5 x 3, rawbits, bitmap
$ head -c 2 /path/to/input-clean.pbm
P4

Check the status immediately after the command if you are scripting:

$ printf '%s\n' "$?"
0

A successful status says that the conversion completed. It does not prove that every speck was unwanted, so inspect the result with an image viewer or a later Netpbm tool before replacing the source.

3. Raise the neighbour threshold deliberately

Set -minneighbors when a two-pixel or larger cluster should also be removed. For example, this removes black pixels that do not have at least two touching black neighbours:

$ pbmclean -minneighbors=2 -black /path/to/input.pbm > /path/to/input-black-clean.pbm

The threshold applies to each pixel in basic mode. A pair of adjacent black pixels still has only one black neighbour each, so both are treated as isolated at a threshold of 2. The -black option limits changes to black pixels and leaves white pixels alone. Use -white for the reverse. Supplying both gives the default both-colours behaviour.

Do not use a high threshold casually. The manual records that a value greater than 8 generates a completely inverted image, or a completely white or black image when a colour filter is selected. That is destructive to image content and is not a normal despeckling setting.

4. Remove small connected blobs with extended mode

Use -extended when the unwanted marks are connected shapes rather than isolated pixels. In this mode, the program erases each foreground-colour blob smaller than the required size. The minimum blob size is one more than -minneighbors, and the default threshold is 4, so a black blob needs at least 5 pixels to survive.

$ pbmclean -extended -black -minneighbors=2 /path/to/input.pbm > /path/to/input-small-blobs-removed.pbm

Here the minimum surviving black blob is three pixels. A three-pixel line, square or L-shape survives; smaller black blobs are erased. Extended mode defaults the foreground to black. Add -white when the connected foreground you want to clean is white.

Basic and extended mode have different defaults, which is the common trap: basic mode defaults to one neighbour, while extended mode defaults to four. Put the threshold in the command whenever a repeatable result matters.

5. Promote a verified result without risking the source

Once you have inspected the cleaned image, replace an existing output only after a successful write. Make a backup if the old output is valuable:

$ cp --preserve=all /path/to/input-clean.pbm /path/to/input-clean.pbm.bak
$ pbmclean -extended -black -minneighbors=2 /path/to/input.pbm > /path/to/input-clean.pbm.new
$ mv /path/to/input-clean.pbm.new /path/to/input-clean.pbm

The temporary destination means a failed run leaves the previous cleaned file in place. If the command fails, remove only the incomplete .new file after checking it is the intended path. Keep the original PBM until the replacement has been visually checked. Removing the backup is irreversible, so do that separately when you no longer need recovery.

6. Diagnose the likely mistakes

If the command cannot open the image, check the path and read permission without changing anything:

$ ls -l /path/to/input.pbm
$ test -r /path/to/input.pbm && printf '%s\n' readable

If the result removes legitimate detail, rerun from the untouched source with basic mode, a lower threshold, or a colour filter. If isolated white marks remain, remember that the default cleans both colours only when they meet the isolation rule; use -white when you need to target white pixels explicitly. If a small connected mark remains, compare basic mode with -extended and state the threshold rather than repeatedly increasing it.

Option names can use the shortest unique abbreviation, and an option value may be separated by whitespace instead of =, but full names are clearer in scripts. The old numeric option syntax and the singular historical spelling are compatibility notes for older Netpbm releases, not good choices for new commands.