# coyote: CGSTRETCH

- coyote/Image Processing
- coyote/Widget Programming
- [Source code]

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.