This program is part of Netpbm.
pnmhisteq increases the contrast of a PGM or PPM image through the technique of "histogram equalization."
pnmhisteq computes a histogram of the luminosity of the pixels in the image. It then calculates a mapping between each luminosity and a new luminosity such that it spreads out intensity levels around histogram peaks and compresses them at troughs. I.e. it moves pixels around in the histogram so as to make it flat. It applies that mapping to the input image to produce the output image. The effect of this is that the image has equal numbers of pixels at each possible intensity level, which means it uses the available levels of intensity more efficiently and thereby has more visible detail.
Mathematically, the luminosity mapping is this: Assume the pixels are sorted by luminosity into B buckets numbered from 0 (lowest luminosity) to B-1. N[i] is the number of pixels in bucket i. T is the total number of pixels (sum of N[i] over all i). W is the luminosity of white.
pnmhisteq replaces an input pixel whose luminosity falls into bucket j with one whose luminosity is:
j --- \ > (N[i] / T) * W / --- i=0
Considering a grayscale image for simplicity, this means that pixels in the most luminous bucket become white. Pixels in the 10th per centile of luminosity become 10% of white.
pnmhisteq maps a single luminosity in the input to a single luminosity in the output. That means if pixels A and B both have luminosity .2 in the input, and pixel A has luminosity .4 in the output, pixel B also has luminosity .4 in the output. And since the luminosities in the input are not continuous, the luminosities in the output aren't either and pnmhisteq doesn't meet the ideal of having exactly the same number of pixels of each luminosity in the output.
If you're processing a related set of images, for example frames of an animation, it's generally best to apply the same luminosity mapping to every frame, since otherwise you'll get distracting frame-to-frame changes in the brightness of objects. pnmhisteq's -wmap option allows you to save, as a PGM image, the luminosity map it computes from an image. The -rmap option causes pnmisteq to use such an image as its luminosity map.
So you can run pnmhisteq with -wmap on a composite you created with pnmcat of the images you intend to process. Then, you can run pnmisteq with -rmap on each of the individual images, using the luminosity map you generated from the composite.
Use pnmhistmap to see the result. Run a color image through ppmtopgm first so that you see a histogram of the luminosity instead of histograms of the three color components. It should generally show a flat histogram. But due to the quantization effects described above, you might see high bars interleaved with low bars, with the local average being flat. To see local averages, use the -width option of pnmhistmap.
You can abbreviate any option to its shortest unique prefix.
Histogram equalization is effective for increasing the visible detail in scientific imagery and in some continuous-tone pictures. It is often too drastic, however, for scanned halftone images, where it does an excellent job of making halftone artifacts apparent. You might want to experiment with pnmnorm and pnmgamma for more subtle contrast enhancement.
The luminosity map file supplied by the -rmap option must have the same maxval as the input image. This is always the case when the map file was created by the -wmap option of pnmhisteq. If this restriction causes a problem, simply adjust the maxval of the map with pamdepth to agree with the input image.
If the input is a PBM file (on which histogram equalization is an identity operation), the only effect of passing the file through pnmhisteq will be the passage of time.