>  Docs Center  >  Libraries  >  Coyote  >  CGCONTOUR

CGCONTOUR

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_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.



© 2019 Harris Geospatial Solutions, Inc. |  Legal
My Account    |    Store    |    Contact Us