Coyote Graphics Routines

Date: Fri Mar 27 12:51:50 2015

single page | use frames     summary     class     fields     routine details     file attributes

.\

cgimage.pro

Graphics


The purpose of this program is to create a TV command that works the way the TV command would be expected to work if it was written today, rather than 25 years ago. In other words, it knows the difference between an 8-bit device and a 24-bit device, it honors the POSITION keyword like other graphics commands in IDL, it honors the !P.MULTI value, like other graphics commands in IDL, it works seamlessly with both 8-bit and 24-bit images. In addition to other modern features, this program can also display images that contain an alpha channel and can display transparent images.

There is a common block in cgImage that is defined as follows upon exiting this command:

COMMON FSC_$CGIMAGE, $ _cgimage_xsize, $ ; The X size of the image. _cgimage_ysize, $ ; The Y size of the imge. _cgimage_winxsize, $ ; The X size of the window displaying the image. _cgimage_winysize, $ ; The Y size of the window displaying the image. _cgimage_position, $ ; The final position of the image in the window. _cgimage_winID, $ ; The window index number of the window displaying the image. _cgimage_current ; Set to 1 if a call to cgImage is made.
The program requires the Coyote Library to be installed on your machine.

To learn more about transparent images and cgImage see the article Working with Transparent Images and cgImage.

Examples

To display an image with a contour plot on top of it, type:

filename = FILEPATH(SUBDIR=['examples','data'], 'worldelv.dat') image = BYTARR(360,360) OPENR, lun, filename, /GET_LUN READU, lun, image FREE_LUN, lun thisPostion = [0.1, 0.1, 0.9, 0.9] cgIMAGE, image, POSITION=thisPosition, /KEEP_ASPECT_RATIO CONTOUR, image, POSITION=thisPosition, /NOERASE, XSTYLE=1, $ YSTYLE=1, XRANGE=[0,360], YRANGE=[0,360], NLEVELS=10
To display four images in a window without spacing between them:
!P.Multi=[0,2,2] cgImage, image, Margin=0 cgImage, image, Margin=0 cgImage, image, Margin=0 cgImage, image, Margin=0 !P.Multi = 0
To display four image in a window with associated color bars:
!P.Multi=[0,2,2] p = [0.02, 0.3, 0.98, 0.98] LoadCT, 0 cgImage, image, Position=p cgColorbar, Position=[p[0], p[1]-0.1, p[2], p[1]-0.05] p = [0.02, 0.3, 0.98, 0.98] LoadCT, 2 cgImage, image, Position=p cgColorbar, Position=[p[0], p[1]-0.1, p[2], p[1]-0.05] p = [0.02, 0.3, 0.98, 0.98] LoadCT, 3 cgImage, image, Position=p cgColorbar, Position=[p[0], p[1]-0.1, p[2], p[1]-0.05] p = [0.02, 0.3, 0.98, 0.98] LoadCT, 5 cgImage, image, Position=p cgColorbar, Position=[p[0], p[1]-0.1, p[2], p[1]-0.05] !P.Multi =0
To set a missing value to -32767 and the color white and do a 3% histogram clip of the image:
cgLoadCT, 4, /Brewer, NColors=254 TVLCT, palette, /Get cgImage, image, Missing_Value=-32767, Missing_Color='white', Stretch='Clip', Clip=3
To display a transparent image on top of another image:
cgImage, cgDemoData(7), CTIndex=0 cgImage, cgDemoData(5), CTIndex=33, Transparent=50, $ AlphaFGPosition=[0.25, 0.25, 0.75, 0.75], Missing_Value=0

Author information

Author

FANNING SOFTWARE CONSULTING:

David W. Fanning 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com/

Copyright

Copyright (c) 2011-2015, Fanning Software Consulting, Inc.

History

Modification History:

