Create and Use PBM Masks Safely with pbmmask

You will finish with a PBM mask that is white over an object's figure and black over its background, ready for a Netpbm paste or arithmetic operation. The examples use pbmmask from Netpbm 11.5.2, installed here as package version 2:11.05.02-1.1build1.

Allow about fifteen minutes. You need a shell, the Netpbm tools, and a PBM input image. The commands read and write files in your working directory and normally need no elevated privileges. This guide does not change system configuration or install software.

1. Check the installed command

Confirm which executable will run and record the local Netpbm version. This is an ordinary, read-only check:

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

The command accepts an optional PBM file. With no file argument it reads PBM data from standard input, so it also fits into a pipeline. The output is another PBM image on standard output. Keep diagnostics on standard error when redirecting output.

2. Make a small test image

Before using a valuable image, test the behaviour with a tiny ASCII PBM. In the PBM format, 0 is white and 1 is black. This seven-by-seven sample has a black cross on a white background:

$ cat > cross.pbm <<'EOF'
P1
7 7
0 0 0 0 0 0 0
0 0 0 0 0 0 0
0 0 0 1 0 0 0
0 0 1 1 1 0 0
0 0 0 1 0 0 0
0 0 0 0 0 0 0
0 0 0 0 0 0 0
EOF
$ file cross.pbm
cross.pbm: Netpbm image data, size = 7 x 7, bitmap, ASCII text

The here-document replaces an existing cross.pbm. If that file matters, choose a new name or copy it first. This is the only file-changing step so far.

3. Create the mask without destroying an existing output

Run pbmmask and redirect its output to a new filename:

$ pbmmask cross.pbm > cross-mask.pbm
$ printf 'exit status: %s\n' "$?"
exit status: 0
$ pnmnoraw cross-mask.pbm
P1
7 7
0000000
0000000
0001000
0011100
0001000
0000000
0000000

The displayed mask has 1 over the cross and 0 elsewhere. pbmmask determines automatically which input colour is the background, then emits white for that background and black for the figure. That means the mask follows the object rather than blindly assuming that the input background is white.

$ file cross-mask.pbm
cross-mask.pbm: Netpbm image data, size = 7 x 7, rawbits, bitmap

The normal output is raw PBM, which is compact binary data. pnmnoraw is only being used above to make the pixels readable in a terminal; it does not change the original mask unless you redirect its output.

4. Add a one-pixel expansion when needed

Use -expand when the mask needs to extend one pixel out from the figure. This can provide a small white border around an image in the mask workflow:

$ pbmmask -expand cross.pbm > cross-mask-expanded.pbm
$ pnmnoraw cross-mask-expanded.pbm
P1
7 7
0000000
0011100
0111110
0111110
0111110
0011100
0000000

Compare this with the unexpanded result. The shape grows outwards by one pixel where space is available, but it cannot grow beyond the image edges. Do not add -expand automatically: it changes the mask boundary and may make an object overlap nearby content.

If a generated mask is wrong, the recovery is simple: leave the source PBM untouched and regenerate the output with a different destination name. To discard an unneeded test output, remove that specific file only after checking that it is not needed. There is no persistent setting to undo.

5. Use the mask in a black-background paste

For an object whose background is black, the manual gives this two-stage paste pattern. Replace the placeholder coordinates with the destination position:

$ pbmmask object.pbm > object-mask.pbm
$ pnmpaste -and destination.pbm object-mask.pbm X Y \
    | pnmpaste -or object.pbm X Y > composed.pbm
$ file composed.pbm
composed.pbm: Netpbm image data, size = ..., bitmap

The first paste keeps the destination where the object mask is black. The second pastes the object where its figure belongs. The two commands are ordinary file-processing operations, but > composed.pbm truncates an existing file before the pipeline completes. Use a new name or write to a temporary file, inspect it, then replace the old result deliberately.

For an object with a white background, invert the mask and create a black-background copy of the object before the same paste pattern:

$ pbmmask object.pbm > object-mask.pbm
$ pnminvert object-mask.pbm | pnmpaste -and object.pbm 0 0 > blackback.pbm
$ pnmpaste -and destination.pbm object-mask.pbm X Y \
    | pnmpaste -or blackback.pbm X Y > composed.pbm

Keep each intermediate file until the final image has been checked. If a command fails, preserve the original input and inspect the error before retrying.

6. Diagnose the common failures

A non-zero status and an error about a bad magic number usually mean that the input is not PBM or is not a supported Netpbm image. Check the file without changing it:

$ file /path/to/input.pbm
$ head -n 3 /path/to/input.pbm
P1
7 7

A valid ASCII PBM starts with P1; raw PBM uses P4. If the file is a PNG, JPEG or another format, convert it with an appropriate Netpbm tool first. Do not rename a non-PBM file and assume its contents have changed.

If the figure is treated as background, inspect the image's border and the dominant colour. Background detection is automatic, so an unusual image with no clear background can produce a mask that is technically valid but visually unhelpful. Test a representative file and view the result before using it in a batch.

pbmmask is described as probably superseded by pambackground. That does not make the tested command invalid for an existing PBM workflow, but it is a useful boundary: for new background-segmentation work, compare the newer tool's behaviour and output format rather than silently replacing a working pipeline.