Read PPM Colour Frequencies with ppmhist

You will finish with a repeatable way to inspect the colours in a PPM image, see how many pixels use each one, change the report order and format, and produce a small palette image when another program needs one. The examples were checked with Netpbm 11.5.2, packaged here as netpbm 2:11.05.02-1.1build1.

Allow about ten minutes. You need a shell, ppmhist, and a readable PPM file. The normal report only reads the image and writes to standard output. No elevated privileges are needed, and this guide does not alter the source image.

1. Check the installed command

Confirm which executable is being used and record its Netpbm version. This is a read-only checkpoint:

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

The version matters because the summary at the top of a human report was added in Netpbm 10.82. Also, since Netpbm 10.88, colours with equal frequency have a stable RGB tie-break order. If your output differs on an older installation, check the version before treating that as an image difference.

2. Generate a basic histogram

Pass the PPM path as the final argument:

$ ppmhist /path/to/image.ppm
 Summary: 3 colors: 1 black, 1 white, 0 gray, 1 color

   r     g     b      lum       count
 ----- ----- -----  -----     -------
     0     0     0      0           3
   255     0     0     76           2
   255   255   255    255           1

Your rows will depend on the image. The report lists red, green and blue sample values, a luminosity value, and the number of pixels with that exact colour. The default sort is frequency, with the most common colours first. The displayed component range follows the PPM maxval, so do not assume every file uses 255.

The summary is useful for a quick scan, but the rows are the data to feed into a review or script. The command writes the report to standard output, so redirect it only after choosing a destination you will not accidentally overwrite.

3. Make output suitable for a script or comparison

Suppress the headings and summary with -noheader:

$ ppmhist -noheader /path/to/image.ppm > /tmp/image-colours.txt
$ sed -n '1,5p' /tmp/image-colours.txt
     0     0     0      0           3
   255     0     0     76           2
   255   255   255    255           1

This is still whitespace-formatted text, not a CSV or a machine-readable interchange format. Treat the columns as a report rather than splitting blindly on a particular number of spaces.

Use -sort=rgb when you want a deterministic colour order from low red to high red, then green and blue:

$ ppmhist -sort=rgb -noheader /path/to/image.ppm

Use the full option spelling in scripts. The default frequency order is usually better for finding dominant colours; RGB order is easier to compare with a palette or a colour table.

4. Choose a different colour representation

For web or graphics work, hexadecimal components can be more convenient:

$ ppmhist -hexcolor -noheader /path/to/image.ppm
  0000  0000  0000      0           3
  00ff  0000  0000     76           2
  00ff  00ff  00ff    255           1

For calculations, -float scales the components and luminosity to the range 0 to 1:

$ ppmhist -float -sort=rgb -noheader /path/to/image.ppm
 0.000 0.000 0.000  0.000           3
 1.000 0.000 0.000  0.299           2

-hexcolor and -float are alternatives. Do not combine either with -map, and do not combine them with each other. The installed command rejects conflicting choices with an error such as You can specify only one of -hexcolor, -float, and -map.

5. Export a one-row palette

Use -map when another Netpbm program needs a PPM colour map rather than a human report:

$ ppmhist -map /path/to/image.ppm > image-palette.ppm
$ head -5 image-palette.ppm
P3
# color map
3 1
255
#Summary: 3 colors: 1 black, 1 white, 0 gray, 1 color

The result is a genuine plain PPM image with one column per distinct input colour and one row. Its comments retain histogram information. Check the magic number and dimensions before passing it on:

$ file image-palette.ppm
image-palette.ppm: Netpbm image data, size = 3 x 1, pixmap, ASCII text

Redirection with > truncates an existing file before ppmhist runs. If the palette name already exists, write to a new temporary name and replace the old file only after checking it. For example, use image-palette.ppm.new, then run mv image-palette.ppm.new image-palette.ppm after verification. If the command fails, remove the incomplete .new file and the original remains available. Do not use sudo to write a working-directory palette.

6. Investigate invalid sample values

Normally, ppmhist rejects a PPM sample greater than the file's declared maxval. That is a malformed image, not a harmless variation. Preserve the original and copy it to a disposable working file before investigating.

The -forensic option tells ppmhist to count the actual sample values despite that invalid declaration and to report the invalid pixels:

$ ppmhist -forensic /path/to/suspect.ppm
... histogram and invalid-pixel diagnostics ...

Do not interpret a forensic histogram as proof that the image is valid. It is a diagnostic view of data that violates the PPM declaration. Values above 65535 cannot be processed even with this option. In the rarely used plain PPM format, a number above that limit may appear where a sample belongs.

This is the point at which the usual distraction trap appears: an image viewer may display something while the file remains structurally invalid. Check the declared maxval and the producer that wrote the file before repairing or converting it. Repairing the original is outside this read-only workflow and should be done on a copy.

7. Diagnose common failures

If the command cannot open the file, check the path and read permission without changing anything:

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

If the report contains unexpected counts, remember that identical RGB triples are counted together, while two visually similar colours remain separate entries. Also check the PPM maxval and whether the file is plain or raw PPM. A conversion step before ppmhist can change both the samples and the number of distinct colours.

-colorname adds a name from the system colour dictionary. An exact dictionary match is shown plainly; the nearest dictionary colour is marked with an asterisk. This option fails if the dictionary is unavailable, so use it for display rather than as a canonical colour identity.