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.  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 because of 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.

OPTIONS

       In addition to the options common to all programs based on libnetpbm (most notably -quiet,
       see
        Common  Options  ⟨index.html#commonoptions⟩ ), pnmhisteq 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 included in the histogram and modified in the output image.
              This is a special purpose option intended for images 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 different 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
              number = 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 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.

SEE ALSO

       pnmnorm(1), pnmcat(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