Turn a Netpbm Lookup Table into an Index Image with pamunlookup

You will finish with a small, repeatable Netpbm workflow that replaces each image tuple with the index of an equal tuple in a lookup table. The result is a one-channel PAM index image, suitable for feeding back to pamlookup or for inspecting as labelled data. These examples use the installed Netpbm package version 2:11.05.02-1.1build1.

Allow about fifteen minutes. You need pamunlookup, a PAM or PNM lookup image, an input image, and a writable working directory. The examples use plain-text PPM files so that the data is easy to inspect. They do not need root or sudo.

1. Check the installed command

Confirm that the command in your PATH is the one you intend to run. This is a read-only check:

$ command -v pamunlookup
/usr/bin/pamunlookup
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1

The manual gives one required option, -lookupfile, followed by the input image. The output always goes to standard output. A file name of - means standard input, but do not use standard input for both the image and the lookup table.

Checkpoint: the command exists, the package version is known, and you have two separate readable image files.

2. Create a small lookup table

A lookup table is an image whose tuples are assigned indexes from zero upwards. This three-pixel PPM maps red to 0, yellow to 1, and beige to 2:

$ cat > map.ppm <<'EOF'
P3
3 1
255
255 0 0  255 255 0  210 180 140
EOF

Here P3 is the plain-text PPM format, the dimensions are three columns by one row, and 255 is the maximum colour value. The lookup table can instead be a PAM or another supported PNM image, but its tuples must be in the same form as the tuples in the input.

Verify the file before using it:

$ pamfile map.ppm
map.ppm: PPM, 3 by 1  maxval 255

The wording can vary slightly between Netpbm builds. Check that it identifies a PPM image with the expected dimensions.

3. Prepare an image containing those tuples

This input repeats red and beige and puts yellow in the middle of the first row:

$ cat > input.ppm <<'EOF'
P3
3 2
255
255 0 0  255 255 0  255 0 0
210 180 140  210 180 140  210 180 140
EOF
$ pamfile input.ppm
input.ppm: PPM, 3 by 2  maxval 255

Keep the source image. The command reads it and does not edit it, while shell redirection creates or truncates the output path.

4. Generate the index image

Run pamunlookup with the lookup file and redirect standard output to a new destination:

$ pamunlookup -lookupfile=map.ppm input.ppm > indexes.pam
$ pamfile indexes.pam
indexes.pam: PAM, 3 by 2 by 1 maxval 3
    Tuple type: INDEX

The exact spacing in pamfile output is not significant. The important results are the original width and height, depth 1, tuple type INDEX, and a maximum value equal to the lookup-table size. The lookup table has three entries, so this output has maxval 3.

The index values are binary PAM data after the header. If you need to inspect them without guessing at binary bytes, use the file as input to another Netpbm tool that understands PAM. Do not open the whole file in a text editor.

5. Understand unmatched tuples

If an input tuple is absent from the lookup table, pamunlookup writes one greater than the highest valid lookup index. With three entries, an unmatched tuple receives index 3. That is why the output maxval is the table size rather than the largest ordinary index, 2.

This sentinel is useful, but it is not one of the table entries. Treat it as an unmatched value in later processing. Do not silently interpret it as the fourth colour. If the input and table use different maxvals or tuple types, normalise them first with the appropriate Netpbm converter and then verify the converted files.

6. Check the inverse relationship

The documented inverse is pamlookup without its -byplane mode. Feed the index image back through the same table and write a separate PPM:

$ pamlookup -lookupfile=map.ppm indexes.pam > roundtrip.ppm
$ pamfile roundtrip.ppm
roundtrip.ppm: PPM, 3 by 2  maxval 255

For the example, the round trip reconstructs the tuple values represented by the indexes. Compare image content with a Netpbm-aware tool rather than using cmp: Netpbm may choose a different legal encoding, such as raw PPM instead of plain-text PPM, even when the pixels are the same.

7. Avoid overwriting useful output

$ pamunlookup -lookupfile=map.ppm input.ppm > indexes.pam.new
$ pamfile indexes.pam.new
$ mv indexes.pam.new indexes.pam

If the command fails, remove only the incomplete indexes.pam.new after checking the error. If the final move has already replaced a file, recover it from your normal backup. This workflow changes no service or system configuration, so there is no privileged undo step.

8. Diagnose the common failures

A missing or unreadable lookup file is an input problem. Check paths and permissions without changing them:

$ test -r map.ppm && echo 'lookup table is readable'
$ test -r input.ppm && echo 'input image is readable'

An empty input, an invalid Netpbm header, or mismatched image data causes a non-zero exit and an error on standard error. Keep standard output redirected to a temporary file so a failed run cannot be mistaken for a valid result. If the command reports that a tuple is not in the lookup table, decide whether the sentinel index is acceptable or add the tuple to a newly generated table. Do not edit the original table blindly, because changing entry order changes every index after that entry.