NAME

     hist_spec - performs histogram specification on an image

SYNOPSIS

     #include "histogram.h"

     Image *hist_spec(Image *imageP, int mode, char **input);

      <imageP> - pointer to the input Image structure;
      <mode> - if mode = 1, interactively get the histogram
               if mode = 0, the histogram is specified by input;
      <input> - expressions for the specified histogram

     Image *histogram_spec(Image* imageP, float **histogram);
      <imageP> - pointer to the input Image structure;
      <histogram> - the specified histogram

PATH

     $CVIPHOME/HISTOGRAM/histogram.c

DESCRIPTION

     The histogram_spec() function performs a histogram  specifi-
     cation on an image pointer Image* using the histogram speci-
     fied in the pointer to pointer to float  float**  passed  to
     the function.  The specified histogram is computed by calcu-
     lating the cumulative distrubution function of both the ori-
     ginal  histogram and the desired histogram.  The cdf for the
     original histogram is then mapped to the  desired  histogram
     using  the inverse cdf.  If Pr(x) is the original histogram,
     and Pz(x) is the desired histogram, then  the  cdf[Pr(x)]  =
     T(r) = s, and cdf[Pz(x)] = G(z) = v.  The inverse of this is
     z = inv[G(v)].  Therefore z = inv[G(T(r))].  Where r is  the
     original  grey-level, and z is the new grey-level.

     The histogram_spec can perform a different specification  on
     each color band in the image.

     hist_spec()   is   a    higher    level    function    above
     histogram_spec().  The  difference  is that hist_spec() will
     get a mathematical formula for  each  band  to  specify  the
     desired  histogram,  create the specified the histogram, and
     call histogram_spec(). Usually, the user  calls  hist_spec()
     directly, and calls histogram_spec() indirectly.

RETURN VALUES

     Both functions return a valid Image pointer on success;  and
     return a NULL pointer on failure.

BUGS

     May not work with some gif images.

SEE ALSO

     makeHistogram_Image     define_histogram,     get_histogram,
     get_histogram_Image,     histogram_show,     make_histogram,
     showMax_histogram

AUTHOR

     Copyright (C) 1992, 1996 SIUE - by Scott E.  Umbaugh,  David
     Lyons and Yansheng Wei.