Manual: pnmhisteq

Pnmhisteq User Manual(1)			   General Commands Manual			    Pnmhisteq User Manual(1)

NAME
       pnmhisteq - histogram equalize a PNM image

SYNOPSIS
       pnmhisteq

       [-gray]

       [-noblack] [-nowhite]

       [-rmap pgmfile]

       [-wmap pgmfile]

       [-verbose]

       [pnmfile]

DESCRIPTION
       This program is part of Netpbm(1).

       pnmhisteq increases the contrast of a PGM or PPM image through the technique of "histogram equalization."[1]

       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.	Pix‐
       els 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 bright‐
       ness 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 pamcat 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  lumi‐
       nosity  instead of histograms of the three color components.  It should generally show a flat histogram.	 But because
       of the quantization effects described above, you might see high bars interleaved with low bars, with the local  aver‐
       age being flat.	To see local averages, use the -width option of pnmhistmap.

OPTIONS
       In addition to the options common to all programs based on libnetpbm (most notably -quiet, see  Common Options ), pn‐
       mhisteq recognizes the following command line options:

       You can abbreviate any option to its shortest unique prefix.

       -gray  When  processing	a  color  image, only gray pixels (those with identical red, green, and blue values) are in‐
	      cluded in the histogram and modified in the output image.	 This is a special purpose option intended  for	 im‐
	      ages  where the actual data are gray scale, with color annotations you don't want modified.  Weather satellite
	      images that show continent outlines in color are best processed using this option.  The option has  no  effect
	      when the input is a graymap.

       -noblack
	      Do  not include black pixels in the equalization.	 The black pixels in the output are exactly the black pixels
	      in the input and the number of black pixels does not affect the color of any other pixels.

	      Sometimes, black isn't as much a color as a background or annotation for the real colors, so you want to treat
	      it specially this way.  Think of a picture of stars, which is nearly all black, but with lots of stars of dif‐
	      ferent brightness.  You want to change the brightnesses of the stars to maximize contrast between them, but if
	      you considered the blackness to be significant, all the stars would end up close to full white.

	      This option was new in Netpbm 10.70 (March 2015).

       -nowhite

	      Same as -noblack, but for the white pixels.

	      This option was new in Netpbm 10.70 (March 2015).

       -rmap mapfile
	      Process the image using the luminosity map specified by the PGM file mapfile.

	      The PGM image, usually created by an earlier run of pnmhisteq with the -wmap option,  contains  a	 single	 row
	      with  number  of	columns equal to the maxval (greatest intensity value) of the image plus one.  Each pixel in
	      the image is transformed by looking up its luminosity in the corresponding column in the map file (column num‐
	      ber = luminosity) and changing it to the value given by that column.

       -wmap mapfile
	      Creates a PGM file mapfile, containing the luminosity map computed from the  histogram  of  the  input  image.
	      This map file can be read on subsequent runs of pnmhisteq with the -rmap option, allowing a group of images to
	      be processed with an identical map.

       -verbose
	      Prints the histogram and luminosity map on Standard Error.

LIMITATIONS
       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 mak‐
       ing halftone artifacts apparent.	 You might want to experiment with pnmnorm and pnmgamma for more subtle contrast en‐
       hancement.

       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, sim‐
       ply 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.

SEE ALSO
       pnmnorm(1), pamcat(1), pamdepth(1), pnmgamma(1), pnm(1),

       [1]    Russ, John C.  The Image Processing Handbook.  Boca Raton: CRC Press, 1992.  Pages 105-110.

DOCUMENT SOURCE
       This manual page was generated by the Netpbm tool 'makeman' from HTML source.  The master documentation is at

	      http://netpbm.sourceforge.net/doc/pnmhisteq.html

netpbm documentation					22 March 2015				    Pnmhisteq User Manual(1)