# coyote: CGCONTOUR

- coyote/Graphics
- [Source code]

Description

      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.
      .. image:: cgcontour.png
      The program requires the `Coyote Library <http://www.idlcoyote.com/documents/programs.php>`
      to be installed on your machine.

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_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_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.
      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.
      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 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.
      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 <http://www.exelisvis.com/docs/CONTOUR_Procedure.html>`
         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 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.

Copyright

      Copyright (c) 2010-2014, Fanning Software Consulting, Inc.