Map Numeric Image Values to Colours with pamlookup

You will finish with a small, reproducible colour lookup workflow: a greyscale image supplies numeric indices, a one-row PPM supplies colours, and pamlookup writes the mapped image to standard output. This guide uses Netpbm 11.5.2, provided here by package netpbm version 2:11.05.02-1.1build1.

Allow about fifteen minutes. You need the Netpbm tools, a PAM or PNM index image, and a PAM or PNM lookup image. The examples use plain-text PGM and PPM files so that their values are easy to inspect. No command needs elevated privileges when you work in a directory you own.

1. Check the installed command

Confirm which executable will run and record the installed Netpbm version. These are read-only checks:

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

The command takes one index image as its positional argument and requires -lookupfile to name the table image. The result is written to standard output, so redirect it to a new destination. Do not use sudo merely because the input is an image.

2. Make a small index and colour table

For a first test, create an index image with values from 0 to 2 and a three-entry colour table. The table is one row wide enough for those values: column 0 is red, column 1 is yellow, and column 2 is pale beige.

$ mkdir -p "$HOME/pamlookup-demo"
$ cd "$HOME/pamlookup-demo"
$ printf 'P2\n3 2\n2\n0 1 0\n2 2 2\n' > index.pgm
$ printf 'P3\n3 1\n255\n255 0 0   255 255 0   245 245 220\n' > colours.ppm

These are ordinary PGM and PPM files. In the index, the first row is 0 1 0 and the second is 2 2 2. The maximum index value is 2, so the lookup table needs at least three columns. Check both headers before mapping:

$ pamfile index.pgm colours.ppm
index.pgm:    PGM plain, 3 by 2  maxval 2
colours.ppm:  PPM plain, 3 by 1  maxval 255

Your pamfile wording can differ slightly between Netpbm builds. The useful facts are the dimensions, format and maximum value.

3. Map whole-number indices to colour tuples

Run the default mode, whole tuple indexing. Each sample in the one-plane index image is treated as a column number in the one-row lookup image:

$ pamlookup index.pgm -lookupfile=colours.ppm > mapped.ppm
$ pamfile mapped.ppm
mapped.ppm:  PPM raw, 3 by 2  maxval 255

The output keeps the index image's width and height, but takes its tuple depth, image type and maximum value from the lookup image. Here it is a two-row, three-column PPM. The first output row is red, yellow, red; the second is beige, beige, beige.

Checkpoint: inspect the result with an image viewer or another Netpbm converter. A PPM may be written in raw binary form even when the inputs were plain text, so use pamfile rather than sed to inspect the complete output.

4. Handle an index that is not in the table

In whole tuple mode, a lookup table that is too narrow does not automatically stretch. Without -fit, an index beyond the table dimensions uses the top-left lookup tuple unless you provide -missingcolor. This default can hide bad or unexpected data.

For a deliberate fallback, make a table with only two entries and map an index containing 2:

$ printf 'P3\n2 1\n255\n255 0 0   0 0 255\n' > short-colours.ppm
$ pamlookup index.pgm -lookupfile=short-colours.ppm -missingcolor=black > missing-black.ppm
$ pamfile missing-black.ppm
missing-black.ppm:  PPM raw, 3 by 2  maxval 255

The pixels with index 2 are black. -missingcolor matters only for PNM lookup images, and it has no effect when -fit or -byplane is used. Colour names are parsed by Netpbm's colour parser; use a simple name such as black or a documented colour value accepted by your installation.

Alternatively, use -fit when the table is a palette that should be stretched or shrunk to the index image's maximum value:

$ pamlookup index.pgm -lookupfile=short-colours.ppm -fit > fitted.ppm
$ pamfile fitted.ppm
fitted.ppm:  PPM raw, 3 by 2  maxval 255

-fit resizes the lookup image to the required width using Netpbm scaling. It is a data transformation, not a way to mark invalid indices, so choose it only when interpolation or resampling is what you want.

5. Use each image plane as its own index

Add -byplane when each sample in a multi-plane image should be looked up independently. The output has the index image's dimensions and the lookup image's maximum value. A one-plane PGM makes the rule visible without needing a multi-plane PAM:

$ printf 'P2\n3 2\n2\n0 1 0\n2 0 2\n' > plane-index.pgm
$ printf 'P2\n3 1\n7\n3 4 7\n' > sample-table.pgm
$ pamlookup -byplane plane-index.pgm -lookupfile=sample-table.pgm > plane-result.pgm
$ pamfile plane-result.pgm
plane-result.pgm:  PGM raw, 3 by 2  maxval 7

The output samples are 3, 4, 3 on the first row and 7, 3, 7 on the second. In this mode pamlookup always scales the lookup image to the index range, and both -fit and -missingcolor have no effect. For a true multi-plane input, every sample at a row, column and plane is mapped separately.

Whole tuple mode has a second form: a two-plane index image supplies ordered pairs. The first sample selects a lookup-table row and the second selects a column. Use pamstack to combine two one-plane index images before passing them to pamlookup; the lookup image then needs the corresponding two-dimensional layout.

6. Avoid destructive redirection and diagnose failures

Shell redirection truncates its destination before pamlookup starts. Preserve an existing result by choosing a new name, then replace it only after checking the new file:

$ pamlookup index.pgm -lookupfile=colours.ppm > mapped.ppm.new
$ pamfile mapped.ppm.new
$ mv mapped.ppm.new mapped.ppm

If the command fails, the old mapped.ppm remains in place. The temporary output may be incomplete, so remove it only after checking which file is safe to discard. Do not delete the original index or lookup images until the mapped image has been inspected.

A missing or unreadable lookup file is an input-path or permission problem. An invalid lookup dimension may mean that the table is too short for whole tuple mode; decide between a deliberate -missingcolor fallback and -fit. The index image and lookup image may each be read from standard input with -, but not both at once because pamlookup needs two independent inputs.