coyote: CGSTRETCH

Description
The program implements an interactive way to stretch an image histogram and provide
contrast for 2D image arrays. This is commonly known as "contrast stretching."
The program supports the following stretches::
      LINEAR         Linear stretch between end points.
      CLIP           Linear, except a 2% of pixels are clipped at either end of histogram.
      GAMMA          An exponential function.
      LOG            A natural logarithmic function, similar to gamma but with fixed shape.
      ASINH          An inverse hyperbolic sine function (strong log function).
      SQUARE ROOT    The square-root of the image pixels is stretched linearly.
      EQUALIZATION   Image histogram is equalized before stretching.
      ADAPTIVE EQUALIZATION Image histogram is equalized with Adapt_Hist_Equal before stretching.
      GAUSSIAN       A gaussian normal distribution function is applied to the stretch.
      STDDEV         The image is stretched by multiples of its standard deviation from its mean value.
      COMPRESSION    The mid-tones of the image are compressed by varying amounts.
.. image:: cgstretch.png
Categories
Image Processing, Widgets
Examples
If you have a 2D image in the variable "image", you can run this program like this::
    IDL> image = cgDemoData(7)
    IDL> cgStretch, image
    IDL> cgStretch, image, TYPE='GAMMA'
    IDL> cgStretch, image, TYPE='LOG', EXPONENT=5.5
    IDL> cgStretch, image, TYPE='ASINH', BETA=0.1
Author
FANNING SOFTWARE CONSULTING::
   David W. Fanning 
   1645 Sheely Drive
   Fort Collins, CO 80526 USA
   Phone: 970-221-0438
   E-mail: davidf@dfanning.com
   Coyote's Guide to IDL Programming: http://www.dfanning.com
History
Change History::
   Written by David W. Fanning, April 1996, as XStretch.
   XStretch retired and the program was renamed cgStretch, 21 October 2012.
   Added Compression stretch and updated to Coyote Graphics stretch functions. 27 March 2015. DWF.
Copyright
Copyright (c) 1996-2012, Fanning Software Consulting, Inc.
 procedure validates a threshold value to make sure it doesn't
out of range.
Returns
A validated threshold value in the appropriate range.
Params
theimage: in, required
   The image data to be stretched. It must be 2D array or a pointer to a 2D array.
Returns
The stretched image is returned.
Keywords
beta: in, optional, type=float, default=3.0
    The beta factor in a Hyperpolic Sine stretch.
block: in, optional, type=boolean, default=0
    Set this keyword if you wish the program to be a blocking widget.
brewer: in, optional, type=boolean, default=0
     Set this keyword if you wish to use the Brewer color tables.
colors: in, optional, type=string
     A five element string array, listing the colors for drawing the
     histogram plot. If a particular color is represented as a null string, then the
     default for that color is used. The colors are used as follows::
         colors[0] : Background color. Default: "white".
         colors[1] : Axis color. Default: "black".
         colors[2] : Min threshold color. Default: "firebrick".
         colors[3] : Max threshold  color. Default: "steel blue".
         colors[4] : ASinh color. Default: "grn6".
         colors[5] : Histogram color. Default: "charcoal".
colortable: in, optional, type=integer, default=0
     The color table to display the image in. By default, gray-scale colors.
constant: in, optional, type=float, default = 1.0
     The constant value in a logarithmic stretch. 
exclude: in, optional, type=numeric
     The value to exclude in a standard deviation stretch.
exponent: in, optional, type=float, default=4.0
     The logarithm exponent in a logarithmic stretch.
filename: in, optional, type=string
     If no image is supplied as a positional parameter, this keyword can be
     used to specify the name of an image file to read with ImageSelect.
gamma: in, optional, type=float, default=1.5
     The gamma factor in a gamma stretch.
group_leader: in, optional, type=integer
     The identifier of the widget group leader is this program is called from within
     a widget program.
