pnmhisteq(1)                                         pnmhisteq(1)

NAME
       pnmhisteq - histogram equalise a portable anymap

SYNOPSIS
       pnmhisteq [-gray] [-rmap pgmfile] [-wmap pgmfile] [-ver-
               bose] [pnmfile]

DESCRIPTION
       pnmhisteq increases the contrast of a portable graymap  or
       pixmap through the technique of histogram equalisation[1].
       A histogram of the luminance of pixels in the map is  com-
       puted,  from which a transfer function is calculated which
       spreads out intensity levels around  histogram  peaks  and
       compresses  them at troughs.  This has the effect of using
       the available levels of  intensity  more  efficiently  and
       thereby increases the detail visible in the image.

       Mathematically,  if  N[i] is the number of pixels of lumi-
       nosity i in the image and T is the total number of pixels,
       luminosity j is replaced by:

                j
               ---
               \
                >   N[i] / T

               ---
               i=0

       If  you're processing a related set of images, for example
       frames of an animation, it's generally best to  apply  the
       same  intensity map 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 portable graymap, the luminosity map computed from an
       image  (usually  a  composite  of the images you intend to
       process created with pnmcat).  Then, you can  subsequently
       process each of the individual images using the luminosity
       map saved in the file, supplied with the -rmap option.

OPTIONS
       -gray     When  processing  a  pixmap,  only  gray  pixels
                 (those  with identical red, green, and blue val-
                 ues) 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  colour  annotations you
                 don't want modified.  Weather  satellite  images
                 that  show continent outlines in colour are best
                 processed using this option.  The option has  no
                 effect when the input is a graymap.

       -rmap mapfile
                 Process the image using the luminosity map spec-
                 ified by  the  portable  graymap  mapfile.   The
                 graymap,  usually  created  by an earlier run of
                 pnmhisteq with the -wmap option, contains a sin-
                 gle row with number of columns equal to the max-
                 val (greatest intensity)  of  the  image.   Each
                 pixel  in the image is transformed by looking up
                 its luminosity in the  corresponding  column  in
                 the  map file and changing it to the value given
                 by that column.

       -wmap mapfile
                 Creates a portable graymap, 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  pro-
                 cessed with an identical map.

       -verbose  Prints the histogram and luminosity map on stan-
                 dard error.

       All flags can be abbreviated to their shortest unique pre-
       fix.

BUGS
       Histogram  equalisation  is  effective  for increasing the
       visible detail in scientific imagery and in some  continu-
       ous-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 pgnnorm, ppmnorm, 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,  sim-
       ply  adjust  the  maxval of the map with pnmdepth to agree
       with the input image.

       If the input is a PBM file (on which  histogram  equalisa-
       tion is an identity operation), the only effect of passing
       the file through pnmhisteq will be the passage of time.

SEE ALSO
       pgmnorm(1), pnm(5), pnmcat(1),  pnmdepth(1),  pnmgamma(1),
       pnmnorm(1)

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

AUTHOR
        Copyright (C) 1995 by John Walker (kelvin@fourmilab.ch).
                WWW home page: http://www.fourmilab.ch/

       Permission to use, copy, modify, and distribute this soft-
       ware and its documentation for any purpose and without fee
       is hereby granted, without any conditions or restrictions.
       This  software  is  provided  ``as is'' without express or
       implied warranty.

                          19 March 1995                         1