## 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.