.\
cgstretch.pro
Image Processing, Widgets
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.
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 information
- 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- Copyright
Copyright (c) 1996-2012, Fanning Software Consulting, Inc.
- 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.
Routines
result = cgSTRETCH_VALIDATE_THRESHOLD(threshold, info)This procedure validates a threshold value to make sure it doesn't get out of range.
result = cgSTRETCH_SCALEIMAGE(info)The function stretches the image according to the current stretch parameters.
cgSTRETCH_IMAGEWINDOWKILLED, imageWindowIDThe call-back routine responds appropriately when the image window is destroyed by the user.
cgSTRETCH_SAVETOMAIN, eventThe event handler saves the stretched image to the main program level, where it can be manipulated further.
cgSTRETCH_DRAWLINES, minThresh, maxThresh, infoThis procedure draws the minimum and maximum threshold lines on the histogram plot.
cgSTRETCH_NOTIFYOTHERS, infoThis procedure will notify interested parties (who have signed up with the NotifyObj or NotifyPro keywords) about program events.
cgSTRETCH_HISTOPLOT, info [, MAXVALUE=MAXVALUE] [, WID=WID]This procedure draws the histogram plot for the image.
cgSTRETCH_PARAMETERS, eventThis event handler sets up the stretch parameters for the different stretches.
cgSTRETCH_FLIPIMAGE, eventThis event handler will reverse the image in the Y direction.
cgSTRETCH_GAMMA, eventThis event handler saves the Gamma pull-down menu events.
cgSTRETCH_NEGATIVE, eventThis event handler reverses the image to a negative image.
cgSTRETCH_OPENIMAGE, eventThis event handler allows new images to be opened and displayed.
cgSTRETCH_SAVEAS, eventThis event handler saves the stretched image in various raster and PostScript formats.
cgSTRETCH_SAVEHISTOAS, eventThis event handler saves the histogram in various raster and PostScript formats.
cgSTRETCH_SETTHRESHOLD, eventThis event handler sends the threshold values for the stretch.
cgSTRETCH_PRINT, eventThis event handler sends the output to a printer.
cgSTRETCH_PROCESS_EVENTS, eventThis event handler ONLY responds to button down events from the draw widget.
cgSTRETCH_MOVELINE, eventThis event handler continuously draws and erases a threshold line until it receives an UP event from the draw widget.
cgSTRETCH_RESTORE, eventThe event handler restores the original stretch parameters.
cgSTRETCH_STRETCHTYPE, eventThe event handler handles events from the Stretch Type buttons.
cgSTRETCH_QUIT, eventThe event handler that deals with the QUIT button.
cgSTRETCH_COLORS, eventThe event handler that deals setting image colors
cgSTRETCH_MAXVALUE, eventThe event handler that deals with the setting of the Max Value widget.
cgSTRETCH_IMAGE_RESIZE, eventThe event handler that deals with resizing the image window.
cgSTRETCH_HISTOGRAM_RESIZE, eventThe event handler that deals with resizing the histogram window.
cgSTRETCH_CLEANUP, tlbThe widget clean-up routine.
cgSTRETCH, theImage [, Beta=float] [, /Block] [, /Brewer] [, Colors=string] [, Colortable=integer] [, Constant=float] [, Exclude=numeric] [, Exponent=float] [, Filename=string] [, Gamma=float] [, Group_Leader=integer] [, MinThresh=MinThresh] [, MaxThresh=MaxThresh] [, Max_Value=varies] [, Multiplier=float] [, Mean=float] [, /Negative] [, /No_Window] [, Notify_Obj=struct] [, Notify_Pro=string] [, Sigma=float] [, Title=string] [, Type=integer] [, UValue=UValue] [, XPos=integer] [, YPos=integer], _EXTRA=_EXTRAThe widget definition module for this interative contrast stretching program.
Routine details
top cgSTRETCH_VALIDATE_THRESHOLD
result = cgSTRETCH_VALIDATE_THRESHOLD(threshold, info)
This procedure validates a threshold value to make sure it doesn't get out of range.
: Returns: A validated threshold value in the appropriate range.
Parameters
- threshold in required
The input threshold to check and validate.
- info in required
The program's information structure.
top cgSTRETCH_SCALEIMAGE
result = cgSTRETCH_SCALEIMAGE(info)
The function stretches the image according to the current stretch parameters.
Return value
The stretched image is returned.
Parameters
- info in required
The information structure for the program.
top cgSTRETCH_IMAGEWINDOWKILLED
cgSTRETCH_IMAGEWINDOWKILLED, imageWindowID
The call-back routine responds appropriately when the image window is destroyed by the user.
Parameters
- imageWindowID in required
The identifier of the image draw widget.
top cgSTRETCH_SAVETOMAIN
cgSTRETCH_SAVETOMAIN, event
The event handler saves the stretched image to the main program level, where it can be manipulated further.
Parameters
- event in required
The event structure.
top cgSTRETCH_DRAWLINES
cgSTRETCH_DRAWLINES, minThresh, maxThresh, info
This procedure draws the minimum and maximum threshold lines on the histogram plot.
Parameters
- minThresh in required
The minimum threshold value.
- maxThresh in required
The maximum threshold value.
- info in required type=struct
The information structure for the program.
top cgSTRETCH_NOTIFYOTHERS
cgSTRETCH_NOTIFYOTHERS, info
This procedure will notify interested parties (who have signed up with the NotifyObj or NotifyPro keywords) about program events.
Parameters
- info in required
The info structure of the program.
top cgSTRETCH_HISTOPLOT
cgSTRETCH_HISTOPLOT, info [, MAXVALUE=MAXVALUE] [, WID=WID]
This procedure draws the histogram plot for the image.
Parameters
- info in required
The information structure for the program.
Keywords
- MAXVALUE in optional
The maximum value that the histogram plot will display.
- WID in optional
The window index number of the window the histogram plot should be drawn in.
top cgSTRETCH_PARAMETERS
cgSTRETCH_PARAMETERS, event
This event handler sets up the stretch parameters for the different stretches.
Parameters
- event in required
The event structure.
top cgSTRETCH_FLIPIMAGE
cgSTRETCH_FLIPIMAGE, event
This event handler will reverse the image in the Y direction.
Parameters
- event in required
The event structure.
top cgSTRETCH_GAMMA
cgSTRETCH_GAMMA, event
This event handler saves the Gamma pull-down menu events.
Parameters
- event in required
The event structure.
top cgSTRETCH_NEGATIVE
cgSTRETCH_NEGATIVE, event
This event handler reverses the image to a negative image.
Parameters
- event in required
The event structure.
top cgSTRETCH_OPENIMAGE
cgSTRETCH_OPENIMAGE, event
This event handler allows new images to be opened and displayed.
Parameters
- event in required
The event structure.
top cgSTRETCH_SAVEAS
cgSTRETCH_SAVEAS, event
This event handler saves the stretched image in various raster and PostScript formats.
Parameters
- event in required
The event structure.
top cgSTRETCH_SAVEHISTOAS
cgSTRETCH_SAVEHISTOAS, event
This event handler saves the histogram in various raster and PostScript formats.
Parameters
- event in required
The event structure.
top cgSTRETCH_SETTHRESHOLD
cgSTRETCH_SETTHRESHOLD, event
This event handler sends the threshold values for the stretch.
Parameters
- event in required
The event structure.
top cgSTRETCH_PRINT
cgSTRETCH_PRINT, event
This event handler sends the output to a printer.
Parameters
- event in required
The event structure.
top cgSTRETCH_PROCESS_EVENTS
cgSTRETCH_PROCESS_EVENTS, event
This event handler ONLY responds to button down events from the draw widget. If it gets a DOWN event, it does two things: (1) finds out which threshold line is to be moved, and (2) changes the event handler for the draw widget to cgSTRETCH_MOVELINE.
Parameters
- event in required
The event structure.
top cgSTRETCH_MOVELINE
cgSTRETCH_MOVELINE, event
This event handler continuously draws and erases a threshold line until it receives an UP event from the draw widget. Then it turns draw widget motion events OFF and changes the event handler for the draw widget back to cgSTRETCH_PROCESS_EVENTS.
Parameters
- event in required
The event structure.
top cgSTRETCH_RESTORE
cgSTRETCH_RESTORE, event
The event handler restores the original stretch parameters.
Parameters
- event in required
The event structure.
top cgSTRETCH_STRETCHTYPE
cgSTRETCH_STRETCHTYPE, event
The event handler handles events from the Stretch Type buttons.
Parameters
- event in required
The event structure.
top cgSTRETCH_QUIT
cgSTRETCH_QUIT, event
The event handler that deals with the QUIT button.
Parameters
- event in required
The event structure.
top cgSTRETCH_COLORS
cgSTRETCH_COLORS, event
The event handler that deals setting image colors
Parameters
- event in required
The event structure.
top cgSTRETCH_MAXVALUE
cgSTRETCH_MAXVALUE, event
The event handler that deals with the setting of the Max Value widget.
Parameters
- event in required
The event structure.
top cgSTRETCH_IMAGE_RESIZE
cgSTRETCH_IMAGE_RESIZE, event
The event handler that deals with resizing the image window.
Parameters
- event in required
The event structure.
top cgSTRETCH_HISTOGRAM_RESIZE
cgSTRETCH_HISTOGRAM_RESIZE, event
The event handler that deals with resizing the histogram window.
Parameters
- event in required
The event structure.
top cgSTRETCH_CLEANUP
cgSTRETCH_CLEANUP, tlb
The widget clean-up routine.
Parameters
- tlb in required
The identifier of the widget that died.
top cgSTRETCH
cgSTRETCH, theImage [, Beta=float] [, /Block] [, /Brewer] [, Colors=string] [, Colortable=integer] [, Constant=float] [, Exclude=numeric] [, Exponent=float] [, Filename=string] [, Gamma=float] [, Group_Leader=integer] [, MinThresh=MinThresh] [, MaxThresh=MaxThresh] [, Max_Value=varies] [, Multiplier=float] [, Mean=float] [, /Negative] [, /No_Window] [, Notify_Obj=struct] [, Notify_Pro=string] [, Sigma=float] [, Title=string] [, Type=integer] [, UValue=UValue] [, XPos=integer] [, YPos=integer], _EXTRA=_EXTRA
The widget definition module for this interative contrast stretching program.
Parameters
- theImage in required
The image data to be stretched. It must be 2D array or a pointer to a 2D array.
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.
- MinThresh in optional
The initial minimun threshold value for the stretch.
- MaxThresh in optional
The initial maximum threshold value for the stretch.
- 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.
- 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.
- Mean in optional type=float default=0.5
The mean factor in a logarithmic 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_PROorNOTIFY_OBJkeywords.- 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_Objkeyword..- 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.
- _EXTRA
File attributes
| Modification date: | Fri Mar 27 11:04:09 2015 |
| Lines: | 3,123 |
| Docformat: | rst rst |