Make Exact-Colour Masks from PPM Images with ppmcolormask

You will finish with a PBM bitmap mask whose black pixels mark selected colours in a PPM image. The mask can be inspected on its own or passed to another Netpbm tool such as pamcomp.

Allow about fifteen minutes. You need a readable PPM file and the Netpbm utilities. These examples use Netpbm 11.5.2, installed here as Debian package version 2:11.05.02-1.1build1. The command reads an image, writes the mask to standard output, and does not modify the source image.

1. Check the installed command

Confirm which executable will run and record the package version. Both checks are ordinary commands and do not need elevated privileges:

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

The version output contains build details as well. If your package is older, check its local manual page before relying on newer colour matching behaviour.

2. Create one mask for an exact colour

The mandatory option is -color=COLOR_LIST. The input filename is optional. Start with one exact colour and redirect standard output to a new PBM file:

$ ppmcolormask -color=red /path/to/input.ppm > /path/to/red-mask.pbm

Replace both paths with files you intend to use. The output is black where the input is red and white elsewhere. It has the same width and height as the PPM input, but its format is PBM rather than PPM.

Verify the result before using it in a larger pipeline:

$ pnmfile /path/to/input.ppm /path/to/red-mask.pbm
/path/to/input.ppm:     PPM ..., WIDTH by HEIGHT ...
/path/to/red-mask.pbm:  PBM ..., WIDTH by HEIGHT

The exact format wording depends on whether the input is plain or raw PPM, but the dimensions should match. A mismatched mask is a pipeline error, not something to fix by stretching the image blindly.

3. Mark several exact colours

Separate colours with commas in one -color value. This example marks red, pink and salmon:

$ ppmcolormask -color=red,pink,salmon /path/to/input.ppm > /path/to/warm-mask.pbm
$ pnmfile /path/to/warm-mask.pbm
/path/to/warm-mask.pbm:  PBM ..., WIDTH by HEIGHT

Each named colour is parsed as an exact colour name. For reproducible processing, use explicit RGB notation when a named colour could be ambiguous. The manual accepts the rgb:R/G/B form, for example:

$ ppmcolormask -color=rgb:80/80/ff /path/to/input.ppm > /path/to/blue-mask.pbm

Do not assume that a visually similar pixel will match an exact colour. A photograph or antialiased edge usually contains many nearby RGB values, so an exact mask can have gaps around shapes.

4. Use Berlin-Kay names for fuzzy colour groups

A bk: colour asks ppmcolormask to select pixels that are better described by that Berlin-Kay colour than by other Berlin-Kay names. This is a fuzzy classification, not an exact RGB comparison:

$ ppmcolormask -color=bk:red /path/to/input.ppm > /path/to/red-family-mask.pbm
$ ppmcolormask -color=bk:red,bk:orange,bk:yellow /path/to/input.ppm > /path/to/fire-mask.pbm

The installed manual says this option was added in Netpbm 10.34. It uses a simplified HSV-based fuzzy model, so its boundaries are not equivalent to a hand-picked RGB tolerance. If the exact pixels that qualify matter, test a representative image and inspect the PBM before deploying the command in a batch job.

5. Read the PPM from standard input

Omit the input filename when another command supplies PPM data on standard input:

$ cat /path/to/input.ppm | ppmcolormask -color=red > /path/to/red-mask.pbm
$ pnmfile /path/to/red-mask.pbm
/path/to/red-mask.pbm:  PBM ..., WIDTH by HEIGHT

A direct filename is usually easier to audit, but standard input is useful in a pipeline. Keep the output redirection visible so that a failed command cannot be mistaken for a successfully written mask. Check the shell status when chaining commands:

$ ppmcolormask -color=red /path/to/input.ppm > /path/to/red-mask.pbm
$ printf 'ppmcolormask status: %s\n' "$?"
ppmcolormask status: 0

6. Handle errors without overwriting useful files

An unknown colour is an input error. For example, the installed command reports an error and returns status 1 for an invalid name:

$ ppmcolormask -color=not-a-real-colour /path/to/input.ppm > /path/to/test-mask.pbm
ppmcolormask: unknown color 'not-a-real-colour'
$ printf 'status: %s\n' "$?"
status: 1

Because shell redirection opens the destination before the program runs, a failed command can leave an empty or partial destination. For important output, write to a new temporary path, check the status, then replace the old mask only after verification:

$ tmp_mask=$(mktemp /tmp/red-mask.XXXXXX)
$ if ppmcolormask -color=red /path/to/input.ppm > "$tmp_mask" && pnmfile "$tmp_mask"; then
>     mv -- "$tmp_mask" /path/to/red-mask.pbm
> else
>     rm -- "$tmp_mask"
>     printf 'mask was not replaced\n' >&2
>     exit 1
> fi

7. Pass the mask to pamcomp

The PBM output can serve as an alpha-style mask for pamcomp. The order of the arguments matters: the mask names the areas where the foreground is selected:

$ ppmcolormask -color=red /path/to/input.ppm > /tmp/red-mask.pbm
$ pamcomp /path/to/background.ppm /path/to/input.ppm \
>     -alpha=/tmp/red-mask.pbm > /path/to/composite.ppm
$ pnmfile /path/to/composite.ppm
/path/to/composite.ppm:  PPM ..., WIDTH by HEIGHT

Both input images and the mask must be suitable for the same composition dimensions. If the final destination matters, use the temporary-file check from the previous step before replacing it.

If the final target is PNG, the manual points out that pnmtopng -transparent can express transparent-colour handling without this separate mask and pamcomp step. Choose the shorter pipeline only after checking that its transparency semantics match your intended output.