Find Exact Pixel Tuples and Colours with pamfind

You will locate every pixel whose tuple matches a value in a Netpbm image, either by decimal samples or by a named colour. The result is a list of row and column coordinates, with an option for output that is easier for a script to parse. Allow about ten minutes if the image is already in PNM or PAM format.

You need the netpbm package and a readable PNM or PAM file. These examples were checked with package version netpbm 2:11.05.02-1.1build1. The command only reads its input and writes coordinates to standard output. It does not alter the image, so elevated privileges are not normally needed.

1. Check the installed command and image

Confirm that the executable is available and identify the input before searching it:

$ command -v pamfind
/usr/bin/pamfind
$ file /path/to/image.ppm
/path/to/image.ppm: Netpbm image data, size 3 x 2, pixmap

Your file description will vary. The relevant point is that the input is a Netpbm image, such as PPM, PGM, PBM or PAM. If the file is another format, convert it with a suitable Netpbm tool first. Keep the original while checking the conversion.

2. Search for an exact tuple

Use -target when you know the sample values. Give them in tuple order and provide exactly as many values as the image depth requires. For an RGB image, red at the maximum sample value is normally 255,0,0:

$ pamfind -target=255,0,0 /path/to/image.ppm
Locations containing tuple (255/0/0)/255:
(0, 0)
(0, 2)
(1, 1)

The coordinates are printed as row and column, starting at zero. The heading shows the requested tuple and the image's maximum sample value. The sample output above came from a three-column, two-row PPM containing three red pixels. Your coordinates will of course depend on the image.

A search with no matches is still a successful search. It prints the heading and no coordinate lines, and the command returns status 0. Do not treat an empty result as proof that the image is empty; it only says that the requested tuple was not found.

3. Search by a named colour

For a visual colour image, the named-colour option is often clearer than decimal samples:

$ pamfind -color=red /path/to/image.ppm
Locations containing tuple (255/0/0)/255:
(0, 0)
(0, 2)
(1, 1)

The colour name is interpreted by Netpbm's colour parser. Use this mode only when the input has depth 3. The program rejects a depth-1 greyscale image instead of pretending that its single samples are RGB:

$ pamfind -color=red /path/to/greyscale.pgm
pamfind: You specified -color, but the input image has depth 1, not 3

If a depth-3 image contains data that is not really visual RGB, the named-colour mode still treats its tuples as colours. Use -target when the samples have another meaning or when you need exact values without colour-name parsing.

4. Produce coordinates for a script

Add -machine when another program will consume the result. It removes the explanatory heading and prints one zero-based row and column pair per match:

$ pamfind -target=255,0,0 -machine /path/to/image.ppm
0 0
0 2
1 1

This is the same information as the human-readable form, not a different search. A simple shell loop can consume the two fields:

pamfind -target=255,0,0 -machine /path/to/image.ppm |
while read -r row column; do
    printf 'red pixel at row=%s column=%s\n' "$row" "$column"
done

Keep the command's exit status separate from whether any lines were printed. A valid search with zero matches returns success, so use the presence of output when you need to decide whether a match exists.

5. Avoid the option and input traps

You must specify exactly one of -target and the named-colour option. Omitting both, or supplying both, is a command-line error. Do not guess the number of target samples: an RGB image needs three values, while a greyscale image needs one. The target values must also use the image's sample scale. An image with a maximum value other than 255 will not treat 255,0,0 as the same tuple as 1,0,0.

The input image is optional in the synopsis, which means standard input can be used. That is useful for a pipeline, but it can also make a typo look like a stalled command while the program waits for data. Pass an explicit filename while testing:

$ pamfind -target=0,0,0 /path/to/image.ppm

When a pipeline is intentional, make its source obvious and check the producer separately:

$ pamcut -left=5 -top=7 -width=1 -height=1 /path/to/image.ppm | pamfind -target=0,0,0

This searches the one-pixel image emitted by pamcut; it does not ask pamfind to inspect the original coordinates. To inspect the tuple at a known location instead, the manual's usual pattern is pamcut followed by pamtable.

6. Recover from a failed search

First verify the path and readability without changing anything:

$ test -r /path/to/image.ppm && echo readable
readable
$ file /path/to/image.ppm

Then check the image's format and depth with an appropriate Netpbm inspection tool, or retry with a known-good PPM. If the named-colour mode fails on depth 1, switch to a one-sample -target or use a genuine depth-3 image. If coordinates look wrong, confirm that you are reading row and column in that order and that the target's sample scale matches the input.

There is no undo operation because pamfind makes no state change. If you created an intermediate conversion file, remove only that file after checking that no later command needs it. Do not delete the source image as part of troubleshooting.