Written by: David W. Fanning, from modifications to TVIMAGE. 3 Feb 2011. 8 Feb 2011. Added OPOSITION keyword. DWF. 27 Feb 2011. Added keywords to make cgImage more compatible with TVImage calls. DWF. Color table vectors must be obtained AFTER loading the color palette. 6 March 2011. DWF. I have been convinced (conversations with Wayne Landsman) that if the CENTER keyword is set, the MINUS_ONE keyword is not needed, since it was created to solve the same problem. So, I have changed the default setting of MINUS_ONE to 0. 14 March 2011. DWF. Corrected a problem with restoring color tables if a PALETTE is used. 31 March 2011. DWF. Whoops! Documented a CHARSIZE keyword, but forgot to define it. 7 July 2011. Damnation! I did the same thing with the FONT keyword! 25 July 2011. And now a TITLE keyword! What the devil is going on!? 29 Aug 2011. Very slight modifications to image size and start position so that the image is positioned completely inside the axes. 30 Sept 2011. DWF. Fitting the image inside the axes causes image matching problems (and lines!) in other programs, so I've decided to only do positioning inside axes when the user asks for this capability by setting the new FIT_INSIDE keyword. 16 Nov 2011. DWF. Problem with transparent images with alpha channels caused by changes in the TVImage->cgImage transition. Added AlphaFGPosition keyword to address issues. Cleaned up the code and improved the internal documentation. 22 Nov 2011. DWF. Added the ability to stretch 2D image arrays in various ways before display. 1 Dec 2011. Added the ability to handle missing data in 2D arrays before display. 1 Dec 2011. Added a DISPLAY keyword to display the image in windows with the image aspect ratio. 2 Dec 2011. Added the ability to send the output directly to a file via the OUTPUT keyword. 9 Dec 2011, DWF. PostScript, PDF, and Imagemagick parameters can now be tailored with cgWindow_SetDefs. 14 Dec 2001. DWF. Modified to use cgDefaultColor for default color selection. 24 Dec 2011. DWF. Changes to allow better default colors, based on changes to cgColor and cgDefaultColor. 1 Feb 2012. DWF. I was passing the wrong MINVALUE and MAXVALUE values to the scaling function. 12 Feb 2012. DWF. I made cgImage aware of a "feature" of MAP_SET that sets !P.MULTI[0]=-1, which was screwing up the algorithm to cause cgImage to erase the display window. 28 Feb 2012. DWF. Added a Standard Deviation stretch, including the EXCLUDE and MULTIPLIER keywords to the SDevScl command. 6 June 2012. DWF. Now saving the image POSITION in FSC_$CGIMAGE common block, even if in PostScript, because other routines (e.g., cgMap) may depend on it (e.g., using ONIMAGE keyword). 26 July 2012. DWF. Added the ability to use escape characters in plot titles to specify cgSymbol symbols. 27 July 2012. DWF. Modified the way the XRANGE and YRANGE keywords work when the OVERPLOT keyword is also set. In this case, I will modify the image position to honor the XRANGE and YRANGE values with respect to the axes that the image is being overplot onto. 15 August 2012. DWF. Set the NOERASE keyword if the OVERPLOT keyword is set and NOERASE is undefined. 16 Aug 2012. DWF. Modified the way the HIST_EQUAL stretch works. Previously the image was displayed as all zeros if the input image had a minimum value less that zero. 21 Aug 2012. DWF. Fixed a problem with the INTERPOLATE variable that prevented interpolaton from occurring. 12 Sept 2012. DWF. A misspelled MULTIPLIER keyword was interfering with a Standard Deviation stretch. 16 Sept 2012. DWF Added the TRANSPARENT keyword to allow transparent display of images. 17 October 2012. DWF. Added the MAPCOORD keyword to allow the XRANGE and YRANGE of the image to be specified by the map coordinate object. 17 October 2012. DWF. Added CTINDEX, BREWER, and REVERSE keywords to make loading a color table palette easier. 17 October 2012. DWF. Now setting MISSING_VALUE pixels to completely transparent if a transparent image is created. 17 October 2012. DWF. Added the ability to apply a stretch to a 2D image prior to converting it to a transparent image. 18 October 2012.DWF. Added a FILENAME keyword so that files of known format (GeoTIFF, JPEG, PNG, etc.) can be read to supply an image for display. 18 October 2012. DWF. Fixed a problem that prevented transparent images from be displayed with !P.Multi. 20 Oct 2012. DWF. Provided a fix to allow transparent images in versions of IDL from IDL 6.4 and earlier. 18 Nov 2012. DWF. When reading a GeoTiff file, the map object created should be named mapCoord, not map, so that the image data ranges can be set automatically. 11 January 2013. DWF. Additional work to allow overplotting of transparent images. 12 Jan 2013. DWF. For some reason I thought I had to have transparency ON when overplotting. This turns out to be wrong and gets in the way of outputting to PostScript and working with some map projected images. I've removed this requirement in the code. I also fixed a problem in which the OUTPUT position changes if the TRANSPARENT keyword is used. 27 January 2013. DWF. I had some code dealing with XRANGE and YRANGE properties of the image when a map coodinate object was used with cgImage. This was inadvertently setting the XRANGE and YRANGE properties of the image, which was in turn causing the range values to be SAVED in the plotting system variables. This interferred with backward compatibility with the TV command, so I have removed it. 31 Jan 2013. DWF. Whoops! Typo in my last fix. Getting too old, I guess. 6 Feb 2013. DWF. Setting any of the MISSING_*** keywords while doing multiple plots resulted in the value of !P.Multi being ignored for the image. This is fixed for now, but just a warning. Setting these keywords creates transparent images, and makes things MUCH more complicated. So, I'm probably at the limit of what is possible now. :-) 30 April 2013. DWF. The LAYOUT keyword went on walkabout after the last changes. Restored to operation. 12 July 2013. DWF. The YTITLE keyword was missing when passed to cgWindow. Fixed now. 24 Oct 2013. DWF. Fixed a couple of places where I meant "missing_index" and used "missing_color". 26 Jan 2014. DWF. Added check for open graphics window when displaying alpha-channel image. 31 March 2014. DWF. Added XVECTOR and YVECTOR keywords. 1 April 2014. DWF. Fixed a problem in which the POSITION of the image was specified as an integer array when it should have been a floating point array. 8 January 2015. DWF. Added compression stretch and updated retired program references. 27 Mar 2015. DWF.

Routines

