Reduce PPM Colours with Ordered Dithering and ppmdither

You will turn a Netpbm image into a PPM with fewer colours, while keeping the original file untouched. You will also choose separate red, green and blue shade counts and check that the result is a valid image. Allow about fifteen minutes, including time to inspect the output.

This guide uses ppmdither from Netpbm package version 2:11.05.02-1.1build1 on the machine where these examples were checked. The installed manual describes the command as an ordered dither, and its manual page is dated 16 December 2009. Other Netpbm releases may differ, so check the local manual before putting an option into a long-lived script.

1. Check the command and keep the source

Confirm that the command is installed and identify the input image. This is a read-only step and does not need elevated privileges:

$ command -v ppmdither
/usr/bin/ppmdither
$ pnmfile /path/to/input.ppm

ppmdither accepts a Netpbm image as input, not only a file with a .ppm name. The output is always a PPM image. Keep the source until you have checked the new file. Do not run the command as root: reading an image and writing a result in your working directory should normally be an ordinary user operation.

Checkpoint: choose a new output name such as input-dithered.ppm. Shell redirection truncates an existing destination before the program starts, so do not point it at the only copy of an image.

2. Apply the documented default palette

Run the command with no colour options and redirect standard output to a new file:

$ ppmdither /path/to/input.ppm > input-dithered.ppm

The default is 5 red shades, 9 green shades and 5 blue shades, including black in each channel. That is a nominal palette of 225 combinations. The command uses a 16 by 16 ordered dithering matrix by default, because the matrix power is 4. It writes the image to standard output, so a successful command is normally quiet.

Check both the exit status and the file header immediately after the conversion:

$ printf 'exit status: %s\n' "$?"
exit status: 0
$ pnmfile input-dithered.ppm
input-dithered.ppm: PPM raw, ...

The exact pnmfile wording depends on the installed Netpbm tools. The useful evidence is a zero exit status and a report identifying a PPM file. If the command reports an end-of-file or read error, fix the input rather than treating the partial destination as a usable image.

3. Choose fewer shades for a restricted palette

Set the number of shades independently for the three primary channels. Each value must be at least 2 and includes black. This example produces a binary red, green and blue choice:

$ ppmdither -red=2 -green=2 -blue=2 \
    /path/to/input.ppm > input-rgb-binary.ppm
$ pnmfile input-rgb-binary.ppm

This is the setting described by the manual for a basic RGB format suitable for primitive colour printers. It does not mean that the output is monochrome: red, green and blue each still have their own two-level channel. A common distraction is to assume that one number controls the complete palette. In fact, the rough maximum is the product of the three channel counts, so 2,2,2 and 5,9,5 produce very different results.

For a less severe reduction, increase only the channel that is losing useful detail. For example:

$ ppmdither -red=3 -green=5 -blue=3 \
    /path/to/input.ppm > input-balanced.ppm

Use full option names in scripts. The program permits abbreviations to the shortest unique prefix, and permits either a space or an equals sign before a value, but explicit spelling is easier to review:

$ ppmdither -red 3 -green 5 -blue 3 /path/to/input.ppm \
    > input-balanced-space.ppm

4. Adjust the ordered matrix when patterns are distracting

The -dim option sets the power of two used for the square dithering matrix. The default is power 4, which gives a 16 by 16 matrix. A smaller value changes the repeating pattern:

$ ppmdither -dim=3 -red=3 -green=5 -blue=3 \
    /path/to/input.ppm > input-dim8.ppm

Here, -dim=3 means a matrix dimension of 2 to the power 3, or 8 by 8. The option is not an image resize and it does not set the number of colours. Compare this output with the previous file at the same display size. Ordered dithering deliberately creates a pattern, so judge the result visually as well as by its header.

If a particular matrix gives visible repeating marks, return to the default first, then alter one setting at a time. This makes it clear whether the change came from the matrix or from the palette.

5. Inspect or convert the result

PPM is an uncompressed interchange format and can be large. After checking the dithered image, use another installed Netpbm tool if you need a different format:

$ pnmtopng input-dithered.ppm > input-dithered.png
$ file input-dithered.png

pnmtopng is a separate command and is not part of ppmdither's output step. If it is not installed, retain the PPM or use the image conversion tool approved for your system. Do not delete the source or the PPM until the converted file has been opened and checked.

If you need to replace an existing result, make a backup before doing so:

$ cp --preserve=all input-dithered.ppm input-dithered.ppm.bak
$ ppmdither -red=2 -green=2 -blue=2 /path/to/input.ppm \
    > input-dithered.ppm.new
$ pnmfile input-dithered.ppm.new
$ mv input-dithered.ppm.new input-dithered.ppm

The final mv changes the destination only after the new file has been written and checked. If conversion fails, leave the original in place and investigate the error. Recovery is to restore the backup with cp --preserve=all input-dithered.ppm.bak input-dithered.ppm; do not remove the backup until the replacement has been verified.

6. Diagnose the usual failures

An input read error usually means the path is wrong, the file is incomplete, or the input is not a valid Netpbm image. Check it without changing anything:

$ ls -l /path/to/input.ppm
$ pnmfile /path/to/input.ppm
$ ppmtoppm /path/to/input.ppm > /dev/null

The last command is a separate parser check if ppmtoppm is installed. If the input is another Netpbm format, use the appropriate converter first, then feed its PPM output to ppmdither. A zero exit status only says that the command completed; open the result or pass it to a later checker to confirm that the visual output is acceptable.

Values below 2 are outside the documented minimum for -red, -green and -blue. The -dim value is an exponent, not a literal matrix width. Keep each test reproducible by changing one option at a time and by recording the exact command that made the accepted output.