Turn a Small-Colour PPM into High-Contrast Greys with ppmdist

You will finish with a PGM greyscale image whose input colours have been assigned evenly spaced grey levels. The guide uses ppmdist from Netpbm 2:11.05.02-1.1build1, the version installed on this machine. It covers the default intensity ordering, the frequency ordering, standard input, and a safe way to avoid destroying an existing output file.

Allow about ten minutes. You need a shell, a readable PPM image, and permission to write the output directory. The examples do not need sudo: this is an ordinary image conversion, not a system administration operation. Keep the original PPM until you have checked the result.

1. Confirm the installed command

Check the binary and package version before relying on an example:

$ command -v ppmdist
/usr/bin/ppmdist
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1

The exact version string depends on the distribution. The command accepts a PPM file as an optional argument and writes the converted PGM image to standard output. With no file argument, it reads standard input.

Checkpoint: if command -v prints nothing, stop and install Netpbm through your normal package-management process. Do not replace a missing command with a similarly named image tool without checking its format and option syntax.

2. Convert a PPM using the default ordering

The default is -intensity. It sorts the input colours by their greyscale intensity, then maps them to evenly distributed output levels. Redirect standard output to a new PGM file:

$ ppmdist -intensity /path/to/input.ppm > /path/to/output-intensity.pgm

The explicit option makes the choice visible in a script. It is equivalent to omitting the option:

$ ppmdist /path/to/input.ppm > /path/to/output-default.pgm

A successful command normally prints no progress message. Check its exit status immediately if you are testing it interactively:

$ printf 'exit status: %s\n' "$?"
exit status: 0

That status says the program completed. It does not tell you whether the image has the visual contrast you wanted, so inspect the file as well.

3. Verify that the result is a PGM

Use file for a quick format and dimension check:

$ file /path/to/output-intensity.pgm
/path/to/output-intensity.pgm: Netpbm image data, size = 640 x 480, rawbits, greymap

Your dimensions and the wording may differ. The useful checks are that the file exists, has the input dimensions, and is described as a greymap rather than a pixmap. For a small binary PGM, the header starts with P5. This reads only the first two bytes and does not try to display binary pixel data:

$ head -c 2 /path/to/output-intensity.pgm
P5

Some PGM readers also accept plain-text PGM, but the installed command produced rawbits in the local test. Do not use a text editor to inspect the complete file: after the header, pixel bytes may not be printable.

4. Choose frequency ordering when repeated colours matter

Use -frequency when the number of pixels using each input colour should determine its place in the grey scale:

$ ppmdist -frequency /path/to/input.ppm > /path/to/output-frequency.pgm
$ file /path/to/output-frequency.pgm
/path/to/output-frequency.pgm: Netpbm image data, size = 640 x 480, rawbits, greymap

This is a different mapping rule, not a contrast setting. The option sorts colours by how often they occur, then assigns the evenly spaced grey levels. A frequent colour can therefore receive a different grey level from the one it receives under -intensity.

Use the mode that reflects the image's meaning. Intensity ordering keeps the original light-to-dark relationship between distinct colours. Frequency ordering can separate common and uncommon colours more clearly, but it no longer preserves that visual ordering. Both modes are intended for images with a very small number of colours. On a photograph with many colours, this simplistic assignment is unlikely to be useful.

5. Use a pipeline when the PPM is already in standard input

Because the file argument is optional, another Netpbm command can feed ppmdist directly:

$ cat /path/to/input.ppm | ppmdist -intensity > /path/to/output.pgm

For a real conversion pipeline, replace cat with the command that produces PPM. The important boundary is that PPM travels into standard input and PGM comes out on standard output. Do not send diagnostic text into the same stream: it would corrupt the image.

Checkpoint: verify the downstream file before passing it to another image tool:

$ test -s /path/to/output.pgm && file /path/to/output.pgm
/path/to/output.pgm: Netpbm image data, size = 640 x 480, rawbits, greymap

6. Avoid truncating a useful output

Shell redirection with > truncates its destination before ppmdist starts. That matters if you are regenerating an existing image. Write to a temporary name in the same directory, verify it, then replace the old file:

$ ppmdist -intensity /path/to/input.ppm > /path/to/output.pgm.new
$ test -s /path/to/output.pgm.new
$ file /path/to/output.pgm.new
/path/to/output.pgm.new: Netpbm image data, size = 640 x 480, rawbits, greymap
$ mv /path/to/output.pgm.new /path/to/output.pgm

The final mv changes the destination, so run it only after the checks pass. If conversion fails, leave the old output alone and remove the incomplete .new file after checking its exact path. Removal is irreversible; there is no need to delete the original PPM.

If you need a recoverable replacement across filesystems, copy the old output first and preserve its metadata:

$ cp --preserve=all /path/to/output.pgm /path/to/output.pgm.bak

Restore it with mv /path/to/output.pgm.bak /path/to/output.pgm if the replacement is wrong. Delete the backup only after you have checked the new image.

7. Diagnose the common failures

A missing or unreadable input produces a non-zero status. Check the path without changing anything:

$ ls -l /path/to/input.ppm
$ test -r /path/to/input.ppm && echo readable
readable

If the file is not readable, fix its ownership or permissions according to your normal policy. Do not run the whole conversion as root just because a path is wrong. Elevated privileges are only relevant if the input directory genuinely denies your account and you have an approved reason to access it.

If ppmdist reports an invalid PPM, validate the input with an image viewer or another Netpbm reader before changing conversion options. The manual does not define a resize operation, colour-count reduction, or a way to select output maxval. Do not invent those options. Convert or resize with a separate tool before running ppmdist, then verify the new input.

The output has one grey level for each distinct input colour, with maxval set to one less than the number of input colours. That is why this command is a poor fit for ordinary full-colour photographs: many distinct colours can produce a large, coarse mapping rather than a photographic greyscale conversion. For that job, investigate ppmtopgm instead.