result = cgImage_Make_Transparent_Image(image [, transparent] [, MISSING_VALUE=integer] [, PALETTE=bytarr] [, SUCCESS=SUCCESS])

This function creates a transparent image out of a normal 2D or 3D image.

result = cgImage_Prepare_Alpha(image, alphaBackgroundImage, ALPHABGPOSITION=fltarr, ALPHAFGPOSITION=fltarr [, /TV])

This routine prepares a transparent image (an image with an alpha channel) for display.

result = cgImage_Prepare_Output(image [, xsize] [, ysize] [, BOTTOM=integer] [, BETA=float] [, CLIP=float] [, CONSTANT=float] [, EXCLUDE=EXCLUDE] [, EXPONENT=float] [, GAMMA=float] [, /INTERPOLATE] [, MAXVALUE=varies] [, MEAN=float] [, /MINUS_ONE] [, MINVALUE=varies] [, MISSING_INDEX=integer] [, MISSING_VALUE=integer] [, MULTIPLIER=float] [, /NEGATIVE] [, /SCALE] [, STRETCH=integer/string] [, SIGMA=float] [, TOP=integer])

This routine scales or otherwise prepares an image to be displayed.

cgImage, image [, x] [, y] [, /ADDCMD] [, ALPHABACKGROUNDIMAGE=varies] [, ALPHABGPOSITION=fltarr(4)] [, ALPHAFGPOSITION=fltarr(4)] [, /AXIS] [, /AXES] [, AXKEYWORDS=structure] [, BACKGROUND=string] [, BOTTOM=integer] [, BETA=float] [, /BREWER] [, CHARSIZE=float] [, CLIP=float] [, COLOR=string] [, CTINDEX=integer] [, /DISPLAY] [, /ERASE] [, EXCLUDE=EXCLUDE] [, EXPONENT=float] [, FILENAME=string] [, /FIT_INSIDE] [, FONT=integer] [, GAMMA=float] [, /INTERPOLATE] [, /KEEP_ASPECT_RATIO] [, LAYOUT=intarr] [, MAPCOORD=object] [, MARGIN=float] [, MAXVALUE=varies] [, MEAN=float] [, MISSING_COLOR=string] [, MISSING_INDEX=integer] [, MISSING_VALUE=integer] [, /NEGATIVE] [, /MINUS_ONE] [, MINVALUE=varies] [, MULTIMARGIN=varies] [, MULTIPLIER=float] [, NCOLORS=integer] [, /NOERASE] [, /NOINTERPOLATION] [, /NORMAL] [, OUTFILENAME=string] [, OUTPUT=string] [, OPOSITION=float] [, /OVERPLOT] [, PALETTE=byte] [, POSITION=float] [, /QUIET] [, /REVERSE] [, /SAVE] [, /SCALE] [, SIGMA=float] [, STRETCH=integer/string] [, TITLE=string] [, TOP=integer] [, TRANSPARENT=integer] [, /TV] [, /WINDOW] [, XRANGE=fltarr(2)] [, XTITLE=string] [, XVECTOR=XVECTOR] [, YRANGE=fltarr(2)] [, YTITLE=string] [, YVECTOR=YVECTOR] [, _REF_EXTRA=varies]

The purpose of this program is to create a TV command that works the way the TV command would be expected to work if it was written today, rather than 25 years ago.

Routine details

top cgImage_Make_Transparent_Image

result = cgImage_Make_Transparent_Image(image [, transparent] [, MISSING_VALUE=integer] [, PALETTE=bytarr] [, SUCCESS=SUCCESS])

This function creates a transparent image out of a normal 2D or 3D image.

Parameters

image in required

The input image. Must be either 2D or a true-color image.

transparent in optional type=integer default=50

The transparentcy of the image with respect to the background image. A number from 0 to 100.

Keywords

MISSING_VALUE in optional type=integer

The number that represents the missing value in the image. Available only with 2D images. This value is set to be completely transparent in the image.

PALETTE in optional type=bytarr

A 3x256 byte array containing the color table vectors that the image is to be displayed in.

SUCCESS out optional

An output keyword that is set to 1 if the transparent image is created successfully. Otherwise, set to 0.

top cgImage_Prepare_Alpha

result = cgImage_Prepare_Alpha(image, alphaBackgroundImage, ALPHABGPOSITION=fltarr, ALPHAFGPOSITION=fltarr [, /TV])

This routine prepares a transparent image (an image with an alpha channel) for display.

Return value

Returns an image that has been blended with the background image and is suitable for display with cgImage.

Parameters

image in required

The input image that is being prepared for display. It will contain an alpha channel.

alphaBackgroundImage in required

The background image. The input image will be blended with the background image.

Keywords

ALPHABGPOSITION in required type=fltarr

The normalized position or portion of the background image used to create the alpha image.

ALPHAFGPOSITION in required type=fltarr

The normalized position in the background image where the input image is to be located.

TV in optional type=boolean default=0

If this keyword is set, the alpha channel is removed from the input image, because we cannot display an image with an alpha channel if the cgImage command is acting like a smarter IDL TV command.

top cgImage_Prepare_Output

