CGCONTOUR
The purpose of cgContour is to create a wrapper for the traditional IDL graphics
command, Contour. The Contour command has a number of deficiencies that make it
difficult to use in a modern computing environment. cgContour corrects these
deficiencies and allows the user to produce traditional contour plots in a device
and machine independent manner.
Categories
Graphics
Params
data: in, required, type=any
A one- or two-dimensional array containing the values that make
up the contour surface.
x: in, optional, type=any
A vector or two-dimensional array specifying the X coordinates for
the contour surface.
y: in, optional, type=any
A vector or two-dimensional array specifying the Y coordinates for
the contour surface.
Keywords
addcmd: in, optional, type=boolean, default=0
Set this keyword to add the command to an cgWindow. Setting this keyword
automatically sets the WINDOW keyword, but the command does not erase the
graphics window as it would normally.
aspect: in, optional, type=float, default=none
Set this keyword to a floating point ratio that represents the aspect ratio
(ysize/xsize) of the resulting plot. The plot position may change as a result
of setting this keyword. Note that `Aspect` cannot be used when plotting with
!P.MULTI.
axiscolor: in, optional, type=string/integer, default='opposite'
If this keyword is a string, the name of the axis color.
Otherwise, the keyword is assumed to be a color index into the current color table.
axescolor: in, optional, type=string/integer
Provisions for bad spellers.
background: in, optional, type=string/integer, default='background'
If this keyword is a string, the name of the background color.
Otherwise, the keyword is assumed to be a color index into the current color table.
c_colors: in, optional, type=integer/string vector
Set to the index values of the contour colors or to named colors. Must contain
the same number of colors as the number of requested contour levels.
c_labels: in, optional, type=integer
A vector that specifies which contour levels to label. If used, the LABEL
keyword is ignored.
c_charsize: in, optional, type=float
The character size of the annotations used on the contour lines themselves.
By default, 75% of `Charsize`.
cell_fill: in, optional, type=boolean, default=0
Set to indicate filled contours should be created using the "cell fill" method.
This keyword should always be set if displaying filled contours on map projections
or if missing data is present in the data you are contouring.
charsize: in, optional, type=float, default=cgDefCharSize()
The character size for axes annotations. Uses cgDefCharSize to select default
character size, unless !P.Charsize is set, in which case !P.Charsize is always used.
color: in, optional, type=string/integer, default='black'
If this keyword is a string, the name of the data color. By default, same as AXISCOLOR.
Otherwise, the keyword is assumed to be a color index into the current color table.
font: in, optional, type=integer, default=!P.Font
The type of font desired for axis annotation.
fill: in, optional, type=boolean, default=0
Set to indicate filled contours should be created.
irregular: in, optional, type=boolean
If this keyword is set, the data, x, and y input parameters are taken to be
irregularly gridded data, the the data is gridded for use in the contour plot
using the Triangulate and Trigrid method. The resolution of the gridded output
is set by the RESOLUTION keyword.
label: in, optional, type=integer, default=1
An number that tells how to label contour levels. A 0 means
no contour levels are labelled. A 1 (the default) means all contour levels are
labelled. A 2 means label every 2nd contour level is labelled. A 3 means every
3rd contour level is labelled, and so on.
layout: in, optional, type=intarr(3)
This keyword specifies a grid with a graphics window and determines where the
graphic should appear. The syntax of LAYOUT is three numbers: [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.
levels: in, optional, type=any
A vector of data levels to contour. If used, NLEVELS is ignored. If missing,
NLEVELS is used to construct N equally-spaced contour levels.
map_object: in, optional, type=object
If you are overplotting (OVERPLOT=1) on a map projection set up with Map_Proj_Init
and using projected meter space, rather than lat/lon space, then you can use this
keyword to provide a cgMap object that will allow you to convert the `x` and `y`
grid parameters from longitude and latitude, respectively, to projected meter space
before the contour is displayed. Note, you MUST pass the `x` and `y` grid parameters
to cgContour if you are overplotting on a map projection. There is no checking to
be sure these parameters are in the correct longitude and latitude range, respectively.
missingvalue: in, optional, type=any
Use this keyword to identify any missing data in the input data values.
noclip: in, optional, type=boolean, default=0
Normally, the plot is clipped to the axes boundaries. Setting this keyword prevents
such clipping. Normally, this keyword is only used when there is a problem displaying
contour plots in 3D space.
nlevels: in, optional, type=integer, default=6
If the Contour plot LEVELS keyword is not used, this keyword will produce this
number of equally spaced contour intervals. Unlike the Contour NLEVELS keyword,
this keyword actually works!
noerase: in, optional, type=boolean, default=0
Set this keyword to prevent the window from erasing the contents before displaying
the contour plot.
olevels: out, optional
Set to a named variable to return the actual contour levels used in the program.
Unfortunately, output variables cannot be returned if the cgContour command is
being executed in a cgWindow.
onimage: in, optional, type=boolean, default=0
If this keyword is set, and an image has been display previously with cgImage,
then the contour plot will determine the location of the image in the display
window and overplot itself onto that image.
outcolor: in, optional, type=string, default='charcoal'
The color of the contour lines when the `Outline` keyword is used.
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.
outline: in, optional, type=boolean, default=0
This keyword applies only if the `Fill` keyword is set. It will draw the
contour lines on top of the filled contour. It draws the outline in the `OutColor`.
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 PS_END 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
Set this keyword to overplot the contours onto a previously established
data coordinate system.
palette: in, optional, type=byte
A (256x3) color palette containing the RGB color vectors to use for coloring contours.
Contour colors will be sampled from the color table palette into the number
of contour levels required. If the palette is NOT 256 elements in length, then
it is assumed that the length corresponds to the number of levels to be contoured.
position: in, optional, type=float
Set this keyword to a four-element [x0,y0,x1,y1] array giving the contour plot
position in normalized coordinates.
resolution: in, optional, type=integer array, default=[41\,41]
If the IRREGULAR keyword is set, this keyword specifies the X and Y resolution
in a two element integer array of the final gridded data that is sent to the
contour plot.
t3d: in, optional, type=boolean, default=0
Set this keyword to use the 3D axis rotation matrix in !P.T3D.
title: in, optional, type=string
Set this keyword to the title of the plot.
traditional: in, optional, type=boolean, default=0
If this keyword is set, the traditional color scheme of a black background for
graphics windows on the display is used and PostScript files always use a white background.
window: in, optional, type=boolean, default=0
Set this keyword to replace all the commands in the current cgWindow or to
create a new cgWindow, if one doesn't currenly exist, for displaying this command.
To create a new cgWindow if one currenly exists, use the `cgWindow` command
xstyle: in, optional, type=integer, default=1
If unused in the program, set to 1 to force exact axis scaling.
xthick: in, optional, type=integer, default=1
The thickness of the X axis annotations.
xticklen: in, optional, type=float, default=0.025
The length of the X tick marks. Set to a negative value to create outward
facing tick marks.
xticks: in, optional, type=integer
The number of tick intervals on the X axis.
xtickv: in, optional, type=string
A vector of tick values to use with the tick marks. See IDL documentation for
graphics keywords for additional information.
xtitle: in, optional, type=string
Set this keyword to the X title of the plot.
ystyle: in, optional, type=integer, default=1
If unused in the program, set to 1 to force exact axis scaling.
ythick: in, optional, type=integer, default=1
The thickness of the Y axis annotations.
yticklen: in, optional, type=float, default=0.025
The length of the Y tick marks. Set to a negative value to create outward
facing tick marks.
yticks: in, optional, type=integer
The number of tick intervals on the Y axis.
ytickv: in, optional, type=string
A vector of tick values to use with the tick marks. See IDL documentation for
graphics keywords for additional information.
ytitle: in, optional, type=string
Set this keyword to the Y title of the plot.
_ref_extra: in, optional, type=any
Any keyword appropriate for the IDL Contour command is allowed in the program.
Examples
Use as you would use the IDL CONTOUR command::
data = dist(51)
cgContour, data
LoadCT, 33
cgContour, data, /FILL
cgContour, data, /OVERPLOT
If you wish to overplot on top of an image, use the ONIMAGE keyword, rather
than the OVERPLOT keyword:
cgImage, data, /SCALE, XRANGE=[-10, 10], YRANGE=[-5,5], /AXES
cgContour, data, /ONIMAGE
See `Device Independent Contour Plots <http://www.idlcoyote.com/graphics_tips/cgcontour.html>'
for additional examples.
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
History
Change History::
Written, 11 November 2010. DWF.
Restored the CELL_FILL keyword, which had been accidentally removed in
the earlier version. 12 November 2010. DWF.
Add the ability to specify the contour colors as color names. 16 November 2010. DWF.
Now setting decomposition state by calling SetDecomposedState. 16 November 2010. DWF.
Final color table restoration skipped in Z-graphics buffer. 17 November 2010. DWF.
Background keyword now applies in PostScript file as well. 17 November 2010. DWF.
Many changes after BACKGROUND changes to get !P.MULTI working again! 18 November 2010. DWF.
Fixed a small problem with the OVERPLOT keyword. 18 Nov 2010. DWF.
Changes so that color variables don't change type. 23 Nov 2010. DWF.
Added WINDOW keyword to allow graphic to be displayed in a resizable graphics window. 8 Dec 2010. DWF
Modifications to allow cgContour to be drop-in replacement for old Contour commands in
indexed color mode. 24 Dec 2010. DWF.
Previous changes introduced problems with OVERPLOT that have now been fixed. 28 Dec 2010. DWF.
Set NOERASE keyword from !P.NoErase system variable when appropriate. 28 Dec 2010. DWF.
Additional problems with NOERASE discovered and solved. 29 Dec 2010. DWF.
Change to DECOMPOSED color was using incorrect color tables. 29 Dec 2010. DWF.
In some cases, I was turning BYTE values to strings without converting to
INTEGERS first. 30 Dec 2010. DWF.
Still working on getting contour colors to work in decomposed color mode in all
circumstances. 2 Jan 2011. DWF.
Fixed problem with FILL when no contour colors (C_COLORS) are specified. 3 Jan 2011. DWF.
Fixed a problem that preventing output keyword (e.g., PATH_INFO) from being returned properly.
3 Jan 2011. DWF.
Fixed a problem calculating NLEVELS when LEVELS keyword was used instead. 3 Jan 2011. DWF.
TVLCT commands protected from NULL device. 4 Jan 2011. DWF.
Fixed a no color problem when CELL_FILL was set. 11 Jan 2011. DWF.
Fixed a problem with overlaying filled contours with /OVERPLOT. 11 Jan 2011. DWF.
Selecting character size now with cgDefCharSize. 11 Jan 2011. DWF.
Moved setting to decomposed color before color selection process to avoid PostScript
background problems when passed 24-bit color integers. 12 Jan 2011. DWF.
Fixed a problem in which I assumed the background color was a string. 18 Jan 2011. DWF.
Added ADDCMD keyword. 26 Jan 2011. DWF.
Added LAYOUT keyword. 28 Jan 2011. DWF.
Added PALETTE keyword. 4 Feb 2011. DWF.
Color table vectors must be obtained AFTER loading the color palette. 6 March 2011. DWF.
Modified error handler to restore the entry decomposition state if there is an error. 17 March 2011. DWF
Modifications to allow palettes of less than 256 elememts in length to be used. 1 April 2011. DWF.
Modifications to repair axes and tickmarks when creating filled contour plots. 28 May 2011. DWF.
Whoops! Last fix shouldn't apply to OVERPLOTTING. Fixed. 22 June 2011. DWF.
Still more work to get axes overplotting to work correct. 5 July 2011. DWF.
Added an ONIMAGE keyword that allows the contours to be overplotted on top of an image that
has been displayed with cgImage. This requires that the SAVE keyword is set in the
cgImage call.
Improved error handling. 26 Aug 2011. DWF.
Got the data type correct in the part of the code that creates levels. 6 Sept 2011. DWF.
Small change to allow cgWindow to set the current graphics window if it is the only
window on the display. 15 Sept 2011. DWF.
Had to add XTICKV, YTICKV, XTICKS, and YTICKS keywords to get repaired axes to work
properly on filled contour plots. There may be other keywords needed, but I am
going to add them on an as-needed basis. 30 Sept 2011. DWF.
Other keywords WERE needed! I added XTICKLEN and YTICKLEN keywords to the repaired axes
code. 3 Oct 2011. DWF.
Change from 15 Sept 2011 forgot to include the possibility of pixmap windows. Algorithm
made more robust. 27 Oct 2011. DWF.
There was a problem with axes when plotting contours in 3D that has been fixed. 18 Nov 2011. DWF.
Added OLEVELS keyword. 7 Dec 2011. DWF.
Added OUTLINE and OUTCOLOR keywords. 8 Dec 2011. DWF.
Modified the way the axes are drawn when given a negative tick length. 9 Dec 2011. DWF.
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.
Made sure the OUTLINE keyword works with CELL_FILL, too. 16 Dec 2011. DWF.
Modified to use cgDefaultColor for default color selection. 24 Dec 2011. DWF.
Added MAP_OBJECT keyword. 28 Dec 2011. DWF.
Changes to allow better default colors, based on changes to cgColor and cgDefaultColor. 1 Feb 2012. DWF.
Axis repair for filled contour plots (done with AXIS) results in incorrect tick labeling with
date/time axes. Replaced repair code with actual Contour command. 9 March 2012. DWF.
Fixed a problem with color palettes by defining NLEVELS according to the number of colors
in the palette. 19 March 2012. DWF.
Now allowing the user to draw in the "background" color, if the COLOR or AXISCOLOR is "BACKGROUND". 19 March 2012. DWF.
The axis repair change on 9 March was not working in multi plots because the plot was already
advanced. Added a fix to make sure the repair is to the correct multi plot. 20 April 2012. DWF.
Added an ASPECT keyword to maintain the program aspect ratio. 12 July 2012. DWF.
Added the ability to use escape characters in plot titles to specify cgSymbol symbols. 27 July 2012. DWF.
Copyright
Copyright (c) 2010, Fanning Software Consulting, Inc.