Quantise a Set of Netpbm Images with One Shared Palette

You will finish with several Netpbm image files remapped to one shared colour palette. That is useful when images are displayed together and must fit within the same colour budget. The examples use pnmquantall from Netpbm 11.05.02, installed here as package version 2:11.05.02-1.1build1.

Allow about fifteen minutes. You need Netpbm, a shell, and at least two readable Netpbm images such as PPM or PNM files. The normal invocation changes its input files in place, so the first working example deliberately uses -ext to make new files. No elevated privileges are needed when your files are in a directory you can write.

1. Check the installed command

Confirm that the command and its supporting Netpbm tools are available. This is a read-only checkpoint:

$ command -v pnmquantall
/usr/bin/pnmquantall
$ pnmquantall -version
pnmcolormap: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
pnmcolormap: Built from source dated 2024-03-31 09:09:47
pnmcolormap: Built by Debian

The version output comes from pnmcolormap, which pnmquantall invokes internally. The installed package reports 11.05.02, while the tool prints the library version as 11.5.2. Do not treat the extra build details as a promise that another machine will print identical text.

2. Inspect the files you will process

Use a small, explicit file list. Check that every input exists and is readable before running a batch:

$ ls -l /path/to/images/photo-a.ppm /path/to/images/photo-b.ppm
$ file /path/to/images/photo-a.ppm /path/to/images/photo-b.ppm
$ test -r /path/to/images/photo-a.ppm && test -r /path/to/images/photo-b.ppm && echo readable
readable

Replace the paths with your own files. Keep filenames simple and quote them when they contain spaces. The installed wrapper builds a shell command for the shared colour-map step, so avoiding spaces and shell metacharacters in input paths is the safest choice for scripts. Do not use a wildcard until you have checked exactly which files it expands to.

Checkpoint: the list passed to pnmquantall should contain only the images you intend to display together. A shared palette is calculated from all of them, so adding an unrelated image can change the colours in every output.

3. Create suffixed copies

Pass the desired number of colours first, then the input filenames. Put -ext at the beginning, exactly as documented:

$ cd /path/to/images
$ pnmquantall -ext .quant 256 photo-a.ppm photo-b.ppm
$ ls -l photo-a.ppm photo-b.ppm photo-a.ppm.quant photo-b.ppm.quant

Here 256 is the target number of colours for the combined set, and .quant is the extension text. The installed wrapper appends that text literally, so including the leading full stop gives the output names photo-a.ppm.quant and photo-b.ppm.quant. The original files remain in place. The program first combines the inputs to calculate one colour map, then remaps each input through that map.

A successful return normally produces no progress report. Verify the files rather than relying on silence:

$ test -s photo-a.ppm.quant && test -s photo-b.ppm.quant && echo outputs-ready
outputs-ready
$ file photo-a.ppm.quant photo-b.ppm.quant
photo-a.ppm.quant: Netpbm image data, ...
photo-b.ppm.quant: Netpbm image data, ...

The exact file descriptions vary with the input encoding. The useful checks are that both outputs exist, are non-empty, and are still recognised as Netpbm images. Open them or pass them to your next image-processing step before deleting the originals.

4. Protect an existing output name

-ext does not provide a versioned backup system. If an output with the same suffix already exists, the installed program removes that destination before moving the replacement into place. Choose a new suffix, including its leading full stop, or make a backup first:

$ cp --preserve=all photo-a.ppm.quant photo-a.ppm.quant.bak
$ pnmquantall -ext .quant photo-a.ppm photo-b.ppm
$ file photo-a.ppm.quant photo-a.ppm.quant.bak

Copying a backup is ordinary file work and needs no sudo in a writable directory. The backup is your recovery path if the new quantisation is visually unsuitable:

$ mv photo-a.ppm.quant photo-a.ppm.quant.failed
$ mv photo-a.ppm.quant.bak photo-a.ppm.quant

Only remove photo-a.ppm.quant.failed after checking that the restored file is the one you want. Deleting it is irreversible unless another backup exists. If several output files matter, back up each one before rerunning the batch.

5. Understand the destructive form

Without -ext, the command overwrites each input:

$ pnmquantall 256 photo-a.ppm photo-b.ppm

This is a deliberate, destructive operation. It does not create a separate output directory or retain the old pixels. Use it only after the suffixed copies have been checked, or after making backups that you have tested. There is no pnmquantall undo option; recovery means restoring your own copies.

The argument order is another easy trap. This program does not follow the usual Netpbm option rules: -ext cannot be abbreviated, and it must appear before the colour count and filenames. A command such as pnmquantall 256 -ext .quant photo-a.ppm is not the documented form.

6. Diagnose a failed batch

If a source cannot be read, check its path and permissions first:

$ ls -l photo-a.ppm
$ test -r photo-a.ppm && echo readable || echo 'not readable'
$ pnmquantall -ext .quant 256 photo-a.ppm photo-b.ppm
pnmquantall: Failed. ...

The final diagnostic is host and failure dependent. A non-zero exit status means you should inspect every output before using it. Keep the original inputs until all generated files pass the file check and a visual check.

A missing or invalid colour count is also an invocation problem. Re-read the command shape, use an integer supported by your installed Netpbm tools, and retry with -ext so a failed experiment cannot replace the source images. If you need different colormap strategies or finer control, the manual recommends using pnmcolormap and pnmremap directly instead of this convenience wrapper.