result = cgImage_Prepare_Output(image [, xsize] [, ysize] [, BOTTOM=integer] [, BETA=float] [, CLIP=float] [, CONSTANT=float] [, EXCLUDE=EXCLUDE] [, EXPONENT=float] [, GAMMA=float] [, /INTERPOLATE] [, MAXVALUE=varies] [, MEAN=float] [, /MINUS_ONE] [, MINVALUE=varies] [, MISSING_INDEX=integer] [, MISSING_VALUE=integer] [, MULTIPLIER=float] [, /NEGATIVE] [, /SCALE] [, STRETCH=integer/string] [, SIGMA=float] [, TOP=integer])

This routine scales or otherwise prepares an image to be displayed.

Return value

Returns an image that can be displaye properly.

Parameters

image in required

The input image that is being prepared for display.

xsize in optional

The output X size of the image.

ysize in optional

The output Y size of the image.

Keywords

BOTTOM in optional type=integer default=0

If the SCALE keyword is set, the image is scaled before display so that all displayed pixels have values greater than or equal to BOTTOM and less than or equal to TOP.

BETA in optional type=float default=3.0

The beta factor in a Hyperpolic Sine stretch.

CLIP in optional type=float default=2

A number between 0 and 50 that indicates the percentage of pixels to clip off either end of the image histogram before performing a linear stretch.

CONSTANT in optional type=float default=1.0

A constant multiplier for the cgLogScl stretch.

EXCLUDE in optional

The value to exclude in a standard deviation stretch.

EXPONENT in optional type=float default=4.0

The logarithm exponent in a logarithmic stretch.

GAMMA in optional type=float default=1.5

The gamma factor in a gamma stretch.

INTERPOLATE in optional type=boolean default=0

Set this keyword to interpolate with bilinear interpolation the display image as it is sized to its final position in the display window. Interpolation will potentially create image values that do not exist in the original image. The default is to do no interpolation, so that image values to not change upon resizing. Interpolation can result in smoother looking final images.

MAXVALUE in optional type=varies

If this value is defined, the data is linearly scaled between MINVALUE and MAXVALUE. MAXVALUE is set to MAX(image) by default. Setting this keyword to a value automatically sets SCALE to 1. If the maximum value of the image is greater than 255, this keyword is defined and SCALE=1.

MEAN in optional type=float default=0.5

The mean factor in a logarithmic stretch.

MINUS_ONE in optional type=boolean default=0

The value of this keyword is passed along to the cgResizeImage command. It prevents cgResizeImage from adding an extra row and column to the resulting array, which can be a problem with small image arrays.

MINVALUE in optional type=varies

If this value is defined, the data is linearly scaled between MINVALUE and MAXVALUE. MINVALUE is set to MIN(image) by default. Setting this keyword to a value automatically sets SCALE=1. If the minimum value of the image is less than 0, this keyword is defined and SCALE=1.

MISSING_INDEX in optional type=integer default=255

The index of the missing color in the final byte scaled image.

MISSING_VALUE in optional type=integer

The number that represents the missing value in the image.

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.

SCALE in optional type=boolean default=0

Set this keyword to byte scale the image before display. If this keyword is not set, the image is not scaled before display. This keyword will be set automatically by using any of the keywords normally associated with byte scaling an image.

STRETCH in optional type=integer/string default=1

The type of scaling performed prior to display. May be specified as a number or as a string (e.g, 4 or "Log").

Number Type of Stretch 0 None No scaling whatsoever is done. 1 Linear scaled = BytScl(image, MIN=minValue, MAX=maxValue) 2 Clip A histogram stretch, with a percentage of pixels clipped at both the top and bottom 3 Gamma scaled = cgGmaScl(image, MIN=minValue, MAX=maxValue, Gamma=gamma) 4 Log scaled = cgLogScl(image, MIN=minValue, MAX=maxValue, Mean=mean, Exponent=exponent) 5 Asinh scaled = cgAsinhScl(image, MIN=minValue, MAX=maxValue, Beta=beta) 6 SquareRoot A linear stretch of the square root histogram of the image values. 7 Equalization A linear stretch of the histogram equalized image histogram. 8 Gaussian A Gaussian normal function is applied to the image histogram. 9 MODIS Scaling done in the differential manner of the MODIS Rapid Response Team and implemented in the Coyote Library routine ScaleModis. 10 StdDev A standard deviation stretch. scaled = cgSDevScl(image, Multiplier=2.0). 11 Compression Compress the mid-tones of the image. scaled = cgCompressScl(image, Constant=2.0)

SIGMA in optional type=float default=1.0

The sigma scale factor in a Gaussian stretch.

TOP in optional type=integer default=255

If the SCALE keyword is set, the image is scaled before display so that all displayed pixels have values greater than or equal to BOTTOM and less than or equal to TOP.

top cgImage

