top cgContour

Graphics

cgContour, data [, x] [, y] [, /ADDCMD] [, ASPECT=float] [, AXISCOLOR=string/integer] [, AXESCOLOR=string/integer] [, BACKGROUND=string/integer] [, C_ANNOTATION=string] [, C_CHARSIZE=float] [, C_COLORS=integer/string vector] [, C_LABELS=integer], C_ORIENTATION=C_ORIENTATION, C_SPACING=C_SPACING [, /CELL_FILL] [, CHARSIZE=float] [, COLOR=string/integer] [, /FILL] [, FONT=integer] [, /ISOTROPIC] [, /IRREGULAR] [, LABEL=integer] [, LAYOUT=intarr(3)] [, LEVELS=any] [, NLEVELS=integer] [, /NOCLIP] [, /NOERASE] [, MAP_OBJECT=object] [, MISSINGVALUE=any] [, OLEVELS=OLEVELS] [, /ONIMAGE] [, OUTCOLOR=string] [, OUTFILENAME=string] [, /OUTLINE] [, OUTPUT=string] [, /OVERPLOT] [, PALETTE=byte] [, POSITION=float] [, RESOLUTION=integer array] [, /T3D] [, TITLE=string] [, /TRADITIONAL] [, /WINDOW] [, XSTYLE=integer] [, XTHICK=integer] [, XTICKLEN=float] [, XTICKV=string] [, XTICKS=integer] [, XTITLE=string] [, YSTYLE=integer] [, YTHICK=integer] [, YTICKLEN=float] [, YTICKV=string] [, YTICKS=integer] [, YTITLE=string], ZVALUE=ZVALUE [, _REF_EXTRA=any]

Parameters

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_ANNOTATION in optional type=string

The label to be drawn on each contour. Normally contours are labeled with their value. This vector of strings may substitute for those values.

C_CHARSIZE in optional type=float

The character size of the annotations used on the contour lines themselves. By default, 75% of Charsize.

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_ORIENTATION

C_SPACING

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.

FILL in optional type=boolean default=0

Set to indicate filled contours should be created.

FONT in optional type=integer default=!P.Font

The type of font desired for axis annotation.

ISOTROPIC in optional type=boolean default=0

Set this keyword to set the Aspect keyword to the plot aspect ratio that preserves identical scaling for the X and Y axes. This keyword cannot be used with multiple contour plots on the page.

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.

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!

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.

NOERASE in optional type=boolean default=0

Set this keyword to prevent the window from erasing the contents before displaying the contour plot.

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.

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

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

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.

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.

XTICKS in optional type=integer

The number of tick intervals on the X axis.

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.

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.

YTICKS in optional type=integer

The number of tick intervals on the Y axis.

YTITLE in optional type=string

Set this keyword to the Y title of the plot.

ZVALUE

_REF_EXTRA in optional type=any

Any keyword appropriate for the IDL Contour command is allowed in the program.

Examples

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) 2010-2014, Fanning Software Consulting, Inc.

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 cgSetColorState. 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. Added C_ANNOTATION keyword. 10 Nov 2012. DWF. Modified the way default colors are selected when the background color is "white". 4 Dec 2012. DWF. Making more effort to set the CELL_FILL keyword instead of FILL if filling contours on maps. 7 Jan 2013. DWF. Added C_ORIENTATION and C_SPACING keywords and modified the program to allow line filling. 28 Jan 2013. DWF. Added ISOTROPIC keyword. 27 June 2013. DWF. Added sanity check for ISOTROPIC keyword. 6 Feb 2014. DWF. Fixed a bug with the ISOTROPIC keyword. 23 Feb 2014. DWF. Previously, I used the Aspect function to calculate a position of the plot in the window. This was causing problems when encapsulated PostScript files were created, because Aspect uses a landscape aspect ratio and EPS files can only be written in Portrait mode. I also modified the default position to be [0.15, 0.15, 0.915, 0.915], but I am doing this ONLY for graphics windows, not in PostScript output. This should accommodate a wider range of contour plot output. If you find axes cut off, use the POSITION keyword to position the plot correctly. 19 March 2014. DWF Previous fix caused other problems. Reverted to 23 Feb 2014 version of cgContour and have tried another way to solve encapsulated ASPECT problem. Now setting initial position in window with cgAspect. Appears to be working correctly. 25 Nov 2014. DWF.