Remove PBM Specks Safely with pbmclean

Scan an old document and you get flecks of dust sitting on top of the text: pbmclean strips those out of a PBM image for you. You will produce a cleaned copy without disturbing the original, then choose single-pixel cleaning or whole-blob removal when the default is not enough.

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 its 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 even succeeded.

1. Check the installed command

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

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

That same command also prints build details. The manual page installed with this release is dated 19 November 2011, and its documented options are what you should rely on here; do not assume extra resizing, thresholding or file-repair features from the command name alone.

2. Clean isolated pixels in basic mode

Basic mode is the default. It looks at pixels individually and flips one that does not have enough same-colour neighbours. With the default -minneighbors value of 1, only a completely isolated pixel gets flipped, and by default pixels of both colours are considered. Write to a new output name first:

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

The input path is optional, so the same operation reads standard input just as happily:

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

PBM output may come out in raw binary form. On this installed version, a small plain-text P1 input produces a P4 output. That is still valid PBM, but it is not something you should check with cat, since 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

Scripting this? Check the status right after the command:

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

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

3. Raise the neighbour threshold deliberately

Set -minneighbors when a two-pixel or larger cluster should also go. 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

In basic mode the threshold applies per pixel, so a pair of adjacent black pixels still only has one black neighbour each, meaning both get treated as isolated at a threshold of 2. -black limits changes to black pixels and leaves white ones alone; use -white for the reverse, or supply both for the default both-colours behaviour.

4. Remove small connected blobs with extended mode

Reach for -extended when the unwanted marks are connected shapes rather than lone pixels. This mode erases each foreground-colour blob smaller than the required size. The minimum surviving 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, so a three-pixel line, square or L-shape survives while anything smaller is erased. Extended mode defaults its foreground to black; add -white when the connected foreground you want cleaned is white instead.

Basic and extended mode disagree on their defaults, and that is the common trap: basic mode defaults to one neighbour, extended mode defaults to four. Put the threshold in the command explicitly 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, and back up the old one if it is worth keeping:

$ 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 untouched. If the command fails, remove only the incomplete .new file, and only after checking it is the path you think it is. Keep the original PBM around until you have visually checked the replacement. Removing the backup is irreversible, so do that as a separate, deliberate step once recovery is no longer needed.

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

• Result removes legitimate detail. Rerun from the untouched source with basic mode, a lower threshold, or a colour filter.
• Isolated white marks remain. The default only cleans both colours when they meet the isolation rule; use -white when you need to target white pixels explicitly.
• Small connected mark remains. Compare basic mode against -extended and state the threshold explicitly rather than repeatedly cranking it up.

Option names can be abbreviated to the shortest unique prefix, and a value may be separated by whitespace instead of =, but full names read clearer in scripts. The old numeric option syntax and the singular historical spelling are compatibility notes for older Netpbm releases, not good choices for anything you write now.