cgImage, image [, x] [, y] [, /ADDCMD] [, ALPHABACKGROUNDIMAGE=varies] [, ALPHABGPOSITION=fltarr(4)] [, ALPHAFGPOSITION=fltarr(4)] [, /AXIS] [, /AXES] [, AXKEYWORDS=structure] [, BACKGROUND=string] [, BOTTOM=integer] [, BETA=float] [, /BREWER] [, CHARSIZE=float] [, CLIP=float] [, COLOR=string] [, CTINDEX=integer] [, /DISPLAY] [, /ERASE] [, EXCLUDE=EXCLUDE] [, EXPONENT=float] [, FILENAME=string] [, /FIT_INSIDE] [, FONT=integer] [, GAMMA=float] [, /INTERPOLATE] [, /KEEP_ASPECT_RATIO] [, LAYOUT=intarr] [, MAPCOORD=object] [, MARGIN=float] [, MAXVALUE=varies] [, MEAN=float] [, MISSING_COLOR=string] [, MISSING_INDEX=integer] [, MISSING_VALUE=integer] [, /NEGATIVE] [, /MINUS_ONE] [, MINVALUE=varies] [, MULTIMARGIN=varies] [, MULTIPLIER=float] [, NCOLORS=integer] [, /NOERASE] [, /NOINTERPOLATION] [, /NORMAL] [, OUTFILENAME=string] [, OUTPUT=string] [, OPOSITION=float] [, /OVERPLOT] [, PALETTE=byte] [, POSITION=float] [, /QUIET] [, /REVERSE] [, /SAVE] [, /SCALE] [, SIGMA=float] [, STRETCH=integer/string] [, TITLE=string] [, TOP=integer] [, TRANSPARENT=integer] [, /TV] [, /WINDOW] [, XRANGE=fltarr(2)] [, XTITLE=string] [, XVECTOR=XVECTOR] [, YRANGE=fltarr(2)] [, YTITLE=string] [, YVECTOR=YVECTOR] [, _REF_EXTRA=varies]

The purpose of this program is to create a TV command that works the way the TV command would be expected to work if it was written today, rather than 25 years ago. In other words, it knows the difference between an 8-bit device and a 24-bit device, it honors the POSITION keyword like other graphics commands in IDL, it honors the !P.MULTI value, like other graphics commands in IDL, it works seamlessly with both 8-bit and 24-bit images. In addition to other modern features, this program can also display images that contain an alpha channel and can display transparent images.

Also, two-dimensional image arrays can be manipulated, stretched, and scaled directly with keywords to cgImage. These keywords do not work with alpha channel images, or if the TV keyword is used with cgImage.

Parameters

image in required type=various

An 8-bit (MxN), 24-bit (e.g., MxNx3), or a 24-bit + alpha channel (e.g., MxNx4) image to display.

x in optional type=integer

The X position of the lower-left corner of the image in device coordinates. This parameter is only recognized if the TV keyword is set. If the Y position is not used, X is taken to be the image "position" in the window. See the TV command documenation for details.

y in optional type=integer

The Y position of the lower-left corner of the image in device coordinates. This parameter is only recognized if the TV keyword is set.

Keywords

ADDCMD in optional type=boolean default=0

Set this keyword to add this command to an already open cgWindow to be executed when the window is resized. If the DISPLAY keyword is also set, this keyword will act as if the WINDOW keyword were set.

ALPHABACKGROUNDIMAGE in optional type=varies

Normally, when a image with an alpha channel is displayed, the image is blended with whatever is currently in the display window. This means, the program has to obtain that background image. This is not a problem on devices (e.g., WIN, X, Z) that allow this kind of operation, but it is on devices (e.g., the PostScript device, PS) that do not. To get around this problem, you can pass the background image to the cgImage program. This background image will be blended with the alpha channel image you wish to display. If an alpha channel image is displayed on a device in which there is no way to obtain the background image, and this keyword is not used to pass a background image, then the alpha channel image will be blended with a white background image. This keyword is only used if an alpha channel image is passed to the program via the IMAGE parameter. The AlphaBackgroundImage does not need to have the same dimensions as the alpha channel image. The background image can be either a 2D image or a 24-bit image.

ALPHABGPOSITION in optional type=fltarr(4)

The normalized position or portion of the background image that is going to be used to create the alpha channel image. Normally, and by default, the alphabgposition encompasses the entire graphics window, [0.0, 0.0, 1.0, 1.0].

ALPHAFGPOSITION in optional type=fltarr(4)

The normalized position in the background image where the input image is to be located. By default, the input image takes up the entire extent of the background image, [0.0, 0.0, 1.0, 1.0].

AXIS in optional type=boolean default=0

A misspelled version of the AXES keyword. Provided as a service to people whose fingers have minds of their own.

AXES in optional type=boolean default=0

Set this keyword to display the image with axes surrounding the image. If the POSITION keyword is not used, a MARGIN of 0.1 is used to allow the axes to show. If you wish to make the image fit entirely inside the axes, set the FIT_INSIDE keyword. Otherwise, the axis sit on top of the image data.

AXKEYWORDS in optional type=structure

A structure of AXIS keywords and values that can be used to configure the axes in whatever way the user desires. Many of the most often used axis keywords are available as cgImage keywords. For example:

IDL> axis_format = {XTicks:4, XTickname:['Cow', 'Pig', 'Dog', 'Cat', 'Owl']} IDL> cgImage, cgDemoData(7), AXKEYWORDS=axis_format, /Axes, XRange=[0,20]

