Plot PGM and PPM intensity distributions with pnmhistmap

You will turn a PGM or PPM image into a separate histogram image that shows how its intensity values are distributed. You can keep the default scale, narrow the plotted range, select one colour channel, or suppress dominant black and white pixels. Allow about ten minutes if the input file is ready. The examples are read-only with respect to the input, but shell redirection can overwrite an existing output file.

1. Check the installed command

Install the Netpbm package through your normal system package manager if pnmhistmap is missing. This guide was tested with Netpbm package version 2:11.05.02-1.1build1. Check the executable and ask it for its local help:

$ command -v pnmhistmap
/usr/bin/pnmhistmap
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1
$ pnmhistmap --help
pnmhistmap: Use 'man pnmhistmap' for help.

The short help message is normal for this build. The installed manual describes PGM and PPM input, and says the shortest unique option abbreviation is accepted. Spell options in full in scripts so their meaning stays clear.

2. Make a default greyscale histogram

Give the input file as the last argument and redirect the histogram image to a new path. A PGM input produces PBM output:

$ pnmhistmap /path/to/input.pgm > /path/to/input-histogram.pbm
$ file /path/to/input-histogram.pbm
/path/to/input-histogram.pbm: Netpbm image data, size = 256 x 200, rawbits, bitmap

With no size options, the installed command uses a height of 200 pixels and one horizontal bucket for each plotted intensity value. For a normal 8-bit image that means 256 pixels wide. The output is an image, not text that can be read in the terminal. Open the PBM with an image viewer or pass it to another Netpbm converter.

Use -verbose when you need progress and scaling diagnostics:

$ pnmhistmap -verbose /path/to/input.pgm > /path/to/input-histogram.pbm
pnmhistmap: Horizontal scale factor: 1
pnmhistmap: making histogram...
pnmhistmap: finding max. slot height...

The exact final diagnostic can vary with the image. The useful verification is the output file type and dimensions, plus a visual check.

3. Plot selected channels from a colour image

A PPM input produces a PPM histogram with red, green and blue traces overlaid by default. Select one or more channels when the combined view hides the feature you are investigating:

$ pnmhistmap -red -dots /path/to/input.ppm > /path/to/red-histogram.ppm
$ file /path/to/red-histogram.ppm
/path/to/red-histogram.ppm: Netpbm image data, size = 256 x 200, rawbits, pixmap

-dots draws points rather than the default bars. The channel switches have no useful effect on PGM input because it has no separate colour components. For a combined view, omit -red, -green and -blue. For two channels, name both, for example -green -blue.

Keep the source file unchanged while experimenting. If the destination already exists, > truncates it before pnmhistmap starts. Choose a new name or use a temporary output and replace the old file only after checking it:

$ pnmhistmap -green /path/to/input.ppm > /path/to/input-histogram.ppm.new
$ file /path/to/input-histogram.ppm.new
$ mv /path/to/input-histogram.ppm.new /path/to/input-histogram.ppm

The mv command changes the destination, so do not run it until the temporary file has the expected format and dimensions. If conversion fails, leave the original output in place and remove the incomplete .new file deliberately.

4. Focus the intensity range

Use -lval for the lowest value and -rval for the highest. Values outside that inclusive range are ignored, and the left and right edges of the result represent those two values:

$ pnmhistmap -lval 32 -rval 224 -width 384 -height 240 \
    /path/to/input.pgm > /path/to/focused-histogram.pbm
$ file /path/to/focused-histogram.pbm
/path/to/focused-histogram.pbm: Netpbm image data, size = 384 x 240, rawbits, bitmap

-height sets the output height. -width sets the output width, but it does not simply stretch the histogram: when there are fewer pixels than plotted intensity values, multiple values share a bucket; when there are more pixels, some buckets represent no value and have zero count. Treat a changed width as a change in presentation, not extra detail.

For an image with a large black border, -black excludes the black-pixel count while scaling the plotted heights. -white does the same for white pixels. These switches apply to all channels in a colour input. They change the scale, not which pixels are present in the source.

5. Handle the installed maximum-count option

There is a version-specific trap in the local documentation. The installed manpage lists -max N, but the Netpbm binary tested here rejects -max and reports -nmax in its recognised option list. Use the spelling accepted by the executable when you need to force the largest count used for scaling:

$ pnmhistmap -nmax 2 /path/to/input.ppm > /path/to/limited-scale.ppm
$ file /path/to/limited-scale.ppm
/path/to/limited-scale.ppm: Netpbm image data, size = 256 x 200, rawbits, pixmap

This is useful when a single non-black, non-white colour dominates the image. If your installed build rejects -nmax, read its own option error and local manual before adapting a script. Do not silently substitute -max on this machine: its exit status is non-zero and no usable histogram is produced.

6. Diagnose failures without escalating privileges

Most failures are input format, path or option errors. Check the file before trying sudo:

$ file /path/to/input.pgm
$ test -r /path/to/input.pgm && echo readable
$ pnmhistmap /path/to/input.pbm > /tmp/should-not-be-used.pbm
pnmhistmap: Cannot do a histogram of a a PBM file

PBM input is explicitly rejected. A missing or unreadable path is a filesystem problem, and an unrecognised option is a command-version problem. Neither is fixed by elevated privileges. Run as root only if your normal user genuinely lacks permission to read the input or write the chosen destination, and prefer fixing ownership or selecting an appropriate working directory.

The manual also records a limitation: pnmhistmap assumes a maximum pixel value of 255. An image with a smaller maxval uses only the lower-value side of the histogram. If that affects the result, normalise a copy through pamdepth or otherwise rescale the image with a separate, verified workflow. Keep the original until the replacement has been checked.