Turn a Netpbm Lookup Table into an Index Image with pamunlookup

pamunlookup turns each pixel in an image into the index of a matching entry 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 the data is easy to inspect, and none of it needs root or sudo.

1. Check the installed command

Confirm 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. 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.

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

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 take 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. pamunlookup reads it and does not edit it; shell redirection is what 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. What matters: 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. Do not open the whole file in a text editor; if you need to inspect them without guessing at binary bytes, feed the file to another Netpbm tool that understands PAM.

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 gets index 3, which is why the output maxval is the table size rather than the largest ordinary index, 2.

That sentinel is useful, but it is not one of the table entries. Treat it as an unmatched value in later processing, never silently as the fourth colour. If the input and table use different maxvals or tuple types, normalise them first with the appropriate Netpbm converter, 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

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'

• Non-zero exit, error on standard error: an empty input, an invalid Netpbm header, or mismatched image data. Keep standard output redirected to a temporary file so a failed run cannot be mistaken for a valid result.
• Tuple 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.