BACKGROUND in optional type=string default=white

The name of the background color for the image display. Unlike the TV command in IDL, the cgImage command will erase the display before executing the command like other fundamental graphics commands (e.g., Plot, Contour, Surface) in IDL.

BOTTOM in optional type=integer default=0

If the SCALE keyword is set, the image is scaled before display so that all displayed pixels have values greater than or equal to BOTTOM and less than or equal to TOP. Available only with 2D images.

BETA in optional type=float default=3.0

The beta factor in a Hyperpolic Sine stretch. Available only with 2D images.

BREWER in optional type=boolean default=0

This keyword is used only if the CTIndex keyword is used to select a color table number. Setting this keyword allows Brewer color tables to be used.

CHARSIZE in optional type=float

Sets the character size. Used only if the AXES keyword is also set. By default, the value from cgDefCharsize().

CLIP in optional type=float default=2

A number between 0 and 50 that indicates the percentage of pixels to clip off either end of the image histogram before performing a linear stretch. Available only with 2D images.

COLOR in optional type=string default=opposite

The name of the color in which to draw the axes. Used only if the AXES keyword is set.

CTINDEX in optional type=integer

The index number of a color table. The Brewer and Reverse keywords will be checked to see how to load the color table into the Palette keyword. This keyword will take precidence over any colors that are loaded with the Palette keyword. The default is to use whatever colors are loaded in the current hardware color table.

DISPLAY in optional type=boolean default=0

If this keyword is set, a new display window is created (with cgDisplay) that has the same aspect ratio as the image. The image is displayed in that window. If the WINDOW keyword is also set, a new cgWindow is created with the WASPECT keyword set to the image aspect ratio, and the image is displayed in that new cgwindow.

ERASE in optional type=boolean default=1

An obsolete keyword. Used only for compatibility with the earlier TVImage command. The default for cgImage is to always erase the graphics display before displaying the image unless told otherwise by setting the NOERASE keyword. This makes cgImage consistent with other IDL graphics commands.

EXCLUDE in optional

The value to exclude in a standard deviation stretch.

EXPONENT in optional type=float default=4.0

The logarithm exponent in a logarithmic stretch. Available only with 2D images.

FILENAME in optional type=string

The name of a file that IDL can read with READ_IMAGE (e.g, GEOTIFF, TIF, JPEG, PNG, etc.). The file is read to obtain the image to be displayed.

FIT_INSIDE in optional type=boolean default=0

When the AXES keyword is set, the default is to position the axes on top of the image using the POSITION. However, if this keyword is set, the axes are positioned at POSITION and the image is sized so that it fits entirely inside the axes.

FONT in optional type=integer

This keyword selects the font used for axis and title display. The default is to use the value of !P.Font.

GAMMA in optional type=float default=1.5

The gamma factor in a gamma stretch. Available only with 2D images.

INTERPOLATE in optional type=boolean default=0

Set this keyword to interpolate with bilinear interpolation the display image as it is sized to its final position in the display window. Interpolation will potentially create image values that do not exist in the original image. The default is to do no interpolation, so that image values to not change upon resizing. Interpolation can result in smoother looking final images.

KEEP_ASPECT_RATIO in optional type=boolean default=0

By default, the output image is resized into the POSITION in the graphics window. This can result in a distortion of the image aspect ratio (the Y size of the image divided by the X size of the image). Setting this keyword will preserve the original aspect ratio of the image in the output display window. In effect, the image will be placed in the window POSITION in a way that preserves its aspect ratio. The actual final location of the image in the display window can be obtained via the OPOSITION keyword.

LAYOUT in optional type=intarr

This keyword specifies a grid with a graphics window and determines where the graphic should appear. The syntax of LAYOUT is a 3-element array: [ncolumns, nrows, location]. The grid is determined by the number of columns (ncolumns) by the number of rows (nrows). The location of the graphic is determined by the third number. The grid numbering starts in the upper left (1) and goes sequentually by column and then by row. Note that using the LAYOUT keyword automatically sets the NOERASE keyword to 1.

MAPCOORD in optional type=object

An object reference to a map coordinate object (e.g., cgMap). If present, the XRANGE and YRANGE keyword values will be obtained from this map object, if they are not defined otherwise.

MARGIN in optional type=float default=0.0

A single value, expressed as a normalized coordinate, that can easily be used to calculate a position in the window. The margin is used to calculate a POSITION that gives the image an equal margin around the edge of the window. The margin must be a number in the range 0.0 to 0.333. This keyword is ignored if the POSITION or OVERPLOT keywords are used. It is also ignored when cgImage is executed in a multi-plot window, EXCEPT if it's value is zero. In this special case, the image will be drawn into its position in the multi-plot window with no margins whatsoever. (The default is to have a slight margin about the image to separate it from other images or graphics. The default margin is 0.05.)

MAXVALUE in optional type=varies

If this value is defined, the data is linearly scaled between MINVALUE and MAXVALUE. MAXVALUE is set to MAX(image) by default. Setting this keyword to a value automatically sets SCALE to 1. If the maximum value of the image is greater than 255, this keyword is defined and SCALE=1.