max_value: in, optional, type=varies
     Use this keyword to assign a maximun value for the normalized Histogram Plot.
     Images with lots of pixels of one color (e.g. black) skew the histogram. This 
     helps make a better looking plot. Set by default to the maximum value of the 
     histogram data.
maxthresh: in, optional
     The initial maximum threshold value for the stretch.
mean: in, optional, type=float, default=0.5
     The mean factor in a logarithmic stretch.
minthresh: in, optional
     The initial minimun threshold value for the stretch.
multiplier: in, optional, type=float
     The multiplication factor in a standard deviation stretch. The standard deviation
     is multiplied by this factor to produce the thresholds for a linear stretch.
negative: in, optional, type=boolean, default=0
     Set this keyword if you want to display the image with a negative or reverse stretch.
no_window: in, optional, type=boolean, default=0
     Set this keyword if you do no want the program to display an image window. This would 
     be the case, for example, if you are displaying the image in your own window and your program
     is being notified of images changes via the `NOTIFY_PRO` or `NOTIFY_OBJ` keywords.
notify_obj: in, optional, type=struct
     Set this keyword to a structure containing the fields OBJECT and METHOD. When the image is changed, 
     the object identified in the OBJECT field will have the method identified in the METHOD
     field called. The method should be written to accept one positional parameter. The parameter passed 
     to the method is a structure defined as below::
       struct = { image: stretchedImage, $ ; The stretched image.
           r: info.r, $                    ; The R color vector associated with the image
           g: info.g, $                    ; The G color vector associated with the image
           b: info.b, $                    ; The B color vector associated with the image
           type: info.type, $              ; The TYPE of stretch applied to the image.
           minThresh: info.minThresh, $    ; The minimum threshold value.
           maxThresh: info.maxThresh, $    ; The maximum threshold value.
           beta: info.beta, $              ; The current BETA value.
           gamma: info.gamma, $            ; The current GAMMA value.
           mean: info.mean, $              ; The current MEAN value.
           exponent: info.exponent, $      ; The current EXPONENT value.
           multiplier: info.multiplier, $  ; The current MULTIPLIER value.
           sigma: info.sigma }             ; The current SIGMA value.
notify_pro: in, optional, type=string
     Set this keyword to the name of a procedure that should be notified when the image is changed. 
     The procedure should be defined with one positional parameter. The parameter passed
     to the procedure is a structure defined in the `Notify_Obj` keyword..
sigma: in, optional, type=float, default=1.0
     The sigma scale factor in a Gaussian stretch.
title: in, optional, type=string
     The title of the histogram window. By default: 'Drag Vertical Lines to STRETCH Image Contrast'.
type: in, optional, type=integer
     The type of stretch to be applied. May be either a string (e.g, 'GAMMA') or a number from the table below::
       Number   Type of Stretch
         0         Linear         scaled = BytScl(image, MIN=minThresh, MAX=maxThresh)
         1         Gamma          scaled = cgGmaScl(image, MIN=minThresh, MAX=maxThresh, Gamma=gamma)
         2         Log            scaled = cgLogScl(image, MIN=minThresh, MAX=maxThresh, Constant=constant)
         3         Asinh          scaled = cgAsinhScl(image, MIN=minThresh, MAX=maxThresh, Beta=beta)
         4         Linear 2%      A linear stretch, with 2 percent of pixels clipped at both the top and bottom
         5         Square Root    A linear stretch of the square root histogram of the image values.
         6         Equalization   A linear stretch of the histogram equalized image histogram.
         7         Gaussian       A Gaussian normal function is applied to the image histogram.
         8         StdDev         The image is stretched linearly based on its mean and a multiple of its standard deviation.
         9         Compression    scaled = cgCompressScl(image, MIN=minThresh, MAX=maxThresh, Mean=mean, Exponent=exponent)
uvalue: in, optional
     Any IDL variable can be stored in this keyword.
xpos: in, optional, type=integer, default=100
     The X position of the histogram window in pixels from upper-left of display.
ypos: in, optional, type=integer, default=100
     The Y position of the histogram window in pixels from upper-left of display.