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.
beta: in, optional, type=float, default=3.0
The beta factor in a Hyperpolic Sine stretch. Available only with 2D images.
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.
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.
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_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.
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.
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.
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.
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.
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, default=""
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.
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.
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 = cgGmaScl(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).
sigma: in, optional, type=float, default=1.0
The sigma scale factor in a Gaussian stretch. Available only with 2D images.
title: in, optional, type=string, default=""
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, default=""
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, default=""
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.