MEAN in optional type=float default=0.5

The mean factor in a logarithmic stretch. Available only with 2D images.

MISSING_COLOR in optional type=string default=white

The color name of the missing value. Available only with 2D images.

MISSING_INDEX in optional type=integer default=255

The index of the missing color in the final byte scaled image. Available only with 2D images.

MISSING_VALUE in optional type=integer

The number that represents the missing value in the image. Available only with 2D images.

NEGATIVE in optional type=boolean default=0

Set this keyword if you want to display the image with a negative or reverse stretch. Available only with 2D images.

MINUS_ONE in optional type=boolean default=0

The value of this keyword is passed along to the cgResizeImage command. It prevents cgResizeImage from adding an extra row and column to the resulting array, which can be a problem with small image arrays.

MINVALUE in optional type=varies

If this value is defined, the data is linearly scaled between MINVALUE and MAXVALUE. MINVALUE is set to MIN(image) by default. Setting this keyword to a value automatically sets SCALE=1. If the minimum value of the image is less than 0, this keyword is defined and SCALE=1.

MULTIMARGIN in optional type=varies

Sometimes, when displaying multiple images with !P.Multi, you want the images to be slightly smaller than the position created by !P.Multi so you can add, for example, a colorbar or an annotation to the image. This keyword can be used to adjust the image position by a small margin. A four-element array, the margins apply to the [bottom, left, top, right] of the image position. So, to leave room at the top of an image for a color bar, you might type this:

cgImage, image, MultiMargin=[0, 0, 4, 0]
This keyword applies *only* to images displayed with !P.Multi, and if passed a scalar value, will use the same value for all four positions.

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.

NCOLORS in optional type=integer default=256

If this keyword is supplied, the TOP keyword is ignored and the TOP keyword is set equal to NCOLORS-1. This keyword is provided to make cgImgScl easier to use with the color-loading programs such as cgLOADCT:

cgLoadCT, 5, NColors=100, Bottom=100 scaled = cgImgScl(image, NColors=100, Bottom=100)
Setting this keyword to a value automatically sets SCALE=1 and STRETCH='LINEAR', if not defined otherwise. Available only with 2D images.

NOERASE in optional type=boolean default=0

Set this keyword to prevent the command from first erasing the graphics display before displaying the image.

NOINTERPOLATION in optional type=boolean default=0

This is an obsolete keyword that is included here only for compatibility with the older TVImage command. Use the INTERPOLATE keyword.

NORMAL in optional type=boolean default=0

Setting this keyword means image position coordinates x and y are interpreted as being in normalized coordinates. This keyword is only valid if the TV keyword is set.

OUTFILENAME in optional type=string

If the Output keyword is set, the user will be asked to supply an output filename, unless this keyword is set to a non-null string. In that case, the value of this keyword will be used as the filename and there will be no dialog presented to the user.

OUTPUT in optional type=string

Set this keyword to the type of output desired. Possible values are these:

'PS' - PostScript file 'EPS' - Encapsulated PostScript file 'PDF' - PDF file 'BMP' - BMP raster file 'GIF' - GIF raster file 'JPEG' - JPEG raster file 'PNG' - PNG raster file 'TIFF' - TIFF raster file
Or, you can simply set this keyword to the name of the output file, and the type of file desired will be determined by the file extension. If you use this option, the user will not be prompted to supply the name of the output file.

All raster file output is created through PostScript intermediate files (the PostScript files will be deleted), so ImageMagick and Ghostview MUST be installed to produce anything other than PostScript output. (See cgPS2PDF and cgPS_Close for details.) And also note that you should NOT use this keyword when doing multiple plots. The keyword is to be used as a convenient way to get PostScript or raster output for a single graphics command. Output parameters can be set with cgWindow_SetDefs.

OPOSITION out optional type=float

Set this keyword to a named variable to obtain the actual position in the graphics window where the image was located. The output position may be different from the input POSITION, especially if the KEEP_ASPECT_RATIO keyword is set. Note that the output position is also stored in a FSC_$CGIMAGE common block so that other programs (e.g., cgMap, cgImageInfo, etc.) can take advantage of this information.

OVERPLOT in optional type=boolean default=0

Setting this keyword causes the POSITION keyword to be ignored and the image is positioned in the location established by the last graphics command. If the XRange and YRange keywords are also used, the image position is adjusted with respect to the current axes range. Setting this keyword also sets the NoErase keyword, if it is not currently set. It is assumed that the overplotted images fits entirely inside or is coincident with the position or range of the previous image. If not, an informational error is generated and the position is forced into the range of 0 to 1.

PALETTE in optional type=byte

Set this keyword to a 3x256 or 256x3 byte array containing the RGB color vectors to be loaded before the image is displayed. Such vectors can be obtained, for example, from cgLoadCT with the RGB_TABLE keyword:

cgLoadCT, 4, /BREWER, /REVERSE, RGB_TABLE=palette cgImage, cgDemoData(7), PALETTE=palette

POSITION in optional type=float

