Equalise PNM Image Contrast with pnmhisteq

Use pnmhisteq to pull out hidden detail in a flat, low-contrast PGM or PPM image. You will finish with a repeatable way to increase visible detail, inspect the result, and apply one brightness map to a related sequence. The examples use Netpbm 11.5.2, provided here by Debian package netpbm version 2:11.05.02-1.1build1.

Allow about fifteen minutes. You need a shell, a readable PGM or PPM image, and enough space for a new output file. The examples write new files and leave the source image alone. No command needs elevated privileges when your input and output directories are writable by your account.

1. Check the installed command

Confirm that the executable is the one on your path, then ask it for its version details. These are read-only checks:

$ command -v pnmhisteq
/usr/bin/pnmhisteq
$ pnmhisteq -version 2>&1 | head -8
pnmhisteq: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
pnmhisteq: Built from source dated 2024-03-31 09:09:47

The manual describes pnmhisteq as a histogram equaliser for PGM and PPM images. It reads one image, computes a luminosity mapping, and writes the transformed image to standard output. That last detail is easy to miss: use shell redirection to choose the output file.

2. Equalise an image into a new file

Replace the placeholder paths with files you own. The command below keeps the source untouched and creates a new PNM file:

$ pnmhisteq /path/to/input.pgm > /path/to/output-equalised.pgm

For a PPM image, use the same command and keep the appropriate extension:

$ pnmhisteq /path/to/input.ppm > /path/to/output-equalised.ppm

Because the image is binary data, do not use head to inspect the whole output or expect readable pixels in a terminal. Check the file type and its header instead:

$ file /path/to/output-equalised.pgm
/path/to/output-equalised.pgm: Netpbm image data, rawbits, greymap
$ head -n 3 /path/to/output-equalised.pgm
P5
1600 1200
255

The wording from file varies. The useful checks are a successful exit status, a non-empty destination, and a PGM or PPM header with the expected dimensions and maximum value.

$ pnmhisteq /path/to/input.pgm > /path/to/output-equalised.pgm.new
$ file /path/to/output-equalised.pgm.new
$ mv /path/to/output-equalised.pgm.new /path/to/output-equalised.pgm

If the conversion fails, remove the incomplete .new file and the original output remains available. The final mv is the state-changing step; it does not need root when both paths are in a directory you can modify.

3. Choose the right image behaviour

Equalisation redistributes luminosity levels around the image histogram. Dark or bright ranges with useful variation can gain visible separation, but the process is not a subtle linear brightness adjustment. The manual warns that scanned halftones can become harsher because it makes their dot pattern more apparent.

For a colour image, pnmhisteq normally bases the mapping on luminosity. Add -gray when the meaningful image data are greyscale but the file contains coloured annotations that should not be altered:

$ pnmhisteq -gray /path/to/annotated.ppm > /path/to/annotated-equalised.ppm

-gray includes and changes only pixels whose red, green and blue values are identical. It has no effect on a greymap. If you want to inspect a colour image's brightness distribution separately, convert a copy through ppmtopgm and examine that result with a histogram tool. Keep that diagnostic pipeline separate from the file you intend to publish.

Black or white borders can dominate a histogram. The -noblack option excludes black pixels from the equalisation while preserving them as black. -nowhite does the equivalent for white pixels:

$ pnmhisteq -noblack -nowhite /path/to/stars.pgm > /path/to/stars-equalised.pgm

These switches are useful when a background or annotation is not the subject of the contrast adjustment. They are not a general fix for a poor source image. Compare the result with the original before processing a batch.

4. Reuse one map for related images

Equalising each animation frame independently can make brightness change from frame to frame. Build one map from a representative composite or reference image with -wmap:

$ pnmhisteq -wmap /path/to/sequence-map.pgm \
    /path/to/reference.pgm > /path/to/reference-equalised.pgm
$ head -n 3 /path/to/sequence-map.pgm
P5
256 1
255

The map is a one-row PGM. Its width is the input maximum value plus one, so an 8-bit image normally produces 256 columns. It is data, not a human-readable settings file. Keep it with the exact input depth used to create it.

Apply that map to each matching image with -rmap:

$ pnmhisteq -rmap /path/to/sequence-map.pgm \
    /path/to/frame-001.pgm > /path/to/frame-001-equalised.pgm
$ pnmhisteq -rmap /path/to/sequence-map.pgm \
    /path/to/frame-002.pgm > /path/to/frame-002-equalised.pgm

The map must have the same maximum value as the input image. If the depth differs, the manual's suggested repair is to adjust the map with pamdepth before using it. Do not guess at a conversion: verify the maximum value in both files and retain the original map until every output has been checked.

5. Inspect the mapping when the result is surprising

Add -verbose to print the histogram and luminosity map on standard error while the equalised image still goes to standard output:

$ pnmhisteq -verbose /path/to/input.pgm \
    > /path/to/output-equalised.pgm \
    2> /tmp/pnmhisteq-report.txt
$ sed -n '1,12p' /tmp/pnmhisteq-report.txt
  Luminosity map    Number of
 Original    New     Pixels

The exact rows depend on the image. The report helps distinguish a source with a narrow range from a command that was given the wrong file. Delete the report when you no longer need it; it contains diagnostic data, not a recovery file.

A PBM image has only black and white pixels, so histogram equalisation is an identity operation. Passing one through this command only consumes time and produces no useful contrast change. For a gentler adjustment on a continuous-tone image, compare the result with pnmnorm or pnmgamma rather than assuming more equalisation is better.