Replace ppmtomap with pnmcolormap

Found an old script still calling the obsolete ppmtomap? Swap it for its maintained successor pnmcolormap and check the generated map still works. The whole job takes about five minutes if Netpbm is already installed, and needs no root privileges beyond reading the input and writing to a directory you own.

What changes, and what stays the same

ppmtomap is kept only for backward compatibility. Its manual page says pnmcolormap replaced it back in January 2002, so new scripts should call the successor directly. The old command has no options of its own: it accepts the common libnetpbm options and otherwise passes the image through the old colour-map behaviour.

On this machine the installed package is Netpbm 11.5.2, reported by pnmcolormap -version. The command reads a PNM or PAM image and writes a PNM colour map: one pixel per selected colour, not a recoloured copy of the original. Hand that map to pnmremap afterwards if you want to quantise the source image.

1. Check the installed commands

Run this as your normal user, no elevation needed:

$ command -v ppmtomap
/usr/bin/ppmtomap
$ pnmcolormap -version
pnmcolormap: Using libnetpbm from Netpbm Version: Netpbm 11.5.2

The version output carries build details specific to this installation, so the exact wording may differ elsewhere. If ppmtomap exists but pnmcolormap does not, install the Netpbm package through your normal package manager. Do not drop a random executable into /usr/local/bin to paper over a missing package.

2. Generate a map with the replacement

Swap in a real PNM or PAM file for the example path. The first argument is required: it is the number of colours you want in the output.

$ pnmcolormap 64 input.ppm > map.ppm

That asks for up to 64 representative colours; the program can return fewer if the image does not have that many distinct ones. The default map is a single row with one column per colour. For a square-ish layout, useful to some previewers, add -square:

$ pnmcolormap -square 64 input.ppm > map-square.ppm

Use all instead of a number to get every colour in the input with no quantisation:

$ pnmcolormap all input.ppm > map-all.ppm

The filename is optional too. With none given, pnmcolormap reads standard input, handy in a pipeline:

$ pnmtoppm input.pgm | pnmcolormap 32 > map.ppm

That pipeline needs pnmtoppm installed and is only there to show standard-input use. Keep the original input separate from the map: a map is not a replacement image and should never be written over the source file.

3. Compare the old and new commands safely

If an existing script still calls ppmtomap, run both commands into different files before you touch the script:

$ ppmtomap input.ppm > old-map.ppm
$ pnmcolormap all input.ppm > new-map.ppm
$ file old-map.ppm new-map.ppm
old-map.ppm: Netpbm image data, size = 4 x 1, rawbits, pixmap
new-map.ppm: Netpbm image data, size = 4 x 1, rawbits, pixmap

The example dimensions depend on how many distinct colours your input has. For a byte-for-byte comparison, use a command that reports differences without rewriting either file:

$ cmp -s old-map.ppm new-map.ppm
$ printf '%s\n' "$?"
0

A zero status means the files are identical. If they differ, inspect both maps rather than assuming the difference is a bug. The historical gotcha: for PBM or PGM input, ppmtomap produced PPM, while pnmcolormap all produces the same format as the input. If a downstream tool insists on PPM, convert deliberately with the right Netpbm converter rather than leaning on the obsolete wrapper.

4. Use the map to reduce image colours

Making a map does not touch the source image. To actually apply it, use pnmremap and write to a separate output path:

$ pnmremap -map map.ppm input.ppm > reduced.ppm

Check the output exists and is recognised before you let an automated workflow near it:

$ test -s reduced.ppm && file reduced.ppm
reduced.ppm: Netpbm image data, ...

The ellipsis stands in for details that vary with the image. If the command fails, keep input.ppm and read the diagnostic. A common mistake is passing the original image where the map was expected, or using a map built from an incompatible format. No amount of elevated privilege fixes either problem.

Common traps

• Expecting private flags. Do not go looking for a ppmtomap-specific flag set; its manual page defines none.
• Treating 64 as exact. The requested colour count is a target, and the result can come back with fewer.
• Using all by accident. It asks for every input colour with no quantisation and can produce a large map when you actually wanted a small one.
• Redirecting output onto the input. Shell redirection opens the destination before the program even reads the input, which can destroy the source.
• Reaching for sudo out of habit. Use it only when your input directory is deliberately unreadable or the output directory is protected, and prefer copying files to a user-owned working directory instead.