The location of the image in the output window. This is a four-element floating array of normalized coordinates of the type given by !P.POSITION or the POSITION keyword to other IDL graphics commands. The form is [x0, y0, x1, y1]. The default is [0.0, 0.0, 1.0, 1.0]. Note that this keyword is ALSO an output keyword. That is to say, upon return from cgImage this keyword (if passed by reference) contains the actual position in the window where the image was displayed. This may be different from the input values if the KEEP_ASPECT_RATIO keyword is set, or if you are using cgImage with the POSITION keyword when !P.MULTI is set to something other than a single plot. Note that the POSITION keyword should not, normally, be used when displaying multiple images with !P.MULTI. If it is used, its meaning differs slightly from its normal meaning. !P.MULTI is responsible for calculating the position of graphics in the display window. Normally, it would be a mistake to use a POSITION graphics keyword on a graphics command that was being drawn with !P.MULTI. But in this special case, cgImage will use the POSITION coordinates to calculate an image position in the actual position calculated for the image by !P.MULTI. The main purpose of this functionality is to allow the user to display images along with color bars when using !P.MULTI.

QUIET in optional type=boolean default=0

There are situations when you would prefer that cgIMAGE does not advertise itself by filling out the FSC_$CGIMAGE common block. For example, if you are using cgImage to draw a color bar, it would not be necessary. Setting this keyword means that cgImage just goes quietly about it's business without bothering anyone else.

REVERSE in optional type=boolean default=0

Set this keyword to reverse the color table vectors selected with the CTIndex keyword.

SAVE in optional type=boolean default=0

Set this to cause a data coordinate system to be established for the image. The XRANGE and YRANGE keyword values will be used to establish a data coordinate system coincident with the final image position. Setting the AXES keyword automatically sets SAVE=1.

SCALE in optional type=boolean default=0

Set this keyword to byte scale the image before display. If this keyword is not set, the image is not scaled before display. This keyword will be set automatically by using any of the keywords normally associated with byte scaling an image. Available only with 2D images. If set, STRETCH is set to 1, unless it is set to another value.

SIGMA in optional type=float default=1.0

The sigma scale factor in a Gaussian stretch. Available only with 2D images.

STRETCH in optional type=integer/string default=0

The type of scaling performed prior to display. May be specified as a number or as a string (e.g, 3 or "Log"). Available only with 2D images. If Min(image) is less than zero or Max(image) is greater than 255, then the default value for stretch is 1.

Number Type of Stretch:

0 None No scaling whatsoever is done. 1 Linear scaled = BytScl(image, MIN=minValue, MAX=maxValue) 2 Clip A histogram stretch, with a percentage of pixels clipped at both the top and bottom 3 Gamma scaled = GmaScl(image, MIN=minValue, MAX=maxValue, Gamma=gamma) 4 Log scaled = LogScl(image, MIN=minValue, MAX=maxValue, Mean=mean, Exponent=exponent) 5 Asinh scaled = AsinhScl(image, MIN=minValue, MAX=maxValue, Beta=beta) 6 SquareRoot A linear stretch of the square root histogram of the image values. 7 Equalization A linear stretch of the histogram equalized image histogram. 8 Gaussian A Gaussian normal function is applied to the image histogram. 9 MODIS Scaling done in the differential manner of the MODIS Rapid Response Team and implemented in the Coyote Library routine ScaleModis. 10 StdDev Standard deviation stretch. scaled = SDevScl(image, MULTIPLIER=2).

TITLE in optional type=string

Set this keyword to the title of the image plot. No title will appear with the image unless the AXES keyword is also set.

TOP in optional type=integer default=255

If the SCALE keyword is set, the image is scaled before display so that all displayed pixels have values greater than or equal to BOTTOM and less than or equal to TOP. Available only with 2D images.

TRANSPARENT in optional type=integer default=50

A number between 0 and 100 that specifies the percent of transparency between the image being displayed and the background image. Displaying a transparent image does not advance !P.Multi.

TV in optional type=boolean default=0

Setting this keyword makes the cgImage command work much like the brain-dead TV command except that it will get colors right on all output devices. Most of the cgImage keywords are ignored if this keyword is set.

WINDOW in optional type=boolean default=0

Set this keyword to replace all the commands in a current cgWindow or to create a new cgWindow for displaying this command. If the DISPLAY keyword is also set, a new cgWindow will be created.

XRANGE in optional type=fltarr(2)

A two element array giving the X range of the image. By default set to [0, size of image in X].

XTITLE in optional type=string

The X title of the image plot. Used only if AXES is set.

XVECTOR in optional

A vector of X values that can be used as an alternative mthod of specifying the XRange of the plot.

YRANGE in optional type=fltarr(2)

A two element array giving the Y range of the image. By default set to [0, size of image in Y].

YTITLE in optional type=string

The Y title of the image plot. Used only if AXES is set.

YVECTOR in optional

A vector of Y values that can be used as an alternative mthod of specifying the YRange of the plot.

_REF_EXTRA in optional type=varies

Any keywords defined for the TV command can be used. This applies only if the TV keyword is set.

File attributes

Modification date: Fri Mar 27 12:46:54 2015
Lines: 2,547
Docformat: rst rst